# General Translation React SDKs (gt-react, gt-next, gt-react-native): Quickstart App Router de Next.js
URL: https://generaltranslation.com/fr/docs/react/nextjs-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Ajoutez plusieurs langues à une application Next.js avec App Router grâce à General Translation en moins de 10 minutes.

À la fin de ce guide, votre application Next.js affichera du contenu en plusieurs langues, avec un sélecteur de langue que vos utilisateurs pourront utiliser.

**Prérequis :**

* Une application Next.js utilisant l’**App Router** (Next.js 13.0.0 ou version ultérieure, à l’exclusion des versions 15.2.1 et 15.2.2)
* Node.js 20+ (Next.js 16 nécessite la version 20.9+)

<Callout type="info">
  **Astuce :** Exécutez `npx gt@latest` pour tout configurer avec l’[assistant de configuration](/docs/cli/quickstart). Ce guide couvre la configuration manuelle.
</Callout>

<Callout type="info">
  **Remarque :** Si vous utilisez le Pages Router, suivez plutôt le [Quickstart Pages Router de Next.js](/docs/react/nextjs-pages-router-quickstart).
</Callout>

## Quickstart [#quickstart]

### 1. Installez les packages

`gt-next` est la bibliothèque qui gère les traductions dans votre application. `gt` est l’outil CLI qui prépare les traductions pour la production.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-next
    npm i -D gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-next
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-next
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-next
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

### 2. Configurez votre fichier de configuration Next.js

`gt-next` utilise un plugin Next.js appelé **`withGTConfig`** pour configurer l’internationalisation au build. Encapsulez votre configuration Next.js existante avec celui-ci. Dans cet extrait et les suivants, les lignes vertes sont ajoutées et les lignes rouges supprimées ; conservez toutes les options déjà présentes dans votre configuration :

```ts title="next.config.ts"
import { withGTConfig } from 'gt-next/config'; // [!code ++]

const nextConfig = {};

export default nextConfig; // [!code --]
export default withGTConfig(nextConfig); // [!code ++]
```

Ce plugin lit vos paramètres de traduction et s’occupe de tout en arrière-plan. Aucune autre modification de votre configuration Next.js n’est nécessaire.

### 3. Créez un fichier de configuration de traduction

Créez un fichier **`gt.config.json`** à la racine de votre projet. Ce fichier indique à la bibliothèque quelles langues votre application prend en charge :

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

* **`defaultLocale`** — la langue dans laquelle votre application est écrite (votre langue source).
* **`locales`** — les langues dans lesquelles vous souhaitez traduire. Choisissez celles que vous voulez dans la [liste des paramètres régionaux pris en charge](/docs/platform/dashboard/reference/supported-locales).
* **`files.gt.output`** — l’emplacement où le CLI enregistre les fichiers de traduction. `[locale]` est remplacé par chaque code de langue (par ex. `public/_gt/es.json`).

Ajoutez `public/_gt/` à votre **`.gitignore`** — ces fichiers sont générés, pas écrits à la main :

```txt title=".gitignore"
public/_gt/
```

### 4. Ajoutez une fonction de chargement pour les traductions locales

Créez un fichier **[`loadTranslations`](/docs/react/reference/functions/load-translations)** dans votre répertoire `src/` (ou à la racine du projet). Cela indique à `gt-next` comment charger les fichiers de traduction générés par le CLI :

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

<Callout type="info">
  **Remarque :** Ces fichiers de traduction n’existent pas tant que vous ne les avez pas créés avec [`npx gt generate`](/docs/cli/reference/commands/generate) (aucune clé API requise), [`npx gt translate`](/docs/cli/reference/commands/translate) (avec des informations d’authentification) ou manuellement. D’ici là, le bundler signale l’absence du répertoire `public/_gt`, et le bloc `try`/`catch` ci-dessus renvoie `{}` afin que l’application continue de fonctionner avec du contenu non traduit.
</Callout>

`withGTConfig` détecte automatiquement un fichier `loadTranslations.[js|ts]` dans votre répertoire `src/` ou à la racine du projet — aucune configuration supplémentaire n’est requise.

<Callout type="info">
  **Remarque :** Les traductions locales sont intégrées à votre application. Elles se chargent donc instantanément, sans dépendre de services externes. Consultez [Stocker les traductions](/docs/react/guides/storing-translations) pour plus de détails et les compromis associés.
</Callout>

### 5. Ajoutez le GTProvider à votre mise en page

Le composant **[`GTProvider`](/docs/react/reference/components/gt-provider)** donne accès aux traductions à l’ensemble de votre application. Il doit encapsuler votre application au niveau de la mise en page racine. Conservez le reste de votre mise en page existante (polices, métadonnées, styles) tel quel :

```tsx title="app/layout.tsx"
import { GTProvider, useLocale } from 'gt-next'; // [!code ++]

export default function RootLayout({ children }: { children: React.ReactNode }) {
  const locale = useLocale(); // [!code ++]
  return (
    {/* [!code --] */}
    <html lang="en">
    {/* [!code ++] */}
    <html lang={locale}>
      <body>
        {/* [!code --] */}
        {children}
        {/* [!code ++:3] */}
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}
```

<Callout type="warn">
  **Avertissement :** Dans les versions de Next.js qui activent [Cache Components](/docs/react/nextjs/cache-components) par défaut, ou lorsque vous définissez `cacheComponents: true`, Next.js lève une exception pour cette mise en page en l’état. Par défaut, `gt-next` détecte le paramètre régional à partir des en-têtes et des cookies de la requête : il s’agit de données d’exécution, qui bloquent le prérendu. Vous devez donc soit encapsuler le contenu qui lit le paramètre régional dans une limite `<Suspense>`, soit exporter `instant = false` depuis la mise en page pour autoriser une route bloquante :

  ```tsx title="app/layout.tsx"
  export const instant = false;
  ```
</Callout>

### 6. Marquer le contenu à traduire

À présent, encapsulez le texte que vous souhaitez traduire avec le composant **[`<T>`](/docs/react/reference/components/t)**. [`<T>`](/docs/react/reference/components/t) signifie &quot;traduire&quot; :

```tsx title="app/page.tsx"
import { T } from 'gt-next'; // [!code ++]

export default function Home() {
  return (
    <main>
      {/* [!code ++] */}
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      {/* [!code ++] */}
      </T>
    </main>
  );
}
```

Vous pouvez encapsuler autant ou aussi peu de JSX que vous le souhaitez dans [`<T>`](/docs/react/reference/components/t). Tout ce qui s’y trouve — texte, éléments imbriqués, même la mise en forme — est traduit comme une seule unité.

### 7. Ajouter un sélecteur de langue

Ajoutez un **[`<LocaleSelector>`](/docs/react/reference/components/locale-selector)** pour permettre aux utilisateurs de changer de langue :

```tsx title="app/page.tsx"
import { T } from 'gt-next'; // [!code --]
import { T, LocaleSelector } from 'gt-next'; // [!code ++]

export default function Home() {
  return (
    <main>
      {/* [!code ++] */}
      <LocaleSelector />
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

[`LocaleSelector`](/docs/react/reference/components/locale-selector) affiche un menu déroulant contenant les langues définies dans votre `gt.config.json`.

### 8. Configurez les variables d’environnement (facultatif)

Pour prévisualiser les traductions au fur et à mesure du développement, utilisez une [clé API de projet](/docs/platform/dashboard/reference/api-keys#create-project-keys) disposant de l’autorisation de traduction à l’exécution. Une clé avec accès complet fonctionne, mais nous recommandons des permissions **Custom** avec uniquement **traduction à l’exécution** activé afin de limiter les risques.

Créez un fichier **`.env.local`** :

```bash title=".env.local"
NEXT_PUBLIC_GT_DEV_API_KEY="gtx-api-your-runtime-key"
NEXT_PUBLIC_GT_PROJECT_ID="your-project-id"
```

Le préfixe `NEXT_PUBLIC_` expose ces valeurs au code du navigateur afin que les composants client puissent traduire pendant le développement local. Utilisez `NEXT_PUBLIC_GT_DEV_API_KEY` pour le hot reload en développement et conservez `GT_API_KEY` sans préfixe pour le CLI. Les deux paramètres acceptent des clés de projet commençant par `gtx-api-`.

<Callout type="warn">
  **Avertissement :** N’incluez jamais de clé API dans les bundles client déployés ni dans votre dépôt. Supprimez `NEXT_PUBLIC_GT_DEV_API_KEY` et tout `GT_DEV_API_KEY` sans préfixe de votre environnement de build de production ; `gt-next` rejette l’un comme l’autre en production.
</Callout>

<Accordions>
  <Accordion title="Puis-je utiliser gt-next sans clés API ?">
    Oui. Sans clés API, `gt-next` fonctionne comme une bibliothèque i18n classique. Vous n’aurez pas de traduction à la demande pendant le développement, mais vous pouvez quand même :

    * Fournir manuellement vos propres fichiers de traduction
    * Utiliser tous les composants ([`<T>`](/docs/react/reference/components/t), [`<Var>`](/docs/react/reference/components/var), [`LocaleSelector`](/docs/react/reference/components/locale-selector), etc.)
    * Exécuter [`npx gt generate`](/docs/cli/reference/commands/generate) pour créer des modèles de fichiers de traduction, puis les traduire vous-même
  </Accordion>
</Accordions>

### 9. Vérifiez le résultat

Démarrez votre serveur de développement :

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm run dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dev
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun dev
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dev
    ```
  </Tab>
</Tabs>

Ouvrez [http://localhost:3000](http://localhost:3000) et utilisez le menu déroulant des langues pour changer de langue. Vous devriez voir votre contenu traduit.

<Callout type="info">
  **Remarque :** En développement, les traductions se font à la demande ; il est donc possible qu’un bref état de chargement apparaisse la première fois que vous passez à une nouvelle langue. En production, les traductions sont pré-générées et se chargent instantanément.
</Callout>

### 10. Traduire les chaînes

Pour les chaînes simples — comme les attributs `placeholder`, les valeurs `aria-label` ou le texte `alt` — utilisez le hook **[`useGT`](/docs/react/reference/hooks/use-gt)**. Il fonctionne dans les composants serveur synchrones et les composants client :

```tsx title="app/contact/page.tsx"
import { useGT } from 'gt-next';

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

  return (
    <form>
      <input
        placeholder={gt('Enter your email')}
        aria-label={gt('Email input field')}
      />
      <button type="submit">{gt('Send')}</button>
    </form>
  );
}
```

<Accordions>
  <Accordion title="Vous utilisez un composant asynchrone ?">
    Les composants asynchrones ne peuvent pas utiliser de hooks. Importez plutôt [`getGT`](/docs/react/nextjs/reference/functions/get-gt) depuis `gt-next/server` :

    ```tsx
    import { getGT } from 'gt-next/server';

    export default async function Page() {
      const gt = await getGT();
      return <p>{gt('Hello')}</p>;
    }
    ```
  </Accordion>
</Accordions>

### 11. Déployer en production

En production, les traductions [`<T>`](/docs/react/reference/components/t) et [`useGT`](/docs/react/reference/hooks/use-gt) sont pré-générées au moment du build. Ajoutez la commande translate à votre script de build :

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

Définissez vos variables d’environnement de **production** sur votre plateforme d’hébergement (Vercel, Netlify, etc.) :

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

<Callout type="warn">
  **Avertissement :** La commande [`gt translate`](/docs/cli/reference/commands/translate) exécutée lors du build nécessite **Files &gt; Write**, **Translation queue &gt; Enabled** et **Context &gt; Write** ; ajoutez **Traduction à l’exécution** si votre serveur utilise [`tx`](/docs/react/nextjs/reference/functions/tx) ou [`<Tx>`](/docs/react/nextjs/reference/components/tx). Conservez `GT_API_KEY` côté server et ne la faites jamais précéder de `NEXT_PUBLIC_`. (Voir [informations d’authentification de production](/docs/react/nextjs/config#credentials)).
</Callout>

Et voilà : votre application est désormais multilingue. 🎉

## Dépannage [#troubleshooting]

<Accordions>
  <Accordion title="La langue ne change pas quand j’utilise le menu déroulant">
    Vérifiez que les cookies du navigateur sont activés et que le sélecteur s’affiche sous [`<GTProvider>`](/docs/react/reference/components/gt-provider). Si le routage par paramètre régional est activé, vérifiez également que le matcher du middleware et [`pathRegex`](/docs/react/nextjs/config#path-regex) incluent la route actuelle.
  </Accordion>

  <Accordion title="Next.js a rencontré des données d’exécution pendant le prérendu">
    Next.js lève cette erreur lorsque les [Cache Components](/docs/react/nextjs/cache-components) sont activés, soit avec `cacheComponents: true`, soit par défaut dans les versions récentes de Next.js. `gt-next` lit les en-têtes et les cookies de la requête pour détecter le paramètre régional, et Next.js n’autorise pas ces données d’exécution en dehors d’une limite `<Suspense>`. Encapsulez le contenu qui lit le paramètre régional dans `<Suspense>`, ou ajoutez `export const instant = false` à la mise en page ou à la page pour autoriser une route bloquante.
  </Accordion>

  <Accordion title="Les traductions sont lentes en développement">
    C’est normal. En développement, les traductions se font à la demande (votre contenu est traduit en temps réel via l’API). Ce délai **n’existe pas en production** — toutes les traductions sont pré-générées par [`npx gt translate`](/docs/cli/reference/commands/translate).
  </Accordion>

  <Accordion title="Certaines traductions sont inexactes">
    Un texte ambigu peut entraîner des traductions inexactes. Par exemple, « apple » peut désigner le fruit ou l’entreprise. Ajoutez une prop `context` pour aider :

    ```jsx
    <T context="the technology company">Apple</T>
    ```

    [`<T>`](/docs/react/reference/components/t) accepte `context` comme prop. Lorsque vous appelez [`useGT()`](/docs/react/reference/hooks/use-gt) ou [`getGT()`](/docs/react/nextjs/reference/functions/get-gt), transmettez la même chaîne de caractères de désambiguïsation via l’option `$context`.
  </Accordion>
</Accordions>

## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.
