Localización de Next.js para App Router y Pages Router

El enrutamiento por subrutas ofrece una URL visible para cada idioma, como /en/pricing y /fr/pricing. Funciona en un único dominio, es fácil de probar y convierte el cambio de idioma en una transformación de la ruta. El enrutamiento por dominios, como example.fr, puede admitir una marca o unos requisitos legales específicos de cada mercado, pero añade trabajo de DNS, despliegue, analítica y canonicalización. Elige dominios por motivos de producto, no porque la localización los requiera.

En App Router, coloca todas las páginas localizadas bajo app/[locale]. Un Proxy puede inspeccionar el nombre de la ruta, una cookie o la cabecera Accept-Language en el momento de la solicitud y redirigir una URL de entrada neutra a una configuración regional. Next.js 16 cambió el nombre de middleware.ts a proxy.ts, aunque las aplicaciones antiguas siguen usando el término middleware. Considera la negociación una comodidad: cada URL localizada debe seguir siendo accesible directamente y el selector debe usar enlaces ordinarios rastreables.

Una exportación puramente estática no puede ejecutar Proxy, leer cookies de la solicitud ni realizar redirecciones en el momento de la solicitud. Para output: 'export', enumera los segmentos de configuración regional con generateStaticParams y proporciona una experiencia de entrada estática, como una página de inicio con una configuración regional predeterminada o un selector de idioma visible. No prometas detección automática del idioma del navegador en un entorno sin un tiempo de ejecución para solicitudes.

La opción i18n de next.config.js de Pages Router admite subrutas y dominios de configuración regional en aplicaciones Next.js desplegadas. No es compatible con output: 'export'. Si un proyecto con Pages Router debe generar únicamente archivos estáticos, modela la configuración regional como un segmento dinámico explícito y genera esas rutas en lugar de activar el campo i18n integrado. La generación estática y la exportación estática están relacionadas, pero no son el mismo modo de despliegue.

app/
  [locale]/
    layout.tsx
    page.tsx
    pricing/
      page.tsx
messages/
  en.json
  fr.json
  de.json

La siguiente secuencia utiliza una aplicación con App Router porque expone las decisiones a las que se enfrentan la mayoría de los proyectos nuevos. Las importaciones exactas varían según la biblioteca, pero los límites se mantienen estables: valida la configuración regional en la ruta, carga los mensajes de servidor para esa solicitud, proporciona únicamente lo que necesitan los Client Components y genera las configuraciones regionales conocidas durante la compilación cuando la página pueda ser estática.

1. Paso 1

   Añadir el segmento de ruta de configuración regional

   Crea app/[locale] y coloca debajo los layouts y las páginas localizados. Valida params con una única lista de configuraciones regionales compatibles y devuelve una respuesta de página no encontrada para los valores desconocidos.

2. Paso 2

   Definir la negociación y el respaldo

   Decide qué ocurre en una URL sin configuración regional. Un entorno de ejecución para solicitudes puede negociar y redirigir; una exportación estática necesita una página predeterminada determinista o un selector de idioma. Conserva siempre el acceso directo a las URL de configuración regional.

3. Paso 3

   Crear catálogos de mensajes acotados

   Organiza los mensajes por área de producto o ruta en lugar de colocar toda la aplicación en un único archivo. Mantén la misma estructura de espacios de nombres en todas las configuraciones regionales, valida las claves que faltan en CI y evita importar todos los idiomas en un Client Component.

4. Paso 4

   Cargar mensajes en el servidor

   Resuelve un catálogo validado para cada solicitud o ruta generada. Cuando la biblioteca almacene el estado de la configuración regional activa, mantén las instancias del servidor acotadas a la solicitud para impedir que las solicitudes simultáneas filtren sus elecciones de idioma.

5. Paso 5

   Separar la traducción en servidor y cliente

   Traduce en Server Components de forma predeterminada. Añade un proveedor o hook de cliente únicamente en torno al límite interactivo más pequeño que lo necesite y pasa etiquetas traducidas como propiedades cuando resulte más sencillo.

6. Paso 6

   Generar variantes de configuración regional

   Devuelve cada configuración regional compatible desde generateStaticParams para las páginas estáticas. El contenido dinámico también puede requerir combinaciones de slug y configuración regional. Vuelve a compilar cada vez que cambien los catálogos o la lista de configuraciones regionales.

import {NextIntlClientProvider} from 'next-intl';
import {getMessages} from 'next-intl/server';

export default async function LocaleLayout({children, params}: Props) {
  const {locale} = await params;
  const messages = await getMessages();

  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

const locales = ['en', 'fr', 'de'] as const;

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

Haz que el layout raíz de la configuración regional se encargue de las cuestiones comunes a todo el idioma: validar params, cargar el catálogo, definir html lang y dir, y establecer cualquier proveedor de cliente. Las páginas deben solicitar mensajes por espacio de nombres sin saber dónde residen los catálogos. Esta separación permite sustituir las importaciones JSON locales por una descarga durante la compilación o un flujo respaldado por una CDN sin reescribir cada componente.

Para Pages Router, traslada las mismas responsabilidades al enrutamiento por configuración regional de next.config.js, a la carga de mensajes mediante getStaticProps o getServerSideProps y a getStaticPaths para las páginas dinámicas localizadas. Las API del router son distintas, pero las capas de catálogo y de componentes pueden seguir siendo coherentes. Durante una migración, admite ambos routers de forma deliberada y verifica que la navegación nunca elimine el prefijo de configuración regional.

El HTML renderizado es solo el comienzo del SEO multilingüe. Los motores de búsqueda necesitan una URL distinta y estable para cada versión lingüística, además de enlaces claros entre las alternativas. En App Router, generateMetadata puede generar títulos y descripciones localizados junto con alternates.canonical y alternates.languages. Un sitemap también puede enumerar idiomas alternativos. Aplica una política de URL coherente para que los metadatos, la navegación y las entradas del sitemap nunca se contradigan.

Cada página localizada debe hacer referencia a sí misma y a todas las configuraciones regionales equivalentes mediante anotaciones hreflang recíprocas. Usa URL absolutas en producción y añade x-default cuando resulte útil un selector neutro o una experiencia predeterminada. Una URL canónica suele apuntar a la versión del idioma actual, no automáticamente al inglés. Cuando una página no esté disponible en una configuración regional, omite esa alternativa no compatible en lugar de enviar a los rastreadores a contenido no relacionado.

No dependas únicamente de Accept-Language. Googlebot suele rastrear sin una preferencia de idioma útil y el contenido adaptado a la configuración regional bajo una misma URL puede ocultar variantes. Mantén las páginas de cada configuración regional accesibles mediante enlaces normales. Define html lang para los navegadores y las tecnologías de asistencia, pero recuerda que Google determina el idioma principalmente a partir del contenido visible, por lo que la traducción debe ser sustancial y coherente.

• ✓ Devuelve HTML localizado completo en una URL estable y rastreable.
• ✓ Localiza el título, la descripción, los encabezados y el cuerpo visible, no solo la estructura de navegación.
• ✓ Emite una URL canónica para la página actual y enlaces hreflang recíprocos para cada configuración regional disponible.
• ✓ Incluye las URL localizadas en el sitemap y usa x-default como respaldo neutro cuando corresponda.
• ✓ Mantén un selector de idioma rastreable y evita redirecciones forzadas que atrapen a usuarios o bots en una sola configuración regional.

Una biblioteca de Next.js determina cómo selecciona y renderiza los mensajes la aplicación. Una plataforma de localización aborda el ciclo de vida que los rodea: recopilar claves, traducir valores, revisar cambios, mantener alineados los catálogos de cada configuración regional y distribuir contenido aprobado. Estas necesidades aparecen en cuanto los textos cambian con más frecuencia que los despliegues o los colaboradores dejan de limitarse a un único desarrollador.

Translatable está diseñado en torno a archivos de localización JSON. Los equipos pueden importar catálogos existentes, editarlos o traducirlos con ayuda de la IA, sincronizarlos mediante proveedores de Git y distribuir las actualizaciones a través de una CDN. La aplicación conserva el control de su enrutamiento y su biblioteca de i18n, de modo que la distribución de mensajes pueda evolucionar sin vincular los componentes de vista a un entorno de ejecución propietario.

Empieza con catálogos incluidos en el repositorio y un flujo durante la compilación. Introduce la distribución remota solo cuando agilizar las actualizaciones de texto aporte un valor real y conserva un respaldo integrado para las páginas críticas. Este camino progresivo mantiene determinista el renderizado estático y, a medida que crece el producto, ofrece a los equipos de contenido una vía más limpia hacia producción.