Implementing Internationalization in a front end application
Making our product reach an audience beyond our geographical boundaries, and in accordance with local cultures, requires a process known as internationalization, often referred to as i18n, a way of shortening the term “i + nternationalizatio + n” or “i (plus 18 letters, plus) n”.
If you would like to know more about internationalization, I suggest a quick reading on the subject before we go on.
In front end, there are libraries for different stacks such as React, Angular, Vue, etc. I’ll focus here on React, but the fundamental concepts can be applied to any other stack.
What will you find in this article?
Briefly, we will complete the following steps:
- Create a simple application with the React Create App library
- Install an internationalization library
- Write translation files
- Configure our internationalization library accordingly our needs
- Configure a React Provider for the components to be internationalized
- Replace hardcoded texts with translation keys
You can also see the application running on Heroku.
Check out the repository application in Github.
Getting started
Step 1: Creating an application with Create React App
Our first step will be to create a fairly simple React application so that we are able to apply the internationalization concepts. For this, we will use the library Create React App in order to abstract all application setup.
$ npx create-react-app react-i18next-example
$ cd react-i18next-example
$ npm startWith our environment already set up, we can start to internationalize our application. This step will be omitted because this is not the article main focus. The application already prepared, but not yet internationalized, can be found in the application’s repository in Github in the branch without-i18n.
It is a tourist SPA (Single Page App) about lighthouses.
We will need to internationalize the texts within each component in the lighthouses directory, as well as in the Home directory.
Internationalizing
We have many options for internationalization libraries or i18n libraries. Among the most popular are the react-intl hosted by Yahoo and the i18next. After a quick analysis, the last one seemed a little bit more simple to use, as well as can be used not only for react applications, but for many other frameworks such as Angular, Vue, and Vanilla JavaScript and NodeJS.
Some of the many features available by i18next are loading translations on demand through Ajax calls, caching, plurals, namespacing, and browser language detection.
In order to facilitate our work, let’s use an i18next’s extension for React applications, the react-i18next.
Step 2: Installing the i18next and the react-i18next
In a terminal, type the following commands
$ npm install i18next
$ npm install react-i18nextWe also will install the extension that detects the browser language.
$ npm install i18next-browser-languagedetectorStep 3: Creating the translation files
Now that we have installed our i18n library and extensions, let’s create our translation files. Let’s translate only for “pt-BR” and “en”. (Brazil, Portuguese and US English).
Within each component containing texts, let’s create a locale folder, where we will put our JSON files with the translation keys. Starting with the src/components/home/ directory.
For the keys in Portuguese, let’s create the default.json file, and for the keys in English, the default.en.json.
We’ll do the same for the directories below. (we’ll omit this step).
- src/components/lighthouses/Augustine/
- src/components/lighthouses/Hercules/
- src/components/lighthouses/Lindau/
- src/components/lighthouses/Peggys/
Step 4: Creating the i18n config file
In addition to translation files, we’ll need also a config file for the internationalization. This config file will be used to manage the i18n features we want to use. To do so, let’s create an i18n folder under the src/ directory, and within it an index.js file.
In line 2, we imported the i18next-browser-languagedetector module.
In line 3, we imported the translation files.
In line 12, we have a commented key because it is not being used. In case we were not using the language detector feature, this commented key would be used to set up the default language to be loaded. This use case is in the branch simplest-example. In order to test, check out this branch and switch the lng key value from “en” to “pt” and vice versa.
In line 40, we added a callback to be called when we trigger an action to switch the language. This callback is being called on line 14 in the Toolbar component.
Our configuration file accepts a range of options. In our application, however, we’ll only use some of them. For instance: interpolation { defaultValue }, debug, resources, fallbackLng, ns, defaultNS, react { wait, bindI18n, bindStore, nsMode }
Interpolation
Interpolation is one of the most used features in internationalization. This feature allows us to load dynamic values within our translation keys. In our case by using React, the value scapeValue don’t need to be defined as true.
Resources
Resources define the translation files to be loaded. It is also possible to define the translation keys inline in this option.
fallbackLng
Language to be loaded in case the default user language could not be found
ns
Default namespace to be loaded.
React
This option is an object with options related to React.
Step 5: Adding a i18n provider in the app
Almost there! We’ll use the ease that react-i18next extension offers us. Let’s add a provider allowing us to pass all the translations via react props in any place in our application. We’ll do that in the top of our components tree, in the file src/App.js/.
In line 3, we imported the I18nextProvider module. We also imported the i18n config file in line 4, which will be passed as react props in our provider component in line 11. All the application is now encapsulated by the internationalization provider.
Step 6: Replacing hardcoded texts with translation keys
Last but not least, we’ll replace the hardcoded text with the translation keys within our components.
As we can notice, in line 5, the react-i18next addon provide us a t function via react props coming from our i18n provider, defined in the file src/App.js. We call this function in the places we have texts to be translated passing the path of our translation keys as arguments.
Also in the files, where we want to internationalize, we should import the translate module (line 2), and export our file passing the translate module with the default namespace, defined in our i18n config file, in our case (common) namespace. Line 17.
Now, just run the application.
$ npm startIn order to test, just click on the little flags on the application’s header.
Conclusions
Recapping what we saw
- We created an Application with Create React App
- We installed the library i18next and its React extension react-i18next
- We created the translation files
- We created the i18n config file
- We added an i18n Provider at the top of our components tree
- We replaced the hard code text with the translation keys
This is a totally functional use of internationalization in front end. We used a very complete library, but applying only some of their features. We could have created only one JSON file with all our translation keys, but we choose to separate our keys in distinct files. We could have also don’t have any JSON file and put all our translation keys inline into our i18n config file, in the resources option.
Visit the live demo.
