# 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.

<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

### 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 [#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;

```
⨯ [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;

```
./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()`

```
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>

* Consultez le [Guide du middleware](/docs/next/guides/middleware), nécessaire au routage par paramètre régional
* 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)