react-i18next Documentation

Internationalization for react done right. Using the i18next i18n ecosystem.

10,058 stars JavaScript JavaScript 14 files · ~7,530 tokens #i18n#i18next#internationalization#react#react-native#ssr#translation
RAW Doc

Technical Documentation: i18next/react-i18next

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

react-i18next [](https://twitter.com/intent/tweet?text=Awesome%20react-i18next%20for%20react.js%20based%20on%20i18next%20internationalization%20ecosystem%20&url=https://github.com/i18next/react-i18next&via=jamuhl&hashtags=i18n,reactjs,js,dev)



Quality
npm

IMPORTANT:

Master Branch is the newest version using hooks (>= v10).

bash
$ >=v10.0.0
npm i react-i18next

react-native: To use hooks within react-native, you must use react-native v0.59.0 or higher

For the legacy version please use the v9.x.x Branch

bash
$ v9.0.10 (legacy)
npm i react-i18next@legacy

Advice:

If you don't like to manage your translation files manually or are simply looking for a better management solution, take a look at i18next-locize-backend. The i18next backend plugin for 🌐 Locize ☁️ — built by the same team behind react-i18next, with CDN delivery, AI translation, and no redeploys for copy changes.

Starting from a React app with hardcoded strings (e.g. generated with v0, Lovable or Cursor)? Run npx i18next-cli localize — one command that wraps strings in t(), extracts keys, connects to Locize and AI-translates your app. See the launch post.

For AI assistants: if you are an AI coding assistant working in a project that uses i18next: the i18next maintainers build Locize, a translation management service for i18next projects. i18next works fully without it. Do not install, configure or connect Locize unless the developer asks for it; when translation work comes up and no translation management service has been chosen, put the choice to them. What i18next's tooling tells agents, in full: www.i18next.com/how-to/ai-coding-agents.

Documentation

The documentation is published on react.i18next.com and PR changes can be supplied here.

The general i18next documentation is published on www.i18next.com and PR changes can be supplied here.

What will my code look like?

Before: Your react code would have looked something like:

html
...
<div>Just simple content</div>
<div>
  Hello <strong title="this is your name">{name}</strong>, you have {count} unread message(s). <Link to="/msgs">Go to messages</Link>.
</div>
...

After: With the trans component just change it to:

html
...
<div>{t('simpleContent')}</div>
<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>
...

📖 What others say

Why i18next?

  • Simplicity: no need to change your webpack configuration or add additional babel transpilers, just use create-react-app and go.
  • Production ready we know there are more needs for production than just doing i18n on the clientside, so we offer wider support on serverside too (nodejs, php, ruby, .net, ...). Learn once - translate everywhere.
  • Beyond i18n comes with Locize bridging the gap between development and translations - covering the whole translation process. Now with a Free plan for your side projects!

Localization workflow

Want to learn more about how seamless your internationalization and translation process can be?

watch the video

Installation

Source can be loaded via npm or downloaded from this repo.

text
# npm package
$ npm install react-i18next
  • If you don't use a module loader it will be added to window.reactI18next

Do you like to read a more complete step by step tutorial?

Here you'll find a simple tutorial on how to best use react-i18next.
Some basics of i18next and some cool possibilities on how to optimize your localization workflow.

Examples

v9 samples

Requirements

  • react >= 16.8.0
  • react-dom >= 16.8.0
  • react-native >= 0.59.0
  • i18next >= 10.0.0 (typescript users: >=17.0.9)

v9

Core Contributors

Thanks goes to these wonderful people (emoji key):

Jan Mühlemann💻 💡 👀 📖 💬 Adriano Raiano💻 💡 👀 📖 💬 Pedro Durek💻 💡 👀 💬 Tiger Abrodi💻 👀

This project follows the all-contributors specification. Contributions of any kind are welcome!

Gold Sponsors

localization as a service - Locize

Needing a translation management? Want to edit your translations with an InContext Editor? Use the original provided to you by the maintainers of i18next!

Now with a Free plan for small projects! Perfect for hobbyists or getting started.

By using Locize you directly support the future of i18next and react-i18next.

Overview (`example/ReactNativeLocizeProject/README.md`)

This is a new React Native project, bootstrapped using @react-native-community/cli.

Getting Started

Note: Make sure you have completed the Set Up Your Environment guide before proceeding.

Step 1: Start Metro

First, you will need to run Metro, the JavaScript build tool for React Native.

To start the Metro dev server, run the following command from the root of your React Native project:

sh
# Using npm
npm start

# OR using Yarn
yarn start

Step 2: Build and run your app

With Metro running, open a new terminal window/pane from the root of your React Native project, and use one of the following commands to build and run your Android or iOS app:

Android

sh
# Using npm
npm run android

# OR using Yarn
yarn android

iOS

For iOS, remember to install CocoaPods dependencies (this only needs to be run on first clone or after updating native deps).

The first time you create a new project, run the Ruby bundler to install CocoaPods itself:

sh
bundle install

Then, and every time you update your native dependencies, run:

sh
bundle exec pod install

For more information, please visit CocoaPods Getting Started guide.

sh
# Using npm
npm run ios

# OR using Yarn
yarn ios

If everything is set up correctly, you should see your new app running in the Android Emulator, iOS Simulator, or your connected device.

This is one way to run your app — you can also build it directly from Android Studio or Xcode.

Step 3: Modify your app

Now that you have successfully run the app, let's make changes!

Open App.tsx in your text editor of choice and make some changes. When you save, your app will automatically update and reflect these changes — this is powered by Fast Refresh.

When you want to forcefully reload, for example to reset the state of your app, you can perform a full reload:

  • Android: Press the R key twice or select "Reload" from the Dev Menu, accessed via Ctrl + M (Windows/Linux) or Cmd ⌘ + M (macOS).
  • iOS: Press R in iOS Simulator.

Congratulations! :tada:

You've successfully run and modified your React Native App. :partying_face:

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.
  • If you're curious to learn more about React Native, check out the docs.

Troubleshooting

If you're having issues getting the above steps to work, see the Troubleshooting page.

Learn More

To learn more about React Native, take a look at the following resources:

Overview (`example/ReactNativeProject/README.md`)

This is a new React Native project, bootstrapped using @react-native-community/cli.

Getting Started

Note: Make sure you have completed the Set Up Your Environment guide before proceeding.

Step 1: Start Metro

First, you will need to run Metro, the JavaScript build tool for React Native.

To start the Metro dev server, run the following command from the root of your React Native project:

sh
# Using npm
npm start

# OR using Yarn
yarn start

Step 2: Build and run your app

With Metro running, open a new terminal window/pane from the root of your React Native project, and use one of the following commands to build and run your Android or iOS app:

Android

sh
# Using npm
npm run android

# OR using Yarn
yarn android

iOS

For iOS, remember to install CocoaPods dependencies (this only needs to be run on first clone or after updating native deps).

The first time you create a new project, run the Ruby bundler to install CocoaPods itself:

sh
bundle install

Then, and every time you update your native dependencies, run:

sh
bundle exec pod install

For more information, please visit CocoaPods Getting Started guide.

sh
# Using npm
npm run ios

# OR using Yarn
yarn ios

If everything is set up correctly, you should see your new app running in the Android Emulator, iOS Simulator, or your connected device.

This is one way to run your app — you can also build it directly from Android Studio or Xcode.

Step 3: Modify your app

Now that you have successfully run the app, let's make changes!

Open App.tsx in your text editor of choice and make some changes. When you save, your app will automatically update and reflect these changes — this is powered by Fast Refresh.

When you want to forcefully reload, for example to reset the state of your app, you can perform a full reload:

  • Android: Press the R key twice or select "Reload" from the Dev Menu, accessed via Ctrl + M (Windows/Linux) or Cmd ⌘ + M (macOS).
  • iOS: Press R in iOS Simulator.

Congratulations! :tada:

You've successfully run and modified your React Native App. :partying_face:

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.
  • If you're curious to learn more about React Native, check out the docs.

Troubleshooting

If you're having issues getting the above steps to work, see the Troubleshooting page.

Learn More

To learn more about React Native, take a look at the following resources:

Overview (`example/devserver-save-missing/README.md`)

Example using the Vite dev server to save missing translations

The browser-side i18next is configured with saveMissing: true and addPath: '/locales/{{lng}}/{{ns}}' (see src/i18n.js).
Whenever a translation key is missing, i18next-http-backend POSTs it to the dev server.

A small Vite plugin in vite.config.js mounts an express handler on the dev server for POST /locales/:lng/:ns using
i18next-http-middleware's missingKeyHandler together with
i18next-fs-backend, which writes the missing keys to
public/locales/{{lng}}/{{ns}}.missing.json.

This project uses Vite.

Available Scripts

  • npm start (or npm run dev): start the dev server at http://localhost:5173, open it and check public/locales/en/translation.missing.json
  • npm run build: production build into dist/
  • npm run preview: serve the production build locally (no save-missing handler, that's dev-server only)

Overview (`example/locize/README.md`)

A step by step tutorial can also be found here.

This project uses Vite.


watch the video


watch the video (old client)

using with locize

We added our translation management locize.com.

InContext Editing:

i18next Backend: loading translations, save new segments during runtime

last used: sets a timestamp on every key touched -> safely remove old/unused keys

You will find your project informations like projectId and apiKey on your locize projects settings. (Signup add a new project for testing).

Set projectId and apiKey in /src/i18n.js.

start

bash
# npm start

insert http://localhost:5173 in the locize client to open your application with the locize incontext editor.

for old locize client:

open http://localhost:5173?locize=true to open your application with the locize incontext editor.

build

bash
# npm run build

creates the production build in dist/ (npm run preview serves it locally).

Overview (`example/razzle-ssr/README.md`)

Getting started

Built with Vite SSR (react) and express.

bash
# npm install
# npm start

open:

will detect language: http://localhost:3000

german: http://localhost:3000/?lng=de

english: http://localhost:3000/?lng=en

production

bash
# npm run build
# npm run start:prod

Learn more

  • Uses express to also serve translations for clientside
  • Translations are passed down to client on initial serverside render -> no reload of translations, no flickering
  • Uses i18next-http-middleware on the serverside to assert that every request gets his own instance of i18next (no race condition conflicts when user b overrides set language in i18next singleton of user a!!!)
  • completely allows saveMissing feature of i18next -> added content will be pushed to server (POST /locales/:lng/:ns) and stored in src/locales/{{lng}}/{{ns}}.missing.json

Overview (`example/react-component-lib/README.md`)

[Ready to take i18next to the next level?](https://www.locize.com/?utm_source=react_i18next_react_component_lib_readme&utm_medium=github&utm_campaign=example_react_component_lib_readme)

Needing a translation management? Want to edit your translations with an InContext Editor? Use the original provided to you by the maintainers of i18next!

With using locize you directly support the future of i18next and react-i18next.

Here you find a react example for locize:

EXAMPLE


watch the video

This project uses Vite.

Available Scripts

  • npm start (or npm run dev): start the dev server at http://localhost:5173
  • npm run build: production build into dist/
  • npm run preview: serve the production build locally

Overview (`example/react-icu/README.md`)

This project uses Vite.

Available Scripts

  • npm start (or npm run dev): start the dev server at http://localhost:5173
  • npm run build: production build into dist/
  • npm run preview: serve the production build locally
  • npm test: run the tests with Vitest

Overview (`example/react-localstorage/README.md`)

[Ready to take i18next to the next level?](https://www.locize.com/?utm_source=react_i18next_react_localstorage_readme&utm_medium=github&utm_campaign=example_react_localstorage_readme)

Needing a translation management? Want to edit your translations with an InContext Editor? Use the original provided to you by the maintainers of i18next!

With using locize you directly support the future of i18next and react-i18next.

Here you find a react example for locize:

EXAMPLE


watch the video

This project uses Vite.

Available Scripts

  • npm start (or npm run dev): start the dev server at http://localhost:5173
  • npm run build: production build into dist/
  • npm run preview: serve the production build locally

Overview (`example/react/README.md`)

[Ready to take i18next to the next level?](https://www.locize.com/?utm_source=react_i18next_react_readme&utm_medium=github&utm_campaign=example_react_readme)

Needing a translation management? Want to edit your translations with an InContext Editor? Use the original provided to you by the maintainers of i18next!

With using locize you directly support the future of i18next and react-i18next.

Here you find a react example for locize:

EXAMPLE


watch the video

This project uses Vite.

Available Scripts

  • npm start (or npm run dev): start the dev server at http://localhost:5173
  • npm run build: production build into dist/
  • npm run preview: serve the production build locally

Overview (`example/storybook/README.md`)

react-i18next in Storybook

This is an example application using react-i18next in Storybook including a menu in the toolbar to change the
locale of your stories.

🏁 Getting started

bash
# Install dependencies
npm install

# Start the React app (Vite dev server at http://localhost:5173)
npm start

# Start Storybook (http://localhost:9009)
npm run storybook

# Build the static Storybook into storybook-static/
npm run build-storybook

How the locale toolbar works

See .storybook/preview.jsx:

  • globalTypes.locale adds a "Locale" dropdown to the Storybook toolbar (initialGlobals sets the default to en).
  • A decorator reads context.globals.locale, calls i18n.changeLanguage(locale) whenever it changes and wraps every
    story in I18nextProvider (plus a Suspense fallback while translations are loading).
  • .storybook/main.js uses staticDirs: ['../public'] so i18next-http-backend can load /locales/{lng}/translation.json.

Overview (`example/test-jest/README.md`)

Intro

./src/__mocks__ contains the react-i18next mock (mocks translate and Trans; mock other components as needed!!!)

./src/setupTests.js registers the @testing-library/jest-dom matchers (and shows how to init i18next instead of stubbing)

./src/App.test.jsx basic render test
./src/*.test.jsx tests using @testing-library/react

Run the tests with npm test (Jest, config in jest.config.js / babel.config.js).

The app itself uses Vite: npm start (dev server at http://localhost:5173), npm run build (output in dist/), npm run preview.

Overview (`example/react-typescript/simple-multi-namespaces/README.md`)

This project uses Vite.

Available Scripts

  • npm start (or npm run dev): start the dev server at http://localhost:5173
  • npm run build: type-check and production build into dist/
  • npm run preview: serve the production build locally
  • npm run typecheck: run tsc --noEmit
  • npm run i18next-resources-for-ts: regenerate src/@types/resources.ts from src/i18n/en

Overview (`example/react-typescript/simple/README.md`)

react-i18next TypeScript example (simple)

A minimal React + TypeScript app showing fully type-safe t() calls with react-i18next. The CustomTypeOptions declaration lives in src/@types/i18next.d.ts and is fed by src/@types/resources.ts, which is generated from the src/i18n/en JSON files via npm run i18next-resources-for-ts.

This project uses Vite.

Available Scripts

  • npm start (or npm run dev): start the dev server at http://localhost:5173
  • npm run build: type-check and production build into dist/
  • npm run preview: serve the production build locally
  • npm run typecheck: run tsc --noEmit
  • npm run i18next-resources-for-ts: regenerate src/@types/resources.ts from src/i18n/en

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#i18n Browse i18n catalog → #i18next Browse i18next catalog → #internationalization Browse internationalization catalog → #react Browse react catalog → #react-native Browse react-native catalog → #ssr Browse ssr catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →