Vue d’ensemble

Le rendu statique est une fonctionnalité clé du framework Next.js, permettant de générer des pages pré-rendues au moment du build pour des performances et un référencement (SEO) optimaux. Dans ce contexte, toute bibliothèque native à Next.js devrait s’intégrer de façon transparente à ce modèle de rendu. gt-next 6.9.0 introduit la prise en charge du rendu statique, permettant aux applications internationalisées de tirer parti de l’ensemble des capacités de génération statique de Next.js sans compromettre la détection de la locale ni les fonctionnalités de traduction.

Qu'est-ce que le rendu statique ?

Le rendu statique génère le HTML au moment du build plutôt qu'à chaque requête. Bien que cette approche offre des performances exceptionnelles, elle pose des défis pour les bibliothèques i18n qui s'appuient généralement sur les en-têtes de requête, les cookies ou le middleware pour déterminer la langue de l'utilisateur. Pendant le rendu statique, ces dépendances liées au temps de requête ne sont pas disponibles, ce qui impose des approches alternatives pour la détection de la langue.

Configuration du rendu statique

Avant de configurer gt-next, assurez-vous que votre application Next.js est prête pour la génération statique en suivant la documentation de generateStaticParams.

Cette configuration repose sur trois composants clés :

1. Activez le rendu statique dans la configuration

export default withGTConfig(nextConfig, {
  experimentalEnableSSG: true,
})

2. Configurer le middleware

Configurez le middleware pour les requêtes dynamiques :

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

export default createNextMiddleware();

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

3. Définir la détection statique de la langue

Créez une fonction getStaticLocale qui détermine la langue lors du rendu statique. Cette fonction s’exécute uniquement pendant la génération statique ; lors du SSR, le comportement par défaut (lecture des en-têtes, cookies, etc.) est utilisé.

Next.js 15.5+

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

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

Next.js 15.1-15.4

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

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

getStaticRegion peut être appelée pour personnaliser la détection de la région lors du rendu statique.

Avantages

Natif Next.js : Exploite le système intégré de paramètres racine (root params) de Next.js pour garantir la compatibilité avec le rendu statique.

Fonctionnalités supplémentaires

Au-delà de la génération statique, cette version introduit également la prise en charge de fonctions personnalisées getLocale() et getRegion() pouvant être configurées aussi bien pour le SSR que pour le rendu statique.