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.

Note: This logic only applies to entry creation and does not apply to entry publishing. Read more about how to publish localized/unlocalized entries here.

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.

Note: This logic only applies to entry creation and does not apply to entry publishing. Read more about how to publish localized/unlocalized entries here.

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.

Non-localizable Field

Contentstack provides the option to mark any field of your content type as ‘Non-localizable’. This feature is useful for cases where you do not want content managers to translate the value of a field for localized entries. An example of this is a URL field which should remain the same in all localized entries or an image that is common for all localized entries.

When you mark a field as ‘Non-localizable’, you can add data to that field only in the master language entry. The field cannot be edited (or translated) in the localized versions of the entry.

Note: Editing the data of a ‘Non-localizable’ field in the master-language entry will automatically update the field data in all the localized versions of the entry and the version number of the localized entries will increment by 1.

How to set a field as ‘Non-localizable’

If the Non-localizable option is enabled for a field, it restricts editing (or translation) of that field in localized entries. Non-localizable fields can be edited only through the master-language entry, and its value is reflected in the localized entries.

To mark a field as ‘Non-localizable’, follow the steps given below:

  1. In your content type, click on the field that you want to set as ‘Non-localizable’, for example, in your News Article content type, you have set the Date field as the non-localizable field.
  2. In the Field Properties section on the right, under Options, check the Non-localizable option.
  3. Click on Save and Close.

Once you do this, open the entry in the master language. Enter the data for all the fields, including the ‘Non-localizable’ field. Save the entry.

Now, select a language using the language selector located on the top-right corner of the page. This will open the unlocalized copy of the entry. You will find that the ‘Non-localizable’ field has been disabled.

Entry page - Non-Localizable checkbox.png

Points to remember about the ‘Non-localizable’ field

Before using the ‘non-localiable field’ feature, it’s important to understand it completely, and learn how it works in different scenarios.

Case 1: If you edit an existing content type (which has localized entries), and you mark a field as non-localizable, then:

  • The value of the non-localizable field in the master-language entry will be reflected immediately in the localized entries.
  • The current version of all localized entries of that content type will increment by 1 since there is a change in data.

Case 2: If a field of an existing content type is already marked non-localizable, but is later changed to localizable, then:

  • The value of the non-localizable field in the master-language entry will continue to reflect in all the localized entries.
  • In the master-language entry, you will no longer see the ‘Non-localizable’ tag against the field.
  • You will now be able to change the data of the previously tagged non-localizable field in localized entries.
  • The version number will not increment in any of the localized entries.

Case 3: If a field is marked as 'Non-localizable' and you delete all languages except the master language from your stack, then:

  • All entries created for the language will be deleted.
  • In the master-language entry, you will no longer see the ‘Non-localizable’ tag against the field.
  • On adding the deleted language again to your stack, all the entries (that were deleted while deleting the language) will be restored, along with the non-localizable field, which will continue to work as earlier.

Tutorial Video

In this video, we'll see how to set a field as non-localizable.

Introducing Non localizable Fields.png

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.

Bulk Publish Localized Entries on Different Locales

Contentstack provides the option to publish all localized versions of an entry right from the publishing modal of the master language entry.

A localized entry is a separate entity altogether and will have its own versioning system and publishing queue status. When you publish a localized version of an entry, the latest version of that independent entry is sent for publishing.

An unlocalized entry inherits data from its fallback language. If there is no data in the fallback language, then the entry inherits content from the master language entry. When you publish an unlocalized version of an entry, the latest version of the content available in its fallback language is sent for publishing.

For example, you have 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 can publish entry versions available in other languages as well from the publishing modal of English (United States). In the publishing modal, you can select the languages to which you want to publish the selected entries.

To provide content in English (United States), French (France), and Spanish (Spain) but not in Japanese (Japan), deselect the Japanese (Japan) language in the publishing modal.

Note: When you publish multiple language entries at once, only the latest version of the localized entry will be published.

Learn more about bulk publishing entries in different languages here.

Bulk Publish Non-localizable Field Data

Now, if you edit the non-localizable field in the master language entry, you may want to reflect the same changes in the localized entries. For this, Contentstack allows you to publish the entries in multiple languages right from the publishing modal of the master language. This publish request updates the localized entries with the changes made to the non-localizable field.

Learn more about bulk publishing entries in different languages here.

Bulk Publish Localized and Unlocalized Entry Versions Scenarios

Now, let’s see some real-world scenarios to understand how publishing entries on multiple locales works with your localized and unlocalized content.

In this section, we will look at a few scenarios and learn how this feature works in Contentstack.

Scenario 1: Publishing localized and unlocalized entry versions from the publishing modal of the master language

Consider a scenario where you have the following languages available within your stack: English (United States), French (France), Chinese (China), and Spanish (Spain). English (United States) is set as the master language of the stack, while Spanish (Spain) is set as the fallback language for French (France).

When you open the entry page of the master entry [English (United States)], and click on “Publish”, you can select all the other available languages to which you want to publish the entry. Now, consider the following scenario:

  • The entry version present in French (France) is a localized version
  • The entry version present in Spanish (Spain) is an unlocalized version

Now, if you select the languages English (United States), French (France), and Spanish (Spain) from the publishing modal, the following entry versions will be sent for publishing:

  • The latest entry version present in English (United States)
  • The latest localized entry version present in French (France) [independent copy]
  • The latest entry version present in Spanish (Spain) [with content inherited from the master language].

Scenario 2: Publishing localized entry versions from the publishing modal of other localized entry versions

Consider a scenario where you have the following languages available within your stack: English (United States), Japanese (Japan), and Spanish (Spain). English (United States) is set as the master language of the stack while Spanish (Spain) is set as the fallback language for Japanese (Japan).

When you open the entry page of Spanish (Spain) [fallback language], you can also select the entry version that inherits content from this language, Japanese (Japan), for publishing. Now, consider the following scenario:

  • The entry version present in Spanish (Spain) is a localized version
  • The entry version present in Japanese (Japan) is a localized version

Now, if you select the entries present in Spanish (Spain) and Japanese (Japan) from the publishing modal, the following entry versions will be sent for publishing:

  • The latest entry version present in Spanish (Spain) [with content inherited from the master language]
  • The latest localized entry version present in Japanese (Japan) [independent copy]

Here, since the entry present in Japanese (Japan) is the child entry of the entry present in Spanish (Spain) [parent entry], the localized independent copy of the child entry is also available for publishing.

Scenario 3: Publishing localized entry versions in bulk from the publishing modal of the entries list page

Consider a scenario where you have the following languages available within your stack: English (United States), Japanese (Japan), and Spanish (Spain). English (United States) is set as the master language of the stack while Spanish (Spain) is set as the fallback language for Japanese (Japan).

When you open the entry list page, you can send multiple entries for publishing at once. When you click on “Publish”, you can select all the available languages to which you want to publish the entry, for example, English (United States) and Japanese (Japan). Now, consider the following scenario:

  • The entry version present in Spanish (Spain) is a localized version
  • The entry version present in Japanese (Japan) is a localized version

Now, if you select languages English (United States), Spanish (Spain), and Japanese (Japan) from the publishing modal, the following entry versions will be sent for publishing:

  • The latest entry version present in English (United States)
  • The latest entry version present in Spanish (Spain) [with content inherited from the master language]
  • The latest localized entry version present in Japanese (Japan) [independent copy]

Here, since the entry present in Japanese (Japan) is the child entry of the entry present in Spanish (Spain) [parent entry], the localized independent copy of the child entry is also available for publishing.

Limitations on Publishing Localized Entry Versions

  • At a time, you can publish a single entry in 50 languages and 10 environments.
  • At a time, you can publish 10 entries in 10 languages and on 10 environments.
  • When you publish multiple language entries at once, only the latest version of the localized and unlocalized entries will be published.

Manage Translation in Contentstack

Contentstack does not provide translation service. However, you can use Contentstack Webhooks and manage translation at your end. You can also use webhooks along with third-party apps, such as AWS Lambda, to manage translation. We have created a few guides on how to manage translation 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.

Manage language permissions finalized.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