Languages

Add a language

1. In Environment settings, choose Localization.
2. Click Create new Language.
3. Type a name of the language, such as French – Switzerland.
4. Specify a fallback language.
5. Provide a short and standardized language codename such as fr-CH.
6. Click Save.

You can reorder your languages by dragging them.

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 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:

• 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’s links 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.

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:

1. In Environment settings, select Localization.
2. Select the language you want to deactivate.
3. 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.

1. In Environment settings, select Users.
2. Click the user you want to edit.
3. In the Language field, select the languages this user needs to work with.
4. 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.