Internacionalización de Next.js: Guía completa de i18n con next-intl

Más del 75% de los usuarios de Internet prefieren navegar en su idioma nativo, y las empresas que localizan obtienen tasas de conversión un 70% más altas en mercados no ingleses. Next.js combinado con next-intl proporciona un marco de internacionalización sólido que maneja el enrutamiento, las traducciones, el formato y el SEO en cualquier número de idiomas.

Conclusiones clave

• next-intl se integra perfectamente con Next.js App Router y los componentes del servidor
• El enrutamiento con prefijo local mantiene limpias las URL en inglés mientras agrega prefijos para otros idiomas
• Los componentes del servidor cargan traducciones sin sobrecarga del paquete JavaScript del lado del cliente
• Las etiquetas hreflang adecuadas y los mapas de sitio multilingües son esenciales para el SEO internacional

---

Configuración del proyecto

Instale next-intl y organice su proyecto con un directorio i18n que contenga enrutamiento.ts, navegación.ts y request.ts. Coloque su aplicación en [locale] en App Router. Almacene archivos JSON de traducción en un directorio de mensajes en la raíz del proyecto.

Configuración de enrutamiento

Defina el enrutamiento con defineRouting() especificando su matriz de configuraciones regionales, su configuración regional predeterminada y su estrategia de prefijo local. La estrategia "según sea necesario" omite el prefijo para la configuración regional predeterminada (inglés) mientras agrega prefijos /es/, /fr/, /ar/ para otros.

Cree contenedores de navegación con createNavigation(routing) para obtener funciones Link, useRouter, usePathname y redireccionamiento con reconocimiento regional. Úselos en lugar de la navegación nativa de Next.js en toda su aplicación.

Configuración de middleware

En Next.js 16, cree un archivo proxy.ts (que reemplaza el patrón middleware.ts anterior). Exporte una función de proxy creada por createMiddleware (enrutamiento). Configure el comparador para excluir rutas API, archivos estáticos y rutas _next.

---

Archivos de traducción

Estructura JSON (anidada, no plana)

Utilice claves anidadas organizadas por espacio de nombres. Nunca utilice claves planas separadas por puntos como "home.title", ya que rompen la resolución del espacio de nombres next-intl. Traducciones de estructura como:

• común: términos compartidos (botones, etiquetas, estados de carga)
• nav: elementos de navegación
• inicio: contenido de la página de inicio
• acerca de: Acerca del contenido de la página
• admin.common: términos de administración compartidos
• admin.products: página de gestión de productos

Componentes del servidor

Utilice getTranslations("namespace") en componentes del servidor asíncrono. Esto carga las traducciones en el servidor sin impacto en el paquete de clientes. Llame a t("key") para traducciones de cadenas, t.rich("key", { negrita: (chunks) => ... }) para texto enriquecido.

Componentes del cliente

Utilice el gancho useTranslations("namespace") en los componentes del cliente marcados con "usar cliente". El gancho proporciona la misma función t(). Solo las traducciones del espacio de nombres activo se incluyen en el paquete del cliente.

---

Soporte RTL (de derecha a izquierda)

Para árabe, hebreo, urdu y otros idiomas RTL, establezca dir="rtl" en el elemento HTML según la configuración regional actual. En el diseño de configuración regional, verifique si la configuración regional está en su matriz rtlLocales y establezca la dirección en consecuencia.

Utilice las propiedades lógicas de Tailwind CSS (ps, pe, ms, me en lugar de pl, pr, ml, mr) para diseños que cambian automáticamente en modo RTL. Cargue fuentes apropiadas para escrituras RTL (por ejemplo, Noto Sans Arab para árabe y urdu).

---

SEO: Metadatos y Hreflang

Metadatos dinámicos

Cada página debe usar generateMetadata() (nunca exportar metadatos constantes estáticos) para títulos, descripciones y alternativas de hreflang que tengan en cuenta la configuración regional. Cree un objeto Alternatives.languages ​​que asigne cada configuración regional a su ruta URL, además de una entrada x-default que apunte a la versión en inglés.

Mapa del sitio multilingüe

Genere entradas de mapas del sitio para cada página en cada ubicación. Cada entrada debe incluir idiomas alternativos que mapeen todas las variantes locales. Esto permite a los motores de búsqueda ofrecer la versión en el idioma correcto en cada mercado.

Metaetiqueta de idioma de contenido

Configure la metaetiqueta del idioma del contenido en el diseño local para ayudar a los motores de búsqueda y a los rastreadores de inteligencia artificial a identificar el idioma de la página. Esto es especialmente importante para Bing y los motores de búsqueda de IA emergentes.

---

Flujo de trabajo de traducción

1. Edite en.json como única fuente de verdad para todas las cadenas traducibles
2. Ejecute el script de traducción para propagar nuevas claves a todos los archivos locales (usando la API de Google Translate o DeepL para los borradores iniciales)
3. Revisar las traducciones con hablantes nativos para determinar su calidad y adecuación cultural.
4. Pruebe los lenguajes RTL a fondo: verifique el cambio de diseño, la alineación del texto y las entradas de formulario
5. Verifique el SEO con las herramientas de validación de hreflang y la orientación internacional de Google Search Console

Manejo de archivos de traducción grandes

Para aplicaciones con más de 5000 claves de traducción, organice los archivos JSON por espacio de nombres para mejorar la capacidad de mantenimiento. next-intl carga solo los espacios de nombres necesarios para la página actual, manteniendo el rendimiento óptimo.

---

Consideraciones de rendimiento

• Representación del servidor: las traducciones se cargan en el servidor. No se envía ningún JSON de traducción al cliente a menos que el componente sea un componente del cliente.
• División del espacio de nombres: solo se cargan los espacios de nombres activos por página, no todo el archivo de traducción.
• Generación estática: las páginas que utilizan getTranslations() se pueden generar estáticamente en el momento de la compilación para todas las configuraciones regionales.
• Tamaño del paquete: los componentes del cliente incluyen solo las traducciones de sus espacios de nombres. Una página que utiliza useTranslations("home") incluye solo el espacio de nombres "home".

---

Errores comunes

1. Teclas planas: el uso de "home.title" como clave en lugar de { "home": { "title": "..." } } anidado rompe la resolución del espacio de nombres
2. Traducciones faltantes: proporcione siempre un comportamiento alternativo: next-intl muestra el nombre de la clave si falta una traducción, pero a los usuarios esto les parece incorrecto.
3. Cadenas codificadas: audite su código base para detectar cualquier cadena fuera del sistema de traducción.
4. Formato de fecha/número: use formateadores next-intl en lugar de toLocaleDateString() para un comportamiento consistente
5. Metadatos estáticos: el uso de metadatos export const en lugar de generateMetadata() evita títulos y descripciones que tengan en cuenta la configuración regional

---

Preguntas frecuentes

P: ¿Cuántas configuraciones regionales puede manejar next-intl?

No hay límite práctico. Las aplicaciones con más de 11 configuraciones regionales y más de 7000 claves de traducción se ejecutan sin problemas de rendimiento. La representación del lado del servidor significa que las traducciones no inflan los paquetes de clientes.

P: ¿i18n afecta el rendimiento de carga de la página?

Con los componentes del servidor, la carga de la traducción ocurre en el servidor. El impacto en el rendimiento es insignificante. Los componentes del cliente incluyen solo las traducciones de sus espacios de nombres, normalmente unos pocos KB.

P: ¿Cómo manejamos el contenido de la base de datos dinámica en varios idiomas?

El texto estático de la interfaz de usuario utiliza archivos JSON. El contenido de la base de datos (publicaciones de blog, descripciones de productos) requiere almacenar las traducciones en columnas o tablas dedicadas, o utilizar un CMS con un flujo de trabajo de traducción integrado. Algunos equipos usan un híbrido: JSON para UI, base de datos para contenido.

P: ¿Qué pasa con el formato de números y fechas?

next-intl proporciona useFormatter() para formatear números, monedas, fechas y horas relativas según la configuración regional. Todo el formato sigue el estándar Intl y respeta las convenciones locales automáticamente.

---

¿Qué sigue?

La internacionalización es una inversión que rinde dividendos en todos los mercados no ingleses. Comience con sus locales de mayor valor y amplíe desde allí.

Comuníquese con ECOSIRE para obtener ayuda con la implementación de i18n, o explore nuestros servicios de implementación de Odoo para la implementación de ERP multilingüe.

---

Publicado por ECOSIRE: ayuda a las empresas a escalar con soluciones de software empresarial.