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.
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.
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:
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
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:
The React tree must be wrapped withr
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.
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
Let’s define a simple React component which shows this greetings message and use it in the app:
As pointed out in the beginning of this article, all messages are stored in the language specific files (in this demo’s case
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:
extract-messages with a few arguments:
-l: defines the available locales, in this demo en(universal English) and de(universal German)
-o: defines the location of the internationalized JSONs (
-d: defines the default locale, in our demo it is set to English. Based on this argument,
extract-messagescopies the default messages we define in the code to the default locale’s JSON, in our case
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
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
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:
- Define the languages and language files
- Use the
<FormattedMessage>component with the ID of the internationalized message to get the message based on the currently selected locale
yarn extract-intlto 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
- Fill out the rest of the JSONs (languages) with the correct values
- Change the locale passed to
IntlProviderbased 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!
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):
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/!