Languages
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.
- Specify a fallback language.
- Provide a short and standardized language codename such as
fr-CH
. - Click Save.
Language codenames
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 codenameFrench_–_Switzerland
.
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.
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:- Linked via a linked items element.
- Inserted into a rich text element.
- Linked using a textual link in the rich text element. In this case, the API response contains only the item’s ID in the
data-item-id
attribute. The rich text element object’slinks
property is empty.
Opt-in fallbacks for linked content
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:- Linked via a linked items element.
- Inserted into a rich text element.
- Linked using a textual link in the rich text element. In this case, the rich text element object’s
links
property contains metadata of the linked content items, such as their types, codenames, and URL slugs.
- 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.