Contentful Integration

This integration allows someone to synchronize their Contentful content and completed translations between Contentful and Transifex

Nina avatar
Written by Nina
Updated over a week ago

The Contentful integration lets you synchronize your content and completed translations between Contentful and Transifex. Use this integration so that your localization team can leverage most of Transifex's services while translating your Contentful space.

šŸ“Note: Transifex's Contentful integration is available as a paid add-on.

Please contact us to enable Contentful for permanent usage or a 15-day free trial.


Configuring Contentful space

The Contentful space must be configured to support multiple languages and enable localization. By default, your Contentful space only supports one language. You have to configure it to support additional languages.

Enable Locales

šŸ“Note: You will need to have Administrator Rights.

To enable additional locales, you will need to log into your Contentful space, then:

  • Open Settings -> Locales and click Add locale

  • In the Select a locale field, select the required locale from the drop-down menu.

šŸ’”Tip:

  • Optional: Select a fallback language to be displayed if a translation in the selected locale is unavailable.

  • Optional: If you have required fields in your content type, select the Allow empty fields checkbox, or else your editors cannot publish content without adding a translation for the required field.

  • When satisfied, click the Save button. Your locale will be added to your space.

šŸ“Note: You can repeat the same process for all target languages you want to translate your content into.

Enable Fields For Locales

Once locales are added to your space, the next step is to enable them for fields.

šŸ“Note: The Contentful integration supports only field-level localization.

To enable locales for fields:

  • Login to your Contentful space and go to the Content model tab.

  • Go to the required content type and open it. The content type editor is displayed.

  • Click Settings for each field you will localize.

    1. Under the "Settings" tab, select the Enable localization of this field checkbox under the "Field options" area.

    2. Click Confirm to save changes.

  • Click Save to apply changes to the content type.

šŸ“Note: All content can be transferred in Transifex if the respective entry contains localizable fields. If all fields of an entry are non-localizable, no resources will be created/updated in Transifex. You will see a log entry with the CTF_ prefix in the activity log.


Installing Contentful integration

šŸ’”Tip: To connect your Contentful and Transifex accounts, you must be a Transifex project maintainer or administrator.

Follow the steps described below to connect your Contentful and Transifex accounts:

  • Navigate to ā€œhttps://app.transifex.com/ā€œ

    1. Log in to your Transifex account. This will take you to the Transifex Dashboard.

    2. Go to your project Settings > Integrations > Contentful> Install

    3. You will be redirected to the integrationā€™s authorization page, where:

      1. First, it is necessary to grant permission for the integration to perform modifications in Transifex on your behalf.

      2. Next, it is required to authorize the integration in your Contentful account. To do this, select the Authorize button and log into your Contentful account (if you haven't already done so).

      3. Click on Authorize Transifex Integration.

      4. Click again on the Authorize button. You are now ready to link a space.
        ā€‹


Linking a Transifex Project with a Contentful Space

šŸ’”Tip: Clicking on the Link your space button will launch the Contentful Integration wizard to facilitate the setup.

  • Click on the Link your space button. On the wizard's first step, select the Contentful space to sync with the project.

šŸ“Note: If you have configured multiple environments in your Contentful space, you can select any of them to link it with a Transifex project, after you have selected a space. Be aware though, that unlinking one environment and linking another in the same project does not affect the resources already synced in Transifex. If you want to change environments, it's best that you delete first all previously synced resources.

  • Click Next to choose the Contentful content you want to sync with Transifex.

šŸ“Note

  • You need to ensure that the Transifex project's source language matches the default locale of the Contentful Space you are linking with. Please be aware that the default locale in Contentful is 'en-us' (English United States).

  • The content currently synced between Contentful and Transifex includes Entries and Assets based on the respective Content Types and their linked Field Types. The supported field types are Text, Rich Text, and Reference. The later field type is only available with a Contentful subscription in the Enterprise plan.

You can view localizable content and search across Entries in the wizard interface shown.

  • An Entry may or may not contain one or more Assets.

  • Their number will be listed next to each Entry for information purposes.

šŸ“Note: An Asset always has a title and a description apart from the binary content (e.g., a picture, a video, etc.). The Contentful integration only pulls the title and description for translation, not the binary content!

  • When you identify Contentful content you want to sync with your Transifex project, mark it by checking the box on the left of the Entry title.

    • Any selections you have made are persistent, so you can keep searching and navigating on the displayed content list without losing your selections.

    • You can learn more about the functionality of this wizardā€™s step by checking the respective section to Choose content for translation below.

  • When you are done selecting your content, click Next to move to the final step of the setup wizard. This is where you will define how the syncing between Transifex and Contentful will happen (you can find more details here).

  • When you finish this setup step, click the Save & Sync button to sync content from Contentful to Transifex.

šŸ“Note: Some steps described above are also accessible when updating the integration settings. Check the Synching content from Contentful to Transifex and Editing synchronization settings sections below for more.

Choosing Content for Translation

In this subsection, we are expanding on the full functionality provided in the content selection step of the wizard.

In this step, you will see information about Contentful content found in the space you have linked to the specific Transifex project.

For each Entry in the list, you can see some additional information depending on the sync status for that content:

  • The title of the Entry. If there is no title, ā€œUntitledā€ is used instead.

  • Checked if the content is selected to sync between Contentful and Transifex; unchecked otherwise.

šŸ“Note: If an Entry contains References and it is selected, the respective References will be selected automatically.

  • The Content-Type that each Entry is based on

  • The space environment that the Entry was found in

  • The number of Assets contained in the respective Entry

  • The content status in Contentful (draft, published, archived).

  • If already published content is changed in Contentful, its status will be ā€œdraftā€ in the integration.

  • A Last Contentful update field holding the date of the last update of the content in Contentful

šŸ“Note: If you uncheck a Reference but keep the parent Entry checked, then the Reference will not be synchronized in Transifex, yet its parent will continue to be in sync. If, on the other hand, you uncheck the parent Entry and keep the Reference checked, the Reference will continue to be synchronized in Transifex, whereas its parent will not.

āš ļøWarning: If you uncheck an already synced Entry, the associated resource will no longer be synced with the corresponding Entry in Contentful.

Filtering content

To filter the content displayed in the list, choose the drop-down to select the content type and type in the search box:

  • Filtering is available for Entries only.

  • The content list can be filtered by pressing either the Enter key or the Search button.

    • Search will look in the title and content for Entries.

    • You can use double quotes around the search terms to make searching more focused.

    • To clear out a search term, delete it and press the Enter key or Search button (alternatively, you can use the X icon in the search area.)

  • Items in the list have pagination.

  • You can change the page size using the drop-down displayed under the content list and navigate through the different pages using the left and right arrows located in the same area under the content list.

Importing source content options

During the final step of the configuration wizard, labelled "Content Synchronization options," you will find the following import content options to select from:

Import newly published content automatically

You can opt for automatically importing any new content created in Contentful, provided that:

  1. The content is published in Contentful.

  2. The content contains localizable fields.

Import updated published content automatically

You can opt to automatically bring any source updates in Contentful for content already synced with Transifex as long as it has been published in Contentful.

If the updated content contains references to other Entries or Assets, these will also be imported.

Fetch Initial Translations from Contentful

All Contentful content synced for the first time with Transifex will also sync any existing translations into the newly created resource as long as the option "Fetch initial translations from Contentful" is enabled.

  • If the option is unchecked, we always ignore translations found on Contentful and never send them to Transifex.

  • If the option is checked, it works as follows:

    • Every time content is synced from Contentful to Transifex, the integration checks each resource/language separately and:

      • If the language for this resource is empty (there are zero translations), we take the translated content from Contentful and send it to Transifex.

      • If, on the other hand, there is even one translation on Transifex for this resource/language, we consider Transifex to be the source of truth, so we ignore the Contentful translations for that resource/language and do not send them to Transifex.

  • This includes content detected during the integration setup or new content detected on a subsequent sync.

  • Any syncing actions on content with a resource in Transifex will not include translations updated on Contentful.

    • If any translations are present in Transifex's resources, Transifex is considered the source of truth, and any translations in Contentful will be ignored.

      • A relevant warning should be displayed for the specific task in the activity logs.

Exporting localized content options

Syncing localized content back to Contentful can work automatically per Entry in each target language. The integration offers three possible options for automatically sending localized content back to Contentful:

  • 100% translated or updated (for 100% translated)

  • 100% reviewed or updated (for 100% reviewed)

  • 100% proofread or updated (for 100% proofread)

Depending on the setting selection, this will apply to individual Entries as they are localized in each target language. For example, once an Entry is fully translated into French, the French entry will be sent to Contentful. If the Chinese translation of the article is not fully translated, it will not be sent to Contentful.

All the sync options are triggered when the language reaches 100%. This means that if, for example, an already reviewed language is edited, the updated reviewed translation will be sent to Contentful automatically.


Translating content in Transifex

Each Entry synced from Contentful to Transifex will create a resource following the Contentful title name.

  • For example, if you have two blog entries in Contentful titled ā€œWhat Iā€™ve learned so farā€ and ā€œFew tips for installing the appā€, syncing them to Transifex via the integration, you will get two resources with the same names:

    • ā€œWhat Iā€™ve learned so farā€

    • ā€œFew tips for installing the appā€

  • If the Entry has no title, the resource name is constructed using the prefix CTF_entry_ followed by the Entry ID. The resource slug is always the Entry ID, preceded by the same prefix.

šŸ“Note: All fields contained in each entry, as long as they are of type Text, Rich Text, Reference, or Asset, will automatically form the source strings in each Transifex resource.

Regarding assets/references, separate resources are created at Transifex.

  • For example, if we have a parent entry A with one reference entry and one asset

    • Three resources will be created into Transifex:

      • One for the parent entry

      • One for the reference entry

      • One for asset

In the case of Rich Text, these fields will result in separate strings. If a Rich Text field contains References, each reference will also be imported into Transifex as a separate resource.

Once your content is inside Transifex, you can start translating it or manage the localization process as appropriate.

šŸ“Note: In case an Entry/Reference is set with flag localized=Off in all of their fields, then when fetching to TX:

  • You will see the entry with the CTF_ prefix in the Logs UI screen.

  • In the ā€˜Manage contentā€™ pop-up screen, you will see the title of the entry/reference (coming from Contentful).

  • In the TX resources page, the entry/reference won't exist.


Syncing content from Contentful to Transifex

You can import content from Contentful in two ways:

  • Manually

    Syncing content from Contentful to Transifex happens upon saving or updating the integration settings in the integrationā€™s UI (Project Settings ā†’ Integrations ā†’ Contentful ā†’ Manage).

    When a syncing process is initiated, you will be able to see that syncing is in progress in the activity log. This process could take some time, depending on the number and size of the syncing files.

    If you want to add new content for synchronization or remove existing content, click Manage Content in the project integrationā€™s UI to show the Integration Wizard and check all the new content you want to sync. Then click the Save & Sync button to start a new sync process.

  • Automatically

    You can select to automatically import any new published Entries or any updates made on already synced published Entries from Contentful. Click on the ellipsis in the integration's UI and select Edit Settings. You can then select one or both of the following options as described here:

šŸ“Note on Content Updates: If you edit existing content in Contentful and you have not selected to automatically update it in Transifex, or this content is still in draft mode, the changes are not automatically synched to Transifex. You will need to go to the integration wizard and click on Manage Content; once in the wizard, you will need to de-select the content item, click on "Save & Sync", and then re-select it and click "Save & Sync".

šŸ“Note on HTML Translation integrations: Remember that the integration works on top of the HTML file format, which is quite unstructured. When syncing translations from Contentful to Transifex, please pay attention to differences in structure and order of translations as it might affect the mapping of translations to the proper strings. For more details, check Translating HTML Content and HTML.

šŸ“Note on Asset Media: Keep in mind that in case of an Asset (media) - part of either an Entry or Reference - Contentful allows you to create both source and translation texts for this asset. In that case, only the resource for the source (with the respective translation) will be synchronized with Transifex.

šŸ“Note on References from Contentful: When pulling references from Contentful, which can be either entries or assets (media), take into account that the maximum depth of nested references (e.g., ref1 -> ref2 -> ā€¦ ref10) is 10. On a deeper level than that, any other reference will be ignored entirely by Transifex without any warning.

šŸ“Note on Same Title Entries in Contentful: In case two entries in Contentful have the same title (but different content types, and they are localizable), then in the activity logs, you will see two identical entries.


Syncing manually content from Transifex to Contentful

There is an option to send localized content to Contentful manually without waiting for a resource to be 100% translated or reviewed (Project Settings ā†’ Integrations ā†’ Contentful ā†’ Manage ā†’ (ellipsis) Manual Sync).

By clicking on Manual Sync, a modal will appear requesting the threshold localization percentage that Transifex will check on all your project's resources.

All target languages localized above that threshold will be synced with Contentful using the Sync content options you have set up for the integration. For example, suppose you had set up Contentful to sync 100% translated resources. In that case, the manual process will identify all target languages whose translation percentage is equal to or above the threshold percentage you set on the modal and sync all content back to Contentful.

šŸ“Note: Syncing less than 100% translated content to Contentful might result in parts of the content being in the original language for that Entry. This issue will be eliminated when that content is fully translated in Transifex and synced back to Contentful.


Editing synchronization settings

As your project evolves, you may end up wanting to change the workflow of importing source content from Contentful and exporting localized content back to Contentful.

To edit your options:

  • Navigate to the Projectā€™s settings -> integrations tab.

  • Click on the Manage link under the Contentful section to load the integrationā€™s UI

  • Click on the ellipsis and select Edit Settings.

šŸ“Note: While the interface used for editing is the same as that used during the initial setup, you will only be able to change options related to automatically synchronizing content with Contentful.


Activity log

To check the synchronization results, either from Transifex to Contentful or from Contentful to Transifex, you must load the integrationā€™s UI, where all events that happened are logged in chronological order (the most recent ones appear first).

These logs allow you to identify any potential issues with particular Entries that failed to sync or contained Assets with no localizable content. Go to your project settings > integrations tab, and click on the Manage link under the Contentful section to load the integrationā€™s UI.


Uninstalling the Contentful integration

To uninstall the Contentful integration from your project, you have to follow the steps below:

  • Go to your project settings > integrations, click on the ellipsis, and select Remove integration.

  • Click on Remove to confirm the action.


šŸ’”Tip

Looking for more help? Get support from our Transifex Community Forum!

Find answers or post to get help from Transifex Support and our Community.

Did this answer your question?