Skip to main content
Contentful

Easily sync your Contentful content with Lokalise.

Ilya Krukowski avatar
Written by Ilya Krukowski
Updated over a month ago

This feature is available from the Pro plan and above.

The Contentful app allows you to sync content from Contentful, a popular headless CMS that helps manage and distribute content across multiple digital platforms.

Setting up

Create Lokalise project

If you haven’t already, create a Marketing and support project in Lokalise.

Enter a project name, select the base and target languages, and choose Contentful from the Content integration dropdown.

Click Create project to finalize the setup.

Installing the app

Open your Lokalise project, go to the Content management tab, and click Install. Grant Lokalise access to sync with Contentful.

Once authorized, a list of spaces and relevant content types will appear.

If you need to connect a different Contentful account in the future, first log out of Contentful on their platform. Then, when you navigate to the Content management, on Lokalise you’ll be prompted to enter new Contentful login credentials.


Importing items

This app supports automated import. More details can be found in the corresponding article.

Your Contentful data will load automatically, but you may need to click Reload list to refresh the content. To find specific elements, use the search box in the top right corner or apply filters using the Filter dropdown.

Select the content types you want to import and click Import selected.

Missing languages will be automatically added to your Lokalise project. Once imported, the selected items will be connected to translation keys, and the process will run in the background. You can track its progress on the Activity page.

Updating existing translations

If some elements are already linked to translation keys and you want to update their content, enable Overwrite updated translations before importing.

Importing references

If you encounter the Field is a reference issue, it means the item itself does not contain translatable content but references other fields.

To import these references, select the item and enable Import references. This will automatically bring in all linked records.

Character limits

Lokalise respects Contentful's character limits, which can be either user-defined or system-defined. If a user-defined limit exists, it will be applied to the corresponding translation key in Lokalise. Otherwise, the system-defined limit applies:

  • Short text field – 255 characters

  • Long text field – 50,000 characters

  • Short text, list field – 1,000 items per field

  • Rich text field – 200,000 characters


Performing translations and managing locales

Your translation data on Lokalise

Once content is imported from Contentful, each inserted key will have automatically assigned tags to help with organization.

The following tags are added automatically:

  • Contentful – Identifies content coming from the Contentful app

  • Content type – Specifies the type of content (e.g., article, product, course)

  • Entry title – Refers to the title of the imported entry

  • Space name – Shows the Contentful space from which the content was pulled

  • Asset – Applied only to asset fields

Key names are generated using the following structure:

  • Space ID

  • Entry ID or Asset ID (prefixed with asset- for asset fields)

  • Field name

  • String array index (applies only to string arrays)

Each part is separated by a : delimiter.

Note on target languages

Once the necessary data is imported, you can add target languages and begin translations. However, target languages must also be added in Contentful to ensure proper synchronization.

To do this, go to Locales settings in Contentful and click Add locale.

After adding a language in Contentful, you must ensure that its ISO code matches the corresponding language in Lokalise. This consistency is required for successful synchronization.


Exporting items

This app supports automated export. More details can be found in the corresponding article.

Once translations are complete, go to the Content management tab in Lokalise, select the items to export, and click Export selected.

Choose the languages to export and decide whether to upload empty translations. The selected languages will be updated in your Contentful project, and the process will run in the background.

If changes were made in Contentful, you can update existing Lokalise keys by reimporting items from Contentful.


Item validation

Due to limitations in localization fields or incompatible types, some entries and fields may not be linked to translation keys in Lokalise. If all fields in an entry are invalid, the entire entry is classified as ineligible for linking.

Criteria for a valid item:

  • Non-archived entries – Only active entries can be modified. Archived entries cannot be updated during export.

  • Localized fields required – Only fields marked as localized in Contentful can be imported into Lokalise.

Supported field types:

  • Text – Used for extended text fields.

  • Symbol – Used for brief text fields.

  • RichText – Supports formatted text. Lokalise converts proprietary Contentful documents into HTML format for modifications and then reverts them back to RichText for export.

If an object in Contentful is set as localized: false, it will not be linked in Lokalise. To enable localization, update this setting in the Contentful content model.


Technical information and known limitations

  • The app does not currently support syncing with Contentful environments, so it defaults to the master branch.

  • Supported field types for syncing: Text, Symbol, RichText, and assets.

  • RichText fields support common formatting, including bold, italic, underline, superscripts, subscripts, code, links, lists, tables, and quotes. These formatting styles can also be combined.

  • Assets and entries can be added as blocks within RichText fields, but translating them requires a separate import of the related entries or assets into Lokalise.

Did this answer your question?