Setting Up Your Contentful Connector

Once you have enabled localization in Contentful, it is now time to set up the Contentful Connector in Smartling.

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 your Contentful account, you should decide which user account will be used, and verify its permissions. Smartling will update your entries with translations on behalf of your Contentful user account. Therefore, it's important to give this user permission to edit, while still restricting access to spaces which you don’t plan to localize. We recommend creating a new user account with a self-descriptive name.

STEP ONE: Create a New Role in Contentful

You'll need to repeat the steps below for each space that you will be translating.

1. 1. Go to Settings > Roles & Permissions.
   2. Click Create new role from the right-hand side.
      • We recommend setting up a dedicated user role for the connector, e.g. smartling@yourbusinessname.com
   3. Role details: Name (Smartling connector role) and description.
      
      
   4. 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. Media: Create the same four rules as above.
      
   6. Environments:
      • Select required environments.
      • Leave Content types permission unchecked. 
      • Leave Tags permission unchecked. 
        
   7. Permissions: 
      • Check Space Settings permission.
      • Check API keys permission.
      • Note: If you don't already have an API key generated, you can do so by clicking Settings > API keys > Add API Key in Contentful
      • Note: Ensure an API key already exists in the space, or create one before setting up the Connector. The Contentful Connector will not create one, and it will fail to connect if there are no API keys on the space.
        
   8. Save Changes.

STEP TWO: Invite a new user and add them to the new role

• 1. Go to Organization settings > Users.
  2. Click Invite user.
  3. Enter the new user email. This is the email that you'll be using when connecting Smartling to the Contentful account.
  4. Organization role: member
  5. Access to space: Check Smartling connector role for only the spaces that have content to be translated. The screenshot below shows that Smartling will have access to only the Sample project space.
     
     

Check your inbox and complete the invitation. When Smartling asks you to allow access to the Contentful account, use the user email and password.

If your Contentful plan doesn’t allow you to add new roles, you'll need to use the Admin role for your user.

STEP THREE: Enable Localization of Contentful

Before using the Smartling Contentful Connector, you will need to make a couple of minor configuration changes to your Contentful account. For more information, read Enabling Localization of Contentful.

STEP FOUR: Connect Contentful to Smartling

1. Log into Contentful.
2. Log into Smartling.
3. Create a Contentful Connector project type in your Smartling Account.
   • Choose Contentful (Fields) for field-level localization
   • Choose Contentful (Entries) for entry-level localization (entries created in Compose only)
   • For more information on the difference between the two, read the Contentful documentation.
4. Ensure all required target languages are added to the project
5. From within this project, do one of the following
   1. Click on the gear icon > Project Settings > Contentful Settings
6. Click Connect to Contentful.
7. You will be prompted to authorize the Smartling Contentful Connector to use your account. Click Authorize.
   
   If you are not already logged in to Contentful, you will be redirected to the Contentful login page and prompted to enter your credentials. You will then be brought to the Smartling Contentful Connector page.

Your Contentful instance will now be connected to your Smartling project.

STEP Five: Configure Contentful Connector

When you have successfully completed connecting Contentful to Smartling, the Contentful Setting page has the following configurations

• Visual Context Settings
• General
• Language Configuration
• Content Parsing

General

You can configure the behavior of the connector when updates are made to your previously translated content.

1. From within your Smartling Contentful Project, click on Project Settings > Contentful Settings.
2. Click the "Automation of Prior Requests for Translation" dropdown to select your desired behavior.
3. Configure publishing options for delivered translations in Contentful
4. Choose to exclude all media assets from translation, whether they have already been translated previously or not, by selecting the Exclude media assets checkbox.
5. Click Save.

Automation of Prior Requests for Translation

• Automatically request translation (formerly "Auto"): The Contentful Connector will detect changes to previously submitted source content every three hours. Any detected updates are batched into a Job and sit in awaiting authorization. However, if auto-authorize is enabled under Smartling Settings, the updated content is automatically authorized for translation. This feature does not detect content in new assets—only updates to content from assets previously submitted for translation. In other words, if an asset is brand new and has never been requested for translation, its content will not be picked up by this automation. See additional details here. 
• Flag changed content (formerly "Manual"): The Contentful Connector will detect changes to source content every 3 hours, but will not automatically submit content changes for translation. Changed content can be filtered for in the Contentful Asset list by selecting the Out of Sync checkbox. A user can then manually select the assets that should be re-translated, and Request Translation from the Actions dropdown.
• Disabled: The Contentful Connector will not detect changes to source content or automatically submit new changes.

3 hours is the recommended shortest time duration between checks. Talk to your Solutions Architect about changing the frequency to longer wave periods using cron.

Language Configuration 

Precise language mapping between Contentful and Smartling is essential to ensuring the Contentful Connector is set up correctly and your content is passed from Contentful to Smartling for translation. It is also essential to ensuring your content is translated in the correct languages and translation are returned to the correct target sites. Please take extra care in completing the following steps:

1. From within your Smartling Contentful Project, click on Project Settings > Contentful Settings
2. In the Language Configuration section, you will see the number of target languages in your Smartling project, along with the source language in your Smartling project.
3. Confirm your Contentful source language with your Solutions Architect. This should exactly match with what is listed under Source Language (Smartling).
   • The default source language in Contentful is assumed to be en-US 
   • Do not modify the source locale. Changes will break the integration.
   • If you need to change the source locale mapping, reach out to your Solutions Architect.
4. Choose the correct target language from the dropdown menu to map the language in your Contentful language configuration to your Smartling project target language
5. Click Save

Tip: If you decide to adjust the language configuration after the initial language mapping, please contact support for assistance. 

You cannot map a Contentful language to more than one Smartling language. A "wrong locales mapping" error will occur when attempting to use the same Smartling locale twice in the Language Configuration.

Configure Contentful Content Parsing

When Smartling captures content from Contentful, it processes entry fields based on your configuration settings. It may further break down individual fields into smaller strings for translation, making it easier to produce high-quality translations more efficiently. This process is referred to as content parsing or string parsing. 

Follow the steps below to configure how Smartling handles fields based on how your content editors are allowed to format them in Contentful. If a field is not localizable in Contentful, it will not appear in the list of fields for that content type under Content Parsing settings.

Note: If you modify the parsing configuration for a specific asset, the updated settings will only take effect once the source content has been updated in Contentful. This update triggers the connector to re-upload the source content and parse it according to the current configuration.

Steps to Configure Content Parsing 

1. From your Contentful project, click the Settings tab > Contentful Settings.  
2. Under Content Parsing, select your Contentful space. You can also filter by Asset Type.
3. A list of content types will be displayed. Click on the content types to view their fields. 
   
   • If a field appears to be missing, ensure it has been enabled for localization in Contentful.
4. For each field, select a parsing method from the options listed below.
5. Click Save to apply your changes. 

Parsing Option	Description
Copy source	Copies the source content to the target field. The latest version of the source is always delivered as a new version of the target. This happens automatically when Connector delivers a translated file to Contentful - no action required. Simply map the required field as "Copy source" and the Connector will deliver as upon the Job delivery. Please note, content in these fields will not be visible in a Job.
Do not translate	This allows you to control what fields are not translated. Normally, fields that should not be translated should not be configured as "localizable" in your content model. However, some fields need localization, but not really "translation" in Smartling. Examples are fields that contain localizable metadata, such as a JSON field that contains GPS coordinates, or a URL that is used for your application. You can localize these values using the Contentful interfaces or APIs.
Simple Markdown	Only available to clients who started using the connector before we officially supported Markdown. This configuration parses as plain text and treats Markdown tags as "placeholders". Legacy configuration only. User can choose to upgrade to Markdown. Doing so will create new strings that must be re-translated in Smartling.
Markdown	Parses Markdown tags similar to HTML tags for the best experience by translators and maximum Translation Memory leverage. Use this when your field is likely to have markdown.
HTML	Parses the field's HTML tags for the best experience by translators and maximum Translation Memory leverage.  Use this when your field is likely to have HTML markup in it
Rich Text	Only available if the field is Rich Text. Select this to capture the content for translation using are custom rich text parser for Contentful.
ICU	Parses text in the field as ICU MessageFormat. Use this if the fields contain plural-sensitive content.

 

All the content from the fields that are enabled will be captured in Smartling. However, you will still be able to select specific strings when Requesting Translations.

Ensure that these steps are done for each Content Model type.

If any field is not configured, it will not be captured for translation. Whenever a new content type or new field is added, you'll need to configure them under Content Parsing to make sure the content can be captured.

Smartling Settings

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