Vue d’ensemble

La génération statique de site (SSG) pré‑rend les pages au moment du build, créant des fichiers HTML statiques pouvant être servis directement, sans traitement côté serveur. Combinée à l’internationalisation, la SSG génère des versions pré‑rendues pour chaque locale.

Configuration

Conditions requises pour la configuration

Pour activer SSG avec GT, vous avez besoin des éléments suivants :

1. App Router avec routage via middleware - voir le guide sur le middleware
2. Fonction getLocale personnalisée - pour détecter le locale lors du rendu statique
3. Désactiver getRegion - la détection de région n’est pas prise en charge lors du rendu statique
4. Fonction generateStaticParams - pour générer des paramètres statiques pour chaque locale

Étape 1 : Configurer le middleware

Configurez le middleware pour les requêtes dynamiques (voir le guide du middleware) :

// proxy.ts (Next.js 16+) ou middleware.ts (Next.js 15 et versions antérieures)
import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware();

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

Étape 2 : définir la détection de locale et de région

Créez les fonctions getLocale et getRegion pour détecter la locale et la région lors du rendu statique :

Next.js 15.5+

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

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

Next.js 15.1-15.4

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

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

Étape 3 : désactiver getRegion

Étant donné que la détection de région n’est pas prise en charge lors du rendu statique, vous devez redéfinir la fonction getRegion afin qu’elle renvoie une région fixe.

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

Étape 4 : Configurer generateStaticParams

Assurez-vous que generateStaticParams est bien configuré pour vos locales.

import { getLocales } from 'gt-next/server';

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

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

Configuration supplémentaire

Si vous ne souhaitez pas que getLocale.ts et getRegion.ts se trouvent dans votre répertoire racine, vous pouvez spécifier un répertoire personnalisé dans votre fichier next.config.js.

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

Problèmes fréquents

Compatibilité des versions de Next.js

Pour les versions antérieures à Next.js 15.1, il n’existe aucun moyen d’accéder aux paramètres de chemin d’URL lors de la génération statique. Vous devrez mettre à niveau vers Next.js 15.1 ou une version ultérieure pour utiliser le 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

Layout/Page en dehors du répertoire [locale]

Si vous avez un fichier layout.tsx ou page.tsx en dehors du répertoire [locale], cela empêchera la génération statique. Vous verrez probablement le message Error suivant :

La locale d'exportation n'a pas été trouvée dans le module [next]/root-params.js [app-rsc] (ecmascript).
Toutes les exportations du module sont connues de manière statique (il n'a pas d'exportations dynamiques). Il est donc connu de manière statique que l'exportation demandée n'existe pas.

Tous les files layout.tsx doivent se trouver dans le répertoire [locale]. Pour plus d’informations, consultez ce problème Next.js associé.

Pour aller plus loin

• Consultez le guide sur le middleware requis pour le routage par locale
• Consultez les notes de version pour migrer de l’ancien modèle SSG