Internationalize your React App In 5 Easy Steps With React Intl

What is Internationalization?

Internationalization is the term used for making a website suitable for multiple locales (i.e. one or more places and/or languages).

Internationalization is oftentimes shortened to i18n as it starts with an “i”, ends with an “n” and there are 18 other characters in between. Developers just love their abbreviations, don’t they?

A good internationalization framework should provide a decent DX (developer experience) without taking up a lot of implementation time.

React Intl

The library this article presents is called React Intl. With more than 800,000 monthly downloads it’s one of the most used tools for internationalization in the world of React.

React Intl can do a lot more than just choosing messages/strings based on the locale. It can also format numbers and dates based on it!
In this article, however, only the messages aspect of it is covered as this is what most people are mainly looking for.

React Intl will now be presented in the context of a React app bootstrapped with create-react-app, using English and German as demo languages.

The repository with the working code can be found here: https://github.com/adamkss/react-intl-demo.

1. Adding the dependencies

First of all, React Intl has to be added as a dependency by running: yarn add react-intl.

We also need one more dependency to add, and that is extract-react-intl-messages. This development depndency will be used to extract the internationalized messages into their own language files. Thus, run: yarn add -D extract-react-intl-messages.

In order for extract-react-intl-messages to work, make sure to also create a .babelrc file in the root of your project with the following content:

2. Creating the locale specific files

Each locale to be supported needs to have its own file which stores the localised messages in JSON format.

Create a new folder called translations, and create en.json and de.json. Both should be, for now, empty:

Let’s also create an index.js in the translations folder which will export the translations themselves:

3. Wrap your React tree with React Intl’s provider

The React tree must be wrapped withr react-intl’s IntlProvider so the internationalized messages become accessible in each and every component.

IntlProvider expects 2 important props: the actual locale and the internationalized messages selected by the locale.

In the above example the locale is hardcoded. In general, you should either check the browser’s default language (via the navigator object: navigator.language), geo locate the user or let them simply select from a language list.

4. Start defining the messages

Each internationalized message should have an ID and a default value. Defining a default value is not mandatory, but it’s good if you start building your webpage in one language.

Defining an internationalized message is as simple as using the FormattedMessage component of react-intl:

Let’s define a simple React component which shows this greetings message and use it in the app:

This would show us the default message:

5. Adding messages in another language

As pointed out in the beginning of this article, all messages are stored in the language specific files (in this demo’s case en.json and de.json).

We must use the development dependency we added (extract-react-intl-messages) to fill these out with the keys (IDs) of our messages. For example, the greetingsMessage we used above.

For this we need to add a new script called extract-intl to the package.json's scripts key right below the react-scripts:

This script, extract-intl, runs extract-messages with a few arguments:

1. -l: defines the available locales, in this demo en(universal English) and de(universal German)
2. -o: defines the location of the internationalized JSONs (de.json and en.json)
3. -d: defines the default locale, in our demo it is set to English. Based on this argument, extract-messages copies the default messages we define in the code to the default locale’s JSON, in our case en.json

After running this command via yarn extract-intl, take a look at the two JSON files:

You can see that the default language’s localized file has been filled out with the default messages present in the code, whilst the other language file only has the keys. The values are now ready to be defined there as well!

The German version of greetingsMessage can be manually set by modifying de.json:

Now, to try it out, the German locale (de) needs to be passed to IntlProvider, which in turn will use all the German messages defined in de.json:

By doing this modification (swapping the locale passed to react-intl), we now get the German message, without having needed to actually touch the code of the component:

Great! Here is a summary of what needed to be done for internationalization:

1. Define the languages and language files
2. Use the <FormattedMessage> component with the ID of the internationalized message to get the message based on the currently selected locale
3. Run yarn extract-intl to fill out your localisation JSONs with the existing message IDs. This also automatically inserts the default messages (defined in the code) into the default language’s JSON (set in the extract-intl command)
4. Fill out the rest of the JSONs (languages) with the correct values
5. Change the locale passed to IntlProvider based on your needs (by the user’s region, manually, by the browser’s language etc.) which automatically inserts the right messages in your app from the selected locale!

Other ways to access the messages

Sometimes you cannot use the <FormattedMessage> tag to get/define a message. Think about the situation where the title attribute has to be set on an HTML element.

No worries! React Intl provides us with a hook and a HOC (higher order component you wrap your component with) that we can use to get access to the intl object (hook for functional components and a HOC, injectIntl, for class based components):

In closing

React Intl provides a clean and simple way to internationalize your application 🌍. Feel free to give it a try!

Thank you for reading this article all the way through, you rock!

If you liked the content, I would love if you subscribed to my newsletter by visiting https://adamkiss.net/!

Comments

[Andrew Baisden]

Nice something like this will be quite useful.

[Johan Lejdung]

I were just researching libraries for this, great writeup thanks! Do you know if it support any other filetypes? Or how it compares to other libraries that aim do to the same thing?

[georgios lymperis]

In case you need a tool to translate instead of editing the generated JSON files from extract-intl there is a web app lybo.github.io/intl-translations/. It's great for non-technical people.