Sync Contentful data with Lokalise.

Dmitry Olenovs avatar
Written by Dmitry Olenovs
Updated over a week ago

This feature is available from the Pro plan and above.

Use this app to sync your Contentful data with Lokalise.

Technical info and known issues

  • Currently we do not support Contentful environments and always revert to using the master branch.

  • We can only sync Text, Symbols, and RichText (plus assets).

  • RichText works properly with bold, italic, and underlined text as well as with superscripts, subscripts, code, links, lists, tables, quotes, and any combinations of the formatting mentioned previously. You can add assets and entries to the field as those are just blocks. To translate those you'll have to import those entries and/or assets separately.

Setting up

We recommend using a separate Lokalise project for Contentful data localization.

To set up the app for your project:

  1. Navigate to the Apps page:

  2. Find Contentful in the list, click Install and then Connect.

  3. Authorize via OAuth2.

Once you authorize, the list of spaces and relevant content types will appear.

If you need to connect a different Contentful account in the future, you should first log out of Contentful on their platform. Then, when you navigate to the Lokalise app page, you will be prompted to enter login credentials for Contentful. At this point, you can provide the details for the new account.

Importing items

This app also supports automated import. You can learn more in the corresponding article.

Your Contentful data will be loaded automatically (you might need to click Reload list to see all the items).

You can find a specific element by using the search box at the top right corner, or use the Filter dropdown to narrow the scope


Select and download the required content types for further localization by clicking Import selected.

All missing languages will be added to your Lokalise project automatically. By clicking the Import selected button, the chosen items will be connected to translation keys in your project. This process will be performed in the background, and you can check its status on the Activity page:

Please note that if you have already connected certain elements to the translation keys, and would like to update contents for these keys, you have to tick the Overwrite updated translations checkbox before importing:

You may also need to enable the Import references option. What does that mean? If you get an issue Field is a reference:

it simply means that this item will not be imported on its own as it does not contain any translatable content. However, if you select this item and enable the Import references option then all records referenced from this field will get imported automatically.

Note on character limits

Lokalise respects character limits set in Contentful. There are two types of limits: user-defined and system-defined (technical). If a field has a user-defined character limit then it will be set for the corresponding translation key on Lokalise. If there's no user-defined limit then technical limit will be applied:

  • Short text field — 255 characters

  • Long text field — 50000 characters

  • Short text, list field — 1000 items per field

  • Rich Text field — 200 000 characters

Performing translations and managing locales

Your translation data on Lokalise

Let's check how the inserted keys look in Lokalise. I have added a sample Contentful course from the The example project, so the appropriate tags have been linked to the inserted keys:

The following tags are added automatically:

  • Contentful — refers to the app itself

  • Content type

  • Entry title

  • Space name

  • Asset — for asset fields only

The key names are generated using following principle:

  • Space ID

  • Entry ID or Asset ID prefixed with asset-

  • Field name

  • String array index (affects only string arrays)

All of these parts are separated with : delimiter.

Note on target languages

Once the necessary data is imported, you can add the required languages and perform translations.

Please note, target languages must be added in your Contentful project as well. You can do this under the Locales settings by clicking the Add locale button.

Once a language is added in the Contentful settings, you have to connect this language to your data. You have to be sure that an added language has the same ISO codes in both Lokalise and Contentful, so they can be successfully synchronized.

Exporting items

This app also supports automated export. You can learn more in the corresponding article.

Once the translations are done, select the items you want to export to Contentful and click the Export selected button.

Choose the languages to export and decide whether you'd like to upload empty translations:

The selected languages will be updated in your Contentful project. This process will also happen in the background.

In the case that any changes were made in your Contentful project, you can update the existing Lokalise keys by importing items from Contentful.

Item validation

Due to limitations in localization fields or incompatible types, not all entries and their fields can be associated with translation keys in Lokalise. If all fields of an entry are deemed invalid, the entire entry is classified as ineligible for linking.

Criteria for a valid item:

  • Non-archived entries — entries must be active; archived entries cannot be modified upon export.

  • Localized fields required only fields that are localized can be imported into Lokalise.

Acceptable entry field types:

  • Text — a field for extended text.

  • Symbol — a field for brief text.

  • RichText— a field for text with formatting.

The Lokalise app facilitates content modification by converting a proprietary document into HTML format, then reverts it back to a RichText document for export.

Certain objects may be set as "localized": false within your Contentful content model, indicating they are not intended for localization. These items will consequently not be linked in Lokalise. Adjusting this parameter in your Contentful model is necessary for enabling localization:

Did this answer your question?