Descripción general

El renderizado estático es una capacidad fundamental del framework Next.js, que ofrece páginas prerenderizadas en tiempo de compilación para lograr un rendimiento y un SEO óptimos. Dado esto, cualquier biblioteca nativa de Next.js debería funcionar sin problemas dentro de este modelo de renderizado. gt-next 6.9.0 incorpora compatibilidad con el renderizado estático, lo que permite que las aplicaciones internacionalizadas aprovechen al máximo las capacidades de generación estática de Next.js sin comprometer la detección de locales ni la funcionalidad de traducción.

¿Qué es el renderizado estático?

El renderizado estático genera HTML en tiempo de compilación en lugar de en cada solicitud. Si bien este enfoque ofrece un rendimiento excepcional, plantea desafíos para las bibliotecas de i18n que normalmente dependen de los encabezados de la solicitud, las cookies o el middleware para determinar la configuración regional del usuario. Durante el renderizado estático, estas dependencias disponibles solo en tiempo de solicitud no están presentes, por lo que se requieren enfoques alternativos para la detección de la configuración regional.

Configuración de renderizado estático

Antes de configurar gt-next, asegúrate de que tu aplicación de Next.js esté preparada para la generación estática siguiendo la documentación de generateStaticParams.

La configuración consta de tres componentes clave:

1. Habilita el renderizado estático en la configuración

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

2. Configurar el middleware

Configura el middleware para las solicitudes dinámicas:

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

export default createNextMiddleware();

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

3. Definir la detección de locale estática

Crea una función getStaticLocale que determine el locale durante el renderizado estático. Esta función solo se ejecuta durante la generación estática; durante el SSR se utiliza el comportamiento predeterminado (lectura de headers, cookies, etc.).

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

Se puede llamar a getStaticRegion para personalizar la detección de la región durante el renderizado estático.

Beneficios

Compatibilidad nativa con Next.js: Aprovecha el sistema integrado de root params de Next.js para ser compatible con el renderizado estático.

Funcionalidades adicionales

Más allá de la generación estática, esta versión también incorpora compatibilidad con funciones personalizadas getLocale() y getRegion() que se pueden configurar tanto para SSR como para entornos de renderizado estático.