Internationalize your React App In 5 Easy Steps With React Intl
Tags: react, webdev, javascript, frontend
Published: 2020-12-13 16:11:34

# 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:

{% gist https://gist.github.com/adamkss/6a8e2dc9e80fe461eda2cf9424d0ece2 %}

## 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:

{% gist https://gist.github.com/adamkss/14da4504d75386e4642e5f793df87901 %}

{% gist https://gist.github.com/adamkss/d0013050d53e5aa74a3a538c7d0643a5 %}

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

{% gist https://gist.github.com/adamkss/3e74f6d847959f5f71d89ef49799495e %}

## 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.

{% gist https://gist.github.com/adamkss/8eb5ee9f0a3bf3840f50c8507ebe7a0f %}

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`:

{% gist https://gist.github.com/adamkss/1c713bf7e26747d8e6683eb1c312e16f %}

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

{% gist https://gist.github.com/adamkss/13fb0074f16a0ae82ab59aada1761c7b %}

This would show us the default message:
![Screenshot 2020-12-13 at 13.01.41](https://dev-to-uploads.s3.amazonaws.com/i/lhmxc7nkhge9t048iv4w.png)
 
## 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:
{% gist https://gist.github.com/adamkss/da569bfb6cbc3daf778a97635ee9f4be %}

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:

{% gist https://gist.github.com/adamkss/b210272fe1527a356c583af34d81fd4f %}

{% gist https://gist.github.com/adamkss/e657d7c0d48d8e205feb53bd1b285051 %}

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`:

{% gist https://gist.github.com/adamkss/c5d9e3164c055b9672f9595c5d49e916 %}

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`:

{% gist https://gist.github.com/adamkss/45de588366ba9e4b4d91a5a48f6ad367 %}

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:

![Screenshot 2020-12-13 at 13.19.01](https://dev-to-uploads.s3.amazonaws.com/i/i5lq18yeyktq8gosdak0.png)

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):

{% gist https://gist.github.com/adamkss/c04747fdd943da2a49bfb585ab15d6cd %}

{% gist https://gist.github.com/adamkss/d91c28f23b2e67f77482bf2d0f685e1b %}

# 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/!