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.

---

Table of Contents

• App Router Setup
• No-Locale-Path Mode
• 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.

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

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

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

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') }
}

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

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. It accepts [lng] or [locale] as the dynamic route param name.

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 (



      {supportedLngs.map((lng) => (
        <button key={lng} onClick={() => switchLocale(lng)}>{lng}</button>
      ))}



  )
}

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 (



      <button onClick={() => changeLanguage('en')}>English</button>
      <button onClick={() => changeLanguage('de')}>Deutsch</button>



  )
}

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.

---

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