Contentful: Managing references for XTM Cloud projects

Owned by Damian Rozmiarkowski
Last updated: Oct 01, 2024
5 min read

Introduction

By default, XTM Connect – Contentful sends whatever is set to localizable to XTM Cloud, for translation, from the Contentful CMS. Unfortunately, Contentful only permits this to be changed at individual field level for a particular Content model:

2024-10-01 09_06_24-Window.png

What this means is that you need to display the Field options for each field in Edit mode, adjust them individually and specify whether or not the field's contents are to be sent off for translation in XTM Cloud, by selecting the Enable localization of this field checkbox, in the field’s edition panel.

2024-10-01 09_34_29-Window.png

The drawback is that it this does not enable users to select content that is to be localizable within the framework of a specific XTM Cloud project, during the project submission process.

The solution is to use the Manage references feature.

Feature description

Using the Manage references feature, you can specify which referenced content, in relevant entries, is to be translated and which is not to be translated.

  1. To configure the feature, first add either the Reference or Rich text field type (or both) to your Content model, and make them localizable. These are the two field types in which you will be able to add “references”. Do not forget to save the changes.

  1. Next, create your Content item in the Contentful CMS.

  • In the Reference Field Type, you can either add an existing Content item (here: REF 1) or create a new one, based on an existing Content model.

IMPORTANT!

You can only select one Content item for the Reference field type! If you want to include multiple items, you need to add the corresponding number of Reference field types in your Content model.

  • In the Rich text field, there are three elements which act as References that will later be displayed in the Manage references window:

    • Entry (from the Embed dropdown) → Embed another Content item in the Text field (here: REF 2).

    • Inline entry (from the Embed dropdown) → Embed another Content item in the Text field that acts as an inline, that is usually incorporated in the actual text (here: REF 3).

    • Hyperlink (from the top ribbon) → As the name suggests, this is usually a link to another existing Content item, embedded in the Text field. Once you click on it, enter your hyperlink in the Link text field, and select Entry in the Link type section. You can then attach another Content item.

  1. Once you have finished building your Content item, you can start the project submission process. In the XTM Connect Panel, go to the Manage references option and click on it. When you do so, the Manage references popup is displayed.

  1. In the Manage references popup:

  • Select referenced entries that are to be sent for translation in XTM Cloud.

  • Deselect the reference(s) that are not to be sent for translation in XTM Cloud.

  • If the same entry has been referenced multiple times, all subsequent occurrences are marked with the icon. Each occurrence will be selected or deselected for translation.

IMPORTANT!

Contentful limitations on displaying references

If one or more entries that you have selected for translation contain over 1,000 references, they will not be displayed, in Contentful. This means you also cannot display these entries in the Manage references popup and select the relevant ones for translation. However, you can create a project for an entry of that kind and send all its +1,000 references for translation, in XTM Cloud.

If an entry contains fewer than 1,000 references, but they are nested over 10 levels deep, references below the 10th level are only marked with the more label, in the Manage references popup. To see them, you need to display their immediate parent entry. If you create a project for an entry with +10 levels of nesting:

  • without using the Manage references popup to select any references – all references, including the ones below the 10th level, will be sent for translation in XTM Cloud.

  • using the Manage references popup to select some references – only the references that you have actively selected will be sent for translation in XTM Cloud. If you select the 10th level of nesting, references below that level will NOT be sent for translation.

Remember that you can exclude all hyperlinked entries and their references from the translation project scope for all projects created in your XTM Connect – Contentful instance. To do so, contact XTM Support and request our team to make the necessary setting.

  1. Finish making the rest of the translation settings and then send your project to XTM Cloud!