# 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 18+

<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) {
  const translations = await import(`../public/_gt/${locale}.json`);
  return translations.default;
}
```

<Callout type="warn">
  **Avertissement :** Ces fichiers de traduction n’existent pas tant que vous ne les avez pas créés. Ainsi, la première exécution de `npm run dev` échoue à la compilation et la page renvoie une erreur HTTP 500. Exécutez [`npx gt generate`](/docs/cli/reference/commands/generate) (aucune clé API requise) ou [`npx gt translate`](/docs/cli/reference/commands/translate) (avec des identifiants), ou ajoutez des fichiers vides contenant `{}` dans `public/_gt/[locale].json`.
</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 layout

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 du layout racine. Conservez le reste de votre layout existant (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>
  );
}
```

### 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 voir les traductions en développement, vous avez besoin de clés API de General Translation. Elles permettent la **traduction à la demande** : votre application traduit le contenu en temps réel au fur et à mesure du développement.

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

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

Récupérez vos clés gratuites sur [dash.generaltranslation.com](https://dash.generaltranslation.com/en-US/signin) ou en exécutant :

```bash
npx gt auth
```

<Callout type="warn">
  **Avertissement :** Pour le développement, utilisez une clé commençant par `gtx-dev-`. Les clés de production (`gtx-api-`) sont uniquement destinées à la CI/CD.

  N’exposez jamais `GT_API_KEY` dans le navigateur et ne le committez jamais dans votre dépôt.
</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 sont pré-générées au moment du build (sans appels à l’API en temps réel). 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 :** Les clés de production commencent par `gtx-api-` (et non `gtx-dev-`). Obtenez-en une sur [dash.generaltranslation.com](https://dash.generaltranslation.com). Ne la faites jamais précéder de `NEXT_PUBLIC_`.
</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="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), [`useGT()`](/docs/react/reference/hooks/use-gt) et [`getGT()`](/docs/react/nextjs/reference/functions/get-gt) prennent tous en charge `$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.