Localization of your content is crucial if your company operates in several markets. Each market has a different audience with different expectations, and you want to adjust your content to the needs of each audience.Localizable variants of content items are a versatile way to achieve this. Think through your regional needs to set up localization the right way.
Add a language
In Environment settings,choose Localization.
Click Create new Language.
Type a name of the language, such as French – Switzerland.
When you add a language, its codename is generated from its name, with spaces replaced by underscores. For example, a language named French – Switzerland would have the codename French_–_Switzerland.Language codenames are invisible to content creators. Use the codenames in your apps when retrieving localized content or languages.
Default language
Every project has a default language. The default language doesn’t have any fallback language and can't be deactivated.Give the default language a descriptive name that reflects the actual language of your content.
Non-localizable elements
By default, content elements are localizable, with different values in each language. If you mark an element as non-localizable, the element has the same value in all languages.Non-localizable elements are editable only in the default language. The element’s value in the default language is shared across all languages.
Language fallbacks
Language fallbacks determine how Delivery API behaves when you request content in a specific language while that content isn’t translated. In these cases, Delivery API returns the content you requested in the fallback language instead.If you want to retrieve content items only in a specific language, you need to ignore language fallbacks.
Set up language fallbacks
When setting up language fallbacks for your languages:
You need to specify fallbacks for all languages except the default language.
You can create fallback chains. Example: The language French – Switzerland (fr-CH) falls back to French – France (fr-FR), which falls back to the default language.
Your fallback chains can contain cycles. Example: The language French – Switzerland (fr-CH) falls back to French – France (fr-FR), which falls back to French – Switzerland (fr-CH), creating a cycle. The API returns content in the default language if the requested content isn’t available in any of the two languages.
Delivery API might return linked content even if the linked content isn’t translated to the parent item’s language. This depends on whether your project uses the default language fallbacks or language fallbacks for linked content.
Default language fallbacks
The default language fallback aims for language consistency of the returned content. This means that if a content item is translated to the language you request, but the item’s linked content isn’t translated to the requested language, Delivery API doesn’t return the linked content.For example, suppose you request a content item A translated to Spanish, and item A links to a content item B that isn’t translated to Spanish. The API response for content item A will NOT include the untranslated content item B. This applies when content item B is:
Let us know in chat if you’d like to enable language fallbacks for linked content for your project. With fallbacks for linked content enabled, content creators can quickly see available localizations of linked content.Language fallbacks for linked content aim to independently evaluate fallbacks for every linked content item. If the linked content isn’t translated to the same language as the requested parent content item, Delivery API goes through the language fallback chain for the linked content, starting with the requested language.Language fallbacks for linked content apply when content items are:
To illustrate how fallbacks for linked content work, consider the diagram below, which shows several language fallbacks and two content items.
Requesting item A in language M gets you item A in language L because language M falls back to language L. You get the linked item B in language M because each linked item’s fallback chain is evaluated separately.
Requesting item A in language L gets you item A in language L because item A is translated to language L. You get the linked item B in language J because the fallback chain starts with language L and goes through language K to language J.
Deactivate a language
Deactivating a language unpublishes all content in that language. To avoid loss of content, you can’t delete languages. You also can’t deactivate the default language.You can deactivate a language only if it’s not used as a fallback language for any other language.To deactivate a language:
In Environment settings, select Localization.
Select the language you want to deactivate.
Click Deactivate.
Manage user access to localized content
If your team manages content in multiple languages, you can allow each content creator to access only the languages relevant to them. For example, creators working with Russian content don’t need access to Japanese content. This helps your team members avoid distractions and better focus on their work.
In Environment settings, select Users.
Click the user you want to edit.
In the Language field, select the languages this user needs to work with.
Click Save.
You can also set languages available to users in bulk when inviting them to your project.When you allow users to access only certain languages, they won’t see any content in other languages.
Localization strategy plays a significant role in the regions you operate in. It enables you to adapt your content to suit each region’s languages, cultures, and traditions.
Use short machine-readable codenamesWe strongly recommend that you use short, easily identifiable, and machine-readable codenames for your languages. For example, you can specify language codenames based on the IETF or one of the ISO-639 standards.
Deactivated languages do not count towards your subscription limit.
Environment settings, choose Localization.
. All rights reserved.
