Documentation

@/i18n

Data and helpers to work with internationalization data and messages.

Installation

Using npm

yarn add @commercetools/i18n


# or


npm install --save @commercetools/i18n

Supported locales

  • English en
  • German de
  • Spanish es
  • French (France) fr-FR
  • Simplified Chinese zh-CN

Usage

The ApplicationShell internally uses this package, there is no need to explicitly call AsyncLocaleData or the useAsyncLocaleData hook.

If you need to load translations files asynchronously, the library exposes the useAsyncIntlMessages hook, when used it will additionally load the application-kit and ui-kit translations messages, as well as the moment locales.

Using a React component with render props

With static messages

import { IntlProvider } from 'react-intl';
import { AsyncLocaleData } from '@commercetools-frontend/i18n';


const myApplicationMessages = {
  en: {
    Title: 'Application Title',
  },
};


const Application = (props) => (
  <AsyncLocaleData
    locale={props.user.locale}
    applicationMessages={myApplicationMessages}
  >
    {({ isLoading, locale, messages }) => {
      if (isLoading) return null;


      return (
        <IntlProvider locale={locale} messages={messages}>
          ...
        </IntlProvider>
      );
    }}
  </AsyncLocaleData>
);

With dynamic loaded messages (code splitting)

import { IntlProvider } from 'react-intl';
import { AsyncLocaleData } from '@commercetools-frontend/i18n';


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) => {
      // eslint-disable-next-line no-console
      console.warn(
        `Something went wrong while loading the app messages for ${lang}`,
        error
      );


      return {};
    }
  );
};


const Application = (props) => (
  <AsyncLocaleData
    locale={props.user.locale}
    applicationMessages={loadMessages}
  >
    {({ isLoading, locale, messages }) => {
      if (isLoading) return null;


      return (
        <IntlProvider locale={locale} messages={messages}>
          ...
        </IntlProvider>
      );
    }}
  </AsyncLocaleData>
);

Using a React hook

We expose a React hook that works similarly to AsyncLocaleData

import { IntlProvider } from 'react-intl';
import { useAsyncLocaleData } from '@commercetools-frontend/i18n';


const Application = (props) => {
  const { isLoading, locale, messages } = useAsyncLocaleData({
    locale: props.locale,
    applicationMessages: loadMessages,
  });


  if (isLoading) return null;
  return (
    <IntlProvider locale={locale} messages={messages}>
      ...
    </IntlProvider>
  );
};

Generating translation files

The intl messages defined in your React components must be extracted into the core.json source file.

This file contains a key-value map of the translation messages id and value.

Extracting translation messages

This can be achieved by executing the command included in the mc-scrpts CLI tool.

mc-scripts extract-intl [options]

Translation sync

We use Transifex as our localization platform.

Messages included in the core.json source file, which are pushed/merged to the main branch, are synced using the Transifex Github Integration.

Reviewed translations are automatically pushed back by the Transifex Bot using a Pull Request.