# gt-next: General Translation Next.js SDK: Génération de site statique
URL: https://generaltranslation.com/fr/docs/next/guides/ssg.mdx
---
title: Génération de site statique
description: Préaffichez les pages internationalisées au build pour des performances optimales
---

## Vue d’ensemble

La génération de site statique (SSG) prégénère les pages au build en créant des fichiers HTML statiques qui peuvent être servis directement, sans traitement côté serveur.
Combinée à l’internationalisation, la SSG génère des versions prérendues pour chaque paramètre régional.

La configuration diffère selon le routeur :

* **Pages Router** - Utilisez le routage par paramètre régional intégré de Next.js et `withGTStaticProps`
* **App Router** - Utilisez `createNextMiddleware`, une route `[locale]` et `generateStaticParams`

<Callout type="info">
  **Soyez attentif aux problèmes suivants lors de la configuration de la SSG :**

  * [Compatibilité des versions de Next.js](#nextjs-version-compatibility)
  * [Les pages ne sont pas générées statiquement](#pages-not-generating-statically)
  * [Erreur d’exécution en production : &quot;DYNAMIC&#95;SERVER&#95;USAGE&quot;](#production-runtime-error-dynamic_server_usage)
  * [&quot;Le paramètre régional exporté n’existe pas dans le module cible&quot;](#export-locale-doesnt-exist-in-target-module)
  * [Les routes d’image de métadonnées (images OG) échouent avec `getLocale()`](#metadata-image-routes-og-images-fail-with-getlocale)
</Callout>

***

## Configuration du Pages Router

Le Pages Router peut générer une version statique distincte de chaque page pour chaque paramètre régional. Utilisez le routage par paramètre régional intégré de Next.js plutôt que `createNextMiddleware`, afin que Next.js transmette le paramètre régional généré à `getStaticProps`.

### Étape 1 : Configurer le routage par paramètre régional

Ajoutez chaque paramètre régional pris en charge, y compris le paramètre régional par défaut, à la configuration `i18n` de votre config Next.js :

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

const nextConfig: NextConfig = {
  i18n: {
    locales: ['en', 'es', 'fr', 'ja'],
    defaultLocale: 'en',
  },
};

export default withGTConfig(nextConfig);
```

Next.js appelle désormais `getStaticProps` une fois pour chaque paramètre régional configuré. Par exemple, une page située dans `pages/about.tsx` génère `/about` pour l’anglais, `/es/about` pour l’espagnol et `/fr/about` pour le français.

<Callout type="warn">
  **Gardez les paramètres régionaux synchronisés :** les paramètres régionaux et le paramètre régional par défaut dans la configuration `i18n` de Next.js doivent correspondre à ceux définis dans votre `gt.config.json`.
</Callout>

### Étape 2 : Encapsuler getStaticProps

Encapsulez la fonction `getStaticProps` de la page avec `withGTStaticProps` :

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

type AboutPageProps = {
  generatedAt: string;
};

export const getStaticProps: GetStaticProps<AboutPageProps> =
  withGTStaticProps(async () => ({
    props: {
      generatedAt: new Date().toISOString(),
    },
  }));

export default function AboutPage({ generatedAt }: AboutPageProps) {
  return (
    <main>
      <T>
        <h1>About us</h1>
      </T>
      <p>Generated at: {generatedAt}</p>
    </main>
  );
}
```

Si la page n’a pas besoin de props spécifiques, utilisez la forme sans argument :

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

export const getStaticProps = withGTStaticProps();
```

`withGTStaticProps` ajoute le `locale` généré ainsi que son instantané de traduction aux props de la page. Le paramètre régional par défaut reçoit un instantané vide, car son contenu source est déjà présent. Les redirections, `notFound` et les options de régénération statique incrémentielle sont transmises telles quelles.

### Étape 3 : Configurer la navigation de GTProvider

Transmettez à `GTProvider`, dans `_app.tsx`, le paramètre régional généré ainsi que les traductions. Reliez les changements de paramètre régional au Pages Router pour que la sélection d’un paramètre régional charge les props statiques de ce paramètre régional :

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

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

  return (
    <GTProvider
      locale={locale}
      translations={translations}
      _reload={({ locale: nextLocale }) => {
        void router.push(
          { pathname: router.pathname, query: router.query },
          router.asPath,
          { locale: nextLocale }
        );
      }}
    >
      <Component {...restPageProps} />
    </GTProvider>
  );
}
```

Ce callback effectue une navigation via le Pages Router plutôt qu’un rechargement complet du navigateur. Next.js charge les props de page pré-générées associées au paramètre régional sélectionné, et `GTProvider` reçoit l’instantané de traduction correspondant.

Vous pouvez maintenant utiliser `LocaleSelector` normalement :

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

export default function AboutPage() {
  return <LocaleSelector />;
}
```

<Callout type="info">
  **Routes dynamiques :** Les pages telles que `pages/products/[id].tsx` nécessitent toujours `getStaticPaths` pour leurs paramètres dynamiques. Next.js génère chaque chemin retourné une fois pour chaque paramètre régional configuré.
</Callout>

## Configuration de l’App Router

### Prérequis de configuration

Pour activer le SSG avec GT, il vous faut :

1. **App Router avec routage via middleware** - voir le [guide du middleware](/docs/next/guides/middleware)
2. **Fonction `getLocale` personnalisée** - pour détecter le paramètre régional pendant le rendu statique
3. **Désactiver `getRegion`** - la détection de région n’est pas prise en charge pendant le rendu statique
4. **Fonction `generateStaticParams`** - pour générer des paramètres statiques pour chaque paramètre régional
5. **Fichiers de layout dans le répertoire `/[locale]`** - tous les fichiers de layout (généralement `layout.tsx` et `page.tsx`) doivent se trouver sous le répertoire `/[locale]`

### Étape 1 : Configurer le middleware

Configurez le middleware pour les requêtes dynamiques (voir le [guide sur le middleware](/docs/next/guides/middleware)) :

```ts
// proxy.ts (Next.js 16+) ou middleware.ts (Next.js 15 et inférieur)
import { createNextMiddleware } from 'gt-next/middleware';

export default createNextMiddleware();

export const config = {
  matcher: ['/((?!api|static|.*\\..*|_next).*)'],
};
```


### Étape 2 : Définir la détection du paramètre régional et de la région

Créez les fonctions `getLocale` et `getRegion` pour détecter le paramètre régional et la région lors du rendu statique :

#### Next.js 15.5+

```ts
// getLocale.ts
import { locale } from 'next/root-params';

export default async function getLocale() {
  return await locale();
}
```


#### Next.js 15.1-15.4

```ts
// getLocale.ts
import { unstable_rootParams } from 'next/server';

export default async function getLocale() {
  return (await unstable_rootParams())?.locale;
}
```


### Étape 3 : Désactiver getRegion

Comme la détection de région n&#39;est pas prise en charge lors du rendu statique, vous devez redéfinir la fonction `getRegion` pour qu&#39;elle renvoie une région fixe.

```ts
// getRegion.ts
export default async function getRegion() {
  return undefined;
}
```


### Étape 4 : Configurer generateStaticParams

Assurez-vous que [`generateStaticParams`](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) est bien configuré pour vos paramètres régionaux.

```tsx title="page.tsx"
import { getLocales } from 'gt-next/server';

export async function generateStaticParams() {
  return getLocales().map((locale) => ({ locale }));
}

export default async function Page() {
  ...
}
```

### Étape 5 : Déplacez tous les fichiers `layout` dans le répertoire `/[locale]`

Tous les fichiers doivent avoir accès au paramètre régional de l&#39;utilisateur via le segment `/[locale]` dans l&#39;URL.
Ils doivent donc se trouver sous le répertoire `/[locale]`.

Assurez-vous de déplacer votre fichier `layout` racine vers `/[locale]/layout.tsx`.

***

## Configuration supplémentaire

Si vous ne souhaitez pas placer `getLocale.ts` et `getRegion.ts` à la racine de votre projet, vous pouvez spécifier un répertoire personnalisé dans votre fichier `next.config.js`.

```js
// next.config.js
export default withGTConfig(nextConfig, {
  getLocalePath: './src/i18n/getLocale.ts',
  getRegionPath: './src/i18n/getRegion.ts',
});
```


## Problèmes courants d’App Router [#common-issues]

### Compatibilité des versions de Next.js

Pour les versions antérieures à Next.js 15.1, il n’est pas possible d’accéder aux paramètres du chemin de l’URL lors de la génération statique. Vous devrez passer à Next.js 15.1 ou une version ultérieure pour utiliser SSG avec gt-next.

### Pages non générées statiquement

Si vos pages ne sont pas générées statiquement, assurez-vous que :

* vos fonctions `getLocale` et `getRegion` sont correctement configurées

### Erreur d’exécution en production : &quot;DYNAMIC_SERVER_USAGE&quot;

```text
⨯ [Error: An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details. A digest property is included on this error instance which may provide additional details about the nature of the error.] {
  digest: 'DYNAMIC_SERVER_USAGE'
}
```

Cette erreur se produit lorsque les fichiers `getLocale` ou `getRegion` n&#39;existent pas ou ne sont pas correctement configurés.
Vérifiez bien que [l’étape 2](#step-2-define-locale-and-region-detection) et [l’étape 3](#step-3-disable-getregion) sont bien terminées.

### &quot;Le paramètre régional exporté n’existe pas dans le module cible&quot;

```text
./getLocale.ts:2:1
Export locale doesn't exist in target module
  1 | // getLocale.ts
> 2 | import { locale } from 'next/root-params';
    | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  3 | export default async function getLocale() {
  4 |   return await locale();
  5 | }
```

Cette erreur se produit généralement lorsqu’un fichier `layout.tsx`, `page.tsx`, etc. ne se trouve pas dans le répertoire `/[locale]`.
Pour corriger ce problème, assurez-vous que tous vos fichiers de segments de route (généralement `layout.tsx` et `page.tsx`) se trouvent sous le répertoire `/[locale]`.

<Callout type="info">
  En SSG, le seul moyen de résoudre le paramètre régional d’un utilisateur est de passer par le chemin de l’URL.
  Donc, si on essaie d’exécuter un fichier `layout.tsx` en dehors du répertoire `/[locale]`, une erreur se produira, car il n’a pas accès à ce paramètre racine.
  Ce qui est peu intuitif, c’est que lorsqu’une page est rendue, tous les fichiers `layout.tsx` qui l’encapsulent le sont aussi.
  Vous pouvez donc avoir ajouté la SSG à un fichier `page.tsx` bien situé dans le répertoire `/[locale]`, alors qu’en réalité, l’erreur vient d’un fichier `layout.tsx` situé ailleurs.
</Callout>

<Accordions>
  <Accordion title="Exemple de structure de fichiers problématique">
    <Files>
      <Folder name="app" defaultOpen={true}>
        <File name="layout.tsx    <--- Appel problématique à getLocale()" />

        <Folder name="[locale]">
          <File name="layout.tsx" />

          <File name="page.tsx    <--- Page SSG" />
        </Folder>
      </Folder>

      <File name="getLocale.ts" />

      <File name="getRegion.ts" />

      <File name="next.config.js" />

      <File name="package.json" />

      <File name="proxy.ts" />
    </Files>
  </Accordion>

  <Accordion title="Mais que faire si je veux avoir un layout en dehors du répertoire `/[locale]` ?">
    Nous déconseillons fortement cette pratique.
    Tous les fichiers de segments de route (à l’exception de `not-found.tsx`) doivent se trouver dans le répertoire `/[locale]` lorsque vous utilisez la SSG.

    Mais si vous y êtes contraint, vous aurez besoin de deux fichiers de layout racine distincts : un dans le répertoire `/[locale]` et un autre en dehors.
    Ainsi, la SSG n’exécutera que le layout situé dans le répertoire `/[locale]`.
    De plus, vous devrez peut-être modifier le middleware pour router vers les segments qui existent en dehors du répertoire `/[locale]`, en contournant le middleware de localisation.
  </Accordion>
</Accordions>

### Les routes d’images de métadonnées (images OG) échouent avec `getLocale()`

```text
Error: Route /[locale]/.../opengraph-image used
import('next/root-params').locale() inside a Route Handler.
```

Les routes d’images de métadonnées Next.js (`opengraph-image.tsx`, `twitter-image.tsx`) sont en réalité des gestionnaires de route en interne, et `next/root-params` n’est pas pris en charge dans les gestionnaires de route.
Cela signifie que `getLocale()`, `getMessages()` et `getGT()` échoueront dans ces contextes.

**Correctif :** utilisez `registerLocale()` pour définir explicitement le paramètre régional au début du gestionnaire :

```tsx title="app/[locale]/opengraph-image.tsx"
import { ImageResponse } from 'next/og';
import { registerLocale, getMessages, msg } from 'gt-next/server';

const HEADING = msg('Welcome to our site');

export default async function OGImage({
  params,
}: {
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;
  registerLocale(locale);

  const m = await getMessages();

  return new ImageResponse(
    (
      <div style={{ display: 'flex', fontSize: '48px' }}>
        {m(HEADING)}
      </div>
    ),
    { width: 1200, height: 630 }
  );
}
```

Cela s’applique également à `twitter-image.tsx` et à toutes les autres routes d’images de métadonnées.

***

## Pour aller plus loin

<Callout>
  **Voyez-le en action :** Consultez l’[application d’exemple Static Site Generation](https://github.com/gt-examples/static-site-generation) pour une démonstration fonctionnelle — [aperçu en direct](https://static-site-generation.generaltranslation.dev).
</Callout>

* Configurez le [routage par paramètre régional de Pages Router](/docs/next/guides/middleware#pages-router-locale-routing)
* Consultez le [Guide du middleware](/docs/next/guides/middleware), nécessaire au routage par paramètre régional d’App Router
* Consultez les [notes de version](/devlog/gt-next_v6_10_0) pour migrer depuis l’ancien modèle SSG
* Consultez un exemple d’application dans le monorepo [ici](https://github.com/generaltranslation/gt/tree/main/examples/next-ssg)