Skip navigation

Set up your project languages

David Klement

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, whether they're languages or regions.

Variants of content items are a versatile way to achieve this. Think through your regional needs to set up localization right.

Table of contents

    Add a language

    Add languages to your project so you can localize your content items.

    1. In Project settings, select Localization under Environment settings.
    2. Click Create new Language.
    3. Type a name of the language, for example, French – Switzerland.
    4. Select a fallback language.
    5. Provide a short and standardized codename for the language, for example, fr-CH.
    6. Click Save.

    You can reorder your languages by dragging them.

    Adding lanugages for your Kontent project

    Every project has a default language

    Give the default language a descriptive name that reflects the actual language of your content.

    Language codenames

    When you add a language, its codename is generated from its name, only 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 standardsOpens in a new window.

    The language codenames are invisible to content creators. You'll use the codenames in your apps when getting localized content or languages.

    Language fallbacks

    Every language has a fallback language with the exception of the default language. A fallback language is used when requested content doesn't exist in the specified language.

    For example, when you request a Spanish variant of a content item that's not available in Spanish, the Delivery API returns the item in the fallback language of Spanish.

    To retrieve content items in a specific language only, see ignoring language fallbacks.

    Guidelines for language fallbacks

    • You can create fallback chains. For example, fr-CH (French – Switzerland) can fall back to fr-FR (French – France) which can fall back to the project's default language.
    • Your fallback chains can contain cycles. For example, fr-CH can fall back to fr-BE (French – Belgium) while fr-BE can fall back to fr-CH. If a content item isn't available in any of these two languages, the Delivery API returns it in the default language.
    • Every language except the default one must have a fallback language.

    Exceptions to language fallbacks

    Let's say you request a content item in Spanish and the item links another content item that's not translated to Spanish. The Delivery API will NOT include the untranslated item if it's:

    • Linked using a linked items element
    • Inserted into a rich text element (using  > )

    However, if it's linked in text using > Content item, you'll get just the ID of the content item regardless of its translation status.

    Deactivate a language

    If you don't need a language anymore, you can deactivate it. To ensure that no content is lost, project languages can only be deactivated, not deleted. You can't deactivate the project's default language.

    Deactivating a language will unpublish all content in that language. All languages with a fallback to the deactivated language will use the project's default language as their new fallback.

    To deactivate a project language:

    1. In Project settings, select Localization under Environment settings.
    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.

    Let your users work only with the languages they need

    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 probably don't need access to Japanese content. This helps your team members avoid distractions and better focus on their work.

    1. In Project settings, select Users.
    2. Click the user you want to edit.
    3. In the Language field, select languages this user needs to work with.
    4. Click Save.

    You can also set languages available to users in bulk when you're 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?