Please note that this connector is a paid product. For pricing information, please reach out to your Smartling Customer Success Manager.

Configure Contentful user permissions

Before connecting Smartling to Contentful, decide which Contentful user account the Contentful Connector will use, and verify that account's permissions. The Contentful Connector updates Contentful entries with translations on behalf of this user account, so the account needs permission to edit content, while access should stay restricted to only the spaces you plan to localize. We recommend creating a new Contentful user account with a self-descriptive name (for example, smartling@yourbusinessname.com) rather than reusing a personal account.

Step 1: Create a dedicated role in Contentful

Repeat the steps below in Contentful for each space you plan to translate.

1. In Contentful, go to Settings > Roles & Permissions.
2. Click Create new role.
   • Smartling recommends naming this role something self-descriptive, such as "Smartling Connector."
3. Under Role details, enter a name (for example, "Smartling connector role") and a description.
   

4. Under Content, create four rules:

   • Read - Any entry - All content types
   • Edit - Any entry - All content types - All fields - All locales
   • Publish - Any asset - Any locale
   • Unpublish - Any asset - Any locale

   

5. Under Media, create the same four rules listed above.
   

6. Under Environments:

   • Select the environments this role should have access to.
   • Leave the Content types permission unchecked.
   • Leave the Tags permission unchecked.

   

7. Under Permissions:

   • Check the Space Settings permission.
   • Check the API keys permission.
   • If the space does not already have an API key, create one under Settings > API keys > Add API Key in Contentful before continuing. The Contentful Connector does not create API keys itself, and connection will fail if the space has no API key.

   

8. Click Save Changes.

Step 2: Invite a new user and assign the role

1. In Contentful, go to Organization settings > Users.
2. Click Invite user.
3. Enter the email address for the dedicated connector user created in Step 1. This is the email address you'll use later when authorizing the connection between Smartling and Contentful.
4. Set Organization role to member.
5. Under Access to space, check the Smartling connector role (created in Step 1) only for the spaces that contain content to be translated. In the example below, the connector user has access to only the Sample project space.
   
6. Check the invited user's email inbox and complete the invitation.

If your Contentful plan does not support custom roles, assign the Admin role to the connector user instead.

Step 3: Enable localization in Contentful

Before connecting the Smartling Contentful Connector, make a few configuration changes in Contentful so your content is flagged as localizable. See Enabling Localization of Contentful for those steps.

Step 4: Connect Contentful to Smartling

1. Log in to Contentful using the dedicated connector user you created in Steps 1 and 2. This is important because the account you are logged in as during this step is the account used for OAuth authorization.
2. Log in to Smartling.
3. In your Smartling account, create a Contentful Connector project:
   • Choose Contentful (Fields) for field-level localization.
   • Choose Contentful (Entries) for entry-level localization.
   • See the Contentful documentation for the difference between the two.
4. In the Smartling project, add all required target languages.
5. Go to the project's Settings tab > Contentful Settings.
6. Click Connect to Contentful.
7. In the Contentful Data Residency dialog, select the region where your organization's Contentful data resides (Default or EU), then click Connect.
8. Click Authorize to let the Smartling Contentful Connector access your Contentful account. If you aren't already logged in to Contentful, you'll be redirected to the Contentful login page first.
   

Step 5: Add a Contentful space

A Smartling project can connect to one or more Contentful spaces. Each space is configured independently, with its own environment and source locale, in the Configured spaces table on the Contentful Settings page.

Each space can only be connected to one environment at a time within a given Smartling project. This means:

• Different spaces can use different environments. For example, you can connect Space A using its master environment and Space B using its testing environment.
• The same space cannot be connected twice with different environments. For example, you cannot connect Space A's master environment and Space A's testing environment within the same project.

If you need to translate content from multiple environments of the same space (for example, separate staging and production environments), set up a separate Smartling project for each environment.

Each space must also use the same source language. A Smartling project can have only one source locale. You can configure spaces with variations of the same language, such as en in Space 1 and en-US in Space 2, but you cannot use different source languages, such as en-US in Space 1 and fr-FR in Space 2.

1. In the Smartling Contentful project, go to the Settings tab > Contentful Settings.
2. In the Configured spaces section, click + Add space.
3. Step 1 of 3, select a Contentful space: choose one Contentful space to configure. A space with unresolved errors in Contentful can't be added until those errors are fixed.
4. Step 2 of 3, select an environment: choose the Contentful environment Smartling should read content from (for example, master). The locale list in the next step reflects the locales available in this environment.
5. Step 3 of 3, select a source locale: choose the source locale for this space. Contentful marks one locale as Default for the selected environment.
6. Click Save.

The new space appears as a row in the Configured spaces table, showing its space name, environment ID, and source locale. Repeat these steps for each additional Contentful space you want to translate through this Smartling project.

If Contentful can no longer reach a configured space (for example, because access was revoked or the space was deleted in Contentful), that space is labeled [unavailable] in the table. Remove an unavailable space from the Configured spaces table if you no longer need it.

Step 6: Configure the connector

When you have successfully connected Contentful to Smartling, the Contentful Settings page displays the following configurations:

• Visual Context Settings: how Smartling generates previews of translated content for that space.
• General: how the connector handles changes to previously translated content.
• Language Configuration: how Contentful locales map to Smartling target languages.
• Content Parsing: how individual fields are parsed and broken down for translation.

General

The General settings control how the Contentful Connector behaves when updates are made to previously translated content.

1. In the Smartling Contentful project, go to the Settings tab > Contentful Settings.
2. Use the Automation of Prior Requests for Translation dropdown to select the desired behavior (see options below).
3. Configure publishing options for delivered translations in Contentful.
4. Optional: select the Exclude media assets checkbox to exclude all media assets from translation, regardless of whether they were translated previously. This option isn't available for the Contentful (Entries) Connector.
5. Click Save.

Automation of prior requests for translation

• Automatically request translation (formerly "Auto"): every three hours, the Contentful Connector checks for changes to previously submitted source content. Detected updates are batched into a job and held for authorization. If auto-authorize is enabled under Smartling Settings, the updated content is authorized for translation automatically. This option only detects updates to content that was previously submitted for translation; it does not detect content in brand-new assets that have never been submitted.
• Flag changed content (formerly "Manual"): every three hours, the Contentful Connector checks for changes to source content but does not submit the changes for translation automatically. Changed content can be found in the Contentful Asset list by selecting the Out of Sync checkbox. From there, a user can manually select assets and choose Request Translation from the Actions dropdown.
• Disabled: the Contentful Connector does not check for source content changes and does not submit new changes for translation.

Three hours is the shortest check interval Smartling recommends. To use a longer interval, talk to your Solutions Architect about configuring a custom cron schedule.

Language configuration

Accurate language mapping between Contentful and Smartling ensures your content is captured for translation, translated into the correct languages, and returned to the correct target locales. Complete the following steps carefully:

1. In the Smartling Contentful project, go to the Settings tab > Contentful Settings.
2. In the Language Configuration section, review the target languages configured in the Smartling project alongside the source language.
3. Confirm the Contentful source language with your Solutions Architect; it must exactly match the language listed under Source Language (Smartling).
   • Contentful's default source language is assumed to be en-US.
   • Do not change the source locale mapping yourself: doing so will break the integration. Contact your Solutions Architect if the source locale mapping needs to change.
4. For each Contentful language, choose the matching Smartling target language from the dropdown menu.
5. Click Save.

To adjust the language mapping after initial setup, contact Smartling support for assistance.

A single Contentful language cannot map to more than one Smartling language. Reusing the same Smartling locale twice in the Language Configuration produces a "wrong locales mapping" error.

Configure Contentful content parsing

When Smartling captures content from a Contentful space, it processes each entry field according to the Content Parsing configuration for that field. Content parsing (also called string parsing) can break a field's content into smaller strings, making translation more efficient and improving translation quality.

Only fields that are enabled for localization in Contentful appear in the Content Parsing settings for a content type. If a field is missing from the list, check that it's enabled for localization in Contentful first.

If you change the parsing configuration for a field, the new configuration only takes effect the next time the source content for that field is updated in Contentful. That update triggers the Contentful Connector to re-upload the source content and parse it using the current configuration.

Steps to configure content parsing

1. In the Smartling Contentful project, go to the Settings tab > Contentful Settings.
2. Under Content Parsing, select a Contentful space from the dropdown. This list reflects the spaces you added in Step 5. You can also filter by Asset Type. These filters aren't available for the Contentful (Entries) Connector.
3. Select a content type from the list to view its fields. If an expected field is missing, confirm it's enabled for localization in Contentful.
4. For each field, select a parsing method from the table below.
5. Click Save to apply the changes.

Repeat these Content Parsing steps for every content type, in every configured space.

A field that has no parsing configuration is not captured for translation. Whenever a new content type or field is added in Contentful, configure it under Content Parsing so its content can be captured going forward.

To translate content stored in JSON object fields, see Translating Custom JSON Fields in Contentful.

All content in fields with a parsing configuration is captured in Smartling automatically. You can still select specific strings when requesting translations.

If you're using the entry-level version of the connector, see the additional parsing options described in Smartling's Hosted Connector Configuration Overview.

Smartling settings

Talk to your Customer Success Manager or Solutions Architect about additional auto-authorization and translation retrieval options.