Translations

Defining source messages

As a first step, we recommend defining 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.
Below you will find some examples of consuming the Intl messages.

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

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

Based on your translation tool, you may need to transform the extracted messages to the appropriate format. For that 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'

{
  "Channels.title": "Channels list"
}

Importing translations

The JSON files containing the translations need to be loaded within the application. The <ApplicationShell> 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 low, 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.

Given the translation messages are located in the i18n/data folder, you can define a function to dynamically load the messages:

const loadMessages = (lang) => {
  let loadAppI18nPromise;
  switch (lang) {
    case 'de':
      loadAppI18nPromise = import(
        '../../i18n/data/de.json' /* webpackChunkName: "app-i18n-de" */
      );
      break;
    case 'es':
      loadAppI18nPromise = import(
        '../../i18n/data/es.json' /* webpackChunkName: "app-i18n-es" */
      );
      break;
    default:
      loadAppI18nPromise = import(
        '../../i18n/data/en.json' /* webpackChunkName: "app-i18n-en" */
      );
  }

  return loadAppI18nPromise.then(
    (result) => result.default,
    (error) => {
      console.warn(
        `Something went wrong while loading the app messages for ${lang}`,
        error
      );

      return {};
    }
  );
};

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