next-i18next

The repository provides several reference implementations for different Next.js routing and deployment scenarios:

• App Router (Locale in path): app-router-simple (e.g., /en/...)
• App Router (Cookie-based): app-router-no-locale-path (no locale in URL)
• Mixed Routers: mixed-routers (using both App Router and Pages Router in one project)
• Pages Router (Standard): pages-router-simple (using getStaticProps / getServerSideProps)
• Pages Router (Static Export): pages-router-ssg (configured for output: 'export')
• Pages Router (Client-side loading): pages-router-auto-static-optimize (using chained backend for client-side loading)

If you were using i18next and react-i18next directly in v15, follow these steps to migrate to next-i18next v16 for App Router:

1. Install the new version: npm install next-i18next@16.
2. Create an i18n.config.ts file defining your languages and namespaces.
3. Replace custom proxy/middleware logic with createProxy(config) in a proxy.ts file.
4. Replace custom translation initialization/getT with initServerI18next and getT imported from next-i18next/server.
5. Replace your custom I18nProvider with the one provided by next-i18next/client.
6. In client components, replace useTranslation with useT from next-i18next/client.

For Next.js 16+, create a proxy.ts file at your project root. This replaces middleware.ts and handles language detection (via cookies or Accept-Language), redirects, and setting the x-i18next-current-language header for Server Components.

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).*)'],
}

To use clean URLs without a locale prefix (e.g., /about instead of /en/about), set localeInPath: false in your I18nConfig.

In this mode:

• Routes live directly under app/ (no [lng] segment).
• Middleware detects language from cookies or Accept-Language and sets the header without redirecting.
• Server Components use getT() to read language from the header.
• Client Components use useT() (language comes from I18nProvider).
• Use useChangeLanguage() to switch languages; it updates the cookie and triggers a server re-render.

const i18nConfig: I18nConfig = {
  supportedLngs: ['en', 'de'],
  fallbackLng: 'en',
  localeInPath: false,
  resourceLoader: (language, namespace) =>
    import(`./app/i18n/locales/${language}/${namespace}.jsonspi`),
}

If automatic configuration detection fails (common in monorepos/workspaces), you can manually provide the config object. This also allows you to use different file extensions like .mjs or .cjs.

1. Update _app.tsx

Pass the config as the second argument to appWithTranslation.

// _app.tsx
import type { AppProps } from 'next/app'
import { appWithTranslation } from 'next-i18next'
import nextI18NextConfig from '../next-i18next.config'

const MyApp = ({ Component, pageProps }: AppProps) => (
  <Component {...pageProps} />
)

export default appWithTranslation(MyApp, nextI18NextConfig)

2. Update getStaticProps or getServerSideProps

Instead of calling serverSideTranslations directly, create a wrapper function (e.g., getServerTranslations) that injects your configuration.

To set up next-i18next in a Next.js project, install the core packages using npm:

npm install next-i18next i18next react-i18next

For projects using only the Pages Router, use the next-i18next/pages API. You must wrap your _app.tsx with appWithTranslation and use serverSideTranslations in getStaticProps or getServerSideProps to load resources.

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

When using locale-in-path (e.g., /en/about), switch languages by navigating to the new locale prefix using next/navigation.

'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} onClick={() => switchLocale(lng)}>{lng}</button>
      ))}
    </div>
  )
}

To migrate Pages Router users from v15 to v16, update your imports as follows:

1. Change base imports from next-i18next to next-i18next/pages.
2. Update serverSideTranslations import to next-i18next/pages/serverSideTranslations.
3. Update type imports to use next-i18next/pages: import type { TFunction, WithTranslation, I18n } from 'next-i18next/pages'