react-i18next is the most widely used way to translate a React app, and also one of the easiest to set up in a way that bites you later: a blank screen from a missing Suspense boundary, plurals that only work in English, or every language bundled into the main chunk. This tutorial builds a complete setup for a Vite + React + TypeScript app on the current releases (i18next v26 and react-i18next v17), from install to tests, and explains why each piece is there.
Install i18next and react-i18next, initialize i18next once with initReactI18next, a fallback language, and your translation resources, then call const { t } = useTranslation() in components. Add i18next-browser-languagedetector to pick the user's language and i18next-http-backend to load translation files on demand, wrap the app in <Suspense>, and type your keys with CustomTypeOptions.
| Package | Current major | Role |
|---|---|---|
i18next |
v26 | Framework-agnostic core: resources, fallback, interpolation, plurals, formatting |
react-i18next |
v17 | React bindings: useTranslation, Trans, I18nextProvider, Suspense support |
i18next-browser-languagedetector |
v8 | Detects language from the query string, cookie, localStorage, or browser settings |
i18next-http-backend |
v4 | Fetches translation JSON files at runtime; v4 relies on the platform's native fetch |
Because the core knows nothing about React, the same configuration and JSON files can also power React Native or a Node.js service. If your app is a Next.js App Router project, read our next-intl vs react-i18next comparison first; react-i18next hooks are client-only there, and next-intl is often the simpler fit.
npm install i18next react-i18next i18next-browser-languagedetector i18next-http-backendYou only need the HTTP backend if you load translations at runtime. Small apps with two or three languages can import JSON directly instead; both options are shown below.
i18next organizes strings by language and namespace. A namespace is one JSON file, usually per feature, so pages can load only what they use:
public/
locales/
en/
common.json
checkout.json
de/
common.json
checkout.json
src/
i18n.ts
main.tsx
App.tsx{
"nav": {
"home": "Home",
"pricing": "Pricing"
},
"greeting": "Welcome back, {{name}}!",
"cart_one": "{{count}} item in your cart",
"cart_other": "{{count}} items in your cart",
"terms": "By continuing you accept our <termsLink>terms</termsLink>."
}
That is public/locales/en/common.json. Files in Vite's public/ folder are served as-is at /locales/..., which is exactly where the HTTP backend looks by default. For a refresher on nesting and key naming, see our JSON translation files guide.
// src/i18n.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import HttpBackend from "i18next-http-backend";
export const supportedLngs = ["en", "de", "pl", "ar"] as const;
i18n
.use(HttpBackend)
.use(LanguageDetector)
.use(initReactI18next)
.init({
supportedLngs,
fallbackLng: "en",
load: "languageOnly", // "de-AT" loads "de"
ns: ["common"],
defaultNS: "common",
debug: import.meta.env.DEV,
interpolation: {
escapeValue: false, // React already escapes rendered output
},
backend: {
loadPath: `${import.meta.env.BASE_URL}locales/{{lng}}/{{ns}}.json`,
},
detection: {
order: ["querystring", "localStorage", "navigator"],
lookupQuerystring: "lng",
caches: ["localStorage"],
},
});
export default i18n;A few of these options deserve an explanation:
supportedLngs stops the detector from requesting files for languages you do not ship.fallbackLng is used for any key missing in the active language, so an untranslated string shows English instead of a raw key.escapeValue: false is safe in React because JSX escapes strings. Leave it on if you also use i18next outside React to build HTML.loadPath uses BASE_URL so the app still finds its files when deployed under a sub-path.Import the module once, before rendering, and give the app a Suspense boundary:
// src/main.tsx
import { StrictMode, Suspense } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";
import "./i18n";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<Suspense fallback={<div className="app-loading" />}>
<App />
</Suspense>
</StrictMode>,
);
Why Suspense: useTranslation suspends while a namespace is loading (react.useSuspense defaults to true). Without a boundary, React has nothing to show and the app renders blank or throws. If you prefer to handle loading yourself, set react: { useSuspense: false } and check the ready flag that useTranslation returns.
For a small app, skip the backend and import the files. Translations are then available synchronously, and no Suspense fallback ever shows:
// src/i18n.ts (bundled variant)
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import enCommon from "./locales/en/common.json";
import deCommon from "./locales/de/common.json";
i18n.use(initReactI18next).init({
resources: {
en: { common: enCommon },
de: { common: deCommon },
},
lng: "en",
fallbackLng: "en",
defaultNS: "common",
interpolation: { escapeValue: false },
initAsync: false,
});
export default i18n;
The trade-off is size: every user downloads every language. Switch to the backend, or to dynamic import() per language, once that starts to matter. (initAsync replaced the old initImmediate option, which i18next v26 no longer accepts.)
// src/components/Header.tsx
import { useTranslation } from "react-i18next";
export function Header({ userName, cartCount }: { userName: string; cartCount: number }) {
const { t } = useTranslation();
return (
<header>
<nav>
<a href="/">{t("nav.home")}</a>
<a href="/pricing">{t("nav.pricing")}</a>
</nav>
<p>{t("greeting", { name: userName })}</p>
<p>{t("cart", { count: cartCount })}</p>
</header>
);
}
Components that use useTranslation re-render automatically when the language changes. To avoid repeating a long prefix, pass keyPrefix: useTranslation("common", { keyPrefix: "nav" }) lets you write t("home").
i18next placeholders use double curly braces: {{name}}. Pass values in the options object, never by concatenating strings, because word order changes between languages.
The built-in formatter wraps the Intl APIs, so numbers, currencies, dates, and relative times format per language:
{
"orderTotal": "Total: {{amount, currency}}",
"shippedOn": "Shipped on {{date, datetime}}",
"downloads": "{{value, number}} downloads"
}t("orderTotal", {
amount: 1499.5,
formatParams: { amount: { currency: order.currency } },
});
// en: "Total: $1,499.50" de: "Total: 1.499,50 $"
t("shippedOn", {
date: new Date(order.shippedAt),
formatParams: { date: { dateStyle: "long" } },
});Take the currency from your data, not from the language: a German user looking at a USD invoice should still see dollars, formatted the German way. Our Intl API guide covers the formatting options in depth.
i18next resolves plurals with Intl.PluralRules. You write one key per plural category, with a suffix, and pass count:
{
"cart_one": "{{count}} item in your cart",
"cart_other": "{{count}} items in your cart",
"cart_zero": "Your cart is empty"
}
t("cart", { count: 3 }) picks cart_other. The optional _zero key is a special case: when it exists and count is 0, i18next uses it even in languages like English that have no grammatical zero form.
Other languages need other categories. Polish uses one, few, many, and other:
{
"cart_one": "{{count}} produkt w koszyku",
"cart_few": "{{count}} produkty w koszyku",
"cart_many": "{{count}} produktów w koszyku",
"cart_other": "{{count}} produktu w koszyku"
}
Arabic uses all six categories (zero, one, two, few, many, other). Your code does not change; only the translation files do. That is the main reason to never write count === 1 ? ... : ... in a component. Ordinals ("1st", "2nd") work the same way with t("place", { count, ordinal: true }) and keys like place_ordinal_one. For background on why categories beat if/else, see our guide to plurals and ICU MessageFormat.
i18next's format is not ICU. If your translators or other apps already use ICU MessageFormat, add the i18next-icu plugin rather than mixing syntaxes in the same files.
When a sentence contains a link or bold text, splitting it into three keys breaks translation. Use Trans with named components instead:
// src/components/TermsNotice.tsx
import { Trans } from "react-i18next";
import { Link } from "react-router";
export function TermsNotice() {
return (
<p>
<Trans
i18nKey="terms"
components={{ termsLink: <Link to="/terms" /> }}
/>
</p>
);
}
The translation "By continuing you accept our <termsLink>terms</termsLink>." keeps the whole sentence together, translators can move the tag, and the rendered link is a real router component. Pass interpolation values through the values prop and a plural count through count. Prefer named components over the older indexed form (<1>...</1>); indexes break as soon as someone edits the JSX.
Load feature namespaces only where they are used. Asking for a namespace that is not loaded yet makes the HTTP backend fetch it, and the component suspends until it arrives:
// src/pages/Checkout.tsx
import { useTranslation } from "react-i18next";
export default function Checkout() {
// "checkout" is primary; "common" is available as a fallback namespace
const { t } = useTranslation(["checkout", "common"]);
return (
<main>
<h1>{t("title")}</h1>
<button>{t("common:nav.home")}</button>
</main>
);
}
Combine this with route-level code splitting (React.lazy) and a page's JavaScript and its strings arrive together. To avoid a loading flash on navigation, preload in a route loader or on hover with i18n.loadNamespaces("checkout").
![Diagram of namespace lazy loading: at app start only common.json loads; opening Checkout lazy-loads the page chunk and useTranslation(["checkout", "common"]) fetches /locales/en/checkout.json and suspends; then t("title") and t("common:nav.home") render. i18n.loadNamespaces("checkout") preloads it](/blog/inline/react-i18next-tutorial-2.webp)
Translation files in public/ are not fingerprinted, so browsers and CDNs may cache stale copies after a deploy. Add a version query string through the backend's queryStringParams option (for example, a build ID) or set short cache headers on /locales/.
// src/components/LanguageSwitcher.tsx
import { useEffect } from "react";
import { useTranslation } from "react-i18next";
import { supportedLngs } from "../i18n";
const labels: Record<(typeof supportedLngs)[number], string> = {
en: "English",
de: "Deutsch",
pl: "Polski",
ar: "العربية",
};
export function LanguageSwitcher() {
const { i18n } = useTranslation();
const current = i18n.resolvedLanguage ?? "en";
useEffect(() => {
document.documentElement.lang = current;
document.documentElement.dir = i18n.dir(current);
}, [current, i18n]);
return (
<select value={current} onChange={(e) => i18n.changeLanguage(e.target.value)}>
{supportedLngs.map((lng) => (
<option key={lng} value={lng}>
{labels[lng]}
</option>
))}
</select>
);
}
Use i18n.resolvedLanguage, not i18n.language, for UI state: language can be a detected value like de-AT, while resolvedLanguage is the supported language actually in use. changeLanguage loads any missing namespaces, and the detector caches the choice in localStorage. Setting dir matters for Arabic and Hebrew; pair it with CSS logical properties.
Augment i18next's CustomTypeOptions with your source-language resources:
// src/@types/i18next.d.ts
import "i18next";
import common from "../../public/locales/en/common.json";
import checkout from "../../public/locales/en/checkout.json";
declare module "i18next" {
interface CustomTypeOptions {
defaultNS: "common";
resources: {
common: typeof common;
checkout: typeof checkout;
};
}
}
Now t("nav.hom") is a compile error, keys autocomplete, and recent versions also type interpolation values (for example, {{value, number}} expects a number). Make sure resolveJsonModule is enabled in tsconfig.json and that the declaration file is inside an included folder. On large catalogs, the optional selector API (enableSelector in CustomTypeOptions, then t(($) => $.nav.home)) keeps editor type-checking fast.
Mocking t to return the key hides broken interpolation and plurals. Create a dedicated instance with bundled resources and no Suspense instead:
// src/test/i18n.ts
import i18next from "i18next";
import { initReactI18next } from "react-i18next";
import common from "../../public/locales/en/common.json";
export function createTestI18n() {
const instance = i18next.createInstance();
instance.use(initReactI18next).init({
lng: "en",
fallbackLng: "en",
defaultNS: "common",
resources: { en: { common } },
interpolation: { escapeValue: false },
react: { useSuspense: false },
initAsync: false,
saveMissing: true,
missingKeyHandler: (_lngs, ns, key) => {
throw new Error(`Missing translation: ${ns}:${key}`);
},
});
return instance;
}// src/components/Header.test.tsx
import { render, screen } from "@testing-library/react";
import { I18nextProvider } from "react-i18next";
import { expect, test } from "vitest";
import { Header } from "./Header";
import { createTestI18n } from "../test/i18n";
test("pluralizes the cart count", () => {
render(
<I18nextProvider i18n={createTestI18n()}>
<Header userName="Ada" cartCount={2} />
</I18nextProvider>,
);
expect(screen.getByText("2 items in your cart")).toBeInTheDocument();
});Add a CI step that compares each language's keys against English (here is a ready-made script and GitHub Actions workflow), and run the app in a pseudo-locale to catch hard-coded strings and truncated layouts; our pseudo-localization guide walks through it.
useSuspense: true and an async backend, the app renders nothing while translations load.t at module scope. A constant like const LABEL = i18n.t("save") is evaluated once, often before resources load, and never updates. Call t during render.count. Plural suffixes are only chosen when you pass count; passing the number under another name skips plural resolution.count === 1 ? "item" : "items" is wrong for Polish, Russian, and Arabic. Let suffixed keys do the work.key_plural and numeric suffixes; current i18next only understands CLDR suffixes like _one and _other.i18next-icu, ICU braces render literally.i18n.language for comparisons. It may be en-US while your files are en; use resolvedLanguage.i18next is the framework-agnostic core that stores translations and handles fallback, interpolation, plurals, and formatting. react-i18next is the React binding on top of it, adding the useTranslation hook, the Trans component, I18nextProvider, and Suspense support. You install and initialize both.
Write one key per plural category with a suffix such as item_one and item_other, then call t("item", { count }). i18next picks the suffix with Intl.PluralRules, so languages like Polish can add _few and _many keys without any code changes.
Only if translations load asynchronously. useTranslation suspends while namespaces load because react.useSuspense defaults to true, so wrap your app in a Suspense boundary or set useSuspense to false and check the ready flag. Bundled resources with initAsync: false never suspend.
Create a declaration file that augments the i18next module's CustomTypeOptions interface with defaultNS and a resources object built from your source-language JSON files. TypeScript then autocompletes keys and reports unknown keys in t() and the Trans component.
It works, but in the App Router its hooks only run in Client Components, so server rendering needs a separate i18next instance per request. For Next.js-only projects, next-intl is often simpler; react-i18next fits better when you share translations with React Native, Vite apps, or a Node.js backend.
A solid react-i18next setup comes down to a handful of decisions: one i18n module imported before render, a Suspense boundary, namespaces per feature loaded on demand, suffixed plural keys instead of conditionals, Trans for rich text, and CustomTypeOptions so typos fail the build. Once the code is in place, the ongoing work is keeping every language file in step with English; if you want help with that, Babelize generates per-language JSON files that react-i18next can load.