How to translate your React app with react-intl

Setup your first React app

We're setting up a small React application to learn how localization works. Of course you can skip this section if you want to use your own application for that.

If you haven't already installed the create-react-app scripts, install them using npm:

npm install -g create-react-app

With the following lines you create an empty react app and start it:

npx create-react-app my-app
cd my-app
npm start

The last line automatically opens the URL http://localhost:3000 and dislays the welcome message rendered by the created app.

As we want to use react-intl to localize our application, add it to you project:

npm install --save react-intl

Add internationalization

The file src/index.js renders the App react element into your DOM:

ReactDOM.render(
    <App/>,
    document.getElementById('root')
);

To make the internationalization functions visible in all our components we have to wrap the App component with IntlProvider. It expects the current locale as property. For the moment we're setting it to a fixed language, later we will determine the user's locale by evaluating the language request sent by the browser.

import {IntlProvider} from "react-intl";

ReactDOM.render(
    <IntlProvider locale='en'>
        <App/>
    </IntlProvider>,
    document.getElementById('root')
);

Now we have to find all language-specific string in our app. In the simple application generated by create-react-app there are two such strings in App.js:

    <h1 className="App-title">Welcome to React</h1>
    ...
    To get started, edit <code>src/App.js</code> and save to reload.

Replace these strings by a FormattedMessage component, and move the text to its defaultMessage attribute:

    import {FormattedMessage, FormattedHTMLMessage} from 'react-intl';
    ...
    <h1 className="App-title">
        <FormattedMessage id="app.title"
                          defaultMessage="Welcome to {what}"
                          description="Welcome header on app main page"
                          values={{ what: 'react-intl' }}/>
    </h1>
    ...
    <FormattedHTMLMessage id="app.intro"
                          defaultMessage="To get started, edit <code>src/App.js</code> and save to reload."
                          description="Text on main page"/>

If you refresh your browser window the welcome string changes from "Welcome to React" to "Welcome to react-intl". As we haven't defined a translation for the ID app.title, the string defined by defaultMessage is used. If neither a translation nor a default message is defined, the ID would be displayed. The description property will be displayed to the translator to give him some context information.

To learn more about message formatting, parameters and localized number and date formats please have a look at the react-intl Documentation.

Translate your application

In the first step we have to load the locale data for languages we want to support. This data is provided by react-intl and specifies the date, time, number, ... formats for each language. The locale data is added by calling addLocaleData().

Add these lines to index.js:

import { addLocaleData } from "react-intl";
import locale_en from 'react-intl/locale-data/en';
import locale_de from 'react-intl/locale-data/de';

addLocaleData([...locale_en, ...locale_de]);

The translations of our custom text messsages will be stored for each language in a separate .json file. Let's create the JSON file src/translations/de.json for the German translation. We also create an en.json file instead of using defaultText specified in the source code, this makes language handling a bit simpler.

src/translations/en.json:

{
    "app.title": "Welcome to react-intl",
    "app.intro": "To get started, edit <code>src/App.js</code> and save to reload."
}

src/translations/de.json:

{
    "app.title": "Willkommen bei react-intl",
    "app.intro": "Zum Loslegen editiere <code>src/App.js</code>."
}

Now we can load these JSON files and pass one of them to IntlProvider, depending on the language the user has configured in the browser:

Add these lines to src/index.js:

import messages_de from "./translations/de.json";
import messages_en from "./translations/en.json";

const messages = {
    'de': messages_de,
    'en': messages_en
};
const language = navigator.language.split(/[-_]/)[0];  // language without region code

ReactDOM.render(
    <IntlProvider locale={language} messages={messages[language]}>
    ...

Change the preferred language in your browser settings and reload the page to see how the language of your application changes. For languages other than "de" or "en" the translation messages are undefined and react-intl will display the defaultText.

Managing translations

Maintaining the translations files manually is quite a pain as the IDs in all these files must be kept in sync with the IDs used in the javascript source code. We use two tools to simplify this task:

• babel-plugin-react-intl to extract all message IDs from the source code
• BabelEdit to create and update the translations files and keep them consistent with the IDs extracted with babel-plugin-react-intl

Extract message IDs from source code

The translation IDs can automatically extracted from the source code using babel-plugin-react-intl. First we have to install this babel plugin:

npm install --save-dev babel-cli babel-preset-react-app babel-plugin-react-intl

Create a .babelrc file in the project directory. babel-plugin-react-intl will store the extracted message IDs in the build/messages directory, for each source file a corresponding json file is created:

{
    "presets": ["react-app"],
    "plugins": [
        [ "react-intl", {
            "messagesDir": "build/messages"
        }]
    ]
}

By adding the following line to the scripts section of your package.json you can use npm run extract-messages to start babel and extract the message IDs from your sources:

"scripts": {
    "extract-messages": "NODE_ENV=production babel ./src  --out-file /dev/null"    (Mac/Linux)
    "extract-messages": "set NODE_ENV=production&& babel ./src >NUL"               (Windows)
}

If babel is already called as part of your build process you can skip this step.

Maintain translation files with BabelEdit

To get started with BabelEdit download it from here: Download BabelEdit

The editor is currently in beta phase and you can use it for free.

Select the right-most button to create a react-intl project:

Select the build/messages directory of your React application, which contains the messages extracted with babel-plugin-react-intl:

If you've specified defaultMessage texts in your source code, you can specify the corresponding translation file here. The defaultMessages are automatically copied to this translation file, and they will be displayed read-only by the BabelEdit UI:

Now you can define additional languages. If you've already created translation files as described in the previous section you can select them here, too. Their content will be imported:

BabelEdit loads the message definitions files as well as the translations files. The left side displays a tree view with your translation IDs, the right side the translations. The Approved checkbox allows you to mark translations as final. This additional information is stored in a BabelEdit project file (extension .babel).

The editor automatically reloads the files after they have been updated ? e.g. from a new run of babel-plugin-react-intl. Each time you save the BabelEdit project the JSON translation files are updated, too.

Use add additional languages, change the primary language or update the directory containing the extracted message definitions you can use the Languages and Settings buttons in the toolbar.