Contentful Connector

Setting Up Your Contentful Connector

Once you have enabled localization in Contentful, it is now time to set up the Contentful Connector in Smartling. This article will describe how to:

  1. Configure Contentful User Permissions
  2. Connecting Contentful to Smartling
  3. Contentful Connector Configuration
  4. Language Configuration 
  5. Configure Contentful Content Parsing

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.

  1. Create the new role. You'll need to repeat the steps below for each space that you will be translating.
    • Go to Settings > Roles & Permissions.
    • Click Create new role from the right-hand side.
    • Role details: Name (Smartling connector role) and description.
    • Content: Create two rules:
      • Read - Any entry - All content types
      • Write - Any entry - All content types - All fields - All locales
        image1.png
    • Media: Create the same two rules as above.
      image2.png
    • Content model: Leave this unchecked.
    • API keys: Only check Can access existing API keys for this space.
      • Note: Ensure an API key already exists in the space, or create one before setting up Connector. The Contentful Connector will not create one, and it will fail to connect if there are no API keys on the space.
    • Space settings: Leave this checked.
  1. Invite a new user and add them to the new role
    • Go to Organization settings > Users.
    • Click Invite user.
    • Enter the new user email. This is the email that you'll be using when connecting Smartling to the Contentful account.
    • Organization role: member
    • 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.
      image3.png

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.

Connecting Contentful to Smartling

  1. Log into Contentful.
  2. Log into Smartling.
  3. Create a Contentful Connector project type in your Smartling Account.
  4. From within this project, do one of the following
    1. Click on the gear icon > Project Settings > Contentful Settings (New Experience)
    2. Click Connectors > Contentful Content (Classic).
  5. Click Connect to Contentful.
  6. You will be prompted to authorize the Smartling Contentful Connector to use your account. Click Authorize.

    authorize_prompt.pngIf 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.

Contentful Connector Configuration

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 "How do you want Smartling to handle changes to the source content for items that you have previously requested to be translated?" dropdown to select your desired behavior.
  3. Choose to exclude all media assets from translation by selecting the Exclude media assets checkbox.
  4. Click Save.

How do you want Smartling to handle changes to the source content for items that you have previously requested to be translated?

  • Auto: The Contentful Connector will detect changes to source content every 3 hours. Any changes detected to the source content will be submitted to Smartling for translation, batched into a Job and sit in awaiting authorization. However, if auto-authorize is enabled under Smartling Settings, the updated content will be batched into a Job and automatically authorized for translation. Smartling will not detect net new content, only updates to content that have been submitted for translation in the past.
  • Manual: The Contentful Connector will detect changes to source content every 3 hours, but will not submit new content for translation. Changed content will be indicated by a checkmark in the Outdated column in the Contentful tab.
  • 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 

  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 Contentful account, labelled as "Contentful: Czech", for example. These details should match dropdown menus with your Smartling target languages.
  3. Choose the correct target language from the dropdown menu to map the language in your Contentful language configuration to your Smartling project target language.
  4. Click Save after mapping each of the target languages.

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.

The default source language is assumed to be en-US. If you have a different source language contact Smartling Support.

Configure Contentful Content Parsing

When Smartling captures content from Contentful it may process the fields of an entry based on your configuration settings and may break down the individual fields into even smaller strings for translation. This process makes it easier to produce higher quality translations faster.

Follow the steps below to configure how Smartling should handle fields based on how your content editors are allowed to format them in Contentful.  We support plain text / markdown, HTML, and Contentful Rich Text. Of course, if a field is not "localizable" in your content model then it won't even appear in the list of fields for that content type in the Smartling settings.

Do not translate

Use this if the field shouldn't be translated using Smartling.

Normally, fields that don't need to 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 contain GPS coordinates, or a URL that is used for your application. You would 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 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.
Plain text All text and characters treated as plain text.  Use this for fields that you expect to only have plain text with no markup or formatting.
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 contains plural-sensitive content.

By default, Smartling will assume that content is formatted as plain text / markdown.

  1. Do one of the following:
    • In the New Experience, from your Contentful project, click the gear icon and select Project Settings. Then, on the left side, click Contentful Settings.  
    • In the Classic Experience, go to Projects (select your Contentful project) > Project Settings > Contentful Settings.
  2. Under Content Parsing, select your Contentful space. A list of the localizable fields appears.
  3. For each field, decide whether it requires translation, and if so, which parser should be used for that field.
  4. Click Save.

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.

 

Was this article helpful?