# General Translation React SDKs (gt-react, gt-next): Quickstart du Pages Router de Next.js
URL: https://generaltranslation.com/fr/docs/react/nextjs-pages-router-quickstart.mdx
---
title: Quickstart du Pages Router de Next.js
description: Ajoutez plusieurs langues à une application Next.js Pages Router avec General Translation en moins de 10 minutes.
related:
  links:
    - /docs/react/guides/translating-jsx
    - /docs/react/guides/translating-strings
    - /docs/react/guides/managing-locales
    - /docs/react/guides/formatting-variables

---

# Quickstart du Pages Router de Next.js

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

Dans le Pages Router, `gt-next` fonctionne via `getServerSideProps` : à chaque requête, le serveur détermine le paramètre régional de l’utilisateur, charge un instantané des traductions et transmet les deux à un `<GTProvider>` dans `_app.tsx`, afin que le premier rendu soit déjà traduit.

Le point d’entrée `gt-next/server` est réservé à l’App Router et ne fonctionne pas avec le Pages Router.

**Prérequis :**

* Une application Next.js utilisant le **Pages Router**
* Node.js 18+

<Callout type="info">
  **Remarque :** Si vous utilisez l’App Router, suivez plutôt le [Quickstart Next.js App Router](/docs/react/nextjs-quickstart). Il utilise les Server Components et ne nécessite aucune configuration `getServerSideProps`.
</Callout>

## Quickstart [#quickstart]

### 1. Installez les paquets

`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 config Next.js

`gt-next` utilise un plugin Next.js appelé **`withGTConfig`** pour configurer l’internationalisation au moment du build. Encapsulez votre configuration Next.js existante avec celui-ci :

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

const nextConfig = {};

export default withGTConfig(nextConfig);
```

Ce plugin lit vos paramètres de traduction et s’occupe de tout connecter en arrière-plan. Pour les URL avec un préfixe de paramètre régional, consultez le [guide du middleware Pages Router](/docs/react/nextjs/pages-router-middleware).

### 3. Créez un fichier de configuration des traductions

Créez un fichier **`gt.config.json`** à la racine de votre projet. Ce fichier indique à la bibliothèque quelles langues vous prenez 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 votre application. Choisissez-les dans la [liste des paramètres régionaux pris en charge](/docs/platform/dashboard/reference/supported-locales).
* **`files.gt.output`** — l’emplacement où la 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. Ajouter une fonction de chargement pour les traductions locales

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

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

`withGTConfig` détecte automatiquement un fichier `loadTranslations.[js|ts]` à la racine de votre projet ou dans le répertoire `src/` — 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 en savoir plus sur les détails et les compromis associés.
</Callout>

### 5. Encapsulez getServerSideProps dans vos pages

Encapsulez le `getServerSideProps` de chaque page avec **`withGTServerSideProps`**. À chaque requête, il détermine le paramètre régional de l&#39;utilisateur — à partir du cookie `generaltranslation.locale` s&#39;il est défini, sinon à partir de l’en-tête `Accept-Language` — charge un instantané de traductions pour ce paramètre régional et injecte les deux dans les props de votre page :

```tsx title="pages/index.tsx"
import type { GetServerSideProps } from 'next';
import { withGTServerSideProps } from 'gt-next';

export const getServerSideProps: GetServerSideProps = withGTServerSideProps(
  async (context) => {
    return {
      props: {
        // vos propres props
      },
    };
  }
);
```

Si une page n’a pas besoin de ses propres props côté serveur, appelez-la sans argument :

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

export const getServerSideProps = withGTServerSideProps();
```

`withGTServerSideProps` ajoute `locale` et `translations` à vos props (ainsi qu’un indicateur interne `enableI18n`). Si votre fonction interne renvoie `redirect` ou `notFound`, le résultat est transmis tel quel, sans charger les traductions.

### 6. Ajoutez GTProvider à votre application

Le composant **`GTProvider`** donne à toute votre application accès aux traductions. Dans `_app.tsx`, récupérez les props injectées depuis `pageProps` et transmettez-les au provider. Le type **`WithGTServerSideProps`** décrit cette structure injectée :

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

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

  return (
    <GTProvider locale={locale} translations={translations}>
      <Component {...restPageProps} />
    </GTProvider>
  );
}
```

Comme le paramètre régional et les traductions arrivent avec la réponse du serveur, le contenu s’affiche dès le premier rendu dans la langue de l’utilisateur — aucun état de chargement côté client.

### 7. Marquer le contenu à traduire

Maintenant, entourez le texte que vous voulez traduire avec le composant **`<T>`**. `<T>` signifie &quot;translate&quot; :

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

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

Vous pouvez inclure autant ou aussi peu de JSX que vous le souhaitez dans `<T>`. Tout ce qu’il contient — le texte, les éléments imbriqués, même la mise en forme — est traduit comme une seule unité.

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

Ajoutez un **`<LocaleSelector>`** pour que les utilisateurs puissent changer de langue :

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

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

`LocaleSelector` affiche un menu déroulant contenant les langues de votre `gt.config.json`. Lorsque l&#39;utilisateur choisit une langue, `gt-next` enregistre ce choix dans le cookie `generaltranslation.locale` et recharge la page, afin que le serveur réaffiche l&#39;ensemble dans le nouveau paramètre régional.

### 9. Configurer les variables d’environnement (facultatif)

Pour voir les traductions pendant le développement, vous avez besoin de clés API de General Translation. Elles activent 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"
```

Obtenez gratuitement vos clés sur [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) 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 réservées au CI/CD.

  N’exposez jamais `GT_API_KEY` dans le navigateur et ne l’ajoutez jamais au contrôle de version.
</Callout>

### 10. Vérifiez que tout fonctionne

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>

### 11. Traduire des chaînes (pas seulement du JSX)

Pour les chaînes simples — comme les attributs `placeholder`, les valeurs `aria-label` ou le texte `alt` — utilisez le hook **`useGT`** :

```tsx title="pages/contact.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>
  );
}
```

### 12. Déployer en production

En production, les traductions sont pré-générées au build (aucun appel d’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** dans votre fournisseur 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-`). Récupérez-en une sur [dash.generaltranslation.com](https://dash.generaltranslation.com). Ne la préfixez jamais avec `NEXT_PUBLIC_`.
</Callout>

C&#39;est tout — votre application est désormais multilingue. 🎉

## Dépannage [#troubleshooting]

<Accordions>
  <Accordion title="Ai-je besoin de withGTServerSideProps sur chaque page ?">
    Oui — `<GTProvider>` nécessite les props `locale` et `translations`, et elles n&#39;existent que sur les pages dont `getServerSideProps` est encapsulé. Pour les pages qui ne récupèrent pas leurs propres données, exportez la version sans argument :

    ```tsx
    export const getServerSideProps = withGTServerSideProps();
    ```
  </Accordion>

  <Accordion title="Puis-je utiliser getStaticProps à la place ?">
    Oui. Encapsulez la page avec `withGTStaticProps` et continuez à passer les props générées à `GTProvider` dans `_app.tsx`. Consultez le [guide de génération de site statique du Pages Router](/docs/react/nextjs/pages-router-static-site-generation) pour la configuration complète.
  </Accordion>

  <Accordion title="La langue ne change pas quand j'utilise le menu déroulant">
    `gt-next` stocke la préférence de langue de l&#39;utilisateur dans un cookie nommé `generaltranslation.locale`. Si vous avez déjà fait des tests avec une autre langue, ce cookie peut remplacer votre sélection. Supprimez vos cookies et réessayez.

    * [Chrome](https://support.google.com/chrome/answer/95647)
    * [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored)
    * [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0)
  </Accordion>

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

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