# General Translation Knowledge Base: Comment ajouter l’i18n à une application Next.js utilisant le Pages Router ?
URL: https://generaltranslation.com/fr/kb/add-i18n-to-nextjs-pages-router.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Ajoutez un bloc i18n contenant locales et defaultLocale à next.config.js, et Next.js sert /es et /fr, redirige les visiteurs selon la langue de leur navigateur et transmet le paramètre régional à getStaticProps et getServerSideProps. Une bibliothèque se charge d’afficher les messages ; gt-next de General Translation génère en plus les traductions à partir du texte intégré dans le JSX.
Category: Internationalisation
Last updated: 2026-10-28
Authors: General Translation Team
Published: 2026-10-28

Le Pages Router intègre le routage internationalisé depuis Next.js 10 : déclarez vos paramètres régionaux et une valeur par défaut dans le bloc `i18n` de `next.config.js`, et Next.js sert chaque langue à sa propre URL, redirige les nouveaux visiteurs selon la langue de leur navigateur et transmet la locale active à vos fonctions de récupération de données. En revanche, il ne charge, n’affiche ni ne traduit aucun texte : Next.js a conçu ce routage pour fonctionner de pair avec une bibliothèque d’i18n. Il vous faut donc toujours choisir une bibliothèque pour les messages et un moyen de produire les traductions ([internationalisation du Pages Router de Next.js](https://nextjs.org/docs/pages/guides/internationalization)).

## Ce que fait le routage i18n intégré

Toute la fonctionnalité tient en un seul bloc de configuration :

```js title="next.config.js"
/** @type {import('next').NextConfig} */
module.exports = {
  i18n: {
    // Tous les paramètres régionaux proposés par le site, y compris celui par défaut
    locales: ['en', 'es', 'fr'],
    // Servi sans préfixe : /about, /es/about, /fr/about
    defaultLocale: 'en',
  },
};
```

Une fois cette configuration en place, Next.js se charge de quatre tâches :

* **URL.** Le routage par sous-chemin conserve les paramètres régionaux par défaut sur `/about` et ajoute un préfixe aux autres (`/fr/about`). Pour servir plutôt les paramètres régionaux depuis des domaines distincts, comme `example.fr`, ajoutez une liste `domains` contenant un `domain` et un `defaultLocale` par entrée.
* **Détection.** Lors d'une visite sur `/`, Next.js lit l'en-tête `Accept-Language` et redirige vers le préfixe ou le domaine correspondant. Un cookie `NEXT_LOCALE`, défini par votre sélecteur de langue, a priorité sur l'en-tête. Définissez `localeDetection: false` pour désactiver la redirection.
* **Paramètre régional dans votre code.** `useRouter()` renvoie `locale`, `locales` et `defaultLocale`. `getStaticProps` et `getServerSideProps` reçoivent `locale` dans leur contexte, et `getStaticPaths` reçoit `locales`.
* **`<html lang>`.** Next.js attribue à cet attribut la valeur de la locale active, sauf si votre `_document` définit la sienne.

Cela suffit pour implémenter l&#39;i18n à la main. Cette page charge un fichier JSON par paramètre régional au moment de la compilation :

```tsx title="pages/index.tsx"
import type { GetStaticProps, InferGetStaticPropsType } from 'next';
import Link from 'next/link';
import { useRouter } from 'next/router';

export const getStaticProps = (async ({ locale }) => {
  // Next.js appelle cette fonction une fois par paramètre régional configuré, au moment du build.
  const messages = (await import(`../messages/${locale}.json`)).default;
  return { props: { messages } };
}) satisfies GetStaticProps;

export default function Home({ messages }: InferGetStaticPropsType<typeof getStaticProps>) {
  const { locales } = useRouter(); // ['en', 'es', 'fr']

  return (
    <main>
      <h1>{messages.title}</h1>
      <nav>
        {locales?.map((code) => (
          // La même page dans chaque langue : /, /es, /fr
          <Link key={code} href="/" locale={code} lang={code}>
            {new Intl.DisplayNames([code], { type: 'language' }).of(code)}
          </Link>
        ))}
      </nav>
    </main>
  );
}
```

Une compilation de production compilée sert `/es` sous la forme `<html lang="es">` avec le titre en espagnol, et une requête vers `/` avec `Accept-Language: fr-CA` reçoit une redirection 307 vers `/fr`. Chaque lien affiche le nom de la langue dans cette langue même (English, español, français), comme il se doit pour un [sélecteur de langue](/kb/language-switcher).

### Ce qui reste à votre charge

Le routage s&#39;arrête à l&#39;URL. Les formes plurielles, le formatage des nombres et des dates et l&#39;interpolation de chaînes de caractères relèvent d&#39;une bibliothèque, tout comme la synchronisation des fichiers de messages au fil de l&#39;évolution des composants. Next.js n&#39;ajoute pas non plus de liens `hreflang` entre les versions linguistiques : c&#39;est à vous de les ajouter avec `next/head`. (Voir [Qu&#39;est-ce que hreflang ?](/kb/what-is-hreflang).) Et rien de tout cela ne produit de traduction.

Trois limites sont à prendre en compte lors de la planification :

* **Pas d&#39;export statique.** Le routage internationalisé ne fonctionne pas avec `output: 'export'`, car il repose sur la couche de routage de Next.js.
* **La durée du build augmente avec chaque paramètre régional.** Chaque page `getStaticProps` non dynamique est générée une fois par paramètre régional : 50 paramètres régionaux et 10 pages représentent donc 500 appels. Les routes dynamiques doivent renvoyer chaque paramètre régional depuis `getStaticPaths`, faute de quoi Next.js ne génère que celui par défaut.
* **Plafonds.** `locales` et `domains` sont chacun limités à 100 entrées.

### Elle n&#39;est pas transposée dans l&#39;App Router

La configuration `i18n` est une fonctionnalité du Pages Router. Dans l&#39;App Router, `useRouter` importé depuis `next/navigation` ne fournit plus `locale`, `locales` ni `defaultLocale`, et Next.js précise que ses fonctionnalités i18n intégrées ne sont pas nécessaires dans le répertoire `app` ([guide de migration](https://nextjs.org/docs/app/guides/migrating/app-router-migration#step-5-migrating-routing-hooks)). Les applications App Router placent plutôt le paramètre régional dans un segment `[locale]`, ou le résolvent dans le middleware. (Voir [Comment ajouter l&#39;i18n à une application Next.js App Router ?](/kb/add-i18n-to-nextjs).)

## Bibliothèques qui affichent les messages

| Bibliothèque                                                               | Configuration initiale avec le Pages Router                                                                                                                             | Rédaction du texte                                                                                                                 | Provenance des traductions                                                                                |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [next-i18next](https://github.com/i18next/next-i18next#pages-router-setup) | `appWithTranslation` encapsule `_app` ; `serverSideTranslations(locale, ['common'])` dans `getStaticProps` ou `getServerSideProps`, importé depuis `next-i18next/pages` | Clés dans des espaces de noms JSON, affichées avec `t('title')`                                                                    | Vous, des traducteurs ou un système de gestion de la traduction (TMS) tel que Locize                      |
| [next-intl](https://next-intl.dev/docs/getting-started/pages-router)       | `NextIntlClientProvider` dans `_app`, avec les `messages` renvoyés par `getStaticProps`                                                                                 | Clés dans un fichier JSON par paramètre régional, affichées avec [`useTranslations`](/docs/react/reference/hooks/use-translations) | Vous ou vos traducteurs                                                                                   |
| [react-intl](https://formatjs.github.io/docs/react-intl)                   | `IntlProvider` dans `_app`, qui reçoit la locale active et ses messages                                                                                                 | Messages ICU intégrés sous forme de `defaultMessage`, extraits avec `formatjs extract`                                             | Vous, des traducteurs ou un TMS                                                                           |
| General Translation (`gt-next`)                                            | `withGTServerSideProps` ou `withGTStaticProps` sur chaque page ; [`GTProvider`](/docs/react/reference/components/gt-provider) dans `_app`                               | JSX encapsulé dans [`<T>`](/docs/react/reference/components/t), chaînes avec [`useGT`](/docs/react/reference/hooks/use-gt)         | Générées par [`npx gt translate`](/docs/cli/reference/commands/translate), relues dans le tableau de bord |

next-i18next 16 prend en charge les deux routeurs et conserve, sous `next-i18next/pages`, son API habituelle pour le Pages Router. La documentation de next-intl recommande l&#39;App Router, mais le Pages Router reste pleinement pris en charge. Avec le Pages Router, chacune de ces bibliothèques s&#39;appuie sur le bloc `i18n` présenté plus haut pour les URL et la détection.

Choisissez next-i18next si vous disposez déjà d&#39;espaces de noms i18next ou si vous souhaitez profiter de son écosystème de plugins. Choisissez next-intl si vous prévoyez de passer à l&#39;App Router et voulez conserver la même API avant et après la migration. Choisissez react-intl si vos messages sont des chaînes ICU avec lesquelles vos traducteurs travaillent déjà. Choisissez General Translation si vous préférez garder le texte intégré dans vos composants et laisser les traductions être générées, relues et mises à jour à mesure que le code évolue. (Consultez [next-intl vs. gt-next](/kb/next-intl-vs-gt-next) pour une comparaison détaillée.)

Si vous restez sur next-i18next ou next-intl, la CLI de General Translation peut tout de même traduire leurs fichiers JSON, y compris les chaînes ICU, sans migration ([traduction de fichiers JSON](/docs/cli/reference/formats/json-files)).

## Ajouter General Translation à une application Pages Router

Cette configuration initiale ajoute l&#39;espagnol et le français à une application Pages Router, chaque langue étant servie sur sa propre URL. Elle a été testée avec une application générée par `create-next-app` 16.4.3 (`--no-app`), Next.js 16.4.3, `gt-next@11.4.16` et `gt@2.26.11`. `gt-next` prend en charge Next.js 13.0.0 et les versions ultérieures, à l&#39;exception des versions 15.2.1 et 15.2.2. Son point d&#39;entrée `gt-next/server` est réservé à l&#39;App Router.

### 1. Installer la bibliothèque et la CLI

```bash
npm install gt-next@11.4.16
npm install --save-dev gt@2.26.11
```

### 2. Définir vos langues

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["en", "es", "fr"],
  "files": {
    "gt": {
      "output": "public/_gt/[locale].json"
    }
  }
}
```

Conservez `en` dans `locales` : cette même liste alimente le bloc `i18n` de Next.js, qui exige la présence des paramètres régionaux par défaut.

### 3. Activer le routage i18n de Next.js

```ts title="next.config.ts"
import type { NextConfig } from 'next';
import { withGTConfig } from 'gt-next/config';
import gtConfig from './gt.config.json';

const nextConfig: NextConfig = {
  i18n: {
    locales: gtConfig.locales,
    defaultLocale: gtConfig.defaultLocale,
  },
};

export default withGTConfig(nextConfig);
```

Next.js se charge du routage et de la détection décrits ci-dessus. Vous n&#39;avez besoin ni du middleware `gt-next`, ni d&#39;un dossier `pages/[locale]`.

`create-next-app` génère `<Html lang="en">` dans `pages/_document.tsx`, ce qui remplace le paramètre régional : dans l&#39;application de test, `/es` renvoyait `lang="en"` avec un contenu en espagnol. Supprimez cette prop pour laisser Next.js la définir :

```tsx title="pages/_document.tsx"
import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}
```

### 4. Charger les traductions depuis des fichiers locaux

```ts title="loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  try {
    const translations = await import(`./public/_gt/${locale}.json`);
    return translations.default;
  } catch {
    // Tant que les fichiers n'existent pas, on affiche le texte source
    return {};
  }
}
```

`withGTConfig` détecte `loadTranslations.ts` à la racine du projet ou dans `src/`. Les traductions sont intégrées à votre compilation : l&#39;application n&#39;effectue donc aucun appel à General Translation à l&#39;exécution. (Voir [stocker les traductions](/docs/react/guides/storing-translations).)

### 5. Transmettre le paramètre régional et les traductions à chaque page

Encapsulez la fonction de données de chaque page. Le wrapper lit `context.locale` depuis Next.js et ajoute `locale` et `translations` aux props de la page :

```tsx title="pages/about.tsx"
import { T, withGTStaticProps } from 'gt-next';

// Next.js génère cette page une fois pour chaque paramètre régional.
export const getStaticProps = withGTStaticProps();

export default function About() {
  return (
    <T>
      <h1>About us</h1>
    </T>
  );
}
```

Utilisez `withGTServerSideProps()` de la même manière sur les pages server-rendered. Les deux fonctions acceptent votre propre fonction de données en argument, par exemple `withGTStaticProps(async (context) => ({ props: { posts } }))`, et transmettent tel quel tout résultat `redirect` ou `notFound`. Encapsulez chaque page qui affiche du contenu traduit.

Transmettez ensuite ces props à [`GTProvider`](/docs/react/reference/components/gt-provider) dans `_app` :

```tsx title="pages/_app.tsx"
import type { AppProps } from 'next/app';
import Router from 'next/router';
import { GTProvider, type WithGTServerSideProps } from 'gt-next';

export default function App({ Component, pageProps }: AppProps<WithGTServerSideProps>) {
  const { locale, translations } = pageProps;

  return (
    <GTProvider
      locale={locale}
      translations={translations}
      // Changer de langue via la navigation Next.js : /es, /fr, puis retour à /
      _reload={({ locale: nextLocale }) => {
        void Router.push(Router.pathname, Router.asPath, { locale: nextLocale });
      }}
    >
      <Component {...pageProps} />
    </GTProvider>
  );
}
```

### 6. Marquer le contenu à traduire

```tsx title="pages/index.tsx"
import { LocaleSelector, T, useGT, withGTServerSideProps } from 'gt-next';

export const getServerSideProps = withGTServerSideProps();

export default function Home() {
  const gt = useGT();

  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Find your next project</h1>
        <p>Explore projects from teams around the world.</p>
      </T>
      <input type="search" placeholder={gt('Search projects')} aria-label={gt('Search projects')} />
    </main>
  );
}
```

[`<T>`](/docs/react/reference/components/t) traduit le titre et le paragraphe ensemble, en s&#39;appuyant sur leur balisage comme contexte. [`useGT`](/docs/react/reference/hooks/use-gt) se charge des chaînes d&#39;attributs. [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) affiche chacun de vos paramètres régionaux dans sa propre langue. Si vous choisissez Español, `NEXT_LOCALE=es` est enregistré ; Next.js le lit lors de la visite suivante sur `/`, et le callback `_reload` redirige la page vers `/es`.

### 7. Générer des traductions et vérifier la compilation

Connectez-vous avec [`npx gt login`](/docs/cli/reference/commands/login), définissez `GT_PROJECT_ID`, puis exécutez [`npx gt translate`](/docs/cli/reference/commands/translate) pour générer `public/_gt/es.json` et `fr.json`. Pour tester la configuration initiale sans compte, [`npx gt generate`](/docs/cli/reference/commands/generate) génère les mêmes fichiers avec le texte source en anglais, que vous pourrez traduire à la main.

Dans l&#39;application de test, une fois le fichier espagnol complété, `next build` a réussi et `next start` a servi :

* `/` avec `<html lang="en">` et le titre en anglais
* `/es` avec `<html lang="es">`, ainsi que le titre et l&#39;espace réservé en espagnol
* `/es/about`, compilée avec `withGTStaticProps`, en espagnol
* `/` avec `Accept-Language: es` sous forme de redirection 307 vers `/es`

## Déployer et maintenir les traductions à jour

Traduisez avant chaque compilation pour que les nouveaux textes soient disponibles dans toutes les langues dès leur mise en production :

```json title="package.json"
{
  "scripts": {
    "build": "gt validate && gt translate && next build"
  }
}
```

Chez votre hébergeur, définissez `GT_PROJECT_ID` ainsi qu&#39;une clé API de projet nommée `GT_API_KEY`, dotée des autorisations **Fichiers &gt; Écriture** et **Translation queue &gt; Enabled**. Conservez la clé server-side et ne lui ajoutez jamais le préfixe `NEXT_PUBLIC_`. Si la compilation régénère `public/_gt/` à chaque fois, ajoutez ce dossier à `.gitignore`. [`gt validate`](/docs/cli/reference/commands/validate) fait échouer la compilation en présence de contenu susceptible de casser la traduction, avant même le moindre appel API, et les exécutions suivantes ne traduisent que le contenu source nouveau ou modifié.

Les relecteurs peuvent modifier n&#39;importe quelle traduction dans l&#39;[Éditeur de Traduction](/docs/platform/dashboard/guides/reviewing-translations) de General Translation, et un [groupe de contexte](/docs/platform/dashboard/guides/defining-context-for-translations) assure la cohérence des termes du glossaire et du ton avec vos autres projets. Pour des versions linguistiques indexables, ajoutez `hreflang`, des URL canoniques et des titres traduits ; le guide [SEO multilingue pour Next.js](/kb/multilingual-nextjs-seo) détaille chacun de ces points.

## Questions fréquentes

### L&#39;option i18n de next.config.js fonctionne-t-elle avec l&#39;App Router ?

Non. Il s&#39;agit d&#39;une fonctionnalité propre au Pages Router : les applications App Router utilisent un segment de route `[locale]` ou un middleware, et `gt-next` documente une configuration initiale distincte pour l&#39;App Router.

### Puis-je utiliser getStaticProps avec gt-next ?

Oui. Encapsulez-la avec `withGTStaticProps` : Next.js génère alors une version de la page par paramètre régional. Pour les routes dynamiques, `getStaticPaths` doit toujours renvoyer un chemin par paramètre régional.

### Ai-je besoin d&#39;un middleware pour l&#39;i18n avec le Pages Router ?

Non. Next.js résout le paramètre régional à partir de l&#39;URL, du cookie `NEXT_LOCALE` et de l&#39;en-tête `Accept-Language` avant même l&#39;exécution de vos fonctions de données.

## Points clés

* Le bloc `i18n` de `next.config.js` apporte au Pages Router des URL par paramètre régional, des redirections basées sur `Accept-Language` depuis `/`, le cookie `NEXT_LOCALE`, ainsi que `locale` dans `useRouter()` et les fonctions de récupération de données.
* Il n&#39;affiche ni ne traduit les messages, n&#39;ajoute pas de balises `hreflang`, ne fonctionne pas avec `output: 'export'` et ne s&#39;applique pas à l&#39;App Router.
* Supprimez le `lang="en"` codé en dur dans `pages/_document.tsx`, sans quoi le HTML de chaque paramètre régional déclarera l&#39;anglais.
* next-i18next, next-intl et react-intl affichent les traductions que vous leur fournissez ; `gt-next` de General Translation les génère en plus, avec `withGTStaticProps` ou `withGTServerSideProps` sur chaque page et [`GTProvider`](/docs/react/reference/components/gt-provider) dans `_app`.
* Ajoutez [`gt validate && gt translate`](/docs/cli/reference/commands/validate) avant `next build` pour que chaque livraison soit disponible dans toutes les langues.

## Related questions

- [Comment ajouter l’i18n à une application Next.js App Router ?](https://generaltranslation.com/fr/kb/add-i18n-to-nextjs.mdx): Commencez par gt init pour configurer General Translation dans un projet App Router pris en charge, puis balisez le contenu source, générez les traductions et vérifiez le changement de langue. gt-next conserve les textes dans le JSX avec leur contexte de traduction ; la CLI, l’éditeur du tableau de bord et Locadex prennent en charge la génération, la relecture et les mises à jour continues. Ce guide présente également la configuration initiale explicite avec des fichiers locaux.
- [Alternatives à next-intl : gt-next ou next-intl](https://generaltranslation.com/fr/kb/next-intl-vs-gt-next.mdx): next-intl affiche les traductions que vous fournissez dans un catalogue de messages pour chaque langue. gt-next affiche lui aussi des traductions, mais General Translation les génère en plus à partir du texte intégré directement dans votre JSX. Les deux sont sous licence MIT et prennent en charge l’App Router et les Composants serveur. Si vos catalogues next-intl fonctionnent déjà, vous pouvez les conserver et confier leur traduction à General Translation, sans migration.
- [Comment configurer le SEO d’une application Next.js multilingue ?](https://generaltranslation.com/fr/kb/multilingual-nextjs-seo.mdx): Attribuez à chaque langue sa propre URL préfixée, comme /en/about et /es/about, puis publiez html lang, une URL canonique autoréférente, des variantes localisées hreflang avec x-default, un titre et une description traduits, ainsi qu’une entrée de plan de site pour chaque langue publiée. Marquez les versions non publiées en noindex. Le package gt-next de General Translation associe chaque langue à sa propre URL et traduit les titres avec getGT.
- [Bonnes pratiques pour le sélecteur de langue : UX, SEO et accessibilité](https://generaltranslation.com/fr/kb/language-switcher.mdx): Affichez chaque langue sous son propre nom, comme Deutsch ou 日本語, et bannissez les drapeaux, qui représentent des pays. Faites pointer chaque option vers la même page dans cette langue grâce à un lien explorable par les robots, mémorisez le choix dans un cookie et ne redirigez jamais automatiquement une URL localisée.
- [Alternatives à i18next : General Translation ou i18next](https://generaltranslation.com/fr/kb/general-translation-vs-i18next.mdx): Choisissez General Translation pour conserver vos textes directement dans vos composants React et générer des traductions en tirant parti de leur structure JSX et du contexte de votre produit. Vous pouvez aussi conserver i18next et utiliser General Translation pour traduire vos catalogues existants. i18next assure le rendu des messages et la sélection des formes plurielles ; la génération des traductions relève d’un service distinct.

## Previous and next questions

- Previous question: [Comment ajouter l’i18n à TanStack Start ?](https://generaltranslation.com/fr/kb/add-i18n-to-tanstack-start.mdx)
- Next question: [Comment créer un plan de site pour un site web multilingue ?](https://generaltranslation.com/fr/kb/multilingual-sitemap.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/fr/kb/sitemap.md) for every article.