Documentation

Internationalization

commercetools Frontend has built-in concepts for internationalization. You can put additional facilities on top of this in your frontend.

The API hub expects a proper locale on every API call to be set by the frontend. The given locale must be fitting the configuration of the project (locales configured for the project and the default locale). The API hub will then select the appropriate translation and forward the selected locale to any backend system.

We support multi-language and multi-region setups which can be done in different ways depending on your requirements.

There are generally 3 things that can be translated or adapted to the target regions by other means:

  • page structure and data
  • Data from external APIs (products, content, …)
  • User interface strings (buttons, captions, …)

Not only can each project be multi-lingual and multi-region, but you can also have a dedicated project by region or language.

We can identify languages and regions by their locale. For example, en_GB would stand for English - Great Britain. This is especially important for slight variations in languages, like the difference between English in Great Britain and the USA, but also for countries using multiple languages, like Switzerland (de_CH for German, fr_CH for French and it_CH for Italian).

Page structure and data

The simplest way to set up internationalization is just a single language per project. If you'd like to do this, tell us to create multiple projects, with 1 language each.

The other way to do this is to use a single project with multiple languages. This way, the structure and pages are shared across all languages. You can still overwrite pages for a specific language or locale, for example, to show different start pages to customers from Germany. You'd also need to define a default language.

Or, both mechanisms can be combined:

  • English website (en_GB)
  • Swiss website (de_CH, fr_CH, it_CH) with a similar page folder tree as the English website, but different pages

If a single project defines multiple locales, all contents of fields configured as translatable can be translated in the Studio.

See the decisions to consider article for more information.

Retrieving translated data from API hub

The API hub automatically selects the appropriate translated data for you based on the locale sent to the corresponding API call. This way, you can expect any textual data that's translatable to be in the correct (or the default) language.

Data from external APIs

The API hub submits the current locale to your API hub extensions so that those can obey the locale setting appropriately.

User interface strings

(Also known as internationalization of Frontend components)

Making Frontend component data translatable Textual input fields (string, text, and markdown) are automatically translatable. That means you can use a field of that type to automatically have internationalized input in Studio and will automatically receive the correct localized text in the frontend.

If you want to disable internationalization for a specific field, you can provide the setting translatable: false. For example:

{
  "schema": [
    {
      "name": "Settings",
      "fields": [
        // other fields,
        {
          "label": "Price label",
          "field": "priceLabel",
          "type": "string",
          "translatable": false
        }
      ]
    }
  ]
}

You can't make a non-translatable field type translatable.

Hard-coded translations and number/date formatting

In many cases you might want a text to be translatable but don't want to make the translatable text configurable in Studio. An example is button texts for submit or cancel. In addition, you'll want to format numbers and dates nicely according to the visitor's locale.

These tasks can easily be achieved using standard libraries from the Next.js ecosystem, such as: