DEV Community

Cover image for Super fast React Localization ๐ŸŒ (i18n) with i18next and Tolgee ๐Ÿ
Tolgee profile image Jan Cizmar
Jan Cizmar Subscriber for Tolgee

Posted on • Originally published at tolgee.io

Super fast React Localization ๐ŸŒ (i18n) with i18next and Tolgee ๐Ÿ

#webdev #react #javascript #typescript

So you develop an app in React and you want many users to use it, right? To make your app usable for users in foreign countries, you have to translate your App to their languages. ๐Ÿ‡ฌ๐Ÿ‡ง ๐Ÿ‡จ๐Ÿ‡ณ ๐Ÿ‡ฎ๐Ÿ‡น ๐Ÿ‡ช๐Ÿ‡ธ ๐Ÿ‡ซ๐Ÿ‡ท

In this article, I am going to show you, how to integrate i18next and Tolgee into your project and how easy and fast you can translate a React app using these tools.

Tolgee has also its native integrations. Which are a bit easier to set up, so if you're not used to i18next, maybe it would be easier for you to [start with those (http://tolgee.io/docs/web/using_with_react/installation/docs/web/using_with_react/installation).

What is i18next?

i18next is a library enabling you to localize your app. Basically, you are calling methods of this library providing keys to be translated. The methods return value in specified language retrieved from localization files. There is much more about i18next, but let's keep it simple for this tutorial. You can read more about i18next here.

OK! And what is Tolgee?

Tolgee is an open-source tool combining localization platform and integrations to provide a simple way to translate the web
applications for both developers and translators. ๐Ÿ‘จโ€๐Ÿ’ป๐Ÿ‘ฉ๐Ÿปโ€๐Ÿ’ป๐Ÿง–๐Ÿผ๐Ÿ‘ฉ๐Ÿปโ€๐Ÿ’ป๐Ÿง–๐Ÿผ

Tolgee Localization Platform is a place, where you can manage all your localization strings in the simple UI. It's made to simplify the localization process as much as possible. With Tolgee you can translate the localization strings directly in the application you develop without editing localization data files. You can also automatically generate screenshots from your app, which can be used in the future by translators of your project.

So let's dive in to the hacking!

Bootstrapping the App ๐Ÿ”ฅ

I am going to use Create React App for this, since it's the simplest way to bootstrap a React app.

Dwight

I am going to use Typescript, but if you're JavaScript purist, remove the --template typescript part. Open your terminal and command it to execute...

npx create-react-app@5.0.0 i18next-tolgee-demo --template typescript && cd i18next-tolgee-demo
Enter fullscreen mode Exit fullscreen mode

Then install packages necessary for the localization (i18n).

npm install react-i18next i18next-icu i18next @tolgee/i18next @tolgee/ui
Enter fullscreen mode Exit fullscreen mode

If the process succeeded we are prepared to start hacking! ๐Ÿ˜Ž

Open the project in your favourite editor, and go to App.tsx and replace all the crap with this:

import React from 'react';
import './App.css';

function App() {
  return (
    <div className="App">
      <h1>
        Hello world!
      </h1>
    </div>
  );
}

export default App;
Enter fullscreen mode Exit fullscreen mode

We don't need the default CRA content.

Setting up a Tolgee project

To get started, we are going to need a new project in Tolgee Platform.

  1. Login to Tolgee Platform or use your
    self-hosted Tolgee instance.

  2. Create a new project by clicking Add button in the top right. And fill the project name.

Add button

Optionally, you can add multiple languages to translate your app into.

  1. Expand your user menu in top right corner and choose API keys.

Project menu

  1. Hit plus button, then leave all checkboxes checked and click save.

  2. Done. You have obtained your API key!

Configuring i18next with Tolgee

First, let's create a file called .env.development.local in the project root. This file contains our Tolgee configuration.

REACT_APP_TOLGEE_API_URL=https://app.tolgee.io
REACT_APP_TOLGEE_API_KEY=<your_api_key>
Enter fullscreen mode Exit fullscreen mode

Then go to index.tsx and configure i18n object from i18next library.

import {withTolgee} from '@tolgee/i18next';
import i18n from "i18next";
import ICU from 'i18next-icu';
import {initReactI18next} from "react-i18next";

withTolgee(i18n, {
  apiUrl: process.env.REACT_APP_TOLGEE_API_URL,
  apiKey: process.env.REACT_APP_TOLGEE_API_KEY,
  ui: process.env.REACT_APP_TOLGEE_API_KEY
    ? require('@tolgee/ui').UI
    : undefined,
})
  .use(ICU)
  .use(initReactI18next)
  .init({
    supportedLngs: ['en', 'cs'],
    fallbackLng: 'en'
  });
Enter fullscreen mode Exit fullscreen mode

This sets Tolgee as translation provider for i18next and enables ICU message formatter. Change supportedLngs to language tags you created while creating project in Tolgee platform.

Then wrap your <App/> component with Suspens component.

<Suspense fallback={<div>Loading...</div>}>
  <App/>
</Suspense>
Enter fullscreen mode Exit fullscreen mode

So when translations are loading, fallback is rendered.

Translating on steroids ๐Ÿ’ช

Now we can start translating. Let's go to App.tsx again and obtain t function by calling useTranslation hook. Then use the t function in the returned JSX.

function App() {
  const {t} = useTranslation()

  return (
    <div className="App">
      <h1>
        {t('hello_world', 'Hello world!')}
      </h1>
    </div>
  );
}
Enter fullscreen mode Exit fullscreen mode

The first parameter is the translation key, which is a unique identifier of the string. Normally I would recommend to also provide some information about the placing of the string in the app. So if the text is for example placed in settings, it would be good practice naming it settings.hello-world. The second parameter is default value, which is going to be rendered, when no translation is provided in localization data.

Now start the dev server or restart it, if you already started, so the .env properties are refreshed.

npm run start
Enter fullscreen mode Exit fullscreen mode

After project is built, open it in the browser. You should see Hello world! ๐Ÿ‘‹ message.

Now let's do some the magic. ๐Ÿ’ซ

Project menu

Click on the "Hello world!" text while holding Alt key or โŒฅ key on Mac.

Quick translation appears if everything is configured well. If not, double-check your .env.development.local and check the properties are accessible in the browser by printing them to console using console.log().

In context dialog

In the quick translation dialog, try to change the value to something else like "Hello universe!" and hit save. See? The text was changed in the DOM as well.

String saved or edited in the translation dialog is stored in the platform, so you can edit there as well.

Platform

You can also edit more languages in the quick translation dialog. Also, you can take screenshots, which can be later used by translators, translating your strings in Tolgee platform.

In context dialog2

Your mama can translate like this ๐Ÿ‘ต

Translating using this dialog or Tolgee platform is very simple so anybody from your team or even your mama can translate your app like this. So when you would like to save some time, you can just provide access to the platform or/and to the app in development mode and let anybody translate it.

But let's get back to the code.

Switching the language

To be able to switch the language, create following LanguageSelector component.

import React from 'react';
import {useTranslation} from 'react-i18next';

export const LangSelector: React.FC = () => {
  const {i18n} = useTranslation();

  return (
    <select
      className="lang-selector"
      onChange={(e) => i18n.changeLanguage(e.target.value)}
      value={i18n.language}
    >
      <option value="en">๐Ÿ‡ฌ๐Ÿ‡ง English</option>
      <option value="cs">๐Ÿ‡จ๐Ÿ‡ฟ ฤŒesky</option>
    </select>
  );
};
Enter fullscreen mode Exit fullscreen mode

And use it in the App component...

<div className="App" style={{padding: 40}}>
  <LangSelector/>
  <h1>
    {t(`hello_world`)}
  </h1>
</div>
Enter fullscreen mode Exit fullscreen mode

Great! Now you are able to switch the language!

Language switching

Preparing for production

In production mode you don't want to leak you API key. You want your translations to be part of the production build. There are multiple options to obtain your exported localization files.

Option 1: Using Tolgee Platform

  1. Open your project in the Tolgee Platform
  2. Click on "Export" item in the side menu
  3. Hit "Export as zip of .json files" button
  4. Download of exported data starts immediately

Option 2: Using API endpoint

If you have curl installed in your system, you can download the data using it.

curl "https://app.tolgee.io/api/project/export/jsonZip?ak=<YOUR API KEY>" \
--output data.zip
unzip data.zip
delete data.zip
Enter fullscreen mode Exit fullscreen mode

This is useful, when you would like to automate localization data downloading in our CI/CD workflow.

Using the data

To use your exported data, store them into src/i18n folder. So your project structure would look like this:

src
...
โ”œโ”€โ”€ App.tsx
โ”œโ”€โ”€ LangSelector.tsx
โ”œโ”€โ”€ i18n
โ”‚ย ย  โ”œโ”€โ”€ cs.json
โ”‚ย ย  โ””โ”€โ”€ en.json
โ”œโ”€โ”€ index.css
โ”œโ”€โ”€ index.tsx
...
Enter fullscreen mode Exit fullscreen mode

Now, lets provide the data to Tolgee. There are multiple ways, how to do so described in docs. But I am going to provide them as imported static objects, which is good option, since the App is small and there are not many translations yet.

Go to the index.tsx file and import the localization jsons:

import enLang from "./i18n/en.json"
import csLang from "./i18n/cs.json"
Enter fullscreen mode Exit fullscreen mode

And then provide them to Tolgee config.

withTolgee(i18n, {
  apiUrl: process.env.REACT_APP_TOLGEE_API_URL,
  apiKey: process.env.REACT_APP_TOLGEE_API_KEY,
  ui: process.env.REACT_APP_TOLGEE_API_KEY
    ? require('@tolgee/ui').UI
    : undefined,
  staticData: {
    en: enLang,
    cs: csLang
  }
})
  .use(ICU)
  .use(initReactI18next)
  .init({
    supportedLngs: ['en', 'cs'],
    fallbackLng: 'en'
  });
Enter fullscreen mode Exit fullscreen mode

To test it works, you can comment out the apiKey param. App should be translated without fetching the data from Tolgee API.

Congrats! ๐ŸŽ‰ Now you are able to speed up your localization process!

TL;DR

  • Tolgee is an open-source tool, simplifying localization process and removing unnecessary tasks
  • It enables you or your colleagues to modify translated string in the context of developed web application
  • Tolgee is also a localization platform, where you can manage all your translations
  • If you like our project, please star our projects on GitHub
  • To read more about i18next Tolgee integration, visit Tolgee docs

Top comments (0)

Read next

nikl profile image

How I Supercharged Cursor Editor with Pieces and Unlimited AI?

Nik L. -

programmerraja profile image

Code Against the Clock: How I Enhanced My Scrum Master Productivity

Boopathi -

torver213 profile image

Dark mode & light mode in next. Js 14 app router with material-ui without ui flickering

Peter Kelvin Torver -

charan_sajjanapu profile image

Evolution of Web Tech and Browsers

Charan Sajjanapu -