# gt-next: General Translation Next.js SDK: Generación estática de sitios URL: https://generaltranslation.com/es/docs/next/guides/ssg.mdx --- title: Generación estática de sitios description: Renderiza previamente páginas internacionalizadas en tiempo de construcción para un rendimiento óptimo --- ## Descripción general La generación estática de sitios (SSG) renderiza previamente páginas en tiempo de construcción, creando archivos HTML estáticos que pueden servirse directamente sin procesamiento del lado del servidor. Cuando se combina con la internacionalización, SSG genera versiones renderizadas previamente para cada configuración regional. **Ten en cuenta estos posibles problemas al configurar SSG:** * [Compatibilidad de versiones de Next.js](#nextjs-version-compatibility) * [Las páginas no se generan estáticamente](#pages-not-generating-statically) * [Error de runtime en producción: "DYNAMIC_SERVER_USAGE"](#production-runtime-error-dynamic_server_usage) * ["La exportación 'locale' no existe en el módulo de destino"](#export-locale-doesnt-exist-in-target-module) * [Las rutas de imágenes de metadatos (imágenes OG) fallan con `getLocale()`](#metadata-image-routes-og-images-fail-with-getlocale) *** ## Configuración ### Requisitos de configuración Para habilitar SSG con GT, necesitas: 1. **App Router con enrutamiento mediante middleware** - consulta la [guía de middleware](/docs/next/guides/middleware) 2. **Función `getLocale` personalizada** - para detectar la configuración regional durante el renderizado estático 3. **Deshabilitar `getRegion`** - la detección de región no es compatible con el renderizado estático 4. **Función `generateStaticParams`** - para generar parámetros estáticos para cada configuración regional 5. **Archivos de layout dentro del directorio `/[locale]`** - todos los archivos de layout (normalmente `layout.tsx` y `page.tsx`) deben estar dentro del directorio `/[locale]` ### Paso 1: Configura el middleware Configura el middleware para las solicitudes dinámicas (consulta la [guía de middleware](/docs/next/guides/middleware)): ```ts // 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: Define la detección de la configuración regional y la región Crea las funciones `getLocale` y `getRegion` para detectar la configuración regional y la región durante el renderizado estático: #### Next.js 15.5+ ```ts // getLocale.ts import { locale } from 'next/root-params'; export default async function getLocale() { return await locale(); } ``` #### Next.js 15.1-15.4 ```ts // getLocale.ts import { unstable_rootParams } from 'next/server'; export default async function getLocale() { return (await unstable_rootParams())?.locale; } ``` ### Paso 3: Deshabilita getRegion Como la detección de región no está disponible con el renderizado estático, debes sobrescribir la función `getRegion` para que devuelva una región fija. ```ts // getRegion.ts export default async function getRegion() { return undefined; } ``` ### Paso 4: Configura generateStaticParams Asegúrate de haber configurado [`generateStaticParams`](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) para cada una de tus configuraciones regionales. ```tsx title="page.tsx" import { getLocales } from 'gt-next/server'; export async function generateStaticParams() { return getLocales().map((locale) => ({ locale })); } export default async function Page() { ... } ``` ### Paso 5: Mueve cualquier archivo de layout dentro del directorio `/[locale]` Todos los archivos deben poder acceder a la configuración regional del usuario a través del segmento `/[locale]` de la URL. Por lo tanto, deben estar dentro del directorio `/[locale]`. Asegúrate de mover tu archivo de layout raíz a `/[locale]/layout.tsx`. *** ## Configuración adicional Si no quieres tener `getLocale.ts` y `getRegion.ts` en el directorio raíz, puedes especificar un directorio personalizado en tu archivo `next.config.js`. ```js // next.config.js export default withGTConfig(nextConfig, { getLocalePath: './src/i18n/getLocale.ts', getRegionPath: './src/i18n/getRegion.ts', }); ``` ## Problemas comunes [#common-issues] ### 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. Tendrás que actualizar a Next.js 15.1 o una versión posterior para usar SSG con gt-next. ### Páginas que no se generan de forma estática Si tus páginas no se generan de forma estática, asegúrate de que: * Las funciones `getLocale` y `getRegion` estén configuradas correctamente ### Error de runtime en producción: "DYNAMIC_SERVER_USAGE" ``` ⨯ [Error: An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details. A digest property is included on this error instance which may provide additional details about the nature of the error.] { digest: 'DYNAMIC_SERVER_USAGE' } ``` Este error se produce cuando los archivos `getLocale` o `getRegion` no existen o no están configurados correctamente. Comprueba de nuevo que el [paso 2](#step-2-define-locale-and-region-detection) y el [paso 3](#step-3-disable-getregion) estén completos. ### "La exportación 'locale' no existe en el módulo de destino" ``` ./getLocale.ts:2:1 Export locale doesn't exist in target module 1 | // getLocale.ts > 2 | import { locale } from 'next/root-params'; | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3 | export default async function getLocale() { 4 | return await locale(); 5 | } ``` Este error suele producirse cuando tienes un archivo `layout.tsx`, `page.tsx`, etc. que no está dentro del directorio `/[locale]`. Para solucionar este problema, asegúrate de que todos los archivos de tus segmentos de ruta (normalmente `layout.tsx` y `page.tsx`) estén dentro del directorio `/[locale]`. Durante SSG, la única forma de determinar la configuración regional de un usuario es a través de la ruta de la URL. Por tanto, si intentamos ejecutar un archivo `layout.tsx` fuera del directorio `/[locale]`, se producirá un error porque no tiene acceso a este parámetro raíz. La parte poco intuitiva es que, cuando se renderiza una página, también se renderiza cada archivo `layout.tsx` que la envuelve. Así que podrías haber añadido SSG a un archivo `page.tsx` que sí está dentro del directorio `/[locale]`, pero en realidad el error lo esté provocando un archivo `layout.tsx` ubicado en otro sitio. Desaconsejamos encarecidamente esta práctica. Todos los archivos de segmentos de ruta (excepto `not-found.tsx`) deben estar dentro del directorio `/[locale]` cuando uses SSG. Pero, si es imprescindible, necesitarás dos archivos root layout independientes: uno dentro del directorio `/[locale]` y otro fuera. De este modo, SSG solo ejecutará el layout dentro del directorio `/[locale]`. Además, puede que tengas que modificar el middleware para enrutar a los segmentos que existan fuera del directorio `/[locale]`, omitiendo el middleware de localización. ### Error en las rutas de imágenes de metadatos (imágenes OG) con `getLocale()` ``` Error: Route /[locale]/.../opengraph-image used import('next/root-params').locale() inside a Route Handler. ``` Las rutas de imagen de metadatos de Next.js (`opengraph-image.tsx`, `twitter-image.tsx`) son internamente Route Handlers, y `next/root-params` no se admite en los Route Handlers. Esto significa que `getLocale()`, `getMessages()` y `getGT()` fallarán en estos contextos. **Solución:** Usa `registerLocale()` para establecer explícitamente la configuración regional al principio del manejador: ```tsx title="app/[locale]/opengraph-image.tsx" import { ImageResponse } from 'next/og'; import { registerLocale, getMessages, msg } from 'gt-next/server'; const HEADING = msg('Welcome to our site'); export default async function OGImage({ params, }: { params: Promise<{ locale: string }>; }) { const { locale } = await params; registerLocale(locale); const m = await getMessages(); return new ImageResponse( (
{m(HEADING)}
), { width: 1200, height: 630 } ); } ``` Esto también se aplica a `twitter-image.tsx` y a cualquier otra ruta de imágenes de metadatos. *** ## Más información **Míralo en acción:** Consulta la [app de ejemplo de generación estática de sitio](https://github.com/gt-examples/static-site-generation) para ver una demo funcional — [vista previa en vivo](https://static-site-generation.generaltranslation.dev). * Consulta la [guía de middleware](/docs/next/guides/middleware), necesaria para el enrutamiento por configuración regional * Consulta las [notas de lanzamiento](/devlog/gt-next_v6_10_0) para migrar desde el patrón heredado de SSG * Consulta una app de ejemplo en el monorepo [aquí](https://github.com/generaltranslation/gt/tree/main/examples/next-ssg)