Skip navigation

Set up your languages

8 min read
Download PDF

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.

Table of contents

    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.

    Adding lanugages for your Kontent project

    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.

    Use short machine-readable codenames

    We 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.

    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. If the content isn't available in any of the two languages, the Delivery API returns content in the default language.

    Delivery API might return linked content even if the linked content isn't translated to the parent item's language. This depends on the language fallback behavior enabled for your environment.

    Default language fallback behavior

    The default fallback behavior 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 that's translated to Spanish, and the 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:

    If you need fallbacks for linked content, you can opt-in for an alternative language fallback behavior.

    Opt-in language fallbacks for linked content

    The alternative fallback behavior aims for independent evaluation of language 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 the item A in language M gets you the item A in language L because language M falls back to language L. You get the linked item B in language M because the fallback chain is evaluated separately for each linked item.
    • Requesting the item A in language L gets you the 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.

    Simplified illustration of languages J, K, L, and M, and two content items A and B translated to different languages.

    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.

    1. In Environment settings, select Localization.
    2. Select the language you want to deactivate.
    3. Click Deactivate.
    Deactivating a language in Kontent.

    Deactivated languages do not count towards your subscription limit.

    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 a user to access only certain languages, they won't see any content in other languages.

    What's next?