React internationalization with react-intl

Struggling with React internationalization? Not sure which library to pick? Need to support a variety of formatting options? Many questions arise when we need to choose the best solution for our project. In this post, you will find how to set up internationalization in your React app with one of the most popular libraries out there, the react-intl.

The react-intl is a part of Format.JS, a set of JavaScript libraries for internationalization and formatting. It is a well-documented and maintained library. It works well in all major browsers. For older browsers, there are polyfills. Plenty of formatting options and support for the ICU Message syntax makes it very handy.

Let's start.

Create new React project

First things first, let’s create a new React app with Create React App.

npx create-react-app react-intl-example

Add React Intl dependency

To use the react-intl library in the project, you need to add it as a dependency.

cd react-intl-example
npm i --save react-intl

Create localization files

The next step is to create the localization files for the required locales. It is good practice to keep all localization files in one place (e.g. src/lang). In this example, we will add three JSON files under the lang directory: ar.json, en.json, and es-MX.json. These files are going to hold translations for the Arabic, English, and Spanish (Mexico).

Below, you can see how the project structure should look after adding mentioned files.

react-intl-example
|-- lang
|   |-- ar.json
|   |-- en.json
|   |-- es-MX.json
|-- src
|   |-- App.js
|   |-- App.test.js
|   |-- index.js
|   |-- ...
|-- ...
|-- package.json
|-- package-lock.json

As we are going to use localization messages later, let’s populate added files with some content.

ar.json:

{
  "message.simple": "رسالة بسيطة."
}

en.json:

{
  "message.simple": "A simple message."
}

es-MX.json:

{
  "message.simple": "Un mensaje sencillo."
}

Wrap your app with the IntlProvider

Finally, wrap the top-level app component with the IntlProvider from the react-intl library and pass the appropriate messages (check the LocalizationWrapper component).

App.js:

import React, { useState, useEffect } from "react";
import { useIntl, IntlProvider, FormattedMessage } from "react-intl";

let initLocale = "en";
if (navigator.language === "es-MX") {
  initLocale = "es-MX";
} else if (navigator.language === "ar") {
  initLocale = "ar";
}

function loadMessages(locale) {
  switch (locale) {
    case "ar":
      return import("./lang/ar.json");
    case "en":
      return import("./lang/en.json");
    case "es-MX":
      return import("./lang/es-MX.json");
    default:
      return import("./lang/en.json");
  }
}

function getDirection(locale) {
  switch (locale) {
    case "ar":
      return "rtl";
    case "en":
      return "ltr";
    case "es-MX":
      return "ltr";
    default:
      return "ltr";
  }
}

function LocalizationWrapper() {
  const [locale, setLocale] = useState(initLocale);
  const [messages, setMessages] = useState(null);
  useEffect(() => loadMessages(locale).then(setMessages), [locale]);

  return messages ? (
    <IntlProvider locale={locale} messages={messages}>
      <App locale={locale} direction={getDirection(locale)} onLocaleChange={(locale) => setLocale(locale)} />
    </IntlProvider>
  ) : null;
}
export default LocalizationWrapper;

function App({ locale, direction, onLocaleChange }) {
  const intl = useIntl();

  return (
    <div>
      <div style={{ textAlign: "center" }}>
        <select value={locale} onChange={(e) => onLocaleChange(e.target.value)}>
          <option value="en">en</option>
          <option value="es-MX">es-MX</option>
          <option value="ar">ar</option>
        </select>
      </div>

      <div dir={direction}>
        <h3>Declarative examples</h3>
        <FormattedMessage id="message.simple" />

        <h3>Imperative examples</h3>
        {intl.formatMessage({ id: "message.simple" })}
      </div>
    </div>
  );
}

Congratulations, you have successfully set up internationalization in your React app!

More details and examples you can find in the original post.

All code samples are available on the GitHub repo.

We hope you found it helpful.