Haz tu pregunta y obtén un resumen del documento referenciando esta página y el proveedor AI de tu elección
Historial de versiones
- Versión inicialv7.0.01/11/2025
El contenido de esta página ha sido traducido con una IA.
Ver la última versión del contenido original en inglésSi tienes una idea para mejorar esta documentación, no dudes en contribuir enviando una pull request en GitHub.
Enlace de GitHub a la documentaciónCopiar el Markdown del documento a la portapapeles
Cómo internacionalizar tu aplicación Next.js usando next-intl en 2026
Tabla de Contenidos
¿Qué es next-intl?
next-intl es una biblioteca popular de internacionalización (i18n) diseñada específicamente para Next.js App Router. Proporciona una forma fluida de construir aplicaciones Next.js multilingües con excelente soporte para TypeScript y optimizaciones integradas.
Si lo prefieres, también puedes consultar la guía de next-i18next, o usar directamente Intlayer.
Consulta la comparación en next-i18next vs next-intl vs Intlayer.
Prácticas que debes seguir
Antes de sumergirnos en la implementación, aquí hay algunas prácticas que debes seguir:
- Configura los atributos HTML
langydir
En tu layout, calculadirusandogetLocaleDirection(locale)y establece<html lang={locale} dir={dir}>para una accesibilidad y SEO adecuados. - Divide los mensajes por namespace
Organiza los archivos JSON por locale y namespace (por ejemplo,common.json,about.json) para cargar solo lo que necesitas. - Minimiza la carga en el cliente
En las páginas, envía solo los namespaces requeridos aNextIntlClientProvider(por ejemplo,pick(messages, ['common', 'about'])). - Prefiere páginas estáticas
Usa páginas estáticas tanto como sea posible para un mejor rendimiento y SEO. - I18n en componentes del servidor
Los componentes del servidor, como las páginas o todos los componentes que no están marcados comoclient, son estáticos y pueden pre-renderizarse en tiempo de compilación. Por lo tanto, tendremos que pasar las funciones de traducción a ellos como props. - Configura los tipos de TypeScript
Para tus locales, para asegurar la seguridad de tipos en toda tu aplicación. - Proxy para redirección
Usa un proxy para manejar la detección de locale y el enrutamiento, y redirigir al usuario a la URL con el prefijo de locale adecuado. - Internacionalización de tus metadatos, sitemap, robots.txt
Internacionaliza tus metadatos, sitemap, robots.txt usando la funcióngenerateMetadataproporcionada por Next.js para asegurar un mejor descubrimiento por los motores de búsqueda en todos los locales. - Localiza los enlaces
Localiza los enlaces usando el componenteLinkpara redirigir al usuario a la URL con el prefijo de locale adecuado. Es importante asegurar el descubrimiento de tus páginas en todos los locales. - Automatiza pruebas y traducciones
Automatizar pruebas y traducciones ayuda a ahorrar tiempo en el mantenimiento de tu aplicación multilingüe.
Consulta nuestra documentación que lista todo lo que necesitas saber sobre internacionalización y SEO: Internationalization (i18n) with next-intl.
Guía paso a paso para configurar next-intl en una aplicación Next.js
Consulta la Plantilla de Aplicación en GitHub.
Aquí está la estructura del proyecto que crearemos:
Copiar el código al portapapeles
Instalar Dependencias
Instala los paquetes necesarios usando npm:
bashCopiar códigoCopiar el código al portapapeles
- next-intl: La biblioteca principal de internacionalización para Next.js App Router que proporciona hooks, funciones del servidor y proveedores del cliente para gestionar las traducciones.
Configura tu Proyecto
Crea un archivo de configuración que defina los locales soportados y configure la solicitud de next-intl. Este archivo sirve como la única fuente de verdad para tu configuración i18n y asegura la seguridad de tipos en toda tu aplicación.
Centralizar la configuración de locales previene inconsistencias y facilita agregar o eliminar locales en el futuro. La función
getRequestConfigse ejecuta en cada solicitud y carga solo las traducciones necesarias para cada página, permitiendo la división de código y reduciendo el tamaño del paquete.src/i18n.tsCopiar códigoCopiar el código al portapapeles
Definir Rutas Dinámicas por Locales
Configura el enrutamiento dinámico para las locales creando un directorio
[locale]en tu carpeta de la aplicación. Esto permite que Next.js maneje el enrutamiento basado en la localización donde cada locale se convierte en un segmento de la URL (por ejemplo,/en/about,/fr/about).Usar rutas dinámicas permite que Next.js genere páginas estáticas para todas las locales en tiempo de compilación, mejorando el rendimiento y el SEO. El componente layout establece los atributos HTML
langydirbasados en la locale, lo cual es crucial para la accesibilidad y la comprensión por parte de los motores de búsqueda.src/app/[locale]/layout.tsxCopiar códigoCopiar el código al portapapeles
src/app/[locale]/about/page.tsxCopiar códigoCopiar el código al portapapeles
Crea tus archivos de traducción
Crea archivos JSON para cada locale y namespace. Esta estructura te permite organizar las traducciones de manera lógica y cargar solo lo que necesitas para cada página.
Organizar las traducciones por namespace (por ejemplo,
common.json,about.json) permite hacer code splitting y reduce el tamaño del bundle. Solo cargas las traducciones necesarias para cada página, mejorando el rendimiento.locales/en/common.jsonCopiar códigoCopiar el código al portapapeles
locales/fr/common.jsonCopiar códigoCopiar el código al portapapeles
locales/en/about.jsonCopiar códigoCopiar el código al portapapeles
locales/fr/about.jsonCopiar códigoCopiar el código al portapapeles
Utiliza las Traducciones en Tus Páginas
Crea un componente de página que cargue las traducciones en el servidor y las pase tanto a los componentes del servidor como del cliente. Esto asegura que las traducciones se carguen antes de renderizar y previene el parpadeo de contenido.
La carga de traducciones del lado del servidor mejora el SEO y previene el FOUC (Flash of Untranslated Content). Al usar
pickpara enviar solo los namespaces requeridos al proveedor del cliente, minimizamos el paquete JavaScript enviado al navegador.src/app/[locale]/about/page.tsxCopiar códigoCopiar el código al portapapeles
Usar Traducciones en Componentes Cliente
Los componentes cliente pueden usar los hooks
useTranslationsyuseFormatterpara acceder a las traducciones y funciones de formato. Estos hooks leen del contextoNextIntlClientProvider.Los componentes cliente necesitan hooks de React para acceder a las traducciones. Los hooks
useTranslationsyuseFormatterse integran perfectamente con next-intl y proporcionan actualizaciones reactivas cuando cambia la configuración regional.No olvides agregar los namespaces requeridos a los mensajes cliente de la página (solo incluye los namespaces que tus componentes cliente realmente necesitan).
src/components/ClientComponent.tsxCopiar códigoCopiar el código al portapapeles
Usar traducciones en componentes del servidor
Los componentes del servidor no pueden usar hooks de React, por lo que reciben las traducciones y los formateadores a través de props desde sus componentes padres. Este enfoque mantiene los componentes del servidor síncronos y permite que se aniden dentro de componentes cliente.
Los componentes del servidor que podrían estar anidados bajo límites de cliente necesitan ser síncronos. Al pasar cadenas traducidas y valores formateados como props, evitamos operaciones asíncronas y aseguramos un renderizado adecuado. Pre-calcula las traducciones y el formato en el componente padre de la página.
src/components/ServerComponent.tsxCopiar códigoCopiar el código al portapapeles
En tu página/layout, usa
getTranslationsygetFormatterdenext-intl/serverpara precomputar traducciones y formatos, luego pásalos como props a los componentes del servidor.Cambiar el idioma de tu contenido
OpcionalPara cambiar el idioma de tu contenido con next-intl, renderiza enlaces conscientes del locale que apunten al mismo pathname mientras cambias el locale. El provider reescribe las URLs automáticamente, así que solo tienes que apuntar a la ruta actual.
src/components/LocaleSwitcher.tsxCopiar códigoCopiar el código al portapapeles
Usar el componente Link localizado
Opcionalnext-intlproporciona un subpaquetenext-intl/navigationque contiene un componente Link localizado que aplica automáticamente la locale activa. Ya lo hemos extraído para ti en el archivo@/i18n, por lo que puedes usarlo así:src/components/MyComponent.tsxCopiar códigoCopiar el código al portapapeles
Acceder a la locale activa dentro de Server Actions
OpcionalLas Server Actions pueden leer la locale actual usando
next-intl/server. Esto es útil para enviar correos electrónicos localizados o almacenar preferencias de idioma junto con los datos enviados.src/app/actions/get-current-locale.tsCopiar códigoCopiar el código al portapapeles
getLocalelee la locale establecida por el proxy denext-intl, por lo que funciona en cualquier parte del servidor: Route Handlers, Server Actions y funciones edge.Internacionaliza tus Metadatos
OpcionalTraducir contenido es importante, pero el objetivo principal de la internacionalización es hacer que tu sitio web sea más visible para el mundo. I18n es una palanca increíble para mejorar la visibilidad de tu sitio web mediante un SEO adecuado.
Los metadatos correctamente internacionalizados ayudan a los motores de búsqueda a entender qué idiomas están disponibles en tus páginas. Esto incluye configurar las etiquetas meta hreflang, traducir títulos y descripciones, y asegurar que las URLs canónicas estén correctamente establecidas para cada locale.
src/app/[locale]/about/layout.tsxCopiar códigoCopiar el código al portapapeles
Internacionaliza tu Sitemap
OpcionalGenera un sitemap que incluya todas las versiones locales de tus páginas. Esto ayuda a los motores de búsqueda a descubrir e indexar todas las versiones en diferentes idiomas de tu contenido.
Un sitemap correctamente internacionalizado asegura que los motores de búsqueda puedan encontrar e indexar todas las versiones en diferentes idiomas de tus páginas. Esto mejora la visibilidad en los resultados de búsqueda internacionales.
src/app/sitemap.tsCopiar códigoCopiar el código al portapapeles
Internacionaliza tu archivo robots.txt
OpcionalCrea un archivo robots.txt que maneje correctamente todas las versiones de locales de tus rutas protegidas. Esto asegura que los motores de búsqueda no indexen páginas de administración o panel en ningún idioma.
Configurar correctamente robots.txt para todos los locales evita que los motores de búsqueda indexen páginas sensibles cuando tus rutas son diferentes para cada localización.
src/app/robots.tsCopiar códigoCopiar el código al portapapeles
Configurar Proxy para el Enrutamiento de Locales
OpcionalCrea un proxy para detectar automáticamente la locale preferida del usuario y redirigirlo a la URL con el prefijo de locale correspondiente. next-intl proporciona una función proxy conveniente que maneja esto automáticamente.
El proxy asegura que los usuarios sean redirigidos automáticamente a su idioma preferido cuando visitan tu sitio. También guarda la preferencia del usuario para futuras visitas, mejorando la experiencia del usuario.
src/proxy.tsCopiar códigoCopiar el código al portapapeles
Configurar los tipos de TypeScript para la locale
OpcionalConfigurar TypeScript te ayudará a obtener autocompletado y seguridad de tipos para tus claves.
Para ello, puedes crear un archivo global.ts en la raíz de tu proyecto y añadir el siguiente código:
global.tsCopiar códigoCopiar el código al portapapeles
Este código usará la Ampliación de Módulos (Module Augmentation) para añadir los locales y mensajes al tipo AppConfig de next-intl.
Automatiza tus traducciones usando Intlayer
OpcionalIntlayer es una biblioteca gratuita y de código abierto diseñada para asistir en el proceso de localización en tu aplicación. Mientras que next-intl se encarga de la carga y gestión de las traducciones, Intlayer ayuda a automatizar el flujo de trabajo de traducción.
Gestionar las traducciones manualmente puede ser una tarea que consume mucho tiempo y propensa a errores. Intlayer automatiza las pruebas, generación y gestión de traducciones, ahorrándote tiempo y asegurando consistencia en toda tu aplicación.
Intlayer te permitirá:
Declarar tu contenido donde quieras en tu base de código Intlayer permite declarar tu contenido donde quieras en tu base de código usando archivos
.content.{ts|js|json}. Esto permitirá una mejor organización de tu contenido, asegurando una mejor legibilidad y mantenibilidad de tu base de código.Probar traducciones faltantes Intlayer proporciona funciones de prueba que pueden integrarse en tu pipeline de CI/CD o en tus pruebas unitarias. Aprende más sobre cómo probar tus traducciones.
Automatiza tus traducciones, Intlayer ofrece una CLI y una extensión para VSCode para automatizar tus traducciones. Puede integrarse en tu pipeline de CI/CD. Aprende más sobre automatizar tus traducciones. Puedes usar tu propia clave API y el proveedor de IA de tu elección. También proporciona traducciones conscientes del contexto, consulta rellenar contenido.
Conectar contenido externo Intlayer te permite conectar tu contenido a un sistema de gestión de contenido externo (CMS). Para obtenerlo de manera optimizada e insertarlo en tus recursos JSON. Aprende más sobre obtener contenido externo.
Editor visual Intlayer ofrece un editor visual gratuito para editar tu contenido usando un editor visual. Aprende más sobre edición visual de tus traducciones.
Y más. Para descubrir todas las funcionalidades que ofrece Intlayer, por favor consulta la documentación sobre el interés de Intlayer.
Comentarios
Aún no hay comentarios. Sé el primero en compartir tus pensamientos.