This blog is about a recurring topic that every software developer faces at a certain point: internationalisation. What is "internationalisation"? This is what Wikipedia tells us:

--- Start Quote ---

In computing, internationalization and localization (AmE) or internationalisation and localisation (BrE) are means of adapting computer software to different languages, regional peculiarities and technical requirements of a target locale.

--- End Quote ---

Software with a user interface should - in the best of cases - support multiple languages. After all, the world is a diverse place with many languages, and software should adapt to this reality. Especially web-based user interfaces should support internationalisation, since it can be accessed from any country in the world.

React and internationalisation

React is a user interface library, so how can you internationalise a React application? You can build your own custom internationalisation, based on Javascript objects, which act like a dictionary or you can actually use an existing library. In this blog post, we will look at both approaches.

What are the advantages of using your own implementation? Well, the solution can be "minimalistic", and you do not need to worry about dependencies. But you will have to maintain and test it and re-do the work other people have already done.

What are the advantages of using a library? You get lots of functionality out of the box, which has been tested by a large number of users.

Home-made React internationalisation

The author of this blog has created a very simple internationalisation solution which does its job but has no bells and whistles. It consists of two small functions and a language dictionary.

This is what you need to create a home-made internationalisation solution:

  1. one function which identifies the current language
  2. one function which selects the internationalised text based on  the identified language and on a text key
  3. a dictionary with key, value pairs for each language you want to support

1. Current language identification function

Here is an example of a function that identifies the current language:

If you are interested you can copy-paste the code from this link:

https://gist.github.com/onepointconsulting/0686e6dfbfc783d73fb619d6563c3d43

The main function here is extractParameterSimple, that is extracting the language from multiple sources, including the URL, a global object (window.eventsConfig) or from the React properties.

2. Text selection function

Here is an example of a function that selects the internationalised text:

The useTranslation function is a factory function that returns the function that selects the internationalised text. The returned function then queries the language dictionary with the current language and a translation key. It was supposed to support embedded parameters, but the author did not implement it yet, as you can see in the TODO comment.

In case you want to copy the code you can do it here:

https://gist.github.com/onepointconsulting/0e821826897760e06b0d3e2cd121e493

This is how you use this function:

3. Language Dictionary

This is a dictionary (Javascript object) with two levels. The first level is the language and the second one the key of the translated string. It looks like this:

And that is everything there is to it. This solution is simple, but it lacks some features, most notably translated strings with parameters, like, e.g.: "Update {{number}} results".

A Internationalisation Library: react-i18next

What is react-i18next? According to the authors, it is:

--- Start Quote ---

react-i18next is a powerful internationalisation framework for React / React Native, which is based on i18next.

--- End Quote ---

A couple of things to be noted about this answer: 

  • it is powerful, i.e. comes with many features.
  • it targets React and React Native - works both on the Web and in mobile phones and possibly also Smart TVs and tablets, etc.
  • it is based on another framework: i18next

So this is a proper framework with a rich feature set for React and React Native.

A special highlight of this framework seems to be server-side rendering:

--- Start Quote ---

react-i18next is optimally suited for server-side rendering. It provides an extra extension point to work with next.js, e.g. Learn more.

--- End Quote ---

But ok: I was just writing a plain web application with React, so not targeting server-side rendering at this moment.

Installing react-i18next

Most Javascript frameworks these days are installed via npm. And react-i18next is no exception. So I went happily ahead and installed the library via:

npm i react-i18next

And nothing worked, because I had forgotten about the dependencies of the library. These were mentioned in the documentation at the bottom of the Git repository page:

Yes, you also need to install i18next:

npm install i18next

And then you also need some form of language detection, so I ended up installing another library:

npm install i18next-browser-languagedetector

My recommendation is to install these three libraries.

Using react-i18next

First, you need to initialise your react-i18next object and then export it with some code like, e.g.:

You can see from the code above that we are using the language detector, that helps to detect the language in multiple ways, including detecting the browser language or a URL parameter "lng". By using the language detector, you can switch the language on a browser defaulted to English to German, if you use a parameter "lng", e.g.:

http://localhost:3000/?eventDateId=3371071&lng=de

Then you can use the translation function, which also comes with a factory function, like this:

This works especially well for React function components. The useTranslation function is a React Hook. So you cannot use it in class components.

If you have class components, you can either pass the translation function to the props of the component or use a provider to inject it into the props of child components. 

Passing the translation function to the props of a component looks like this:

Using a provider to inject the function into child components works like this:

You can either use the translation component or alternatively the Trans component. This looks like this:

And you can parameterise your translated strings using Javascript objects like so:

You will also need to have a corresponding translation key that inserts the parameter in the right place:

For more features, please visit:

https://react.i18next.com/

Conclusion

Internationalisation is a topic for most web-based UI applications and also for most mobile apps. As a developer, you will need to address it sooner or later. You can build your home-based solution, but if you want to have the comfort of a proper enterprise-grade framework, you should consider react-i18next that offers you React hooks, components and more goodies as well as full interpolation, plurals support and more.