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

    Enrich language names with flags

    Make languages in your project easily recognizable by prepending their names with corresponding flags. You can copy the flag characters from this list, for example.

    Flags in language names provide better user experience

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

    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 except the default one has a fallback language. When you request content in a certain language and the content isn't translated to that language, Kontent returns the content you requested in the fallback language instead.

    Let's have an example where Spanish falls back to English. When you request certain content in Spanish but that content isn't translated to Spanish, you'll get it in English instead because that's the fallback language of Spanish.

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

    Every project has a default language

    The default language doesn't have a fallback language and can't be deactivated. 

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

    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.

    Define access to languages

    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?