# General Translation Knowledge Base: Comment ajouter l’i18n à une application Next.js App Router ?
URL: https://generaltranslation.com/fr/kb/add-i18n-to-nextjs.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 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.
Category: Internationalisation
Last updated: 2026-10-21
Authors: Kevin Liu, Kevin Wu
Published: 2026-10-21

Ce tutoriel ajoute l’anglais, l’espagnol et le français à une petite page de projet. Il couvre un Composant Serveur, un Client Component et un sélecteur de langue. La langue y est sélectionnée via un cookie ; les URL préfixées par le paramètre régional et le SEO multilingue font l’objet d’une étape distincte.

Le package `gt-next` de General Translation est conçu pour Next.js App Router. Il conserve les textes source dans le JSX qui leur donne leur sens et relie ce contenu à la génération des traductions. Utilisez la [prop `context`](/docs/react/reference/components/t#context) pour lever l’ambiguïté de certaines formulations, et définissez des [termes de glossaire et des instructions personnalisées](/docs/platform/dashboard/guides/defining-context-for-translations) pour encadrer la terminologie et le ton. Le workflow de compilation décrit ci-dessous met ensuite à jour les traductions au fil de l’évolution de la source.

## Video

The video is narrated in English, with English captions.

[How do I add i18n to a Next.js app?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/kb-add-i18n-to-nextjs.mp4) (51 s)

General Translation lets you add i18n with `gt-next`: wrap text in `T` and generate translations. Wrap your config in `withGTConfig`, list your languages, add a `loadTranslations` file, put the `GTProvider` in your root layout, add a `<LocaleSelector>` for the menu, and run `npx gt translate` before `next build`.

## Avant de commencer

Utilisez un projet TypeScript existant basé sur l’App Router, avec un répertoire `src/app`. Les exemples ciblent Next.js 16 et utilisent npm. Next.js 16 nécessite Node.js 20.9 ou une version ultérieure. Si vous partez de zéro, suivez d’abord le [guide d’installation de Next.js](https://nextjs.org/docs/app/getting-started/installation). Pour les applications basées sur le Pages Router, consultez plutôt le [Démarrage rapide pour le Pages Router](/docs/react/nextjs-pages-router-quickstart).

L’exemple explicite utilise `gt-next@11.4.12` et `gt@2.26.5`. La bibliothèque, sous licence MIT, peut afficher sans compte les traductions que vous fournissez. Pour obtenir des traductions générées par le service, utilisez un projet GT et [connectez-vous via la CLI ou utilisez une clé d’outillage à portée limitée](/docs/cli/guides/configuring#credentials). Pour les compilations automatisées, utilisez une clé stockée dans le gestionnaire de secrets de votre CI.

## Commencer par la commande de configuration initiale

Lancez l’assistant de configuration dans le répertoire de l’application :

```bash
npx gt@2.26.5 init
```

Choisissez la configuration initiale du framework React pour votre application App Router, les langues source et cibles, ainsi qu&#39;une livraison locale ou via CDN. L&#39;assistant installe `gt-next`, ajoute [`GTProvider`](/docs/react/reference/components/gt-provider) et [`withGTConfig`](/docs/react/nextjs/config), puis crée `gt.config.json`. Avec la livraison locale, il crée également un loader de traductions. La réécriture du framework est expérimentale : vérifiez le diff généré, en particulier au niveau des fournisseurs existants et des wrappers de configuration. [Référence de la configuration initiale](/docs/cli/reference/commands/init).

Il vous reste à marquer le contenu de l&#39;application et à générer ses traductions. Si vous préférez qu&#39;un agent de codage mène la tâche jusqu&#39;à la vérification, utilisez [Configuration initiale pour les agents](https://generaltranslation.com/agent-prompt.md).

La configuration initiale explicite ci-dessous utilise `src/_gt/[locale].json`. Par défaut, l&#39;assistant génère la sortie locale dans `public/_gt/[locale].json` ; conservez ensemble le loader qu&#39;il génère et ce chemin de sortie, ou suivez intégralement la configuration initiale explicite à la place.

## Configurer explicitement la bibliothèque et écrire la page

### 1. Installer le SDK et la CLI

Exécutez les commandes suivantes dans le répertoire de l&#39;application :

```bash
npm install gt-next@11.4.12
npm install --save-dev gt@2.26.5
```

`gt-next` affiche les traductions dans l&#39;application. `gt` est l&#39;outil en ligne de commande qui permet de collecter et de traduire le contenu source. [Démarrage rapide officiel pour Next.js](/docs/react/nextjs-quickstart).

### 2. Configurer Next.js et vos langues

Encapsulez votre configuration Next.js existante avec [`withGTConfig`](/docs/react/nextjs/config). Conservez vos paramètres actuels et combinez-la avec les autres fonctions d&#39;encapsulation de configuration que vous utilisez déjà.

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

export default withGTConfig({});
```

Créez ce fichier à la racine du projet :

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

L&#39;anglais est la langue source. L&#39;espagnol et le français sont les langues cibles. Le chemin de sortie indique au CLI où enregistrer les traductions générées.

### 3. Ajouter un chargeur de traductions locales

Créez `src/loadTranslations.ts`. Le plugin de configuration détecte ce fichier et s&#39;en sert pour charger les fichiers de paramètres régionaux générés :

```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./_gt/${locale}.json`);
  return translations.default;
}
```

Cette configuration intègre les traductions au bundle de l&#39;application : en production, aucun appel à General Translation n&#39;est donc nécessaire à l&#39;exécution pour ce contenu. Les mises à jour des traductions sont livrées avec chaque compilation. [Stockage local des traductions](/docs/react/guides/storing-translations).

Les fichiers n&#39;existent pas encore. Terminez la page et générez-les à l&#39;étape 6 avant de lancer le serveur de développement ; sinon, l&#39;import du loader risque d&#39;échouer.

### 4. Ajoutez le fournisseur à votre mise en page racine

Adaptez `src/app/layout.tsx` comme indiqué ci-dessous. Conservez vos styles, polices, métadonnées et autres fournisseurs existants.

```tsx title="src/app/layout.tsx"
import type { PropsWithChildren } from 'react';
import { GTProvider } from 'gt-next';
import { getLocale } from 'gt-next/server';

export default async function RootLayout({ children }: PropsWithChildren) {
  const locale = await getLocale();

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

[`getLocale`](/docs/react/nextjs/reference/functions/get-locale) résout la langue actuelle côté serveur. [`GTProvider`](/docs/react/reference/components/gt-provider) fournit le contexte de traduction à l&#39;application, y compris à ses composants interactifs.

### 5. Traduire le JSX et les attributs des champs de saisie

Ajoutez la page ci-dessous. Elle reste un Composant Serveur. [`T`](/docs/react/reference/components/t) marque le titre et le paragraphe statiques comme étant à traduire ; [`LocaleSelector`](/docs/react/reference/components/locale-selector) fournit la liste déroulante de sélection de la langue.

```tsx title="src/app/page.tsx"
import { LocaleSelector, T } from 'gt-next';
import SearchBox from './SearchBox';

export default function Home() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Find your next project</h1>
        <p>Explore projects from teams around the world.</p>
      </T>
      <SearchBox />
    </main>
  );
}
```

Créez le champ de recherche en tant que Client Component. Utilisez [`useGT`](/docs/react/reference/hooks/use-gt) pour les attributs dont la valeur est une chaîne de caractères, comme les espaces réservés (placeholders) et les libellés d&#39;accessibilité :

```tsx title="src/app/SearchBox.tsx"
'use client';

import { useGT } from 'gt-next';

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

  return (
    <input
      type='search'
      placeholder={gt('Search projects')}
      aria-label={gt('Search projects')}
    />
  );
}
```

[`useGT()`](/docs/react/reference/hooks/use-gt) renvoie directement la fonction de traduction. Dans un Composant Serveur asynchrone, utilisez plutôt [`getGT`](/docs/react/nextjs/reference/functions/get-gt), importé depuis `gt-next/server`.

N’insérez pas de valeurs dynamiques sous forme d’expressions brutes dans [`T`](/docs/react/reference/components/t). Pour ajouter des noms, des nombres ou des branches, utilisez les [composants de variable et de formatage](/docs/react/guides/formatting-variables) appropriés.

## Générer des traductions et vérifier le résultat

### 6. Générer le contenu traduit

Pour la traduction automatique, connectez-vous avec [`gt login`](/docs/cli/reference/commands/login) et configurez l’identifiant de projet, ou ajoutez une clé API de projet et l’identifiant de projet dans `.env.local` :

```bash title=".env.local"
GT_PROJECT_ID="your-project-id"
GT_API_KEY="your-project-api-key"
```

Gardez la clé confidentielle et excluez le fichier du contrôle de version. N&#39;exposez pas `GT_API_KEY` via une variable `NEXT_PUBLIC_`. La clé utilisée par l&#39;outillage nécessite les autorisations de lecture/écriture de fichiers et d&#39;accès à la file de traduction, ainsi que l&#39;accès au contexte si celui-ci est utilisé. Suivez la [documentation sur les clés API](/docs/platform/dashboard/reference/api-keys).

Générez les traductions :

```bash
npx gt translate
```

La commande envoie le travail de traduction à General Translation et écrit les fichiers de paramètres régionaux dans le chemin de sortie configuré. Relisez le texte généré dans l&#39;[Éditeur de Traduction du tableau de bord](/docs/platform/dashboard/guides/reviewing-translations). Si vous modifiez localement les traductions téléchargées, [`gt save-local`](/docs/cli/reference/commands/save-local) synchronise ces corrections avec la plateforme. La génération par le service est soumise à une [tarification à l&#39;usage](https://generaltranslation.com/pricing).

Pour essayer la bibliothèque sans appeler le service de traduction, exécutez plutôt la commande suivante :

```bash
npx gt generate
```

[`gt generate`](/docs/cli/reference/commands/generate) crée des modèles contenant le texte source ; **il ne traduit pas ce texte**. Modifiez les valeurs textuelles dans `src/_gt/es.json` et `src/_gt/fr.json` en conservant les clés générées et la structure JSX. Par exemple, traduisez le titre espagnol par « Encuentra tu próximo proyecto » et le libellé de recherche par « Buscar proyectos ». Traduisez le reste du texte avant de considérer ces fichiers comme terminés.

Après toute modification du contenu source, relancez [`gt generate`](/docs/cli/reference/commands/generate) et vérifiez les fichiers cibles. La commande conserve les valeurs cibles existantes, ajoute les nouvelles entrées avec leur texte source et supprime celles qui ne figurent plus dans la source.

### 7. Démarrer l&#39;application et changer de langue

```bash
npm run dev
```

Ouvrez l&#39;adresse affichée par Next.js. Sélectionnez l&#39;espagnol, puis le français dans la liste déroulante. Vérifiez que le titre, le paragraphe, l&#39;espace réservé et le libellé accessible du champ de saisie sont bien traduits. Rechargez la page pour vérifier que la langue sélectionnée est conservée, puis revenez à l&#39;anglais.

Si le sélecteur change mais que le texte reste en anglais, examinez les fichiers de la langue cible. Les modèles source générés par [`gt generate`](/docs/cli/reference/commands/generate) restent en anglais tant que vous ne les avez pas traduits. Si la compilation de la page échoue parce qu&#39;un fichier de paramètre régional est manquant, relancez la commande de génération appropriée avant de redémarrer le serveur de développement.

## Compilation pour la production

Exécutez [`gt validate`](/docs/cli/reference/commands/validate) pour détecter les erreurs de syntaxe de traduction avant d’envoyer une requête de traduction hébergée. Les [règles ESLint](/docs/react/guides/linting-your-code) de GT ajoutent des vérifications supplémentaires pendant le développement. Une fois la [traduction en développement configurée](/docs/react/guides/configuring#delivery), vous pouvez également prévisualiser le contenu traduit au fil de vos modifications.

Pour le workflow de traduction automatique, intégrez cette commande de compilation aux scripts existants de votre `package.json` :

```json
{
  "scripts": {
    "build": "gt validate && gt translate && next build"
  }
}
```

Définissez `GT_PROJECT_ID` et `GT_API_KEY` dans l&#39;environnement de compilation. Assurez-vous que la CLI, installée comme dépendance de développement, est disponible lors de cette compilation. Ajoutez `src/_gt/` à `.gitignore` si votre compilation régénère ses traductions à chaque fois.

Si vous avez opté pour la traduction manuelle, conservez vos fichiers traduits sous contrôle de version ou récupérez-les depuis votre propre pipeline de traduction. Exécutez `next build` une fois ces fichiers disponibles. Ne perdez pas l&#39;unique copie de traductions maintenues manuellement en les ignorant comme s&#39;il s&#39;agissait de fichiers régénérables.

Après la compilation, lancez l&#39;application en production et refaites le test de changement de langue. Vous vérifiez ainsi les fichiers qui seront réellement livrés, au lieu de vous fier uniquement au comportement en développement.

Le [workflow de traduction incrémentale](/docs/cli/guides/generating-translations#retranslate) traduit le contenu source modifié et réutilise les traductions correspondantes des versions précédentes. Pour automatiser également les modifications du dépôt, configurez [Locadex](/docs/platform/locadex/guides/configuring-automations) afin d&#39;internationaliser les nouveaux éléments d&#39;IU, de générer des traductions ou de synchroniser les changements de paramètres régionaux via des pull requests. Choisissez les paramètres de déclenchement et de relecture adaptés à votre processus de livraison.

Pour publier des mises à jour sans recompiler l&#39;application, choisissez la [livraison par CDN](/docs/react/nextjs/config) plutôt que le loader local. Les modifications de traduction publiées peuvent alors atteindre l&#39;application déployée, selon ses paramètres de version et de cache.

Pour les pages publiques nécessitant des URL distinctes par langue, poursuivez avec le [routage selon les paramètres régionaux de l&#39;App Router](/docs/react/nextjs/app-router-middleware). L&#39;exemple présenté ici, basé sur un cookie, ne crée pas de pages `/es` et `/fr` et ne configure ni URL canoniques ni métadonnées `hreflang`.

## Un prompt pour votre agent de codage

Commencez par le [prompt officiel de configuration initiale](https://generaltranslation.com/agent-prompt.md), tenu à jour, puis ajoutez ce descriptif de la fonctionnalité :

```text
Utilise l'anglais comme langue source, avec l'espagnol et le français comme langues cibles.
Localise la page du projet à l'aide de traductions incluses localement dans le bundle. Conserve les
fournisseurs et les routes existants. Inclus son titre, son paragraphe, son champ de recherche,
son libellé accessible et un sélecteur de langue. Utilise la terminologie commune du projet.
Vérifie le changement de langue, la persistance après rechargement, le contenu server-rendered,
les attributs côté client et la compilation de production. Indique ce qui a réellement été testé
et ce qui nécessite encore une relecture linguistique. Ne déploie pas et ne fusionne pas.
```

Pour une vue d&#39;ensemble du workflow, consultez [l&#39;i18n sans fichiers de traduction](/kb/i18n-without-translation-files) et [l&#39;utilisation d&#39;un agent de codage](/kb/ai-agent-i18n-setup).

## Related questions

- [Peut-on faire de l’i18n sans fichiers de traduction ?](https://generaltranslation.com/fr/kb/i18n-without-translation-files.mdx): Oui. Les bibliothèques gt-react et gt-next de General Translation permettent d’internationaliser React et Next.js sans clés de traduction ni fichier JSON par langue à maintenir. Le texte reste intégré au JSX, dans le composant `<T>`, et la commande gt translate génère les traductions de chaque langue lors de la compilation, en s’appuyant sur le contexte de votre code. Locadex peut les tenir à jour via des pull requests.
- [Comment internationaliser une application avec Cursor ou Claude Code ?](https://generaltranslation.com/fr/kb/ai-agent-i18n-setup.mdx): Commencez par le prompt Setup for Agents de General Translation dans Cursor ou Claude Code, choisissez une fonctionnalité et des langues cibles, puis laissez l’agent implémenter et vérifier le résultat. La connexion via le navigateur, la documentation lisible par machine et les outils MCP font le lien entre la configuration initiale, la traduction et la relecture. Utilisez Locadex pour automatiser la localisation continue au moyen de pull requests.
- [Comment maintenir les traductions à jour à chaque déploiement ?](https://generaltranslation.com/fr/kb/translations-in-ci.mdx): Exécutez la traduction comme une étape du pipeline avant chaque compilation de production, afin que les nouveaux textes soient livrés traduits avec le déploiement qui les ajoute. Le CLI gt de General Translation s’en charge avec npx gt translate, à l’aide d’une clé API de projet et d’un identifiant de projet stockés comme secrets CI.

## Previous and next questions

- Previous question: [Quelle est la meilleure bibliothèque d’i18n pour une application React ?](https://generaltranslation.com/fr/kb/best-react-i18n-library.mdx)
- Next question: [Comment formater les nombres, les dates et les devises pour chaque paramètre régional ?](https://generaltranslation.com/fr/kb/format-numbers-dates-currencies.mdx)

## Sitemap

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