About Fallback Languages

Fallback language is the parent language from which a given language inherits data from. Contentstack allows you to define a fallback language for every language you add to a stack.

Using fallback language, you have the control over the source content for a given language. You can then make changes to the fetched content and localize the entry in the given language. For a given language, if there is no data available in fallback language, the entry will fetch data from the master language.

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.

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

This logic only applies to entry creation and does not apply to entry publishing. To apply localization on published entries, refer to the section below.

Retrieve Fallback Content When the Entry is Not Available in the Specified Language

When an entry is not published in a specific language, you can fetch content from its fallback language (if it is published) using the Content Delivery API and some custom code.

Let’s consider an example to understand how this can be achieved.

Let’s say English - United States is the master language of the stack. The two other languages added to the stack are German - Germany (with English - United States as fallback) and German - Austria (with German - Germany as fallback).

Here’s what you want to achieve:

If an entry is not published in German (Austria), then you will fetch the entry published in German (Germany). And, if the entry is not published in German (Germany), then you need to fetch content from the master language (English - United States).

Here’s how you can do it:

  1. Try the Get a single entry API request.
    You can use any third-party REST API client, such as Postman, to make API requests.
  2. Within your API request, specify the locale and environment parameter to fetch the content published to a specific language and environment (e.g., German - Austria).

    Note: You need to pass the language code (e.g., de-at) within the locale parameter and the name of the specific publishing environment (e.g., production) within the environment parameter.

  3. If the entry does not return any data for the specified language, then execute the Get a single entry API request again by passing the fallback language code (e.g., de-de, which is German (Germany)) in the locale parameter. Also, pass the publishing environment in the environment parameter. This request will fetch published content from the fallback language.

    Tip: To get the fallback language details for the specified language, you can use the Get all languages API request.

  4. If the fallback language does not return any data for the entry, then pass the master language code in the locale parameter, while executing the same API request.
  5. You can also automate this process of fetching content from the fallback languages by creating a script to check for published content across languages. The following sample script is in Node.js, and helps retrieve published content from the fallback language when there is no published content in the specified language.

    To run this code, install the required modules by typing the following commands in the terminal:

    //install request module
    $ npm install --save request
    //install request-promise module
    $npm install --save request-promise
    //install contentstack module
    $ npm install contentstack --save

    Create a file named index.js and paste the following code into it. Then, add your stack’s API key, delivery token, content type’s ID, entry’s ID, environment’s name, and the locale in which you want to fetch the content.

    const Request = require('request-promise');
    const contentstack = require('contentstack');
    // Step 1: Specify the stack API key, stack access token, and publishing environment in the API request header
    const Config = {
        url: "https://cdn.contentstack.io/v3",
        accessToken: "{{accessToken}}",
        apiKey: "{{apiKey}}",
        environment: "{{environment}}"
    const Stack = contentstack.Stack( { api_key: Config.apiKey, access_token: Config.accessToken, environment: Config.environment });
    let getLanguage = (locale) => {
        var options = {
            uri: `${Config.url}/locales/${locale}`,
            method: 'GET',
            headers: {
                'api_key': Config.apiKey,
                'access_token': Config.accessToken
            json: true
        return Request(options)
            .then(function(parsedBody) {
                return (parsedBody.locale) ? parsedBody.locale: {};
            .catch(function(err) {
                console.log("GET", err)
    //Step 2: Retrieve published entry details for the German - Austria (de-at) language by passing the entry UID
    let query = Stack.ContentType('blog').Entry("blt123something");
        .then(async function success(entry) {
            if (entry)  {
                // Retrieve a field value by passing the field’s UID
                return Promise.resolve(); 
        }, async function error(err) {
            // Step 3: If entry is not found for the requested locale, then check in the fallback locale, i.e. German - Germany (de-de)
            const Language = await getLanguage("de-at");
            if (Language && Language.fallback_locale) {
                return query
                    .then(function success(entry) {
                        if (entry) {
                            return Promise.resolve(); 
                    }, function error(err) {
                        // Step 4: If entry is not found in the fallback locale, then check in the master locale, e.g., English - United States (en-us)
                        return query
                            .then(function success(entry) {
                                if (entry) {
                                return Promise.resolve(); 
                            }, function error(err) {
                                // err object
        .then(() => { process.exit(0); });

    Save this code and run it by typing the following command in the terminal:

    $ node index.js

Was this article helpful?

Thanks for your feedbackSmile-icon

On This Page