On this page
Getting started
Your first translated React component, with i18next set up once for the whole app.
Using a coding agent? Paste this prompt into Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI or any agent that can run terminal commands:
Localize this app with i18next.
Run `npx i18next-cli localize --print-agent-prompt` and follow
the steps it prints, in order, checking each one before the next.
Your agent wraps the texts in t() and writes the translation files; you review the diff, and the translation files stay in your repository unless you choose a translation management service. ⇒ What the prompt tells your agent
Installation
npm install react-i18next i18next
Script tags from a CDN (load i18next's UMD build before react-i18next's), Deno and the supported browsers: Environments.
Configure i18next
Create a file i18n.js beside your index.js:
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
// the translations (the next section moves them into files)
const resources = {
en: {
translation: {
welcome: 'Welcome to React and react-i18next'
}
},
fr: {
translation: {
welcome: 'Bienvenue à React et react-i18next'
}
}
};
i18n
.use(initReactI18next) // passes i18n down to react-i18next
.init({
resources,
lng: 'en', // if you're using a language detector, do not define lng
interpolation: {
// React escapes what it renders; escape t() output yourself
// before dangerouslySetInnerHTML
escapeValue: false
}
});
export default i18n;
Any file name works if you import it accordingly. i18n.use(initReactI18next) passes the instance to react-i18next, which makes it available to all components.
Then import it in index.js:
import { createRoot } from 'react-dom/client';
import './i18n';
import App from './App';
createRoot(document.getElementById('root')).render(<App />);
Outside a component, import your i18n.js and call i18n.t('welcome').
React Native or Expo: the same setup, plus a polyfill for plurals on Hermes, see React Native and Expo.
Translation files
To keep the translations out of your code, load them from files and detect the user's language:
npm install i18next-http-backend i18next-browser-languagedetector
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import Backend from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';
i18n
.use(Backend) // loads /locales/<language>/translation.json
.use(LanguageDetector) // detects the user's language
.use(initReactI18next)
.init({
fallbackLng: 'en',
debug: true, // logs what i18next does; turn off in production
interpolation: {
// React escapes what it renders; escape t() output yourself
// before dangerouslySetInnerHTML
escapeValue: false
}
});
export default i18n;
Create a file public/locales/<language>/translation.json per language, for example:
{
"welcome": "Welcome to React and react-i18next"
}
The React example has a full set. The http backend loads the files while your app renders, so wrap your components in React's Suspense (next section).
Translate your content
Simple content
Before:
<div>Welcome</div>
After:
<div>{t('welcome')}</div>
You get the t function from the useTranslation hook (below). It is the main function of i18next; Essentials lists all its options.
Using the useTranslation hook
import { Suspense } from 'react';
import { useTranslation } from 'react-i18next';
function MyComponent() {
const { t } = useTranslation();
return <h1>{t('welcome')}</h1>;
}
// the http backend may still be loading the translations
export default function App() {
return (
<Suspense fallback="loading">
<MyComponent />
</Suspense>
);
}
The hook takes a namespace or an array of namespaces to load. The t function is bound to the default namespace defined on i18next init, or to the first one passed in.
const { t, i18n } = useTranslation('common');
const { t, i18n } = useTranslation(['page1', 'common']);
Learn more about the hook useTranslation.
Markup and links with Trans
To keep markup or a link inside a translation, use the Trans component. Keep the whole sentence in one string: translators need it to get the result right.
Before:
<div>
Hello <strong>{name}</strong>, you have {count} unread
message(s). <Link to="/msgs">Go to messages</Link>.
</div>
After:
<Trans i18nKey="userMessagesUnread" count={count}>
Hello <strong>{{ name }}</strong>, you have {{ count }} unread
messages. <Link to="/msgs">Go to messages</Link>.
</Trans>
With count, the translation file holds one form per plural; see Plurals.
Learn more about the Trans component.
Next steps
Prefer having code to check out? The React example uses a browser language detector and an http backend to load the translations.
Then read on: the useTranslation hook, the Trans component and namespaces in components. Class components, the older way, get t as a prop from withTranslation.
To move the texts from your components into the translation files, run i18next-cli extract: Extracting translations. With TypeScript, the keys can be typed, so a typo fails at compile time: Typed keys.