Back to top image

Translating Custom JSON Fields in Contentful

Smartling's Contentful (Fields) Connector can translate content stored in JSON object fields within Contentful entries. This guide will walk you through how to configure the connector to find and translate this type of content.

How it works

To translate content from a JSON object field, you need to tell the Smartling connector two things:

  1. Which JSON fields to translate
  2. How to parse the content within those fields (e.g., as HTML, Markdown, or plain text)

This is done by specifying the path to the translatable content within the JSON structure. Follow the steps below to configure translation for JSON object fields.

Step 1: Enable custom JSON parsing

First, you need to enable the Custom JSON parsing option for the JSON fields you want to translate.

  1. From your Contentful Connector project, go to the Settings tab > Contentful Settings
  2. In the Content Parsing section, for the JSON field you want to translate, select Custom JSON parsing option from the drop-down menu and click the Save button. This tells the connector to look for specific paths to translate within this field. 

Step 2: Find the paths to your content

To tell Smartling exactly what to translate, you need to provide the path to each piece of content within the JSON object.

The path follows this format:
/fields/<JSON_field_name>/<source_locale>/<path_within_JSON>

How to find the correct paths

  1. After selecting the Custom JSON parsing option for the desired field, go to the Contentful (Fields) tab in your connector project and request translation for an entry that contains the JSON object fields with the content you want to translate.
  2. In Step 3 of the Request Translation wizard, select Save for Later to create the job, but have the content sit in Awaiting Authorization. You can authorize the job at this point if you wish, but keep in mind that it will only include strings from other fields in the entry; it will not ingest any strings from the JSON object fields yet.
    save-for-later.png

  3. Once the job is created, download the source file from the job via the job's Files tab. Within the Files tab, click the download arrow under Actions.

    download-source-file.png

    In the modal that opens, choose to download the source file.

    download source-file.png

  4. Open the downloaded JSON file. You will see the structure of your Contentful entry. You can now determine the paths to the content you wish to translate. 

Example

Here is an example of what a downloaded JSON file could look like:

{
   "fields": {
     "pageComponents": {
       "en-US": {
         "hero": {
           "headline": "Welcome to Our Store",
           "trackingCode": "HERO_SPRING_2025"
         },
         "features": [
           {
             "title": "Free Shipping",
             "description": "On all orders over $50",
             "icon": "shipping-icon.svg"
           },
           {
             "title": "24/7 Support",
             "description": "We're here to help anytime",
             "icon": "support-icon.svg"
           }
         ]
       }
     },
     "name": {
       "en-US": "Our Store",
       "character_limit": 255
     }
   }
 }

The paths to the translatable content in this example would be:

  • /fields/pageComponents/en-US/hero/headline
  • /fields/pageComponents/en-US/features/title
  • /fields/pageComponents/en-US/features/description

Note on arrays and complex JSON: The connector can handle more complex JSON structures. For detailed information on how to specify paths for different JSON structures, please refer to the JSON documentation.

Step 3: Configure custom JSON parsing

Once you have the paths, you can add them to your connector settings.

  1. From your Contentful Connector project, click the Settings tab > Contentful Settings
  2. Within the Content Parsing section, under Custom JSON Parsing, click Add New Field.
    add-new-field.png
  3. In the Field Path (Contentful) column, enter the path you found in Step 2.
  4. Select the Parsing Type for this content (HTML, Markdown, or Plain text).
  5. In the Description field, we strongly recommend adding a clear and concise description of what this field represents (e.g., "Hero headline on the main page"). This description is for your reference and will help you and your team easily manage your configuration in the future.

    Example: 
    Example-field-for-custom-JSON-mapping.png
  6. Repeat this process for each piece of content you want to translate from your JSON fields. Once saved, the connector will find and send this content for translation in all future jobs. 

You can now re-request the entry that contains a JSON object field. Any JSON fields you added in Step 3 will now be ingested for translation. When requesting translation, you can add the content to the existing job you created in Step 2 or add it to a new job, and then authorize the content for translation. 

Table of Contents