next-i18next

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 and react-i18next 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, take a look at i18next-locize-backend. The i18next backend plugin for 🌐 Locize ☁️ — 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(), extracts keys, connects to Locize and AI-translates your app (review the diff for server components). See the launch post.

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):

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
• No-Locale-Path Mode
• ICU and MF2 with the App Router
• Mixed Router Setup
• Pages Router Setup
• Custom i18next Backends
• API Reference
• Examples
• Migration from v15

App Router Setup

1. Install

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):

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():

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):

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

// 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 (
    <html lang={lng}>
      <body>
        <I18nProvider language={lng} resources={resources}>
          {children}
        </I18nProvider>
      </body>
    </html>
  )
}

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:

// i18n.server.ts
import { createServerI18next } from 'next-i18next/server'
import i18nConfig from './i18n.config'

export const { getT, getResources, generateI18nStaticParams } = createServerI18next(i18nConfig)

// 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

// app/[lng]/page.tsx
import { getT } from 'next-i18next/server'

export default async function Home() {
  const { t } = await getT('home')
  return <h1>{t('title')}</h1>
}

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:

import { Trans } from 'react-i18next/TransWithoutContext'
import { getT } from 'next-i18next/server'

export default async function Page() {
  const { t, i18n } = await getT()
  return (
    <Trans t={t} i18n={i18n} i18nKey="welcome">
      Welcome to <strong>next-i18next</strong>
    </Trans>
  )
}

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

'use client'
import { useT } from 'next-i18next/client'

export default function Counter() {
  const { t } = useT('home')
  return <button>{t('click_me')}</button>
}

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:

'use client'
import { Trans, useT } from 'next-i18next/client'

export default function Greeting() {
  const { t } = useT()
  return <Trans t={t} i18nKey="greeting">Hello <strong>world</strong></Trans>
}

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:

'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 (
    <div>
      {supportedLngs.map((lng) => (
        <button key={lng} => switchLocale(lng)}>{lng}</button>
      ))}
    </div>
  )
}

For the no-locale-path mode (cookie-based), see useChangeLanguage below.

Hide Default Locale

If you want clean URLs for the default language while keeping locale prefixes for other languages, set hideDefaultLocale: true:

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:

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):

'use client'
import { useChangeLanguage } from 'next-i18next/client'

export function LanguageSwitcher() {
  const changeLanguage = useChangeLanguage()
  return (
    <div>
      <button => changeLanguage('en')}>English</button>
      <button => changeLanguage('de')}>Deutsch</button>
    </div>
  )
}

The root layout reads the language from getT() instead of URL params:

// app/layout.tsx (no [lng] segment)
export default async function RootLayout({ children }) {
  const { i18n, lng } = await getT()
  const resources = getResources(i18n)

  return (
    <I18nProvider language={lng} resources={resources}>
      <html lang={lng}>
        <body>{children}</body>
      </html>
    </I18nProvider>
  )
}

See 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':

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 <Link> 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

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:

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) or in Unicode MessageFormat 2 (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 lists what keeps working and what does not.

Install

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:

// 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:

{
  "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:

// 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 (
    <html lang={lng}>
      <body>
        <I18nProvider language={lng} resources={getResources(i18n)}>
          {children}
        </I18nProvider>
      </body>
    </html>
  )
}

A Server Component can not pass a plugin class to a Client Component as a prop: <I18nProvider use={[ICU]}> 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

// 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 (
    <main>
      <p>{t('photos', { count: 5 })}</p>
      <p>{t('order', { status: 'shipped' })}</p>
      <p>
        <IcuTransWithoutContext
          i18nKey='welcome'
          defaultTranslation='Welcome back, <0>{name}</0>!'
          content={[{ type: 'strong' }]}
          values={{ name: 'Ada' }}
          t={t}
          i18n={i18n}
        />
      </p>
    </main>
  )
}

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:

<Trans t={t} i18n={i18n} i18nKey='welcome' values={{ name: 'Ada' }} components={[<strong key='0' />]} />

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

'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 (
    <>
      <p>{t('photos', { count })}</p>
      <button => setCount(count + 1)}>+1</button>
      <IcuTrans
        i18nKey='welcome'
        defaultTranslation='Welcome back, <0>{name}</0>!'
        content={[{ type: 'strong' }]}
        values={{ name: 'Ada' }}
      />
    </>
  )
}

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 below); with typeof a JSON import every message is a string and nothing is checked:

// @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'
  }
}

// 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 1.76.0 or later knows both formats. Set extract.messageFormat to 'icu' or 'mf2' in your i18next.config.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 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:

// i18n.shared.js
module.exports = {
  supportedLngs: ['en', 'de'],
  fallbackLng: 'en',
  defaultNS: 'common',
  ns: ['common', 'footer'],
}

App Router config with basePath:

// 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:

// 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

// 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:

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 for a complete example.

Pages Router Setup

For projects using only the Pages Router, the familiar v15 API is available under next-i18next/pages:

// next-i18next.config.js
module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'de'],
  },
}

// next.config.js
const { i18n } = require('./next-i18next.config.js')
module.exports = { i18n }

// pages/_app.tsx
import { appWithTranslation } from 'next-i18next/pages'

const MyApp = ({ Component, pageProps }) => <Component {...pageProps} />
export default appWithTranslation(MyApp)

// 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 <h1>{t('title')}</h1>
}

See examples/pages-router-simple, examples/pages-router-ssg, and 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.

When a custom backend is provided via use, next-i18next will not add its default resource loader, giving you full control.

i18next-http-backend

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

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:

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:

<I18nProvider
  language={lng}
  resources={resources}
  use={[HttpBackend]}
  i18nextOptions={{
    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' },
  }}
>
  {children}
</I18nProvider>

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 <Suspense> boundary instead of rendering keys, and both passes render the same text:

'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 (
    <I18nProvider
      language={language}
      resources={resources} // app-shell namespaces only, e.g. getResources(i18n, ['common'], [lng])
      use={[backend]}
      ssrBackend
      i18nextOptions={{ react: { useSuspense: true } }}
    >
      <Suspense fallback={<Skeleton />}>{children}</Suspense>
    </I18nProvider>
  )
}

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

API Reference

next-i18next (root export)

next-i18next/proxy (also available as next-i18next/middleware)

next-i18next/server

next-i18next/client

next-i18next/icu and next-i18next/mf2

next-i18next/pages

next-i18next/pages/serverSideTranslations

Config Options

Examples

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):

Rob Capellini 💻 ⚠️	Alexander Kachkaev 📢 💬 🤔 💻 ⚠️	Mathias Wøbbe 💻 🤔 ⚠️	Lucas Feliciano 🤔 👀	Ryan Leung 💻	Nathan Friemel 💻 📖 💡 🤔	Isaac Hinman 💻 📖 🤔 🚧
Adriano Raiano 💻 📖 🤔 🚧	Felix Mosheev 💬 💻 ⚠️	Sébastien Vanvelthem 💻 📖

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

Gold Sponsors

localization as a service - Locize

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

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

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