Localization

Contentstack has a sophisticated multilingual capability. It allows you to create and publish entries in any language. This feature allows you to set up multilingual websites and cater to a wide variety of audience by serving content in their local language(s). And, all of this can be done without the need to code.

How Languages Work

Contentstack offers multi-language support, which allows you to create entries in any language of your choice. When creating entries in other languages, they inherit data initially from the fallback language until they are localized.

Therefore, in order to understand how languages work in Contentstack, you will need to first understand data inheritance, fallback languages, and localization.

How Languages Work

Data inheritance

Let’s say you wish to create a multi-language site that serves content in several languages: English (United States), French (France), Spanish (Spain), and Japanese (Japan).

If you have set English (United States) as the master language, you will need to add French, Spanish, and Japanese manually. Learn more about adding a language to your stack.

While adding languages to your stack, you also need to specify the fallback language for each language that you add. Fallback language is the parent from which the given language inherits data from. By default, the fallback for each language is the master language. You can change this while adding languages to your stack. Learn more about fallback languages.

data inheritance fallback_v4.jpg

After first creating an entry in the master language, i.e., English (United States), when you start creating an entry in any of the added languages (e.g., 'French - France), it will show data inherited from the fallback language.

This is an unlocalized entry. Meaning it is still an entry that is fetching data from its fallback language, and a separate entry has not yet been created in the selected language.

This inheritance continues until you localize the unlocalized entry. This is called data inheritance.

Fallback Language

You need to define a fallback language for every language that you add to your stack. Fallback language is the parent from which the given language inherits data from.

For example, you can set English (United States) as the fallback language for French (France), and French (France) as the fallback language for Spanish (Spain). In this case, when you try to create an entry in Spanish (Spain), it will first fetch the content of the entry created in French (France). If no data is available in French (France), it will fetch data from the master language.

So, in essence, fallback language serves as the source content for given language. You can then make changes to the fetched content and localize the entry in the given language.

Note: You cannot cannot create a fallback-language chain deeper than one level for non-master languages. So, in the above example, you cannot set a fallback language (other than the master language) for Spanish (Spain).

If there is no data in the fallback language, it fetches data from the master language.

Localization – Breaking the Inheritance

Localization is the process of making the content local.

We learned in the Data Inheritance section that the unlocalized entries fetch data from its fallback language. You can then translate the content or make the necessary changes and localize it. To localize an entry, save the unlocalized entry. Read more on how to localize an entry.

When you localize an entry, it ceases to fetch data from the fallback language assigned to it. It breaks the inheritance from the fallback language and becomes independent. Therefore, after localizing, the changes made in the master language or fallback language will not be reflected in the localized entry.

As shown in the following diagram, localizing will cause the inheritance present between the master, fallback, and child entries to break, and an independent copy of the localized entry is created that will possess the same format of the master entry or fallback entry, but with different content.

data inheritance fallback_Localized_v4.png

This localized entry is now a separate entity altogether. It will have its own versioning system and publishing queue status.

Once an entry has been localized, you can unlocalize it again anytime. Learn more about unlocalization, here.

Supported languages

Contentstack supports over 160 languages. You can find the complete list of supported languages here.

These languages are either country-specific languages or generic languages. Let’s learn more about these two types of languages.

Country-specific languages

Country-specific languages are languages that are used in a country. A country can have multiple languages, and a language can be used in multiple countries. Hence, we support various combinations of countries and languages. Examples of country-specific languages include ‘English - United States,’ ‘English - United Kingdom,’ ‘French - Canada,’, ‘Spanish - Spain,’ and ‘Spanish - Peru’.

Generic Languages

Generic languages are languages that are not tied to any country or region, such as ‘English,’ ‘French,’ ‘Spanish’ or ‘Chinese’.

With generic languages, you can create content that caters to broader regions or audiences (for example, all English-speaking visitors). Alternatively, you can use generic languages to create base content for similar languages, and then localize content as and when required for country-specific markets.

Language code format

In Contentstack, each supported language is identified by a corresponding code. For country-specific languages, the code comprises two designators (language and country), separated by a hyphen (-). For generic languages, the code contains just one designator (language).

Examples

'en-us' for English - United States
'fr-fr' for French - France
'es-ar' for Spanish - Argentina
'en' for English

Code Standards

For the language designator, Contenstack uses ISO 639-1 Alpha-2 standard.
For the country designator, Contentstack uses ISO 3166-1 Alpha-2 country code.

Now that you know how languages work, let’s understand how to create content in multiple languages.

We have covered limitations of languages at the bottom of this section.

Add a New Language

Let’s have a look at the process of adding a language to your stack.

  1. Go to Settings > Languages. You will see a list of languages that are added to your stack. The master language will be available by default and cannot be removed from this list.
  2. Click on + New Language, and select the required language from the list of available languages.
  3. Make note of the language code.
  4. Select a fallback language for your new language from the list of available languages. Note that fallback language can be selected only from the languages already added to your stack.
  5. Click on Add.

Once the required language has been added to a stack, the Content Manager can add content in the specified language, or create a localized entry.

Note: The Content Manager can view or create content in multiple languages only if the languages are added to the stack by the Admin/Developer.

Localize an Entry

To localize an entry, follow the steps given below:

  1. Go to the page of the entry that you wish to localize.
  2. Select the language using the language selector option located on the top-right corner of the page.
  3. The page that appears is the unlocalized copy of the original entry. Therefore, the content that you see in this page is the content that it has inherited from its fallback language.
  4. Replace the existing content with the content in the appropriate language. Learn more about managing content translation in Contentstack here.
  5. When you click on 'Save,' a new, localized copy of the same entry will be created in the chosen language.

This new copy will then cease to fetch data from its fallback language. So, any changes made to the entry in the fallback language will not have any impact on the localized copy.

Edit a Localized Entry

Localizing an entry does not create a separate item in the main list of entries. Under any given content type, you will only see the list of entries in the master language, that is, English (United States). Edit the required entry, and then select the language of your choice. You will then be able to view/edit the localized entry.

Manage Versions of Localized Entries

Once an entry has been saved in a different language, it becomes independent of the master language or the fallback language. You can modify this data as per your requirement. Modifying and saving your entry multiple times will increment the version count. Therefore, each language entry has a separate versioning system. This enables you to compare your entry with earlier versions, if needed.

Note: The Content Manager can view or create content in multiple languages only if the languages are added to the stack by the Admin/Developer.

You can view information about the localization status of an entry through the ‘Edit Entry’ page of an entry. To do so, click the ‘Entry Information’ tab on the right-hand side panel of the ‘Edit Entry’ page of your entry. Under the ‘Localization Status’ section, you will find a list of all the languages that are part of your stack.

The languages are separated under three sections: ‘Master’, ‘Localized’, and ‘Unlocalized’. Each language is linked to the latest version of the entry in the specific language.

Localization Status - All.png

Let’s understand the different subsections under Localization Status:

  • The ‘Master’ subsection possesses the link to the version of the entry in the master language.
  • The ‘Localized’ subsection displays the languages in which your entry has been localized.
  • The ‘Unlocalized’ subsection displays the languages in which your entry has not yet been localized.

Clicking on any of the above links will take you to the ‘Edit Entry’ page of the localized entry where you can view and manage them.

Manage Translation in Contentstack

Contentstack does not provide translation services but we allow you to integrate with third-party translation providers and translate content. You can use Contentstack Workflows to set up a workflow stage as 'Send to Translation'. When your workflow stage changes to 'Send to Translation', you can trigger a webhook. Once the webhook triggers, use any popular translation tool such as iLangL or WorldServer to initiate the translation process.

Here is a detailed guide to know more about translating content in Contentstack.

Set the Master Language

Master language is the primary language of your stack. When you create a new stack in Contentstack, you will be prompted to set a language as the master language for your stack. You can later add as many languages as you want for the purpose of localization.

For example, a Japanese user can set the master language of the Stack to 'Japanese' and can publish all data in Japanese. The user can later add English (United States) or any other language as an additional language, and publish in these languages, too. Read Localization for more details.

Set Mstr Lang.png

Set Fallback Language

To set a language as the fallback language for another language of your stack, follow the steps given below:

  1. Go to Settings > Languages. You will see a list of all the languages that can be added to your stack. The master language, 'English (United States)', will be available by default and cannot be removed from this list.
  2. Click on + New Language, and select the required language from the list of available languages.
  3. Make note of the language code.
  4. Select a fallback language for your new language from the list of available languages. Note that fallback language can be selected only from the languages already added to your stack.
  5. Click on Add.

If you want to set a language that has already been added to your stack as a fallback language for another language of your stack, follow the steps given below:

  1. Go to Settings > Languages.
  2. From the list displayed on the page, click on any one of the available languages for your stack.
  3. In the ‘Edit Language’ window, select a fallback language from the list of available languages.
  4. Click on Save.

Update the Fallback Language

To update the fallback language for a particular language of your stack, follow the steps given below:

  1. Go to Settings > Languages.
  2. From the list displayed on the page, click on one of the available languages for your stack that has been assigned a fallback language.
  3. In the ‘Edit Language’ window, select a new fallback language from the list of available languages.
  4. Click on Save.

Unlocalize an Entry

Contentstack allows you to unlocalize a localized entry. When a localized entry is unlocalized, it again starts inheriting data from the fallback locale initially. If there is no data in the fallback locale, then the entry inherits content from the master locale entry. The local copy of the entry is deleted, and all the localized content is lost.

To unlocalize a localized entry for a particular language, follow the steps given below:

  1. Open the entry and select the language.
  2. This will open the localized copy of that language.
  3. From the options given at the bottom of the page, select 'Unlocalize' and confirm.

Rename a Language

Any language added to your stack can be renamed. To do so, click on a language under the 'Languages' section. In the 'Update Language' window that appears, change the name of the language by editing the 'Display Name' textbox. For example, 'Spanish (Spain)' can be renamed to 'Spanish News Portal'.

Tutorial Video

In this tutorial, we will see how to provide a custom name to a language.

Custom Language Name.png

Delete a Language

To delete an existing language from a stack, follow the steps given below:

  1. Go to Settings > Languages.
  2. When you hover on any of the languages (except the default language), you will notice an icon with three vertical dots, which is the More Options icon, on the right.
  3. Click on this icon and select the Delete option.

This will delete all the localized entries created for the language. However, if you add the language again, all the localized entries related to this language will be restored.

Note: You cannot delete the master language. However, to delete a fallback language, you need to make sure that it is not being used as fallback language for other language(s).

Manage Permissions

When creating custom roles, apart from assigning rights and permissions, the Owner or the Developer of the stack can assign languages too. This feature enables you to allow/restrict publishing rights to users on specific languages. Read Roles for more details.

Language permissions.png

Limitations

There are certain limitations that we have applied while using fallback language. Let’s understand what they are:

  • Contentstack allows only one level of data inheritance for fallback languages. You cannot add a fallback language (other than the master language) for the language that is already set as a fallback for another language.
  • You can only select one of the languages added to your stack as a fallback language.
Was this article helpful?
top-arrow