Überblick

Static Site Generation (SSG) rendert Seiten zum Build‑Zeitpunkt vor und erzeugt statische HTML files, die direkt ohne serverseitige Verarbeitung ausgeliefert werden können. In Kombination mit Internationalisierung generiert SSG vorgerenderte Versionen für jede locale.

Setup

Voraussetzungen für die Einrichtung

Um SSG mit GT zu aktivieren, benötigst du:

1. App Router mit Middleware-Routing – siehe Middleware-Anleitung
2. Benutzerdefinierte getLocale-Funktion – für die Locale-Erkennung während des statischen Renderings
3. getRegion deaktivieren – Regionserkennung ist während des statischen Renderings nicht unterstützt
4. generateStaticParams-Funktion – zum Generieren statischer Parameter für jede Locale

Schritt 1: Middleware konfigurieren

Richte die Middleware für dynamische Anfragen ein (siehe Middleware-Leitfaden):

// proxy.ts (Next.js 16+) oder middleware.ts (Next.js 15 und älter)
import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware();

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

Schritt 2: Erkennung von locale und Region definieren

Erstellen Sie je eine Funktion getLocale und getRegion zur Erkennung von locale und Region während des statischen Renderings:

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;
}

Schritt 3: getRegion deaktivieren

Da die Regionserkennung beim statischen Rendering nicht unterstützt wird, musst du die Funktion getRegion so überschreiben, dass sie eine feste Region zurückgibt.

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

Schritt 4: generateStaticParams konfigurieren

Stellen Sie sicher, dass generateStaticParams für Ihre locales konfiguriert ist.

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

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

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

Zusätzliche Konfiguration

Wenn Sie getLocale.ts und getRegion.ts nicht in Ihrem Root-Verzeichnis haben möchten, können Sie in der Datei next.config.js ein eigenes Verzeichnis angeben.

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

Häufige Probleme

Next.js-Versionskompatibilität

Bei Versionen vor Next.js 15.1 ist es nicht möglich, während der statischen Generierung auf URL-Pfadparameter zuzugreifen. Sie müssen auf Next.js 15.1 oder höher aktualisieren, um SSG mit gt-next zu verwenden.

Seiten werden nicht statisch generiert

Wenn deine Seiten nicht statisch generiert werden, stelle sicher, dass:

• Deine getLocale- und getRegion-Funktionen richtig eingerichtet sind

Layout/Page außerhalb des [locale]-Verzeichnisses

Wenn du eine layout.tsx- oder page.tsx-Datei außerhalb des [locale]-Verzeichnisses hast, wird dadurch die statische Generierung verhindert. Du wirst wahrscheinlich den folgenden Error sehen:

Die Export-Locale wurde im Modul [next]/root-params.js [app-rsc] (ecmascript) nicht gefunden.
Alle Exporte des Moduls sind statisch bekannt (es hat keine dynamischen Exporte). Daher ist statisch bekannt, dass der angeforderte Export nicht existiert.

Alle layout.tsx files müssen im [locale]-Verzeichnis liegen. Weitere Informationen finden Sie in diesem zugehörigen Next.js-Issue.

Weiterführende Lektüre

• Siehe den Middleware-Leitfaden, der für das Locale-Routing erforderlich ist
• Siehe die Release Notes zur Migration vom Legacy-SSG-Muster