---
createdAt: 2025-11-01
updatedAt: 2026-09-27
priority: 9
title: "Next.js 16 i18n with next-i18next: App Router Setup Guide"
description: "Set up next-i18next and i18next in a Next.js 16 App Router app step by step: namespaces, locale routing, server and client components, and SEO metadata."
keywords:
  - next-i18next
  - i18next
  - Internationalization
  - Blog
  - Next.js
  - JavaScript
  - React
slugs:
  - blog
  - nextjs-internationalization-using-next-i18next
applicationTemplate: https://github.com/aymericzip/next-i18next-template
history:
  - version: 7.0.6
    date: 2025-11-01
    changes: Initial version
author: aymericzip
---

# How to internationalize your Next.js application using next-i18next in 2026

## Table of Contents

<TOC/>

## What is next-i18next?

**next-i18next** is a popular internationalization (i18n) solution for Next.js applications. While the original `next-i18next` package was designed for the Pages Router, this guide shows you how to implement i18next with the modern **App Router** using `i18next` and `react-i18next` directly.

With this approach, you can:

- **Organize translations** using namespaces (e.g., `common.json`, `about.json`) for better content management.
- **Load translations efficiently** by loading only the namespaces needed for each page, reducing bundle size.
- **Support both server and client components** with proper SSR and hydration handling.
- **Ensure TypeScript support** with type-safe locale configuration and translation keys.
- **Optimize for SEO** with proper metadata, sitemap, and robots.txt internationalization.

> As an alternative, you can also refer to the [next-intl guide](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/i18n_using_next-intl.md), or directly using [Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_16.md).

- [next-intl guide](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/i18n_using_next-intl.md)
- [Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_16.md)

> See the comparison in [next-i18next vs next-intl vs Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/next-i18next_vs_next-intl_vs_intlayer.md).

- [next-i18next vs next-intl vs Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/next-i18next_vs_next-intl_vs_intlayer.md)

> To understand where these libraries come from, read the history of JavaScript i18n.

- [The history of JavaScript i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/history_of_i18n.md)

## What the benchmark says about next-i18next on Next.js

Before diving into setup, understanding the performance and bundle impact of your i18n library is essential. The [i18n benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/nextjs.md) runs the same 10-page, 10-locale Next.js application across major i18n libraries to measure real bundle footprint, string leakage, and hydration overhead.

- [i18n benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/nextjs.md)

<I18nBenchmark framework="nextjs" packages="next-i18next,@intlayer/next-i18next,next-intlayer" vertical/>

<ClickToOpenIframe
  src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md"
  width="100%"
  height="600px"
  style="border:none;"
/>

Key figures for `next-i18next` on Next.js (gzip):

| Setup                             | Library size | Page JS avg | Other-locale leak | Other-page leak |
| :-------------------------------- | -----------: | ----------: | ----------------: | --------------: |
| Base (no i18n)                    |            - |    141.0 KB |              0.0% |            0.0% |
| `next-i18next`                    |      19.7 KB |    169.5 KB |             50.0% |           89.8% |
| `@intlayer/next-i18next` (compat) |       9.4 KB |    150.7 KB |              0.0% |            0.0% |
| `next-intlayer` (native Intlayer) |       5.5 KB |    141.3 KB |              0.0% |            0.0% |

What to take away:

- **Namespace splitting is required:** In naive setups, `next-i18next` ships every namespace on every page (~89.8% page leakage). Splitting into namespaces per route and lazily loading them reduces page JS, but requires careful manual organization.
- **Runtime weight:** The `i18next` client runtime weighs ~19.7 KB gzip on every page. For existing codebases, the [`@intlayer/next-i18next`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/next-i18next.md) compat adapter preserves the same `i18next` API while shrinking runtime to 9.4 KB and eliminating leakage. Native [`next-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/next-intlayer/exports.md) drops down to 5.5 KB.

> See the full data: [Next.js benchmark report](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/nextjs.md), and the [benchmark repository](https://github.com/intlayer-org/benchmark-i18n).

- [Next.js benchmark report](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/nextjs.md)

## Feature comparison on Next.js

How `next-i18next` compares with `next-intl` and Intlayer on the features a Next.js App Router project usually needs:

| Feature                                     | `next-intlayer` (Intlayer)                         | `next-intl`                                            | `next-i18next`                            |
| ------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------- |
| **Translations near components**            | ✅ Content co-located with each component          | ❌ Centralized JSON                                    | ❌ Centralized JSON                       |
| **TypeScript integration**                  | ✅ Auto-generated strict types                     | ✅ Good, via `AppConfig` augmentation                  | ⚠️ Basic                                  |
| **Missing translation detection**           | ✅ TypeScript errors and build-time warnings       | ⚠️ Runtime fallback                                    | ⚠️ Runtime fallback                       |
| **Rich content (JSX, Markdown)**            | ✅ Direct support                                  | ⚠️ Tags via `t.rich`, no Markdown                      | ⚠️ Tags via `<Trans>`                     |
| **AI translation**                          | ✅ Your own provider and API key, with app context | ❌ No                                                  | ❌ No                                     |
| **Visual editor / CMS**                     | ✅ Local visual editor + optional CMS              | ❌ Via external platforms                              | ❌ Via external platforms                 |
| **Localized routing**                       | ✅ Built-in (Next.js and Vite)                     | ✅ Built-in `[locale]` segment                         | ✅ Built-in                               |
| **Pluralization**                           | ✅ Enumeration-based                               | ✅ ICU                                                 | ✅ Suffix-based (`_one`, `_other`)        |
| **Formatting (dates, numbers, currencies)** | ✅ `Intl`-based formatters                         | ✅ `useFormatter`                                      | ✅ `Intl`-based                           |
| **Content formats**                         | ✅ `.ts`, `.tsx`, `.js`, `.json`, `.md`, `.yaml`   | ✅ `.json`, `.js`, `.ts`                               | ⚠️ `.json`                                |
| **ICU MessageFormat**                       | ✅ Via `format: "icu"`                             | ✅ Native                                              | ⚠️ Via `i18next-icu`                      |
| **SEO helpers (hreflang, sitemap)**         | ✅ Metadata, sitemap and robots.txt helpers        | ✅ Good                                                | ✅ Good                                   |
| **Server Components**                       | ✅ Direct access in any Server Component           | ⚠️ Pass `t` or `await getTranslations()` per component | ⚠️ Pass `t` down the component tree       |
| **Per-component tree-shaking**              | ✅ At build time (Babel / SWC)                     | ⚠️ Manual, with `pick()` per route                     | ⚠️ Manual, with namespaces per route      |
| **Lazy loading**                            | ✅ Per locale and per dictionary                   | ✅ Per locale, namespaces managed by hand              | ✅ Per locale, namespaces managed by hand |
| **Runtime size (gzip, benchmark)**          | 4.9 KB                                             | 14.7 KB                                                | 19.7 KB                                   |
| **Missing translations in CI**              | ✅ `npx intlayer test`                             | ⚠️ Not built-in                                        | ⚠️ Not built-in, `saveMissing` at runtime |
| **Ecosystem / community**                   | ⚠️ Smaller, growing fast                           | ✅ Large                                               | ✅ Very large                             |

> Runtime sizes come from the [Next.js benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/nextjs.md). For a detailed discussion, read [next-i18next vs next-intl vs Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/next-i18next_vs_next-intl_vs_intlayer.md).

- [Next.js benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/nextjs.md)
- [next-i18next vs next-intl vs Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/next-i18next_vs_next-intl_vs_intlayer.md)

## Practices you should follow

Before we dive into the implementation, here are some practices you should follow:

- **Set HTML `lang` and `dir` attributes**
  In your layout, compute `dir` using `getLocaleDirection(locale)` and set `<html lang={locale} dir={dir}>` for proper accessibility and SEO.
- **Split messages by namespace**
  Organize JSON files per locale and namespace (e.g., `common.json`, `about.json`) to load only what you need.
- **Minimize client payload**
  On pages, send only required namespaces to `NextIntlClientProvider` (e.g., `pick(messages, ['common', 'about'])`).
- **Prefer static pages**
  Use static page as much as possible for better performance and SEO.
- **I18n in server components**
  Server components, like pages or all components not marked as `client` are statics and can be pre-rendered at build time. So we will have to pass the translation functions to them as props.
- **Set up TypeScript types**
  For your locales to ensure type safety throughout your application.
- **Proxy for redirection**
  Use a proxy to handle the locale detection and routing and redirect the user to the appropriate locale-prefixed URL.
- **Internationalization of your metadata, sitemap, robots.txt**
  Internationalize your metadata, sitemap, robots.txt using the `generateMetadata` function provided by Next.js to ensure a better discovery by search engines in all locales.
- **Localize Links**
  Localize Links using the `Link` component to redirect the user to the appropriate locale-prefixed URL. It's important to ensure the discovery of your pages in all locales.
- **Automate tests and translations**
  Automate tests and translations help loosing time to maintain your multilingual application.

> See our doc listing everything you need to know about internationalization and SEO: [Internationalization (i18n) with next-intl](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/internationalization_and_SEO.md).

- [Internationalization (i18n) with next-intl](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/internationalization_and_SEO.md)

## Step-by-Step Guide to Set Up i18next in a Next.js Application

<iframe
  src="https://ide.intlayer.org/aymericzip/next-i18next-template?file=src/app/i18n.ts"
  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
  loading="lazy"
/>

> See [Application Template](https://github.com/aymericzip/next-i18next-template) on GitHub.

Here's the project structure we'll be creating:

```bash
.
├── i18n.config.ts
└── src # Src is optional
    ├── locales
    │   ├── en
    │   │  ├── common.json
    │   │  └── about.json
    │   └── fr
    │      ├── common.json
    │      └── about.json
    ├── types
    │   └── i18next.d.ts
    ├── app
    │   ├── proxy.ts
    │   ├── i18n
    │   │   └── server.ts
    │   └── [locale]
    │       ├── layout.tsx
    │       ├── (home) # / (Route Group to not pollute all pages with home messages)
    │       │   ├── layout.tsx
    │       │   └── page.tsx
    │       └── about # /about
    │           ├── layout.tsx
    │           └── page.tsx
    └── components
        ├── I18nProvider.tsx
        ├── ClientComponent.tsx
        └── ServerComponent.tsx
```

<Steps>
<Step number={1} title="Install Dependencies">

Install the necessary packages using npm:

```bash packageManager="npm"
npm install i18next react-i18next i18next-resources-to-backend
```

```bash packageManager="pnpm"
pnpm add i18next react-i18next i18next-resources-to-backend
```

```bash packageManager="yarn"
yarn add i18next react-i18next i18next-resources-to-backend
```

- **i18next**: The core internationalization framework that handles translation loading and management.
- **react-i18next**: React bindings for i18next that provide hooks like `useTranslation` for client components.
- **i18next-resources-to-backend**: A plugin that enables dynamic loading of translation files, allowing you to load only the namespaces you need.

</Step>
<Step number={2} title="Configure Your Project">

Create a configuration file to define your supported locales, default locale, and helper functions for URL localization. This file serves as the single source of truth for your i18n setup and ensures type safety throughout your application.

Centralizing your locale configuration prevents inconsistencies and makes it easier to add or remove locales in the future. The helper functions ensure consistent URL generation for SEO and routing.

```ts fileName="i18n.config.ts"
// Define supported locales as a const array for type safety
// The 'as const' assertion makes TypeScript infer literal types instead of string[]
export const locales = ["en", "fr"] as const;

// Extract the Locale type from the locales array
// This creates a union type: "en" | "fr"
export type Locale = (typeof locales)[number];

// Set the default locale used when no locale is specified
export const defaultLocale: Locale = "en";

// Right-to-left languages that need special text direction handling
export const rtlLocales = ["ar", "he", "fa", "ur"] as const;

// Check if a locale requires RTL (right-to-left) text direction
// Used for languages like Arabic, Hebrew, Persian, and Urdu
export const isRtl = (locale: string) =>
  (rtlLocales as readonly string[]).includes(locale);

// Generate a localized path for a given locale and path
// Default locale paths don't have a prefix (e.g., "/about" instead of "/en/about")
// Other locales are prefixed (e.g., "/fr/about")
export function localizedPath(locale: string, path: string) {
  return locale === defaultLocale ? path : `/${locale}${path}`;
}

// Base URL for absolute URLs (used in sitemaps, metadata, etc.)
const ORIGIN = "https://example.com";

// Generate an absolute URL with locale prefix
// Used for SEO metadata, sitemaps, and canonical URLs
export function absoluteUrl(locale: string, path: string) {
  return `${ORIGIN}${localizedPath(locale, path)}`;
}

// Used to set the locale cookie in the browser
export function getCookie(locale: Locale) {
  return [
    `NEXT_LOCALE=${locale}`,
    "Path=/",
    `Max-Age=${60 * 60 * 24 * 365}`, // 1 year
    "SameSite=Lax",
  ].join("; ");
}
```

</Step>
<Step number={3} title="Centralize Translation Namespaces">

Create a single source of truth for every namespace your application exposes. Reusing this list keeps server, client, and tooling code in sync and unlocks strong typing for translation helpers.

```ts fileName="src/i18n.namespaces.ts"
export const namespaces = ["common", "about"] as const;

export type Namespace = (typeof namespaces)[number];
```

</Step>
<Step number={4} title="Strongly Type Translation Keys with TypeScript">

Augment `i18next` to point at your canonical language files (usually English). TypeScript then infers valid keys per namespace, so calls to `t()` are checked end-to-end.

```ts fileName="src/types/i18next.d.ts"
import "i18next";

declare module "i18next" {
  interface CustomTypeOptions {
    defaultNS: "common";
    resources: {
      common: typeof import("@/locales/en/common.json");
      about: typeof import("@/locales/en/about.json");
    };
  }
}
```

> Tip: Store this declaration under `src/types` (create the folder if it doesn't exist). Next.js already includes `src` in `tsconfig.json`, so the augmentation is picked up automatically. If not, add the following to your `tsconfig.json` file:

```json5 fileName="tsconfig.json"
{
  "include": ["src/types/**/*.ts"],
}
```

With this in place you can rely on autocomplete and compile-time checks:

```tsx
import { useTranslation, type TFunction } from "react-i18next";

const { t } = useTranslation("about");

// OK, typed: t("counter.increment")
// ERROR, compile error: t("doesNotExist")
export type AboutTranslator = TFunction<"about">;
```

</Step>
<Step number={5} title="Set Up Server-Side i18n Initialization">

Create a server-side initialization function that loads translations for server components. This function creates a separate i18next instance for server-side rendering, ensuring that translations are loaded before rendering.

Server components need their own i18next instance because they run in a different context than client components. Pre-loading translations on the server prevents flash of untranslated content and improves SEO by ensuring search engines see translated content.

```ts fileName="src/app/i18n/server.ts"
import { createInstance } from "i18next";
import { initReactI18next } from "react-i18next/initReactI18next";
import resourcesToBackend from "i18next-resources-to-backend";
import { defaultLocale } from "@/i18n.config";
import { namespaces, type Namespace } from "@/i18n.namespaces";

// Configure dynamic resource loading for i18next
// This function dynamically imports translation JSON files based on locale and namespace
// Example: locale="fr", namespace="about" -> imports "@/locales/fr/about.json"
const backend = resourcesToBackend(
  (locale: string, namespace: string) =>
    import(`@/locales/${locale}/${namespace}.json`)
);

const DEFAULT_NAMESPACES = [
  namespaces[0],
] as const satisfies readonly Namespace[];

/**
 * Initialize i18next instance for server-side rendering
 *
 * @returns Initialized i18next instance ready for server-side use
 */
export async function initI18next(
  locale: string,
  ns: readonly Namespace[] = DEFAULT_NAMESPACES
) {
  // Create a new i18next instance (separate from client-side instance)
  const i18n = createInstance();

  // Initialize with React integration and backend loader
  await i18n
    .use(initReactI18next) // Enable React hooks support
    .use(backend) // Enable dynamic resource loading
    .init({
      lng: locale,
      fallbackLng: defaultLocale,
      ns, // Load only specified namespaces for better performance
      defaultNS: "common", // Default namespace when none is specified
      interpolation: { escapeValue: false }, // Don't escape HTML (React handles XSS protection)
      react: { useSuspense: false }, // Disable Suspense for SSR compatibility
      returnNull: false, // Return empty string instead of null for missing keys
      initImmediate: false, // Defer initialization until resources are loaded (faster SSR)
    });
  return i18n;
}
```

</Step>
<Step number={6} title="Create Client-Side i18n Provider">

Create a client component provider that wraps your application with i18next context. This provider receives pre-loaded translations from the server to prevent flash of untranslated content (FOUC) and avoid duplicate fetching.

Client components need their own i18next instance that runs in the browser. By accepting pre-loaded resources from the server, we ensure seamless hydration and prevent content flashing. The provider also manages locale changes and namespace loading dynamically.

```tsx fileName="src/components/I18nProvider.tsx"
"use client";

import { useEffect, useState } from "react";
import { I18nextProvider } from "react-i18next";
import { createInstance, type ResourceLanguage } from "i18next";
import { initReactI18next } from "react-i18next/initReactI18next";
import resourcesToBackend from "i18next-resources-to-backend";
import { defaultLocale } from "@/i18n.config";
import { namespaces as allNamespaces, type Namespace } from "@/i18n.namespaces";

// Configure dynamic resource loading for client-side
// Same pattern as server-side, but this instance runs in the browser
const backend = resourcesToBackend(
  (locale: string, namespace: string) =>
    import(`@/locales/${locale}/${namespace}.json`)
);

type Props = {
  locale: string;
  namespaces?: readonly Namespace[];
  // Pre-loaded resources from server (prevents FOUC - Flash of Untranslated Content)
  // Format: { namespace: translationBundle }
  resources?: Record<Namespace, ResourceLanguage>;
  children: React.ReactNode;
};

/**
 * Client-side i18n provider that wraps the app with i18next context
 * Receives pre-loaded resources from server to avoid re-fetching translations
 */
export default function I18nProvider({
  locale,
  namespaces = [allNamespaces[0]] as const,
  resources,
  children,
}: Props) {
  // Create i18n instance once using useState lazy initializer
  // This ensures the instance is created only once, not on every render
  const [i18n] = useState(() => {
    const i18nInstance = createInstance();

    i18nInstance
      .use(initReactI18next)
      .use(backend)
      .init({
        lng: locale,
        fallbackLng: defaultLocale,
        ns: namespaces,
        // If resources are provided (from server), use them to avoid client-side fetching
        // This prevents FOUC and improves initial load performance
        resources: resources ? { [locale]: resources } : undefined,
        defaultNS: "common",
        interpolation: { escapeValue: false },
        react: { useSuspense: false },
        returnNull: false, // Prevent undefined values from being returned
      });

    return i18nInstance;
  });

  // Update language when locale prop changes
  useEffect(() => {
    i18n.changeLanguage(locale);
  }, [locale, i18n]);

  // Ensure all required namespaces are loaded client-side
  // Using join("|") as dependency to compare arrays correctly
  useEffect(() => {
    i18n.loadNamespaces(namespaces);
  }, [namespaces.join("|"), i18n]);

  // Provide i18n instance to all child components via React context
  return <I18nextProvider i18n={i18n}>{children}</I18nextProvider>;
}
```

</Step>
<Step number={7} title="Define Dynamic Locale Routes">

Set up dynamic routing for locales by creating a `[locale]` directory in your app folder. This allows Next.js to handle locale-based routing where each locale becomes a URL segment (e.g., `/en/about`, `/fr/about`).

Using dynamic routes enables Next.js to generate static pages for all locales at build time, improving performance and SEO. The layout component sets the HTML `lang` and `dir` attributes based on the locale, which is crucial for accessibility and search engine understanding.

```tsx fileName="src/app/[locale]/layout.tsx"
import type { ReactNode } from "react";
import { locales, defaultLocale, isRtl, type Locale } from "@/i18n.config";

// Disable dynamic params - all locales must be known at build time
// This ensures static generation for all locale routes
export const dynamicParams = false;

/**
 * Generate static params for all locales at build time
 * Next.js will pre-render pages for each locale returned here
 * Example: [{ locale: "en" }, { locale: "fr" }]
 */
export function generateStaticParams() {
  return locales.map((locale) => ({ locale }));
}

/**
 * Root layout component that handles locale-specific HTML attributes
 * Sets the lang attribute and text direction (ltr/rtl) based on locale
 */
export default function LocaleLayout({
  children,
  params,
}: {
  children: ReactNode;
  params: { locale: string };
}) {
  // Validate locale from URL params
  // If invalid locale is provided, fall back to default locale
  const locale: Locale = (locales as readonly string[]).includes(params.locale)
    ? params.locale
    : defaultLocale;

  // Determine text direction based on locale
  // RTL languages like Arabic need dir="rtl" for proper text rendering
  const dir = isRtl(locale) ? "rtl" : "ltr";

  return (
    <html lang={locale} dir={dir}>
      <body>{children}</body>
    </html>
  );
}
```

</Step>
<Step number={8} title="Create Your Translation Files">

Create JSON files for each locale and namespace. This structure allows you to organize translations logically and load only what you need for each page.

Organizing translations by namespace (e.g., `common.json`, `about.json`) enables code splitting and reduces bundle size. You only load the translations needed for each page, improving performance.

<Tabs group="locale">
 <Tab value='en' label='English'>

```json fileName="src/locales/en/common.json"
{
  "appTitle": "Next.js i18n App",
  "appDescription": "Example Next.js application with internationalization using i18next"
}
```

 </Tab>
 <Tab value='fr' label='French'>

```json fileName="src/locales/fr/common.json"
{
  "appTitle": "Application Next.js i18n",
  "appDescription": "Exemple d'application Next.js avec internationalisation utilisant i18next"
}
```

 </Tab>
</Tabs>

<Tabs group="locale">
 <Tab value='en' label='English'>

```json fileName="src/locales/en/home.json"
{
  "title": "Home",
  "description": "Home page description",
  "welcome": "Welcome",
  "greeting": "Hello, world!",
  "aboutPage": "About Page",
  "documentation": "Documentation"
}
```

 </Tab>
 <Tab value='fr' label='French'>

```json fileName="src/locales/fr/home.json"
{
  "title": "Accueil",
  "description": "Description de la page d'accueil",
  "welcome": "Bienvenue",
  "greeting": "Bonjour le monde!",
  "aboutPage": "Page À propos",
  "documentation": "Documentation"
}
```

 </Tab>
</Tabs>

<Tabs group="locale">
 <Tab value='en' label='English'>

```json fileName="src/locales/en/about.json"
{
  "title": "About",
  "description": "About page description",
  "counter": {
    "label": "Counter",
    "increment": "Increment",
    "description": "Click the button to increase the counter"
  }
}
```

 </Tab>
 <Tab value='fr' label='French'>

```json fileName="src/locales/fr/about.json"
{
  "title": "À propos",
  "description": "Description de la page À propos",
  "counter": {
    "label": "Compteur",
    "increment": "Incrémenter",
    "description": "Cliquez sur le bouton pour augmenter le compteur"
  }
}
```

 </Tab>
</Tabs>

</Step>
<Step number={9} title="Utilize Translations in Your Pages">

Create a page component that initializes i18next on the server and passes translations to both server and client components. This ensures that translations are loaded before rendering and prevents content flashing.

Server-side initialization loads translations before the page renders, improving SEO and preventing FOUC. By passing pre-loaded resources to the client provider, we avoid duplicate fetching and ensure smooth hydration.

```tsx fileName="src/app/[locale]/about/index.tsx"
import I18nProvider from "@/components/I18nProvider";
import { initI18next } from "@/app/i18n/server";
import type { Locale } from "@/i18n.config";
import { namespaces as allNamespaces, type Namespace } from "@/i18n.namespaces";
import type { ResourceLanguage } from "i18next";
import ClientComponent from "@/components/ClientComponent";
import ServerComponent from "@/components/ServerComponent";

/**
 * Server component page that handles i18n initialization
 * Pre-loads translations on the server and passes them to client components
 */
export default async function AboutPage({
  params: { locale },
}: {
  params: { locale: Locale };
}) {
  // Define which translation namespaces this page needs
  // Reuse the centralized list for type safety and autocomplete
  const pageNamespaces = allNamespaces;

  // Initialize i18next on the server with required namespaces
  // This loads translation JSON files server-side
  const i18n = await initI18next(locale, pageNamespaces);

  // Get a fixed translation function for the "about" namespace
  // getFixedT locks the namespace, so t("title") instead of t("about:title")
  const tAbout = i18n.getFixedT(locale, "about");

  // Extract translation bundles from the i18n instance
  // This data is passed to I18nProvider to hydrate client-side i18n
  // Prevents FOUC (Flash of Untranslated Content) and avoids duplicate fetching
  const resources = Object.fromEntries(
    pageNamespaces.map((ns) => [ns, i18n.getResourceBundle(locale, ns)])
  ) satisfies Record<Namespace, ResourceLanguage>;

  return (
    <I18nProvider
      locale={locale}
      namespaces={pageNamespaces}
      resources={resources}
    >
      <main>
        <h1>{tAbout("title")}</h1>

        <ClientComponent />
        <ServerComponent t={tAbout} locale={locale} count={0} />
      </main>
    </I18nProvider>
  );
}
```

</Step>
<Step number={10} title="Use Translations in Client Components">

Client components can use the `useTranslation` hook to access translations. This hook provides access to the translation function and the i18n instance, allowing you to translate content and access locale information.

Client components need React hooks to access translations. The `useTranslation` hook integrates seamlessly with i18next and provides reactive updates when the locale changes.

> Ensure the page/provider includes only the namespaces you need (e.g., `about`).  
> If you use React < 19, memoize heavy formatters like `Intl.NumberFormat`.

```tsx fileName="src/components/ClientComponent.tsx"
"use client";

import { useState } from "react";
import { useTranslation } from "react-i18next";

/**
 * Client component example using React hooks for translations
 * Can use hooks like useState, useEffect, and useTranslation
 */
const ClientComponent = () => {
  // useTranslation hook provides access to translation function and i18n instance
  // Specify namespace to only load translations for "about" namespace
  const { t, i18n } = useTranslation("about");
  const [count, setCount] = useState(0);

  // Create locale-aware number formatter
  // i18n.language provides current locale (e.g., "en", "fr")
  // Intl.NumberFormat formats numbers according to locale conventions
  const numberFormat = new Intl.NumberFormat(i18n.language);

  return (
    <div className="flex flex-col items-center gap-4">
      {/* Format number using locale-specific formatting */}
      <p className="text-5xl font-bold text-white m-0">
        {numberFormat.format(count)}
      </p>
      <button
        type="button"
        className="flex h-12 w-full items-center justify-center gap-2 rounded-full bg-foreground px-5 text-background transition-colors hover:bg-[#383838] dark:hover:bg-[#ccc] md:w-[158px]"
        aria-label={t("counter.label")}
        onClick={() => setCount((c) => c + 1)}
      >
        {t("counter.increment")}
      </button>
    </div>
  );
};

export default ClientComponent;
```

</Step>
<Step number={11} title="Use Translations in Server Components">

Server components cannot use React hooks, so they receive translations via props from their parent components. This approach keeps server components synchronous and allows them to be nested inside client components.

Server components that might be nested under client boundaries need to be synchronous. By passing translated strings and locale information as props, we avoid async operations and ensure proper rendering.

```tsx fileName="src/components/ServerComponent.tsx"
import type { TFunction } from "i18next";

type ServerComponentProps = {
  // Translation function passed from parent server component
  // Server components can't use hooks, so translations come via props
  t: TFunction<"about">;
  locale: string;
  count: number;
};

/**
 * Server component example - receives translations as props
 * Can be nested inside client components (async server components)
 * Cannot use React hooks, so all data must come from props or async operations
 */
const ServerComponent = ({ t, locale, count }: ServerComponentProps) => {
  // Format number server-side using locale
  // This runs on the server during SSR, improving initial page load
  const formatted = new Intl.NumberFormat(locale).format(count);

  return (
    <div className="flex flex-col items-center gap-4">
      <p className="text-5xl font-bold text-white m-0">{formatted}</p>
      {/* Use translation function passed as prop */}
      <div className="flex flex-col items-center gap-2">
        <span className="text-xl font-semibold text-white">
          {t("counter.label")}
        </span>
        <span className="text-sm opacity-80 italic">
          {t("counter.description")}
        </span>
      </div>
    </div>
  );
};

export default ServerComponent;
```

</Step>
<Step number={12} title="Change the language of your content" isOptional={true}>

To change the language of your content in Next.js, the recommended way is to use locale-prefixed URLs and Next.js links. The example below reads the current locale from the route, strips it from the pathname, and renders one link per available locale.

```tsx fileName="src/components/LocaleSwitcher.tsx"
"use client";

import Link from "next/link";
import { useParams, usePathname } from "next/navigation";
import { useMemo } from "react";
import { defaultLocale, getCookie, type Locale, locales } from "@/i18n.config";

export default function LocaleSwitcher() {
  const params = useParams();
  const pathname = usePathname();

  const activeLocale = (params?.locale as Locale | undefined) ?? defaultLocale;

  const getLocaleLabel = (locale: Locale): string => {
    try {
      const displayNames = new Intl.DisplayNames([locale], {
        type: "language",
      });
      return displayNames.of(locale) ?? locale.toUpperCase();
    } catch {
      return locale.toUpperCase();
    }
  };

  const basePath = useMemo(() => {
    if (!pathname) return "/";

    const segments = pathname.split("/").filter(Boolean);

    if (segments.length === 0) return "/";

    const maybeLocale = segments[0] as Locale;

    if ((locales as readonly string[]).includes(maybeLocale)) {
      const rest = segments.slice(1).join("/");
      return rest ? `/${rest}` : "/";
    }

    return pathname;
  }, [pathname]);

  return (
    <nav aria-label="Language selector">
      {(locales as readonly Locale[]).map((locale) => {
        const isActive = locale === activeLocale;

        const href =
          locale === defaultLocale ? basePath : `/${locale}${basePath}`;

        return (
          <Link
            key={locale}
            href={href}
            aria-current={isActive ? "page" : undefined}
            onClick={() => {
              document.cookie = getCookie(locale);
            }}
          >
            {getLocaleLabel(locale)}
          </Link>
        );
      })}
    </nav>
  );
}
```

</Step>
<Step number={13} title="Build a localized Link component" isOptional={true}>

Reusing localized URLs across your app keeps navigation consistent and SEO-friendly. Wrap `next/link` in a small helper that prefixes internal routes with the active locale while leaving external URLs untouched.

```tsx fileName="src/components/LocalizedLink.tsx"
"use client";

import NextLink, { type LinkProps } from "next/link";
import { useParams } from "next/navigation";
import type { ComponentProps, PropsWithChildren } from "react";
import {
  defaultLocale,
  type Locale,
  locales,
  localizedPath,
} from "@/i18n.config";

const isExternal = (href: string) => /^https?:\/\//.test(href);

type LocalizedLinkProps = PropsWithChildren<
  Omit<LinkProps, "href"> &
    Omit<ComponentProps<"a">, "href"> & { href: string; locale?: Locale }
>;

export default function LocalizedLink({
  href,
  locale,
  children,
  ...props
}: LocalizedLinkProps) {
  const params = useParams();
  const fallback = (params?.locale as Locale | undefined) ?? defaultLocale;
  const normalizedLocale = (locales as readonly string[]).includes(fallback)
    ? ((locale ?? fallback) as Locale)
    : defaultLocale;

  const normalizedPath = href.startsWith("/") ? href : `/${href}`;
  const localizedHref = isExternal(href)
    ? href
    : localizedPath(normalizedLocale, normalizedPath);

  return (
    <NextLink href={localizedHref} {...props}>
      {children}
    </NextLink>
  );
}
```

> Tip: Because `LocalizedLink` is a drop-in replacement, migrate gradually by swapping imports and letting the component handle locale-specific URLs.

</Step>
<Step number={14} title="Access the active locale inside Server Actions" isOptional={true}>

Server Actions often need the current locale for emails, logging, or third-party integrations. Combine the locale cookie set by your proxy with the `Accept-Language` header as a fallback.

```ts fileName="src/app/actions/get-current-locale.ts"
"use server";

import { cookies, headers } from "next/headers";
import { defaultLocale, locales, type Locale } from "@/i18n.config";

const KNOWN_LOCALES = new Set(locales as readonly string[]);

const normalize = (value: string | undefined): Locale | undefined => {
  if (!value) return undefined;
  const base = value.toLowerCase().split("-")[0];
  return KNOWN_LOCALES.has(base) ? (base as Locale) : undefined;
};

export async function getCurrentLocale(): Promise<Locale> {
  const cookieLocale = normalize(cookies().get("NEXT_LOCALE")?.value);

  if (cookieLocale) return cookieLocale;

  const headerLocale = normalize(headers().get("accept-language"));
  return headerLocale ?? defaultLocale;
}

// Example of a server action that uses the current locale
export async function stuffFromServer(formData: FormData) {
  const locale = await getCurrentLocale();

  // Use the locale for localized side effects (emails, CRM, etc.)
  console.log(`Stuff from server with locale ${locale}`);
}
```

> Because the helper relies on Next.js cookies and headers, it works in Route Handlers, Server Actions, and other server-only contexts.

</Step>
<Step number={15} title="Internationalize Your Metadata" isOptional={true}>

Translating content is important, but the main goal of internationalization is to make your website more visible to the world. I18n is an incredible lever to improve your website visibility through proper SEO.

Properly internationalized metadata helps search engines understand what languages are available on your pages. This includes setting hreflang meta tags, translating titles and descriptions, and ensuring canonical URLs are correctly set for each locale.

Here's a list of good practices regarding multilingual SEO:

- Set hreflang meta tags in the `<head>` tag to help search engines understand what languages are available on the page
- List all page translations in the sitemap.xml using the `http://www.w3.org/1999/xhtml` XML schema
- Do not forget to exclude prefixed pages from the robots.txt (e.g., `/dashboard`, `/fr/dashboard`, `/es/dashboard`)
- Use custom Link component to redirect to the most localized page (e.g., in French `<a href="/fr/about">À propos</a>`)

Developers often forget to properly reference their pages across locales. Let's fix that:

```tsx fileName="src/app/[locale]/about/layout.tsx"
import type { Metadata } from "next";
import {
  locales,
  defaultLocale,
  localizedPath,
  absoluteUrl,
} from "@/i18n.config";

/**
 * Generate SEO metadata for each locale version of the page
 * This function runs for each locale at build time
 */
export async function generateMetadata({
  params,
}: {
  params: { locale: string };
}): Promise<Metadata> {
  const { locale } = params;

  // Dynamically import translation file for this locale
  // Used to get translated title and description for metadata
  const messages = (await import(`@/locales/${locale}/about.json`)).default;

  // Create hreflang mapping for all locales
  // Helps search engines understand language alternatives
  // Format: { "en": "/about", "fr": "/fr/about" }
  const languages = Object.fromEntries(
    locales.map((locale) => [locale, localizedPath(locale, "/about")])
  );

  return {
    title: messages.title,
    description: messages.description,
    alternates: {
      // Canonical URL for this locale version
      canonical: absoluteUrl(locale, "/about"),
      // Language alternatives for SEO (hreflang tags)
      // "x-default" specifies the default locale version
      languages: {
        ...languages,
        "x-default": absoluteUrl(defaultLocale, "/about"),
      },
    },
  };
}

export default async function AboutPage() {
  return <h1>About</h1>;
}
```

</Step>
<Step number={16} title="Internationalize Your Sitemap" isOptional={true}>

Generate a sitemap that includes all locale versions of your pages. This helps search engines discover and index all language versions of your content.

A properly internationalized sitemap ensures search engines can find and index all language versions of your pages. This improves visibility in international search results.

```ts fileName="src/app/sitemap.ts"
import type { MetadataRoute } from "next";
import { defaultLocale, locales } from "@/i18n";

const origin = "https://example.com";

const formatterLocalizedPath = (locale: string, path: string) =>
  locale === defaultLocale ? `${origin}${path}` : `${origin}/${locale}${path}`;

/**
 * Get a map of all locales and their localized paths
 *
 * Example output:
 * {
 *   "en": "https://example.com",
 *   "fr": "https://example.com/fr",
 *   "es": "https://example.com/es",
 *   "x-default": "https://example.com"
 * }
 */
const getLocalizedMap = (path: string) =>
  Object.fromEntries([
    ...locales.map((locale) => [locale, formatterLocalizedPath(locale, path)]),
    ["x-default", formatterLocalizedPath(defaultLocale, path)],
  ]);

// Generate sitemap with all locale variants for better SEO
// The alternates field tells search engines about language versions
export default function sitemap(): MetadataRoute.Sitemap {
  return [
    {
      url: formatterLocalizedPath(defaultLocale, "/"),
      lastModified: new Date(),
      changeFrequency: "monthly",
      priority: 1.0,
      alternates: { languages: getLocalizedMap("/") },
    },
    {
      url: formatterLocalizedPath(defaultLocale, "/about"),
      lastModified: new Date(),
      changeFrequency: "monthly",
      priority: 0.7,
      alternates: { languages: getLocalizedMap("/about") },
    },
  ];
}
```

</Step>
<Step number={17} title="Internationalize Your robots.txt" isOptional={true}>

Create a robots.txt file that properly handles all locale versions of your protected routes. This ensures that search engines don't index admin or dashboard pages in any language.

Properly configuring robots.txt for all locales prevents search engines from indexing sensitive pages in any language. This is crucial for security and privacy.

```ts fileName="src/app/robots.ts"
import type { MetadataRoute } from "next";
import { defaultLocale, locales } from "@/i18n";

const origin = "https://example.com";

// Generate paths for all locales (e.g., /admin, /fr/admin, /es/admin)
const withAllLocales = (path: string) => [
  path,
  ...locales
    .filter((locale) => locale !== defaultLocale)
    .map((locale) => `/${locale}${path}`),
];

const disallow = [...withAllLocales("/dashboard"), ...withAllLocales("/admin")];

export default function robots(): MetadataRoute.Robots {
  return {
    rules: { userAgent: "*", allow: ["/"], disallow },
    host: origin,
    sitemap: `${origin}/sitemap.xml`,
  };
}
```

</Step>
<Step number={18} title="Set Up Middleware for Locale Routing" isOptional={true}>

Create a proxy to automatically detect the user's preferred locale and redirect them to the appropriate locale-prefixed URL. This improves user experience by showing content in their preferred language.

Middleware ensures that users are automatically redirected to their preferred language when they visit your site. It also saves the user's preference in a cookie for future visits.

```ts fileName="src/proxy.ts"
import { NextResponse, type NextRequest } from "next/server";
import { defaultLocale, locales } from "@/i18n.config";

// Regex to match files with extensions (e.g., .js, .css, .png)
// Used to exclude static assets from locale routing
const PUBLIC_FILE = /\.[^/]+$/;

/**
 * Extract locale from Accept-Language header
 * Handles formats like "fr-CA", "en-US", etc.
 * Falls back to default locale if browser language is not supported
 */
const pickLocale = (accept: string | null) => {
  // Get first language preference (e.g., "fr-CA" from "fr-CA,en-US;q=0.9")
  const raw = accept?.split(",")[0] ?? defaultLocale;
  // Extract base language code (e.g., "fr" from "fr-CA")
  const base = raw.toLowerCase().split("-")[0];
  // Check if we support this locale, otherwise use default
  return (locales as readonly string[]).includes(base) ? base : defaultLocale;
};

/**
 * Next.js proxy for locale detection and routing
 * Runs on every request before the page renders
 * Automatically redirects to locale-prefixed URLs when needed
 */
export function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Skip proxy for Next.js internals, API routes, and static files
  // These should not be locale-prefixed
  if (
    pathname.startsWith("/_next") ||
    pathname.startsWith("/api") ||
    pathname.startsWith("/static") ||
    PUBLIC_FILE.test(pathname)
  ) {
    return;
  }

  // Check if URL already has a locale prefix
  // Example: "/fr/about" or "/en" would return true
  const hasLocale = (locales as readonly string[]).some(
    (locale) => pathname === `/${locale}` || pathname.startsWith(`/${locale}/`)
  );

  // If no locale prefix, detect locale and redirect
  if (!hasLocale) {
    // Try to get locale from cookie first (user preference)
    const cookieLocale = request.cookies.get("NEXT_LOCALE")?.value;

    // Use cookie locale if valid, otherwise detect from browser headers
    const locale =
      cookieLocale && (locales as readonly string[]).includes(cookieLocale)
        ? cookieLocale
        : pickLocale(request.headers.get("accept-language"));

    // Clone URL to modify pathname
    const url = request.nextUrl.clone();
    // Add locale prefix to pathname
    // Handle root path specially to avoid double slash
    url.pathname = `/${locale}${pathname === "/" ? "" : pathname}`;

    // Create redirect response and set locale cookie
    const res = NextResponse.redirect(url);
    res.cookies.set("NEXT_LOCALE", locale, { path: "/" });
    return res;
  }
}

export const config = {
  matcher: [
    // Match all paths except:
    // - API routes (/api/*)
    // - Next.js internals (/_next/*)
    // - Static files (/static/*)
    // - Files with extensions (.*\\..*)
    "/((?!api|_next|static|.*\\..*).*)",
  ],
};
```

</Step>
<Step number={19} title="Automate Your Translations Using Intlayer" isOptional={true}>

Intlayer is a **free** and **open-source** library designed to assist the localization process in your application. While i18next handles the translation loading and management, Intlayer helps automate the translation workflow.

Managing translations manually can be time-consuming and error-prone. Intlayer automates translation testing, generation, and management, saving you time and ensuring consistency across your application.

Intlayer will allows your to:

- **Declare your content where you want in your codebase**
  Intlayer allows to declare your content where you want in your codebase using `.content.{ts|js|json}` files. It will allow a better organization of your content, ensuring better readability and maintainability of your codebase.

- **Test missing translations**
  Intlayer provide test functions to that can be integrated in your CI/CD pipeline, or in your unit tests. Learn more about [testing your translations](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/testing.md).

- **Automate your translations**,
  Intlayer provide a CLI and a VSCode extension to automate your translations. It can be integrated in your CI/CD pipeline. Learn more about [automating your translations](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md).
  You can use your **own API key, and the AI provider of your choice**. It also provide context aware translations, see [fill content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/autoFill.md).

- **Connect external content**
  Intlayer allows you to connect your content to an external content management system (CMS). To fetch it in a optimized way and insert it in your JSON resources. Learn more about [fetching external content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/function_fetching.md).

- **Visual editor**
  Intlayer offers an free visual editor to edit your content using a visual editor. Learn more about [visual editing your translations](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md).

And more. To discover all the features provided by Intlayer, please refer to the [Interest of Intlayer documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/interest_of_intlayer.md).

- [Interest of Intlayer documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/interest_of_intlayer.md)

For detailed performance benchmarks and comparisons, see:

- [Next.js Benchmark Report](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/nextjs.md)
- [i18n Benchmark Suite](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/index.md)
- [i18next vs @intlayer/i18next](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/i18next_vs_intlayer-i18next.md)
- [@intlayer/next-i18next Compat Adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/next-i18next.md)

</Step>

</Steps>

<Sponsor startDate="2026-08-24" endDate="2027-08-24">

Once you have namespaces like common.json and about.json typed through i18next's module augmentation, you've effectively defined a content schema. The next question is where that schema lives and who edits it. Sanity treats it as first-class: you model fields, references, and validation in code, and editors work against that same model in Sanity Studio instead of hand-editing JSON per locale.

Content lives in the Content Lake as structured JSON, queryable through GROQ and served via API, with locale as a field rather than a folder. For a Next.js App Router setup, you can fetch a namespace on the server, pass it into your i18n provider exactly as this pattern expects, and let the same source feed apps, emails, and agents. As locales and surfaces grow, the schema stays the contract; the delivery layer stays i18next.

</Sponsor>