Skip to content
Get packs

Guide · Open source

How to use react-i18next: install, translate and use Trans

Updated · written with AI from the project's own documentation and checked against our catalogue data

react-i18next is a JavaScript library that lets React apps show text in several languages. It connects React components to the i18next translation engine: you mark each string with a key, and the library displays the matching translation for the user's language. This guide walks through installing it, replacing hardcoded text with translation keys, and using the Trans component for text that mixes markup and variables.

react-i18nexti18next/react-i18next · ★ 10.1k · MIT

Quick start

  1. 1Check your versions. Confirm React 16.8.0 or higher and i18next 10.0.0 or higher. TypeScript users need i18next 17.0.9 or higher.
  2. 2Install the package. Run npm install react-i18next in your project folder.
  3. 3Mark your strings. Replace hardcoded text with t() calls that use a translation key.
  4. 4Use Trans for mixed content. Wrap sentences that contain markup or variables in the Trans component with an i18nKey.
  5. 5Add your translations. Store the translated text for each key in your translation files, one set per language.
  6. 6Check the example projects. Compare your setup with the React and TypeScript examples in the repository's example folder.

Check the requirements before you install

The README lists the minimum versions you need. React and react-dom must be 16.8.0 or higher, because the library uses hooks. i18next must be 10.0.0 or higher, and TypeScript users need 17.0.9 or higher. For React Native, the README says you must use react-native 0.59.0 or higher to use hooks.

  • Node.js and npm, needed to install the package
  • React 16.8.0 or higher (react-dom as well)
  • i18next 10.0.0 or higher (TypeScript: 17.0.9 or higher)
  • React Native projects: react-native 0.59.0 or higher

Install react-i18next with npm

The README installs the library from npm. Run the following command in your project folder.

  • If you don't use a module loader, the library is added to window.reactI18next instead.
npm install react-i18next

Replace hardcoded strings with t() and keys

Instead of writing text directly in your components, give each string a key and pass the key to t(). The library looks up the key in your translation files and shows the translation for the user's language.

The README's example turns a plain line of text into a call to t() with a key such as simpleContent.

<div>{t('simpleContent')}</div>

Use the Trans component for mixed markup and variables

Some text contains HTML-like elements, links and values mixed together. The Trans component handles this case. You give it an i18nKey, pass variables such as count, and wrap the sentence in the component. Variables are written inside double braces, and attributes can still use t() for their own translated text.

The README describes the Trans component as the way to handle text that mixes markup and variables. Compare its before and after examples to see how the original sentence is rewritten.

  • Set i18nKey to the key that stores the translated sentence
  • Pass values such as count as props
  • Write variables inside the sentence as double braces, for example {{name}}
  • Use t() inside attributes, for example title={t('nameTitle')}
<Trans i18nKey="userMessagesUnread" count={count}> Hello <strong title={t('nameTitle')}>{{name}}</strong>, you have {{count}} unread message. <Link to="/msgs">Go to messages</Link>. </Trans>

Choose the right version

The master branch is the newest version and uses hooks, for version 10 and above. The README says the legacy version is on a separate v9.x.x branch, and it is installed with the legacy tag. If you are starting a new project, use the default npm install command shown above.

For more detailed walkthroughs and examples, the README links to a step-by-step tutorial on the Locize blog, and to example projects in the example folder of the repository, including a React example and a TypeScript example.

  • Current version: npm install react-i18next (hooks, v10 and above)
  • Legacy version: npm install react-i18next@legacy (v9.x.x branch)

Know what the library does and does not do

react-i18next handles the front-end display of translations. The README also describes i18next's server-side support for Node.js, PHP, Ruby and .NET, so teams can use the same approach across their stack.

Translation files are still something you manage. The README notes that a managed service is optional. It recommends Locize as a paid add-on for teams that do not want to manage translation files by hand, and states that i18next works fully without it.

What people use it for

  • Adding a language switcher to a React web app so visitors see the interface in their own language
  • Translating sentences that include links, bold text and counts, such as unread message notices
  • Using the same i18next setup across a React front end and a server-side i18next service
  • Localizing a React Native app, provided the project uses react-native 0.59.0 or higher

Frequently asked questions

Is react-i18next free to use?

react-i18next is released under the MIT licence, as stated in the project's metadata. Locize is a separate, optional paid service that the README promotes, and i18next works fully without it.

What are the requirements for react-i18next?

The README lists React 16.8.0 or higher, react-dom 16.8.0 or higher, i18next 10.0.0 or higher, and TypeScript users need i18next 17.0.9 or higher. React Native users need react-native 0.59.0 or higher to use hooks.

How do I install react-i18next?

Run npm install react-i18next in your project. If you do not use a module loader, the README says the library is added to window.reactI18next.

What is the Trans component used for?

The Trans component is for text that mixes markup, such as bold text or links, with variables like counts. You pass an i18nKey and write variables inside double braces.

Does react-i18next work with React Native?

Yes, the README says it works with React and React Native. For hooks in React Native, you need react-native 0.59.0 or higher.

What should I use instead of react-i18next?

The source names comparable projects: react-intl, lingui, next-i18next and react-polyglot. Pick based on whether you need the i18next ecosystem, server-side support or a different API style.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

react-i18next suits React and React Native developers who need an app in several languages, especially teams already using i18next or planning server-side i18next too. It is not for non-React projects, for teams stuck on the legacy v9 API, or for anyone who wants a managed translation service as a required part of the stack.

Install options & downloads