Set up your project 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, 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.

Add a language

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

1. From the app menu, choose Project settings.
2. Under Environment settings, choose Localization.
3. Click Create new Language.
4. Type a name of the language, for example, French – Switzerland.
5. Select a fallback language.
6. Provide a unique codename for the language, for example, fr-CH.
7. Click Save.

You can reorder your languages by dragging them.

Language codenames

When you add a language, its codename is generated from its name, only with spaces replaced by underscores. The codename for a language named French – Switzerland would be French_–_Switzerland. 

You can edit the codenames and we recommend that you use short and easily identifiable codenames for your languages, such as fr-CH or en-US. See a list of standard codenamesOpens in a new window.

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

• Content items linked in a rich text follow fallbacks independently.
• Content items in a linked items element are not included in the response if they're not available in the requested language.

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. From the app menu, choose Project settings.
2. Under Environment settings, choose Localization.
3. Click the language you want to deactivate.
4. Click Deactivate.

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. From the app menu, choose Project settings.
2. Under Project settings, click Users.
3. Click a user you want to edit.
4. In the Language field, choose languages this user needs to work with.
5. 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?

• Start translating your content items.
• Set up roles to allow some of your users to manage localization.
• Retrieve localized content via API to deliver native experiences.
• Learn how to switch between languages when working with content.