The Best Libraries for React i18n

React is a popular front-end development library that helps you build scalable UI interfaces. When it comes to internationalizing your apps though, it does not offer a built-in solution. Fortunately for us, it is not hard to do that, especially with the help from some open source libraries like react-intl, i18next or react-intl-universal.

In this article, we will take a look at the different libraries we have when we attempt to localize our React App. We will also understand the pros and cons for each option in terms of flexibility, scalability and most of all, developer productivity as its very important to have a consistent view of the app.

Understanding the pros and cons of each library takes time and effort. The main reason is that almost every language has different rules and conventions and adapting to them in the scope of those libraries, is tricky to do it right.

At the time of this writing, I’m using just plain React v16.2.0 and React Router v4.2.0.

The Base Project

Let’s start by layering a base project that we would like to localize. It would be a typical, unopinionated React project with a minimal boilerplate, useful for starting out fresh.

Where Home  is just a page with some div elements with text:

Having this page we are ready to explore the first library which is react-intl.

React-intl

This library is one of the most popular solutions for i18n in React. Offered by Yahoo is bundled with common locale data like dates, currencies, numbers, and support for over  150+ languages. It uses and builds on the Internationalization API built-in to JavaScript.

In order to use it, you need to configure a few steps.

Install it first:

Then on your root of the application just before you render the initial component:

The locale-data  folder is necessary to be loaded for all supported languages as React Intl relies on that locale data to support its plural and relative-time formatting features.

Notice that the i18nConfig contains all the specific language translations for the current locale. We could have loaded this config before the application starts using a JSON Webpack loader or an ajax call.

Now that we have loaded our supported locale and config messages we only need to wrap the application with the that will apply the i18n context available for our internal React Components.

Now we are ready to provide our translated components. We need to convert our existing text in the Home component into a series of FormattedMessage  components:

Then we need to update our translations to match the keys for each one of the messages.

Now if you notice the app will load with the Greek translations. Notice also that the  FormattedMessage can return also React components and not just text.

If at some point you wanted to just get a translation value as a static text, you would just need to grab the formatMessage method from the context.

First make sure you set a contextTypes for intl  to have access to this.context.intl.formatMessage()  from inside your component:

Then you use it like that for example:

That will just return Καλώς 'Ηρθατε στο React.js

Among other things React-intl has some extra components:

  • FormattedDate: Formats locale-specific dates.
  • ForrmattedTime: Formats locale-specific times.
  • FormattedRelative: Formats locale-specific relative durations.
  • FormattedNumber: Formats locale-specific numbers and decimals.
  • FormattedPlural: Formats locale-specific plurals and quantities.

React-intl offers a good overall package for internationalizing your React Application. However, it is not without its disadvantages. You cannot use it for non-react components as it requires the top level component to inject the context to the children. We will see how the next library helps with providing a holistic solution to this problem.

React-intl-universal

react-intl-universal is a React internationalization package developed by Alibaba Group. It builds on top of React-intl by allowing non-React components use the library by providing a singleton object that can be used to load the current locale. Let’s see how we can use this library in our project.

Install it first:

Using the i18nConfig  We need to load the translations and pass them through the intl.init  method call:

Once we update the state we can render the App component:

Now the API for accessing those translations is simple:

It can also handle locale-specific messages for Times, Dates, Decimals and Plurals.

Having explored those 2 powerful libraries for localization, let’s see one more option that competes equally with the latter.

i18next

i18next aims to target high as it promises to give you a complete solution to localize your product from web to mobile and desktop. i18next is a plugin-based framework and provides you with plugins to:

  • detect the user language
  • load the translations
  • optionally cache the translations
  • extension, by using post-processing – e.g. to enable sprintf support.

It works well with small projects and scales when the project has many translation files to load.

Let’s see how we can use it in our React App.

Install it first:

Next, we need to create a file that will load our i18next configuration and any plugins we need to use. Let’s create a file named i18n.js  and put our translations there.

We needed to put some fallback translations so that we have at least English displayed. Also, we used a LanguageDetector  plugin that will use a variety of method to detect the clients supported languages.

Next, we need to update our root component to use this i18n config:

So now we are ready to go. Let’s see how we can use it in our main Home.js  component:

We need to wrap our component with the translate method passing our namespace. Then we have access to our translations. The Trans component enables you to nest any react content to be translated as one string. Supports both plural and interpolation.

We also added a little language switcher there. If you try to use it you may notice that the switch happens almost instantly and it does not reload the page.

i18next is a huge framework and it supports all the major javascript frameworks over there. I suggest you give it a try and see what a complete solution it is.

Conclusion

When it comes to internationalizing your React apps, it’s important to provide a holistic and future-proof solution that will not inhibit your development efforts. At the end of the day, it’s not just updating some JSON files. Fortunately, PhraseApp can make your life as a developer easier! To learn more about PhraseApp, please refer to the Getting Started guide.

If you found these libraries helpful, stay tuned on this blog for more articles related to this subject, because we are not there yet. I18n has a lot of factors you need to consider and great care has to be given in order to provide the best locale experience for your global community of users.

The Best Libraries for React i18n
Rate this post
Related Posts
Comments