Translations

Defining source messages

To get started, we recommend that you define source messages in the messages.js file next to your React component.

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.

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

Consuming messages as React components

The react-intl library provides several React components to render the message, like <FormattedMessage>.

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.

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>
  );
};

Consuming 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)}
      // ...
    />
  );
};

Extracting 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"
}

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

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;

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

import loadMessages from '../../load-messages';

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

import loadMessages from '../../load-messages';

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