# next-i18next
[](https://www.npmjs.com/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}0>!"
}
```
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