Contentful: Entry-level localization

Owned by Damian Rozmiarkowski (Unlicensed)
Last updated: Jan 03, 2024
10 min read

Introduction

Entry-level localization is an additional feature that enables localized content to be imported as new, individual content items instead of updating an existing content item with a new locale. The feature allows for translating particular content items in a specified way, contrary to a standard XTM Connect – Contentful localization flow, which can be described as “field-level localization”, in which we decide on the fields that are to be localizable. Entry-level localization applies to situations when, for instance, the client intends to have different content and assets for each of their target languages.

This feature can be only enabled by the XTM International Support team, in the Clients tab of the Contentful administrator panel (to which you do not have access). They do so by selecting the Enable entry-level localization option when editing a particular client.

If the feature above is enabled, the Entry-level localization settings section will be displayed in the Settings tab in your Contentful integration.

How does it work?

General rules

Please note the following: which content types are selectable in the options available in the Entry-level localization settings section depend on whatever is first selected in the Content Models section.

Furthermore, a particular content model that has been selected once, in either of the fields, cannot be selected again in another field, preserving the logic of the feature.

Description of options with examples

For the purpose of demonstration, below, we need to distinguish between two types of items: content models and content items. They will be marked in orange and green, for more clarity.

Content types are also called content models.

Each of the fields serves a specific purpose:

  • Content types to be translated as entry-level localization → In this field, you select the content models that will use the entry-level localization feature. Each one is also the content model which hosts the content item, in Contentful, that we will pick up for translation in XTM Cloud. At this point, the content that is based upon the selected content model becomes non-localizable and is not sent off to XTM Cloud, but all the content that is put in Reference fields, and assets that it contains, are localizable and will be sent. For this reason, make sure that the selected content model contains at least one reference field containing further content (in this case, an Article Item) whose own content will be handled in accordance with how you set it up in the two remaining sections. For demonstration purposes, our primary content model is called Sajzik MAIN PAGE.

  • Update existing referenced content entry when translation is imported → In this field, you select content models whose content (Reference Item 1) is a reference to the content item (Article Item) that, in turn, is applied to the main item (Main Item) as a reference as well. This particular content (Reference Item 1) IS localizable and will be sent off to XTM Cloud. Once the translated content is imported back to Contentful, the existing item (Reference item 1) will be updated with a new locale and it will be linked to a newly created target version of Article Item: (Pozycja Artykułu). In other words, this referenced content (i.e. the content which is based upon the particular content model) will use the default flow of the connector, as it has been so far. For demonstration purposes, this content model is called Referenced content TO BE UPDATED.

  • Create new referenced content entry when translation is imported → In this field, you select content models whose content (Reference Item 2) is a reference to the content (Article Item) that, in turn, is applied to the main item (Main Item) as a reference as well. This particular content (Reference Item 2) IS NOT localizable but will be sent off to XTM Cloud, due to the way that the option concerned works. Once the translated content is imported back to Contentful, the existing item (Reference item 2) will not be updated with a new locale but its target version (Pozycja Odniesienia 2) will be created in the form of a new separate content item. It will also be linked to its corresponding target version of a parent item Pozycja Artykułu but it will not be linked to the original parent item (Article Item). In other words, this referenced content (i.e. the content which is based upon the particular content model) will use a new flow in XTM Connect – Contentful. For demonstration purposes, this content model is called Referenced content TO BE RECREATED.

Sample use case

Based on the brief description of the feature in the preceding subsection, let’s try to visualize the flow with a real example.

Content items

Below you will find a description of all the input content items in Contentful that were used in our sample flow. Again, this is just an example of what your content might look like and how it might behave, when the entry-level localization feature is used.

Main Item

The Main Item is the host/parent content item for all the content that is linked to it. It acts as a sort of layout and is not localizable itself. It is the Main Item that we select and send to XTM Cloud. Also, it has a reference field that refers to the second item: the Article Item. This is what the Main Item looks like in Contentful:

The Main Item is based on a content model called Sajzik MAIN PAGE which is fully localizable and is applied in the Content types to be translated as entry-level localization field, in the entry-level localization settings.

IMPORTANT!

The Reference field must be localizable in the Sajzik MAIN PAGE content model – one that is selected in the Content types to be translated as entry-level localization field in the entry-level localization feature.

Other fields, on the other hand, do not have to be localizable since they are not sent off to XTM Cloud anyway.

For the latter reason, when this item is sent to XTM Cloud for translation, the only field that will actually be sent is the Reference (that links the Article Item).

Article Item

The Article Item is directly linked to the Main Item.As you can see, this is also the item that contains further references, in the Reference fields. Their content will be handled differently according to your entry-level localization setup: Reference Item 1 and Reference Item 2. This is what the Article Item looks like in Contentful:

The Article Item is based on the content model called Article PAGE. Note the structure of this content model, which is entirely non-localizable. However, due to the fact that its content item (the Article Item) is linked to the Main Item, whose content model (Sajzik Main PAGE) takes part in the entry-level localization flow, Article Item is sent to XTM Cloud in its entirety.

Reference Item 1

Reference Item 1 is our first item that is directly linked to Article Item, in the Reference field. This is what Reference Item1 looks like in Contentful:

Reference Item 1 is based upon a content model called Referenced content TO BE UPDATED, which is applied in the Update existing referenced content entry when translation is imported field in the entry-level localization settings. For this reason, its content (Reference Item 1) will follow a default XTM Connect – Contentful localization flow. Of course, you must ensure that you identify all the localizable fields within that content model.

Reference Item 2

Reference Item 2 is our second item that is directly linked to Article Item, in the Reference field. This is what Reference Item2 looks like in Contentful:

Reference Item 2 is based upon a content model called Referenced content TO BE RECREATED, which is applied in the Create new referenced content entry when translation is imported field in the entry-level localization settings. For this reason, its content (Reference Item 2) will follow a new localization flow that is offered by XTM Connect – Contentful. Note that this content model should not contain any localizable content items, to prevent Reference Item 2 from being updated with new locales. All the content will be sent to XTM Cloud nonetheless.

Localization flow

Considering the content items and the entry-level localization setup described in the previous sections, let’s see how the whole translation process will proceed.

  1. We send the Main Item (and the only Main Item) to XTM Cloud.

  1. In XTM Cloud, we can see three source files in a newly created XTM Cloud project: Article Item, Reference 1, Reference Item 2.

  1. Let’s translate and finish Reference Item 1 first. Once done, we can see that it has changed its status accordingly, in the Translation queue, and is about to be returned automatically.

As a result, it is imported back to Contentful and the existing item (Reference item 1) is updated with a new locale – a default XTM Connect – Contentful localization flow.

  1. Now, let’s translate and finish Reference 2. We will see something interesting in the Translation queue. Once done, we can see that the content item has changed its status to what appears to be a failed status. The item in question cannot be imported in any way.

As the warning prompt suggests, Reference 2 is a part of the entry-level localization flow which means that it does not follow a standard XTM Connect – Contentful localization flow. The content item cannot be imported due to the fact that the target version of Article Item (Pozycja Artykułu), to which the target version of Reference 2 will be linked (Pozyzja Odniesienia 2), has not yet arrived at Contentful. In other words, all the parent content items that contain Reference 2 need to be finished and imported back to Contentful first.

  1. Finally, let’s translate and finish Article Item. Once done, we can see that it has changed its status accordingly, in the Translation queue, and is about to be returned automatically, immediately followed by Reference 2.

As a result, we can see new target versions, in the form of separate content items, in Contentful.

  • Pozycja Odniesienia 2 → This is a target version of Reference Item 2, that was created in the form of a separate content item in Contentful (instead of being inserted in the original content item – Reference Item 2), according to the entry-level localization flow.

IMPORTANT!

Note, that the source language of such content items is still the language chosen as the default language in the settings for a particular environment, in Contentful (Settings → Environment settings → Locales). Therefore, even though Pozycja Odniesienia 2 is just the Polish language version of its original content item (Reference Item 2), which was written in English, the source language for Pozycja Odniesienia 2 is still English in Contentful.

  • Pozycja Artykułu → This is a target version of the Article Item, created in the form of a separate content item in Contentful (instead of being inserted in the original content item – Article Item), according to the entry-level localization flow.

As you can see, it references two other content items, in the Reference fields: Reference Item 1 (which consists of both the source text and translation, since it followed a standard XTM Connect – Contentful localization flow) and Pozyzja Odniesienia 2 (which is a newly created content item, originating from Reference 2, and only contains the translation).