Documentation

Translations

Elevate, May 20-22-2025, Miami Beach, Florida

Learn more about implementing multiple language support in your customizations.

The Merchant Center is translated into several languages, for example, en, de, and es. The default language is en.

The Merchant Center locale setting can be changed within the user profile page.

When you develop a customization, you have the option to translate it in one or more languages.

Translations are usually included as JSON files that are dynamically imported into the customization based on the user's locale.

To facilitate the management of source messages and translations, we provide some built-in functionalities and tooling.

Define source messages

To get started, we recommend that you define source messages in the messages.js file next to your React component.
messages.jsJavascript
import { defineMessages } from 'react-intl';

export default defineMessages({
  title: {
    id: 'Channels.title',
    defaultMessage: 'Channels list',
  },
});
Source messages are defined as named objects by react-intl, a library with React abstractions on top of the ECMAScript Internationalization API.
We recommend that you familiarize yourself with the ICU Message syntax to take advantage of the different syntax features.

The source messages can then be used in your React components.

Consume messages as React components

The react-intl library provides several React components to render the message, like <FormattedMessage>.
channels.jsJavascript
import { FormattedMessage } from 'react-intl';
import messages from './messages';

const Channels = () => {
  // ...
  return (
    <Spacings.Stack scale="l">
      <Spacings.Stack scale="s">
        <Text.Headline as="h2">
          <FormattedMessage message={messages.title}>
        </Text.Headline>
      </Spacings.Stack>
      {/* ... */}
    </Spacings.Stack>
  )
};
Most of the UI Kit components support formatting messages via the prop intlMessage. This lets you pass your raw message and the component takes care of rendering the message.
channels.jsJavascript
import { FormattedMessage } from 'react-intl';
import messages from './messages';

const Channels = () => {
  // ...
  return (
    <Spacings.Stack scale="l">
      <Spacings.Stack scale="s">
        <Text.Headline as="h2" intlMessage={messages.title} />
      </Spacings.Stack>
      {/* ... */}
    </Spacings.Stack>
  );
};

Consume messages as React Hooks

The react-intl library also provides an imperative API approach via useIntl, which exposes an intl object with several formatting methods.
Using the intl object is usually necessary for props that only accept strings, for example aria-label, title, etc.
import { useIntl } from 'react-intl';

const Button = () => {
  const intl = useIntl();
  return (
    <FlatButton
      label={intl.formatMessage(messages.save)}
      // ...
    />
  );
};

Extract messages for translations

To generate translation files, you can use the official @formatjs/cli package to extract source messages into a core.json source file.

For example:

formatjs extract \
  --out-file=./src/i18n/data/core.json \
  'src/**/messages.js'
The core.json is the so-called source file, which should be used as the reference file for the translations in the other locales.
As a convention, we store the translation files in an i18n folder:
└── src
    └── i18n
        └── data
            ├── core.json
            ├── en.json
            └── de.json
Depending on your translation tool, you may need to transform the extracted messages to the appropriate format. To do this, you can write a formatter file and pass it as the --format option to the script.
formatjs extract \
  --format=./intl-transformer.js
  --out-file=./src/i18n/data/core.json \
  'src/**/messages.js'
At commercetools, we use Transifex as our translation tool. Therefore, in our applications we generate a core.json file with the key being the message id and the value being the default message.
{
  "Channels.title": "Channels list"
}

Import translations

The JSON files that contain the translations need to be loaded within the customization.

  • For Custom Applications: the <ApplicationShell> expects a applicationMessages prop that is used to load the messages in the react-intl provider.
  • For Custom Views: the <CustomViewShell> expects a applicationMessages prop that is used to load the messages in the react-intl provider.
The applicationMessages prop can either be a JSON object or a function returning a promise with the loaded messages.
To keep the bundle size small, the application should only load the messages for a specific locale (and not all of them). This can be achieved by using the Code-Splitting feature.
If the translation messages are located in the i18n/data folder, you can define a function to dynamically load the messages.
load-messages.jsJavascript
import {
  parseChunkImport,
  mapLocaleToIntlLocale,
} from '@commercetools-frontend/i18n';

const getChunkImport = (locale) => {
  const intlLocale = mapLocaleToIntlLocale(locale);
  switch (intlLocale) {
    case 'de':
      return import(
        /* webpackChunkName: "app-i18n-de" */ './i18n/data/de.json'
      );
    default:
      return import(
        /* webpackChunkName: "app-i18n-en" */ './i18n/data/en.json'
      );
  }
};

const loadMessages = async (locale) => {
  try {
    const chunkImport = await getChunkImport(locale);
    return parseChunkImport(chunkImport);
  } catch (error) {
    console.warn(
      `Something went wrong while loading the app messages for ${locale}`,
      error
    );
    return {};
  }
};

export default loadMessages;

The starter templates already provide this function.

In the entry-point.jsx component you can then pass the function to the applicationMessages prop:

For Custom Applications

For Custom Views

entry-point.jsxjsx
import loadMessages from '../../load-messages';

const EntryPoint = () => (
  <ApplicationShell
    applicationMessages={loadMessages}
    // ...
  />
);
entry-point.jsxjsx
import loadMessages from '../../load-messages';

const EntryPoint = () => (
  <CustomViewShell
    applicationMessages={loadMessages}
    // ...
  />
);