# next-i18next [![npm version](https://img.shields.io/npm/v/next-i18next.svg?style=flat-square)](https://www.npmjs.com/package/next-i18next) ![npm](https://img.shields.io/npm/dw/next-i18next) [![Socket Badge](https://badge.socket.dev/npm/package/next-i18next)](https://socket.dev/npm/package/next-i18next) **The easiest way to translate your Next.js apps.** Supports the **App Router** (Server Components, Client Components, middleware), the **Pages Router**, and **mixed** setups where both routers coexist. If you already know i18next: next-i18next v16 is a thin layer on top of [i18next](https://www.i18next.com) and [react-i18next](https://react.i18next.com) that handles the Next.js-specific wiring β€” middleware, server/client split, resource hydration β€” so you don't have to. ## What's new in v16 - **App Router support**: `getT()` for Server Components, `useT()` for Client Components, `createProxy()` for language detection and routing - **Locale-in-path** (`/en/about`) and **no-locale-path** (cookie-based) modes - **Mixed Router**: Use both App Router and Pages Router in the same app with `basePath` scoping - **Custom Backends**: `i18next-http-backend`, `i18next-locize-backend`, `i18next-chained-backend`, etc. - **Edge-safe Proxy**: Zero Node.js dependencies in the proxy/middleware path - **Pages Router**: Existing `appWithTranslation` / `serverSideTranslations` API preserved under `next-i18next/pages` ## Advice: If you don't like to manage your translation files manually or are simply looking for a [better management solution](https://www.locize.com?utm_source=next_i18next_readme&utm_medium=github&utm_campaign=readme), take a look at [i18next-locize-backend](https://github.com/locize/i18next-locize-backend). The i18next [backend plugin](https://www.i18next.com/overview/plugins-and-utils#backends) for 🌐 [Locize](https://www.locize.com?utm_source=next_i18next_readme&utm_medium=github&utm_campaign=readme) ☁️ β€” built by the same team behind next-i18next, with CDN delivery (works great on Vercel/serverless), AI translation, and no redeploys for copy changes. Starting from a Next.js app with hardcoded strings? Run `npx i18next-cli localize`: one command that wraps strings in `t()` (since i18next-cli 1.90 with `await getT()` in Server Components and `useT()` in Client Components; review the diff and the warnings), extracts keys, connects to [Locize](https://www.locize.com?from=next-i18next_readme__localize) and AI-translates your app. See the [launch post](https://www.locize.com/blog/i18next-cli-localize?from=next-i18next_readme__localize). Working with a coding agent (Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, ...)? Paste this prompt; the CLI prints the steps for its installed version, you review the diff, and the translation files stay in your repository unless you choose otherwise ([what the prompt tells your agent](https://www.i18next.com/how-to/ai-coding-agents)): ```text 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. ``` --- ## Table of Contents - [App Router Setup](#app-router-setup) - [No-Locale-Path Mode](#no-locale-path-mode) - [ICU and MF2 with the App Router](#icu-and-mf2-with-the-app-router) - [Mixed Router Setup](#mixed-router-setup-app-router--pages-router) - [Pages Router Setup](#pages-router-setup) - [Custom i18next Backends](#custom-i18next-backends) - [API Reference](#api-reference) - [Examples](#examples) - [Migration from v15](#migration-from-v15) --- ## App Router Setup ### 1. Install ```bash npm install next-i18next i18next react-i18next ``` ### 2. Translation files Place JSON translation files in your project. There are two common patterns: **In `public/locales/`** (served statically, works with default config β€” **local/traditional hosting only**): ``` public/locales/en/common.json public/locales/en/home.json public/locales/de/common.json public/locales/de/home.json ``` > **Serverless platforms (Vercel, AWS Lambda, etc.)**: Files in `public/` are served via CDN but are **not** available on the filesystem at runtime. Use `resourceLoader` with dynamic imports instead (see below). **In `app/i18n/locales/`** (bundled via dynamic imports, requires `resourceLoader` β€” **works everywhere including serverless**): ``` app/i18n/locales/en/common.json app/i18n/locales/de/common.json ``` ### 3. Configuration Create a config file (e.g., `i18n.config.ts`): ```ts import type { I18nConfig } from 'next-i18next/proxy' const i18nConfig: I18nConfig = { supportedLngs: ['en', 'de'], fallbackLng: 'en', defaultNS: 'common', ns: ['common', 'home'], // Recommended: works on all platforms including Vercel/serverless resourceLoader: (language, namespace) => import(`./app/i18n/locales/${language}/${namespace}.json`), } export default i18nConfig ``` The `resourceLoader` uses dynamic `import()` which the bundler can trace, ensuring translation files are included in the serverless function bundle. If you prefer to keep translations in `public/locales/` and are **not** deploying to a serverless platform, you can omit `resourceLoader` β€” next-i18next will read from the filesystem at runtime. > **Tip**: Import `I18nConfig` from `next-i18next/proxy` (not from `next-i18next`) to keep the config file Edge-safe. > **Dev tip β€” hot-reloading translations**: set `reloadOnPrerender: process.env.NODE_ENV === 'development'` in your config to refetch translations on every render in dev so edits to locale files appear without restarting `next dev`. The flag is automatically a no-op in production, so it is safe to keep in your committed config β€” custom backends (HTTP, locize, chained) won't be hit per-request in production builds. Leave it off with `cacheComponents: true`: re-reading the files on every render is uncached I/O, so `next dev` reports "uncached data" at the `getT()` call on every request. > > **Caveat with `import()`-based `resourceLoader`**: dynamic `import()` of JSON is cached at the bundler level and is not reliably re-invalidated by Turbopack/Webpack HMR after the first edit, so hot-reload can stall after one change. For full hot-reload during development, gate your loader so dev uses `fs.readFile` and production keeps bundler-traceable `import()`: > ```ts > const resourceLoader: I18nConfig['resourceLoader'] = > process.env.NODE_ENV === 'development' > ? async (lng, ns) => { > const fs = await import('fs/promises') > const path = await import('path') > const content = await fs.readFile( > path.resolve(process.cwd(), `app/i18n/locales/${lng}/${ns}.json`), > 'utf-8' > ) > return JSON.parse(content) > } > : (lng, ns) => import(`./app/i18n/locales/${lng}/${ns}.json`) > ``` > Pages Router and the App Router default backend already use `fs` and are unaffected. ### 4. Proxy Create `proxy.ts` at your project root (Next.js 16+ replaces `middleware.ts` with `proxy.ts`): ```ts import { createProxy } from 'next-i18next/proxy' import i18nConfig from './i18n.config' export const proxy = createProxy(i18nConfig) export const config = { matcher: ['/((?!api|_next/static|_next/image|assets|favicon.ico|sw.js|site.webmanifest).*)'], } ``` > **Note**: `createMiddleware` from `next-i18next/middleware` is still available for projects on Next.js < 16. The proxy: - Detects language from cookie > Accept-Language header > fallback - Redirects bare URLs to locale-prefixed paths (e.g., `/about` -> `/en/about`) - Sets a custom header (`x-i18next-current-language`) for Server Components - Persists the language in a cookie, but only when it changed: a cookie written by the proxy counts as a modified cookie for Next, and a modified cookie makes every Server Action revalidate and refetch the page. Set `persistCookie: false` if another system owns that cookie, and `cookieOptions` to scope it (e.g. `{ domain: '.example.com', secure: true }`) ### 5. Root Layout ```tsx // app/[lng]/layout.tsx import { initServerI18next, getT, getResources, generateI18nStaticParams } from 'next-i18next/server' import { I18nProvider } from 'next-i18next/client' import i18nConfig from '../../i18n.config' initServerI18next(i18nConfig) export async function generateStaticParams() { return generateI18nStaticParams() } export default async function RootLayout({ children, params, }: { children: React.ReactNode params: Promise<{ lng: string }> }) { const { lng } = await params const { i18n } = await getT() const resources = getResources(i18n) return ( {children} ) } ``` Key points: - `initServerI18next(config)` β€” call once at module scope in the root layout - `getResources(i18n)` β€” serializes loaded translations for client hydration - `I18nProvider` β€” wraps children so client components can use `useT()` #### Initialization without ordering assumptions `initServerI18next(config)` is a side effect: it has to run in the process before the first `getT()`. Module scope of the root layout works because Next loads the root layout before anything below it, but nothing enforces it if a second copy of `next-i18next/server` calls `getT()` first, for example from a Route Handler, which is bundled in its own layer. If you would rather not depend on evaluation order at all, bind the config once and import from that module everywhere: ```ts // i18n.server.ts import { createServerI18next } from 'next-i18next/server' import i18nConfig from './i18n.config' export const { getT, getResources, generateI18nStaticParams } = createServerI18next(i18nConfig) ``` ```tsx // any Server Component, layout or generateMetadata import { getT } from '@/i18n.server' ``` Every caller then imports the module that holds the config, so there is no initialization step and no order to get right. Call `createServerI18next` once at module scope: each call owns its own shared i18next instance. ### 6. Server Components ```tsx // app/[lng]/page.tsx import { getT } from 'next-i18next/server' export default async function Home() { const { t } = await getT('home') return

{t('title')}

} export async function generateMetadata() { const { t } = await getT('home') return { title: t('meta_title') } } ``` On Next.js 16.3+ `getT()` resolves the language from the `[lng]` root param (via `next/root-params`) before falling back to the proxy header and cookie. Reading a root param does not opt the route out of static prerendering, so `getT()` is safe in prerendered routes (including with `cacheComponents: true`). Route Handlers and Server Actions have no root params β€” pass `{ lng }` explicitly there. With `cacheComponents: true`, `next dev` reports "uncached data" at a `getT()` call when that render reads translations from disk with `fs`, once per language: with an `fs`-based `resourceLoader` (like the dev branch in the caveat above), or without a `resourceLoader`, where locale files are read from `public/locales`. An `import()`-based `resourceLoader` does not trigger it. Either way it is file I/O in the dev render, not a dynamic route: `next build` is the check to trust, and it prerenders every locale. For the `Trans` component in Server Components, use `react-i18next/TransWithoutContext` and pass both `t` and `i18n`: ```tsx import { Trans } from 'react-i18next/TransWithoutContext' import { getT } from 'next-i18next/server' export default async function Page() { const { t, i18n } = await getT() return ( Welcome to next-i18next ) } ``` With react-i18next 18, `import { Trans } from 'react-i18next'` works here too: in Server Components its `react-server` export condition resolves to the same component without context. Pass `t` and `i18n` the same way. ### 7. Client Components ```tsx 'use client' import { useT } from 'next-i18next/client' export default function Counter() { const { t } = useT('home') return } ``` `useT` works in both locale-in-path (`/en/about`) and no-locale-path modes. `I18nProvider` follows the `[lng]` or `[locale]` route param when there is one; `useT` itself does not subscribe to the URL, so rewriting it (`history.replaceState`, `?page=`) does not re-render its callers. For the `Trans` component in Client Components: ```tsx 'use client' import { Trans, useT } from 'next-i18next/client' export default function Greeting() { const { t } = useT() return Hello world } ``` ### 8. Language Switching (locale-in-path) When the locale is part of the URL path (e.g., `/en/about` β†’ `/de/about`), switch languages by navigating to the new locale prefix: ```tsx 'use client' import { usePathname, useRouter } from 'next/navigation' export function LanguageSwitcher({ supportedLngs }: { supportedLngs: string[] }) { const pathname = usePathname() const router = useRouter() const switchLocale = (locale: string) => { const segments = pathname.split('/') segments[1] = locale router.push(segments.join('/')) } return (
{supportedLngs.map((lng) => ( ))}
) } ``` For the no-locale-path mode (cookie-based), see `useChangeLanguage` [below](#no-locale-path-mode). --- ## Hide Default Locale If you want clean URLs for the default language while keeping locale prefixes for other languages, set `hideDefaultLocale: true`: ```ts const i18nConfig: I18nConfig = { supportedLngs: ['en', 'de'], fallbackLng: 'en', hideDefaultLocale: true, } ``` In this mode: - `/about` serves the default language (English) β€” no prefix needed - `/de/about` serves German β€” non-default locales keep their prefix - `/en/about` automatically redirects to `/about` (canonical clean URL) - The `[lng]` folder structure stays the same β€” the proxy rewrites internally --- ## No-Locale-Path Mode If you prefer clean URLs without a locale prefix for **all** languages (e.g., `/about` instead of `/en/about`), set `localeInPath: false`: ```ts const i18nConfig: I18nConfig = { supportedLngs: ['en', 'de'], fallbackLng: 'en', localeInPath: false, resourceLoader: (language, namespace) => import(`./app/i18n/locales/${language}/${namespace}.json`), } ``` In this mode: - Routes live directly under `app/` (no `[lng]` segment) - The middleware detects language from cookies / Accept-Language, sets the header, but does **not** redirect - Server Components use `getT()` as usual (language is read from the header) - Client Components use `useT()` as usual (language comes from `I18nProvider`) - Use `useChangeLanguage()` for language switching (updates cookie + triggers server re-render): ```tsx 'use client' import { useChangeLanguage } from 'next-i18next/client' export function LanguageSwitcher() { const changeLanguage = useChangeLanguage() return (
) } ``` The root layout reads the language from `getT()` instead of URL params: ```tsx // app/layout.tsx (no [lng] segment) export default async function RootLayout({ children }) { const { i18n, lng } = await getT() const resources = getResources(i18n) return ( {children} ) } ``` See [`examples/app-router-no-locale-path`](examples/app-router-no-locale-path) for a complete example. --- ## Internal Locale Mode (clean URLs + static prerendering) `localeInPath: false` gives clean URLs, but the language then comes from `headers()`/`cookies()`, which makes every route dynamic. If you need clean URLs **and** static prerendering per locale (e.g. with Next.js Cache Components, `cacheComponents: true`), set `localeInPath: 'internal'`: ```ts const i18nConfig: I18nConfig = { supportedLngs: ['en', 'de'], fallbackLng: 'en', localeInPath: 'internal', localeParamName: 'locale', // only if your segment is app/[locale] instead of app/[lng] } ``` In this mode: - Routes live under `app/[lng]/` exactly like the default mode, so `generateI18nStaticParams()` prerenders every locale - The proxy detects the language (cookie > Accept-Language > fallback) and **rewrites** `/about` to `/de/about` internally β€” the public URL never shows a locale - Explicit locale paths (`/de/about`) are served as-is, like in the default mode β€” the proxy never redirects them, so `` prefetches cannot flip the language cookie. Your own links should be clean (`/about`) - `getT()` reads the language from the `[lng]` root param (Next.js 16.3+), so it does not opt the route out of prerendering - Use `useChangeLanguage()` for language switching, as in no-locale-path mode - `hideDefaultLocale` has no effect here --- ## Static Export (`output: 'export'`) The App Router setup above also works as a static site without a server, in the default locale-in-path mode: - Set `output: 'export'` in `next.config.js` and delete `proxy.ts`: a static export has no server, so the proxy can not run. - Keep `generateI18nStaticParams()` in `app/[lng]/layout.tsx`. `next build` writes one page per language and route (`out/en.html`, `out/de/about.html`, ...). - `getT()` reads the language from the `[lng]` root param on Next.js 16.3+. On older versions, pass it from `params`: `getT('home', { lng })`. - `hideDefaultLocale`, `localeInPath: false` and `localeInPath: 'internal'` depend on the proxy and do not work here. - Nothing redirects bare paths or writes the language cookie: link to locale paths (`/de/about`), and `/` follows the browser languages on every visit. The proxy normally redirects `/`, so the export has no page there. Add a `public/index.html`; the build copies it to `out/index.html`, and it sends visitors to the first supported language in their browser settings, or to the fallback language: ```html ``` Or use a redirect rule on your static host instead (for example `/` to `/en`). --- ## Loading Languages On Demand By default the shared server instance preloads every supported language at startup, so `getResources(i18n)` can serialize any of them. With many locales and namespaces that is a lot of resident memory. Pass `i18nextOptions: { preload: [] }` to load each language on its first request instead: ```ts const i18nConfig: I18nConfig = { supportedLngs: ['en', 'de', 'fr', 'it'], fallbackLng: 'en', i18nextOptions: { preload: [] }, } ``` The store then only holds languages that have been requested so far, so pass `[lng, fallbackLng]` to `getResources` rather than relying on everything being present. On the client the language then changes in two steps: `useChangeLanguage` writes the cookie and calls `router.refresh()`, and `I18nProvider` switches as soon as that re-render delivers the new language's resources. Client Components keep working without any extra setup β€” pass `supportedLngs` to `I18nProvider` only if you want to restrict which languages it accepts (unset, it accepts any language the server sends). --- ## ICU and MF2 with the App Router To write your translations in ICU MessageFormat ([i18next-icu](https://github.com/i18next/i18next-icu)) or in Unicode MessageFormat 2 ([i18next-mf2](https://github.com/i18next/i18next-mf2)) instead of the i18next JSON format, register the plugin in the server config and import `I18nProvider` from `next-i18next/icu` (or `next-i18next/mf2`). Both plugins replace i18next's own plurals, context keys and `{{interpolation}}`; [Using ICU or MF2](https://www.i18next.com/how-to/using-icu-or-mf2) lists what keeps working and what does not. ### Install ```bash npm install i18next-icu intl-messageformat # or, for MF2 npm install i18next-mf2 ``` Both are optional peer dependencies of next-i18next. Apps that never import `next-i18next/icu` or `next-i18next/mf2` do not resolve or bundle them. ### Configuration Add the plugin to `use`, so `getT()` formats the messages on the server: ```ts // i18n.config.ts import type { I18nConfig } from 'next-i18next/proxy' import ICU from 'i18next-icu' const i18nConfig: I18nConfig = { supportedLngs: ['en', 'de'], fallbackLng: 'en', resourceLoader: (language, namespace) => import(`./app/i18n/locales/${language}/${namespace}.json`), use: [ICU], } export default i18nConfig ``` `app/i18n/locales/en/common.json`: ```json { "photos": "You have {count, plural, =0 {no photos} one {# photo} other {# photos}}.", "order": "{status, select, pending {Your order is being prepared.} shipped {Your order is on its way.} other {Your order status is unknown.}}", "welcome": "Welcome back, <0>{name}!" } ``` In the root layout, import `I18nProvider` from `next-i18next/icu` instead of `next-i18next/client`. It takes the same props and registers i18next-icu on the client instance: ```tsx // app/[lng]/layout.tsx import { initServerI18next, getT, getResources, generateI18nStaticParams } from 'next-i18next/server' import { I18nProvider } from 'next-i18next/icu' // or 'next-i18next/mf2' import i18nConfig from '../../i18n.config' initServerI18next(i18nConfig) export async function generateStaticParams() { return generateI18nStaticParams() } export default async function RootLayout({ children, params, }: { children: React.ReactNode params: Promise<{ lng: string }> }) { const { lng } = await params const { i18n } = await getT() return ( {children} ) } ``` A Server Component can not pass a plugin class to a Client Component as a prop: `` in a layout fails the build with "Functions cannot be passed directly to Client Components". `next-i18next/icu` is a Client module that imports the plugin itself, so no `'use client'` wrapper of your own is needed. `useT`, `useChangeLanguage` and `Trans` still come from `next-i18next/client`. Notes: - The client instance does not read the server config. Plugin options in `i18nextOptions.i18nFormat` (for example `bidiIsolation: 'none'` for MF2) have to be passed to `I18nProvider` as well, via its `i18nextOptions` prop, or the server and client render different text. - The proxy imports the same config, so the plugin ends up in the proxy bundle too (about 40 KB for i18next-icu). To keep it out, leave `use` out of the shared config and add it where the server is initialized: `initServerI18next({ ...i18nConfig, use: [ICU] })`. - For MF2, put `MF2` from `i18next-mf2` into `use` and import `I18nProvider` from `next-i18next/mf2`. Messages are written in MF2 syntax, e.g. `.input {$count :number} .match $count one {{You have {$count} photo.}} * {{You have {$count} photos.}}`. ### Server Components ```tsx // app/[lng]/page.tsx import { getT } from 'next-i18next/server' import { IcuTransWithoutContext } from 'react-i18next/IcuTransWithoutContext' export default async function Page() { const { t, i18n } = await getT() return (

{t('photos', { count: 5 })}

{t('order', { status: 'shipped' })}

) } ``` `IcuTransWithoutContext` (react-i18next 17.0.21 or later) uses no React context, so it renders in Server Components. Pass the `t` from `getT()`, it is bound to the request's language. `Trans` from `react-i18next/TransWithoutContext` works as well, with `values` and `components`: ```tsx ]} /> ``` With react-i18next 17, import both from these entry points in Server Components: the `react-i18next` root also loads React context. react-i18next 18 resolves the root to them in Server Components (its `react-server` export condition), so `import { Trans, IcuTrans } from 'react-i18next'` works there as well. ### Client Components ```tsx 'use client' import { useState } from 'react' import { IcuTrans } from 'react-i18next' import { useT } from 'next-i18next/client' export function Photos() { const { t } = useT() const [count, setCount] = useState(0) return ( <>

{t('photos', { count })}

) } ``` ### TypeScript With i18next 26.5.0 or later, set `parseInterpolation: 'icu'` (or `'mf2'`) and the options of `t` from `getT` and `useT`, and the `values` of `IcuTrans` and `IcuTransWithoutContext` (react-i18next 17.1.0 or later), are type-checked against the arguments of each message. The messages need literal types, which `npx i18next-cli types` generates (see [i18next-cli](#i18next-cli) below); with `typeof` a JSON import every message is a `string` and nothing is checked: ```ts // @types/i18next.d.ts import 'i18next' import type Resources from './resources' // generated by `npx i18next-cli types` declare module 'i18next' { interface CustomTypeOptions { defaultNS: 'common' resources: Resources parseInterpolation: 'icu' // or 'mf2' } } ``` ```tsx // photos: 'You have {count, plural, =0 {no photos} one {# photo} other {# photos}}.' const { t } = await getT() t('photos', { count: 5 }) // ok t('photos', { count: 'five' }) // type error: count takes a number t('photos') // type error: 'pass these arguments as t() options': { count: number; } ``` With i18next 26.2.0 to 26.4.x, set `parseInterpolation: false` instead: the default type extractor reads `{{variables}}`, and ICU arguments nested in a plural (`one {{count} row}`) and MF2 variants (`* {{You have {$count} photos.}}`) contain double braces that are not i18next variables, so these `t` calls would not compile. Keys are still checked, the values you pass to `t` are not. ### i18next-cli [i18next-cli](https://github.com/i18next/i18next-cli) 1.76.0 or later knows both formats. Set `extract.messageFormat` to `'icu'` or `'mf2'` in your `i18next.config.ts`: ```ts import { defineConfig } from 'i18next-cli' export default defineConfig({ locales: ['en', 'de'], extract: { input: ['app/**/*.{ts,tsx}'], output: 'app/i18n/locales/{{language}}/{{namespace}}.json', messageFormat: 'icu', // or 'mf2' }, }) ``` `extract` then writes one key per message instead of `_one`/`_other` suffix keys and extracts `IcuTrans` and `IcuTransWithoutContext`, `lint` checks the syntax, the argument names and the plural categories of every language, and `types` writes the resources file with literal message types and `parseInterpolation: 'icu'` or `'mf2'` (i18next-cli 1.77.0 with i18next 26.5.0 or later, else `false`) into a newly generated `i18next.d.ts`. See [`examples/app-router-icu`](examples/app-router-icu) for a complete app with plurals, a select and rich text in Server and Client Components. --- ## Mixed Router Setup (App Router + Pages Router) For projects that use both routers, next-i18next supports a `basePath` option that scopes the App Router middleware to a specific URL prefix while the Pages Router uses Next.js built-in i18n routing for everything else. ### Configuration Create a shared config file for common settings: ```js // i18n.shared.js module.exports = { supportedLngs: ['en', 'de'], fallbackLng: 'en', defaultNS: 'common', ns: ['common', 'footer'], } ``` App Router config with `basePath`: ```ts // i18n.config.ts import type { I18nConfig } from 'next-i18next/proxy' const shared = require('./i18n.shared.js') const i18nConfig: I18nConfig = { ...shared, basePath: '/app-router', resourceLoader: (language, namespace) => import(`./public/locales/${language}/${namespace}.json`), } export default i18nConfig ``` Pages Router config: ```js // next-i18next.config.js const shared = require('./i18n.shared.js') module.exports = { i18n: { defaultLocale: shared.fallbackLng, locales: shared.supportedLngs, }, localePath: typeof window === 'undefined' ? require('path').resolve('./public/locales') : '/locales', } ``` ### Proxy/Middleware With `basePath: '/app-router'`, `createProxy` automatically: - **Skips** any request not under `/app-router/...` (letting Pages Router handle those) - Redirects `/app-router/page` to `/app-router/en/page` - Sets the language header for Server Components under that prefix ```ts // proxy.ts import { createProxy } from 'next-i18next/proxy' import i18nConfig from './i18n.config' export const proxy = createProxy(i18nConfig) export const config = { matcher: ['/app-router/:path*'], } ``` ### next.config.js Include the Pages Router i18n config so Next.js handles locale routing for Pages: ```js const { i18n } = require('./next-i18next.config.js') module.exports = { i18n, reactStrictMode: true, } ``` ### Directory structure ``` app/app-router/[locale]/layout.tsx -- App Router layout app/app-router/[locale]/page.tsx -- App Router pages pages/_app.tsx -- appWithTranslation pages/index.tsx -- Pages Router pages public/locales/en/common.json -- shared translation files ``` App Router pages import from `next-i18next/server` and `next-i18next/client`. Pages Router pages import from `next-i18next/pages` and `next-i18next/pages/serverSideTranslations`. See [`examples/mixed-routers`](examples/mixed-routers) for a complete example. --- ## Pages Router Setup For projects using only the Pages Router, the familiar v15 API is available under `next-i18next/pages`: ```js // next-i18next.config.js module.exports = { i18n: { defaultLocale: 'en', locales: ['en', 'de'], }, } ``` ```js // next.config.js const { i18n } = require('./next-i18next.config.js') module.exports = { i18n } ``` ```tsx // pages/_app.tsx import { appWithTranslation } from 'next-i18next/pages' const MyApp = ({ Component, pageProps }) => export default appWithTranslation(MyApp) ``` ```tsx // pages/index.tsx import { serverSideTranslations } from 'next-i18next/pages/serverSideTranslations' import { useTranslation } from 'next-i18next/pages' export const getStaticProps = async ({ locale }) => ({ props: { ...(await serverSideTranslations(locale, ['common'])), }, }) export default function Home() { const { t } = useTranslation('common') return

{t('title')}

} ``` See [`examples/pages-router-simple`](examples/pages-router-simple), [`examples/pages-router-ssg`](examples/pages-router-ssg), and [`examples/pages-router-auto-static-optimize`](examples/pages-router-auto-static-optimize) for more. --- ## Custom i18next Backends next-i18next supports any i18next backend plugin for loading translations from an API, CDN, or services like [Locize](https://www.locize.com?utm_source=next_i18next_readme&utm_medium=github&utm_campaign=readme). When a custom backend is provided via `use`, next-i18next will **not** add its default resource loader, giving you full control. ### i18next-http-backend ```ts import { defineConfig } from 'next-i18next' import HttpBackend from 'i18next-http-backend' export default defineConfig({ supportedLngs: ['en', 'de'], fallbackLng: 'en', use: [HttpBackend], i18nextOptions: { backend: { loadPath: 'https://cdn.example.com/locales/{{lng}}/{{ns}}.json', }, }, }) ``` ### i18next-locize-backend ```ts import { defineConfig } from 'next-i18next' import LocizeBackend from 'i18next-locize-backend' export default defineConfig({ supportedLngs: ['en', 'de'], fallbackLng: 'en', use: [LocizeBackend], i18nextOptions: { backend: { projectId: 'your-project-id', apiKey: 'your-api-key', // only needed for saving missing keys }, }, }) ``` ### i18next-chained-backend For client-side caching with a remote fallback: ```ts import { defineConfig } from 'next-i18next' import ChainedBackend from 'i18next-chained-backend' import HttpBackend from 'i18next-http-backend' import LocalStorageBackend from 'i18next-localstorage-backend' export default defineConfig({ supportedLngs: ['en', 'de'], fallbackLng: 'en', use: [ChainedBackend], i18nextOptions: { backend: { backends: [LocalStorageBackend, HttpBackend], backendOptions: [ { expirationTime: 7 * 24 * 60 * 60 * 1000 }, { loadPath: '/locales/{{lng}}/{{ns}}.json' }, ], }, }, }) ``` For the client-side `I18nProvider`, pass custom backend plugins via the `use` prop: ```tsx {children} ``` Backends passed here are **browser-only**. `I18nProvider` is a Client Component, but the App Router also renders it on the server, once per request, so a backend attached there would run in Node on every render: fetching per render, and, for backends that refresh on a timer (`i18next-locize-backend` defaults `reloadInterval` to 1 hour whenever `window` is undefined), leaving a live timer behind on each one. next-i18next therefore skips backend plugins during the server pass and renders from `resources`; the browser instance keeps the backend and does the fetching. Non-backend plugins (detectors, post-processors) are applied in both passes. If you want Client Components to load namespaces that are **not** in `resources` on the server as well, so only the namespaces a route renders end up in the HTML and the rest load on demand, opt in with `ssrBackend`. It applies the backends from `use` during the server pass too. Combine it with `react.useSuspense: true`, so a missing namespace suspends into the nearest `` boundary instead of rendering keys, and both passes render the same text: ```tsx 'use client' import { Suspense } from 'react' import { I18nProvider } from 'next-i18next/client' import resourcesToBackend from 'i18next-resources-to-backend' const backend = resourcesToBackend((lng, ns) => import(`../i18n/locales/${lng}/${ns}.json`)) export function Providers({ children, language, resources }) { return ( }>{children} ) } ``` Use `ssrBackend` only with backends that have no timers and no relative URLs, such as `i18next-resources-to-backend` with dynamic imports. HTTP and locize backends must stay browser-only for the reason above. ### Server-side caching On the server, next-i18next uses a **module-level singleton** i18next instance: - Translations are loaded **once** and reused across all subsequent requests - Custom backends benefit from this β€” no re-fetching per request - Additional namespaces are loaded on demand and cached In **serverless environments** (Lambda, Vercel Serverless, etc.), the cache only lives as long as the warm function instance. For serverless, prefer: 1. Bundling translations at build time via `resources` or `resourceLoader` with dynamic imports 2. Downloading translations in CI/CD via [Locize CLI](https://github.com/locize/locize-cli) --- ## API Reference ### `next-i18next` (root export) | Export | Description | |---|---| | `defineConfig(config)` | Type-safe config helper (identity function) | | `normalizeConfig(config)` | Fill in defaults and validate config | | `I18nConfig` | Config type | ### `next-i18next/proxy` (also available as `next-i18next/middleware`) | Export | Description | |---|---| | `createProxy(config)` | Returns a Next.js proxy function (for `proxy.ts`) | | `createMiddleware(config)` | Alias for `createProxy` (for `middleware.ts` on Next.js < 16) | | `defineConfig`, `normalizeConfig`, `I18nConfig` | Re-exported for Edge-safe config usage | ### `next-i18next/server` | Export | Description | |---|---| | `initServerI18next(config)` | Initialize server config (call once at module scope, before the first `getT()`) | | `createServerI18next(config)` | Returns `{ getT, getResources, generateI18nStaticParams }` bound to `config`. No `initServerI18next` and no evaluation order to get right; see [Initialization without ordering assumptions](#initialization-without-ordering-assumptions) | | `getT(ns?, options?)` | Get `{ t, i18n }` for Server Components. Options: `{ lng?, keyPrefix? }` | | `getResources(i18n, namespaces?, languages?)` | Extract loaded resources for client hydration. The shared instance preloads every supported language by default, so pass `languages` (e.g. `[lng, fallbackLng]`) to keep the serialized payload small. Include the fallback language, or keys missing from the current one have nothing to fall back to on the client | | `generateI18nStaticParams()` | Returns `[{ lng: 'en' }, { lng: 'de' }, ...]` for `generateStaticParams`, keyed by `localeParamName` (`generateI18nStaticParams<'locale'>()` narrows the type) | ### `next-i18next/client` | Export | Description | |---|---| | `I18nProvider` | Client-side provider wrapping `I18nextProvider` | | `useT(ns?, options?)` | Translation hook for Client Components (works in all modes) | | `useChangeLanguage(cookieName?, cookieOptions?)` | Language switcher hook for no-locale-path and internal mode; `cookieOptions` takes the same attributes as the config option | | `Trans` | Re-exported from `react-i18next` | ### `next-i18next/icu` and `next-i18next/mf2` | Export | Description | |---|---| | `I18nProvider` | `I18nProvider` from `next-i18next/client` with i18next-icu (`/icu`) or i18next-mf2 (`/mf2`) registered on the client instance. Same props. See [ICU and MF2 with the App Router](#icu-and-mf2-with-the-app-router) | ### `next-i18next/pages` | Export | Description | |---|---| | `appWithTranslation` | HOC for `_app` | | `useTranslation` | Translation hook (re-exported from react-i18next) | | `Trans`, `I18nContext`, `withTranslation` | Re-exported from react-i18next | ### `next-i18next/pages/serverSideTranslations` | Export | Description | |---|---| | `serverSideTranslations(locale, ns?, config?, extraLocales?)` | Load translations for `getStaticProps` / `getServerSideProps` | ### Config Options | Option | Default | Description | |---|---|---| | `supportedLngs` | *required* | Array of supported language codes | | `fallbackLng` | *required* | Default language | | `defaultNS` | `'common'` | Default namespace | | `ns` | `[defaultNS]` | All known namespaces | | `localeInPath` | `true` | `true`: locale prefix in the URL. `false`: clean URLs, language from cookie/header (routes are dynamic). `'internal'`: clean URLs, locale segment only in the internal rewrite (routes stay prerenderable) | | `localeParamName` | `'lng'` | Name of the locale route segment (`app/[lng]`). Used by `generateI18nStaticParams` and root-param language detection | | `hideDefaultLocale` | `false` | When `true` (with `localeInPath: true`), the default language has no URL prefix | | `localePath` | `'/locales'` | Path to locale files relative to `/public` | | `localeStructure` | `'{{lng}}/{{ns}}'` | Locale file directory structure | | `localeExtension` | `'json'` | Locale file extension | | `resources` | β€” | Pre-loaded resources (skips dynamic loading) | | `resourceLoader` | β€” | Custom async loader `(lng, ns) => Promise` | | `basePath` | β€” | Route-folder prefix the proxy handles, e.g. `'/app-router'` for `app/app-router/[lng]/…` in mixed-router setups. Not needed for Next's own `basePath` from `next.config`, which the proxy handles automatically | | `cookieName` | `'i18next'` | Cookie name for language persistence | | `headerName` | `'x-i18next-current-language'` | Header name for server-side language passing | | `cookieMaxAge` | `31536000` (1 year) | Cookie max age in seconds | | `persistCookie` | `true` | Whether the proxy writes the language cookie. `false` reads it but never writes it, for apps where another system owns the cookie | | `cookieOptions` | `{}` | Extra cookie attributes (`domain`, `secure`, `sameSite`, `path`, `maxAge`) applied on top of `{ path: '/', maxAge: cookieMaxAge, sameSite: 'lax' }` | | `ignoredPaths` | `['/api', '/_next', '/static']` | Paths the proxy/middleware should skip | | `use` | `[]` | Extra i18next plugins | | `i18nextOptions` | `{}` | Additional i18next init options | | `nonExplicitSupportedLngs` | `false` | Match `'en'` to `'en-US'` etc. | --- ## Examples | Example | Description | |---|---| | [`app-router-simple`](examples/app-router-simple) | App Router with locale-in-path (`/en/...`) | | [`app-router-no-locale-path`](examples/app-router-no-locale-path) | App Router with cookie-based language (no locale in URL) | | [`app-router-icu`](examples/app-router-icu) | App Router with ICU MessageFormat: plurals, select and rich text in Server and Client Components | | [`mixed-routers`](examples/mixed-routers) | App Router + Pages Router in the same project | | [`pages-router-simple`](examples/pages-router-simple) | Pages Router with `getStaticProps` / `getServerSideProps` | | [`pages-router-ssg`](examples/pages-router-ssg) | Pages Router with static export (`output: 'export'`) | | [`pages-router-auto-static-optimize`](examples/pages-router-auto-static-optimize) | Pages Router with client-side loading via chained backend | --- ## Migration from v15 ### App Router users If you were using i18next and react-i18next directly (as recommended in v15): 1. `npm install next-i18next@16` 2. Create an `i18n.config.ts` with your languages and namespaces 3. Replace your custom proxy/middleware with `createProxy(config)` in `proxy.ts` 4. Replace your custom `getT` / translation init with `initServerI18next` + `getT` from `next-i18next/server` 5. Replace your custom `I18nProvider` with the one from `next-i18next/client` 6. Replace `useTranslation` with `useT` from `next-i18next/client` in client components ### Pages Router users 1. Update imports from `next-i18next` to `next-i18next/pages` 2. Update `serverSideTranslations` import to `next-i18next/pages/serverSideTranslations` 3. Update type imports: `import type { TFunction, WithTranslation, I18n } from 'next-i18next/pages'` 4. Everything else works the same --- ## Contributors Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)):
Rob Capellini
Rob Capellini

πŸ’» ⚠️
Alexander Kachkaev
Alexander Kachkaev

πŸ“’ πŸ’¬ πŸ€” πŸ’» ⚠️
Mathias WΓΈbbe
Mathias WΓΈbbe

πŸ’» πŸ€” ⚠️
Lucas Feliciano
Lucas Feliciano

πŸ€” πŸ‘€
Ryan Leung
Ryan Leung

πŸ’»
Nathan Friemel
Nathan Friemel

πŸ’» πŸ“– πŸ’‘ πŸ€”
Isaac Hinman
Isaac Hinman

πŸ’» πŸ“– πŸ€” 🚧
Adriano Raiano
Adriano Raiano

πŸ’» πŸ“– πŸ€” 🚧
Felix Mosheev
Felix Mosheev

πŸ’¬ πŸ’» ⚠️
SΓ©bastien Vanvelthem
SΓ©bastien Vanvelthem

πŸ’» πŸ“–
This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome! ---

Gold Sponsors

--- **localization as a service - [Locize](https://www.locize.com?utm_source=next_i18next_readme&utm_medium=github&utm_campaign=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! **Now with a [Free plan](https://www.locize.com/pricing?utm_source=next_i18next_readme&utm_medium=github&utm_campaign=readme) for small projects!** Perfect for hobbyists or getting started. By using [Locize](https://www.locize.com/?utm_source=next_i18next_readme&utm_medium=github&utm_campaign=readme) you directly support the future of i18next and next-i18next. ---