Descripción general

Static Site Generation (SSG) prerenderiza páginas en el momento del build, creando archivos HTML estáticos que pueden entregarse directamente sin procesamiento server-side. Cuando se combina con internacionalización, SSG genera versiones prerenderizadas para cada locale.

Configuración

Requisitos de configuración

Para habilitar SSG con GT, debes tener:

1. App Router con enrutamiento mediante middleware - consulta la guía de middleware
2. Función personalizada getLocale - para detectar el locale durante el renderizado estático
3. Deshabilitar getRegion - la detección de región no se admite durante el renderizado estático
4. Función generateStaticParams - para generar parámetros estáticos para cada locale

Paso 1: Configurar el middleware

Configura el middleware para las solicitudes dinámicas (consulta la guía de middleware):

// proxy.ts (Next.js 16+) o middleware.ts (Next.js 15 y versiones anteriores)
import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware();

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

Paso 2: Definir la detección de locale y región

Crea las funciones getLocale y getRegion para la detección de locale y región durante el renderizado estático:

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

Paso 3: Deshabilitar getRegion

Dado que la detección de región no está disponible durante el renderizado estático, debes sobrescribir la función getRegion para que devuelva una región fija.

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

Paso 4: Configurar generateStaticParams

Asegúrate de que generateStaticParams esté configurada para tus locales.

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

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

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

Configuración adicional

Si no deseas getLocale.ts y getRegion.ts en tu directorio raíz, puedes especificar un directorio personalizado en tu archivo next.config.js.

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

Problemas frecuentes

Compatibilidad de versiones de Next.js

En versiones anteriores a Next.js 15.1, no hay forma de acceder a los parámetros de la ruta de la URL durante la generación estática. Deberás actualizar a Next.js 15.1 o posterior para usar SSG con gt-next.

Páginas que no se generan estáticamente

Si tus páginas no se generan estáticamente, asegúrate de que:

• Tus funciones getLocale y getRegion estén configuradas correctamente

Layout/Page fuera del directorio [locale]

Si tienes un archivo layout.tsx o page.tsx fuera del directorio [locale], impedirá la generación estática. Es probable que veas el siguiente error:

El export locale no se encontró en el módulo [next]/root-params.js [app-rsc] (ecmascript).
Todas las exportaciones del módulo son conocidas estáticamente (no tiene exportaciones dinámicas). Por lo tanto, se sabe estáticamente que la exportación solicitada no existe.

Todos los files layout.tsx deben ubicarse dentro del directorio [locale]. Para obtener más información, consulta este issue relacionado de Next.js.

Lecturas adicionales

• Consulta la guía de middleware necesaria para el enrutamiento por locale
• Consulta las notas de la versión para migrar desde el patrón SSG heredado