Super fast React Localization (i18n) with i18next and Tolgee

Updated October 2026: the tutorial now uses Vite, React 19, i18next 26 and the current Tolgee SDK. Every step was tested on a fresh project.

So you build an app in React and you want people all over the world to use it, right? Then you need to translate it to their languages. 🇬🇧 🇨🇳 🇮🇹 🇪🇸 🇫🇷

In this article, I will show you how to add i18next and Tolgee to a React app, and how fast you can translate it with these tools.

Tolgee also has its own native React integration. It is a bit easier to set up, so if you don't use i18next yet, you may want to start there.

What is i18next?

i18next is a popular library for localizing apps. You call its t function with a key, and it returns the text in the current language. i18next can do much more, but let's keep it simple for this tutorial.

OK! And what is Tolgee?

Tolgee is an open-source localization platform with integrations for many frameworks. It makes translating web apps simple for both developers and translators. 👨‍💻👩‍💻

You manage all your strings in the Tolgee platform. But the best part is in-context translation: you hold Alt (⌥ Option on Mac), click any text in your running app, and edit the translation right there. No digging in JSON files. Anyone with access to your Tolgee project can do it, not only developers. You can also take screenshots from the app, so translators see where each string is used.

Let's start hacking!

Bootstrapping the app 🔥

We will use Vite to create the app. It's the simplest way to start a new React project today.

I use TypeScript. If you prefer plain JavaScript, use --template react instead. Open your terminal and run:

npm create vite@latest i18next-tolgee-demo -- --template react-ts
cd i18next-tolgee-demo
npm

Then install the packages for localization (i18n):

npm

Open the project in your favourite editor and replace the content of src/App.tsx with this:

function App() {
  return (
    <div style={{ padding: 40 }}>
      <h1>Hello world!</h1>
    </div>
  );
}

export default App;

You can also delete src/App.css and src/assets. We don't need the default Vite content.

Setting up a Tolgee project

Now we need a project in the Tolgee platform.

1. Log in to Tolgee Cloud or to your self-hosted Tolgee.

2. Click the + Project button. Fill in the project name and add the languages you want. In this tutorial, I use English (en) and Czech (cs).

3. Open Project settings → Advanced and turn on Use namespaces.

4. Open Integrate in the project menu, choose React, and in the Select API key step choose Create new.

5. Copy the key.

Don't skip step 3. i18next always keeps your strings in a namespace. The default one is called translation. Tolgee can only save keys with a namespace when namespaces are on in the project. If they are off, saving a translation from your app fails with "Failed to fetch". You can read more about namespaces in Tolgee.

Configuring i18next with Tolgee

First, create a file called .env.development.local in the project root. It holds the Tolgee configuration:

VITE_TOLGEE_API_URL=https://app.tolgee.io
VITE_TOLGEE_API_KEY

If you use self-hosted Tolgee, put the URL of your server in VITE_TOLGEE_API_URL.

Vite only loads this file when you run the dev server, so the API key never gets into your production build. The Vite template also ignores *.local files in git, so you won't commit the key by mistake.

Then create src/i18n.ts:

import i18n from 'i18next';
import ICU from 'i18next-icu';
import { initReactI18next } from 'react-i18next';
import { Tolgee, DevTools, I18nextPlugin, withTolgee } from '@tolgee/i18next';

const tolgee = Tolgee()
  .use(DevTools())
  .use(I18nextPlugin())
  .init({
    apiUrl: import.meta.env.VITE_TOLGEE_API_URL,
    apiKey: import.meta.env.VITE_TOLGEE_API_KEY,
  });

withTolgee(i18n, tolgee)
  .use(ICU)
  .use(initReactI18next)
  .init({
    lng: 'en',
    fallbackLng: 'en',
    supportedLngs: ['en', 'cs'],
  });

export default i18n;

Here is what it does:

• Tolgee() creates the Tolgee instance. DevTools() adds the in-context editing, and I18nextPlugin() lets Tolgee work with i18next.

• withTolgee connects i18next to Tolgee, so i18next gets its translations from Tolgee.

• ICU turns on the ICU message format, so you can use plurals and variables.

• Change supportedLngs to the language tags from your Tolgee project.

Now import this file in src/main.tsx and wrap <App /> in Suspense:

import { StrictMode, Suspense } from 'react';
import { createRoot } from 'react-dom/client';
import './i18n';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <Suspense fallback={<div>Loading...</div>}>
      <App />
    </Suspense>
  </StrictMode>
);

While the translations are loading, React shows the fallback.

Translating on steroids 💪

Now we can start translating. Go back to src/App.tsx, get the t function from the useTranslation hook, and use it in the JSX:

import { useTranslation } from 'react-i18next';

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

  return (
    <div style={{ padding: 40 }}>
      <h1>{t('hello_world', 'Hello world!')}</h1>
    </div>
  );
}

export default App;

The first parameter is the translation key. It is the unique ID of the string. I recommend adding where the string is used to the key. For example, if the text is in the settings, name it settings.hello_world. The second parameter is the default value. The app shows it when the key has no translation yet.

Start the dev server. If it's already running, restart it, so Vite loads the new .env file.

npm

Open the app in the browser. You should see the Hello world! 👋 message.

Now let's do some magic. 💫

Hold Alt (⌥ Option on Mac) and click the "Hello world!" text.

The quick translation dialog opens. Change the English text to "Hello universe!", add a Czech translation, and click Create. See? The text on the page changes right away.

If the dialog doesn't open, check the values in .env.development.local and restart the dev server. If the dialog opens but saving fails, make sure namespaces are on in your project (step 3 above).

Everything you save in the dialog is stored in the Tolgee platform, so you can edit it there too.

In the dialog, you can also edit more languages at once and add screenshots for your translators.

Your mama can translate like this 👵

Translating in this dialog or in the Tolgee platform is very simple. Anybody on your team can do it, even your mama. Want to save some time? Give people access to the Tolgee project, or to the app running in development mode, and let them translate.

But let's get back to the code.

Plurals and variables

Thanks to the ICU format, one string can handle plurals and variables. Add this line to App.tsx:

<p>
  {t('items_count', 'You have {count, plural, one {# item} other {# items}}', {
    count: 3,
  })}
</p>

It shows "You have 3 items". With count: 1 it shows "You have 1 item". Each language can have its own plural forms, and Tolgee lets translators fill them in.

Switching the language

To switch the language, create src/LangSelector.tsx:

import { useTranslation } from 'react-i18next';

export function LangSelector() {
  const { i18n } = useTranslation();

  return (
    <select
      value={i18n.language}
      onChange={(e) => i18n.changeLanguage(e.target.value)}
    >
      <option value="en">🇬🇧 English</option>
      <option value="cs">🇨🇿 Čeština</option>
    </select>
  );
}

And use it in the App component:

import { useTranslation } from 'react-i18next';
import { LangSelector } from './LangSelector';

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

  return (
    <div style={{ padding: 40 }}>
      <LangSelector />
      <h1>{t('hello_world', 'Hello world!')}</h1>
      <p>
        {t('items_count', 'You have {count, plural, one {# item} other {# items}}', {
          count: 3,
        })}
      </p>
    </div>
  );
}

export default App;

Great! Now you can switch the language. Pick Čeština and you will see the Czech text you added in the dialog.

Preparing for production

When you build your app for production, Tolgee leaves out the in-context tools automatically. Your users won't be able to edit translations, and your app won't call the Tolgee API with your key. So the app needs to get the translations from somewhere else. You have two options.

Option 1: Bundle the translation files

Download the translations with the Tolgee CLI and bundle them with your app. Install the CLI and pull the translations with your API key:

npm install --save-dev @tolgee/cli
TOLGEE_API_KEY=<your_api_key> npx tolgee pull --path

If you use self-hosted Tolgee, add --api-url <your Tolgee URL> to the pull command. In a CI pipeline, store the key as a secret in the TOLGEE_API_KEY environment variable.

The CLI saves one file per language and namespace:

Now tell Tolgee to use these files. Add staticData to the init call in src/i18n.ts:

const tolgee = Tolgee()
  .use(DevTools())
  .use(I18nextPlugin())
  .init({
    apiUrl: import.meta.env.VITE_TOLGEE_API_URL,
    apiKey: import.meta.env.VITE_TOLGEE_API_KEY,
    staticData: {
      'en:translation': () => import('./i18n/translation/en.json'),
      'cs:translation': () => import('./i18n/translation/cs.json'),
    },
  });

The keys have the format language:namespace. Thanks to the dynamic import(), the app only downloads a language when it needs it.

During development, Tolgee still loads the fresh translations from the platform. In production, it uses the files. To try it, build the app and preview it:

npm run build
npm

The app is translated, and it makes no requests to Tolgee. Run tolgee pull before every release, for example in your CI pipeline, so the files are always up to date.

Option 2: Tolgee Content Delivery

If you want to update translations without a new release, use Tolgee Content Delivery. Tolgee publishes your translations to fast storage, and your app loads them from there. The i18next docs show how to set it up.

Congrats! 🎉 Now you can localize your React app much faster!

TL;DR

In this article, you learned how to use the Tolgee open-source localization platform with i18next in a React app. Here is a short summary:

• Set up i18next with withTolgee and the Tolgee() instance from @tolgee/i18next.

• Turn on namespaces in your Tolgee project, because i18next always uses one.

• Hold Alt (⌥ Option on Mac) and click any text in your app to translate it in context. Anyone with access to the project can do it.

• For production, download the translations with tolgee pull and pass them as staticData, or use Tolgee Content Delivery.

• If you like our project, please star it on GitHub:

  • github.com/tolgee/tolgee-platform ⭐

  • github.com/tolgee/tolgee-js ⭐

• To learn more about the i18next integration, read the Tolgee docs.