Haz tu pregunta y obtén un resumen del documento referenciando esta página y el proveedor AI de tu elección
Al integrar el servidor MCP Intlayer a tu asistente de IA, puedes recuperar todos los documentos directamente desde ChatGPT, DeepSeek, Cursor, VSCode, etc.
Ver la documentación del servidor MCPEl 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
Comenzando a internacionalizar (i18n) con Intlayer y Next.js usando Page Router
¿Qué es Intlayer?
Intlayer es una biblioteca innovadora y de código abierto para la internacionalización (i18n) diseñada para simplificar el soporte multilingüe en aplicaciones web modernas. Intlayer se integra perfectamente con el último framework Next.js, incluyendo su tradicional Page Router.
Con Intlayer, puedes:
- Gestionar traducciones fácilmente usando diccionarios declarativos a nivel de componente.
- Localizar dinámicamente metadatos, rutas y contenido.
- Garantizar soporte para TypeScript con tipos autogenerados, mejorando la autocompletación y la detección de errores.
- Beneficiarte de funciones avanzadas, como la detección y el cambio dinámico de idioma.
Intlayer es compatible con Next.js 12, 13, 14 y 15. Si estás utilizando el App Router de Next.js, consulta la guía del App Router. Para Next.js 15, sigue esta guía.
Guía paso a paso para configurar Intlayer en una aplicación Next.js usando Page Router
Paso 1: Instalar dependencias
Instala los paquetes necesarios usando tu gestor de paquetes preferido:
Copiar el código al portapapeles
npm install intlayer next-intlayer
intlayer
intlayer
El paquete principal que proporciona herramientas de internacionalización para la gestión de configuración, traducción, declaración de contenido, transpilación y comandos CLI.
next-intlayer
El paquete que integra Intlayer con Next.js. Proporciona proveedores de contexto y hooks para la internacionalización en Next.js. Además, incluye el plugin de Next.js para integrar Intlayer con Webpack o Turbopack, así como middleware para detectar la configuración regional preferida del usuario, gestionar cookies y manejar redirecciones de URL.
Paso 2: Configura Tu Proyecto
Crea un archivo de configuración para definir los idiomas que soporta tu aplicación:
Copiar el código al portapapeles
import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = { internationalization: { locales: [ Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, // Agrega aquí tus otros locales ], defaultLocale: Locales.ENGLISH, },};export default config;
A través de este archivo de configuración, puedes configurar URLs localizadas, redirección en middleware, nombres de cookies, la ubicación y extensión de tus declaraciones de contenido, deshabilitar los logs de Intlayer en la consola, y más. Para una lista completa de los parámetros disponibles, consulta la documentación de configuración.
Paso 3: Integrar Intlayer con la Configuración de Next.js
Modifica la configuración de Next.js para incorporar Intlayer:
Copiar el código al portapapeles
import { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = { // Tu configuración existente de Next.js};export default withIntlayer(nextConfig);
El plugin withIntlayer() de Next.js se utiliza para integrar Intlayer con Next.js. Garantiza la construcción de archivos de declaración de contenido y los supervisa en modo de desarrollo. Define variables de entorno de Intlayer dentro de los entornos de Webpack o Turbopack. Además, proporciona alias para optimizar el rendimiento y asegura la compatibilidad con componentes del servidor.
Paso 4: Configurar Middleware para la Detección de Idioma
Configura el middleware para detectar y manejar automáticamente el idioma preferido del usuario:
Copiar el código al portapapeles
export { intlayerMiddleware as middleware } from "next-intlayer/middleware";export const config = { matcher: "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};
Adapte el parámetro matcher para que coincida con las rutas de su aplicación. Para más detalles, consulte la documentación de Next.js sobre cómo configurar el matcher.
Paso 5: Definir Rutas Dinámicas por Localidad
Implemente el enrutamiento dinámico para servir contenido localizado según la localidad del usuario.
Crear Páginas Específicas por Localidad:
Cambie el nombre de su archivo de página principal para incluir el segmento dinámico [locale].
bashCopiar códigoCopiar el código al portapapeles
mv src/pages/index.tsx src/pages/[locale]/index.tsx
Actualizar _app.tsx para Manejar la Localización:
Modifique su _app.tsx para incluir los proveedores de Intlayer.
src/pages/_app.tsxCopiar códigoCopiar el código al portapapeles
import type { FC } from "react";import type { AppProps } from "next/app";import { IntlayerClientProvider } from "next-intlayer";const App = FC<AppProps>({ Component, pageProps }) => { const { locale } = pageProps; return ( <IntlayerClientProvider locale={locale}> <Component {...pageProps} /> </IntlayerClientProvider> );}export default MyApp;
Configurar getStaticPaths y getStaticProps:
En tu archivo [locale]/index.tsx, define las rutas y propiedades para manejar diferentes locales.
src/pages/[locale]/index.tsxCopiar códigoCopiar el código al portapapeles
import type { FC } from "react";import type { GetStaticPaths, GetStaticProps } from "next";import { type Locales, getConfiguration } from "intlayer";const HomePage: FC = () => <div>{/* Tu contenido aquí */}</div>;export const getStaticPaths: GetStaticPaths = () => { const { internationalization } = getConfiguration(); const { locales } = internationalization; const paths = locales.map((locale) => ({ params: { locale }, })); return { paths, fallback: false };};export const getStaticProps: GetStaticProps = ({ params }) => { const locale = params?.locale as string; return { props: { locale, }, };};export default HomePage;
getStaticPaths y getStaticProps aseguran que tu aplicación preconstruya las páginas necesarias para todos los locales en el enrutador de páginas de Next.js. Este enfoque reduce el cálculo en tiempo de ejecución y conduce a una mejor experiencia de usuario. Para más detalles, consulta la documentación de Next.js sobre getStaticPaths y getStaticProps.
Paso 6: Declara tu Contenido
Crea y administra tus declaraciones de contenido para almacenar las traducciones.
Copiar el código al portapapeles
import { t, type Dictionary } from "intlayer";const homeContent = { key: "home", content: { title: t({ en: "Welcome to My Website", fr: "Bienvenue sur mon site Web", es: "Bienvenido a mi sitio web", }), description: t({ en: "Comience por editar esta página.", fr: "Commencez par éditer cette page.", es: "Comience por editar esta página.", }), },} satisfies Dictionary;export default homeContent;
Para más información sobre cómo declarar contenido, consulte la guía de declaración de contenido.
Paso 7: Utilice el Contenido en Su Código
Acceda a sus diccionarios de contenido en toda su aplicación para mostrar contenido traducido.
Copiar el código al portapapeles
import type { FC } from "react";import { useIntlayer } from "next-intlayer";import { ComponentExample } from "@components/ComponentExample";const HomePage: FC = () => { const content = useIntlayer("home"); return ( <div> <h1>{content.title}</h1> <p>{content.description}</p> <ComponentExample /> {/* Componentes adicionales */} </div> );};// ... Resto del código, incluyendo getStaticPaths y getStaticPropsexport default HomePage;
Copiar el código al portapapeles
import type { FC } from "react";import { useIntlayer } from "next-intlayer";export const ComponentExample: FC = () => { const content = useIntlayer("component-example"); // Asegúrate de tener una declaración de contenido correspondiente return ( <div> <h2>{content.title}</h2> <p>{content.content}</p> </div> );};
Cuando uses traducciones en atributos de tipo string (por ejemplo, alt, title, href, aria-label), llama
al valor de la función de la siguiente manera:
jsxCopiar códigoCopiar el código al portapapeles
<img src={content.image.src.value} alt={content.image.value} />
Para aprender más sobre el hook useIntlayer, consulta la documentación.
(Opcional) Paso 8: Internacionalización de tus metadatos
En caso de que desees internacionalizar tus metadatos, como el título de tu página, puedes usar la función getStaticProps proporcionada por el Page Router de Next.js. Dentro de esta función, puedes obtener el contenido desde la función getIntlayer para traducir tus metadatos.
Copiar el código al portapapeles
import { type Dictionary, t } from "intlayer";import { type Metadata } from "next";const metadataContent = { key: "page-metadata", content: { title: t({ en: "Create Next App", fr: "Créer une application Next.js", es: "Crear una aplicación Next.js", }), description: t({ en: "Generated by create next app", fr: "Généré par create next app", es: "Generado por create next app", }), },} satisfies Dictionary<Metadata>;export default metadataContent;
Copiar el código al portapapeles
import { GetStaticPaths, GetStaticProps } from "next";import { getIntlayer, getMultilingualUrls } from "intlayer";import { useIntlayer } from "next-intlayer";import Head from "next/head";import type { FC } from "react";interface HomePageProps { locale: string; metadata: { title: string; description: string; }; multilingualUrls: Record<string, string>;}const HomePage: FC<HomePageProps> = ({ metadata, multilingualUrls, locale,}) => { const content = useIntlayer("page"); return ( <div> <Head> <title>{metadata.title}</title> <meta name="description" content={metadata.description} /> {/* Generar etiquetas hreflang para SEO */} {Object.entries(multilingualUrls).map(([lang, url]) => ( <link key={lang} rel="alternate" hrefLang={lang} href={url} /> ))} <link rel="canonical" href={multilingualUrls[locale]} /> </Head> {/* Contenido de la página */} <main>{/* Aquí va el contenido de tu página */}</main> </div> );};export const getStaticProps: GetStaticProps<HomePageProps> = async ({ params,}) => { const locale = params?.locale as string; const metadata = getIntlayer("page-metadata", locale); /** * Genera un objeto que contiene todas las URLs para cada idioma. * * Ejemplo: * ```ts * getMultilingualUrls('/about'); * * // Retorna * // { * // en: '/about', * // fr: '/fr/about', * // es: '/es/about', * // } * ``` */ const multilingualUrls = getMultilingualUrls("/"); return { props: { locale, metadata, multilingualUrls, }, };};export default HomePage;// ... Resto del código incluyendo getStaticPaths
Tenga en cuenta que la función getIntlayer importada desde next-intlayer devuelve su contenido envuelto en un IntlayerNode, lo que permite la integración con el editor visual. En contraste, la función getIntlayer importada desde intlayer devuelve su contenido directamente sin propiedades adicionales.
Alternativamente, puede usar la función getTranslation para declarar sus metadatos. Sin embargo, se recomienda usar archivos de declaración de contenido para automatizar la traducción de sus metadatos y externalizar el contenido en algún momento.
Copiar el código al portapapeles
import { GetStaticPaths, GetStaticProps } from "next";import { type IConfigLocales, getTranslation, getMultilingualUrls,} from "intlayer";import { useIntlayer } from "next-intlayer";import Head from "next/head";import type { FC } from "react";interface HomePageProps { locale: string; metadata: { title: string; description: string; }; multilingualUrls: Record<string, string>;}const HomePage: FC<HomePageProps> = ({ metadata, multilingualUrls, locale }) => { const content = useIntlayer("page"); return ( <div> <Head> <title>{metadata.title}</title> <meta name="description" content={metadata.description} /> {/* Generar etiquetas hreflang para SEO */} {Object.entries(multilingualUrls).map(([lang, url]) => ( <link key={lang} rel="alternate" hrefLang={lang} href={url} /> ))} <link rel="canonical" href={multilingualUrls[locale]} /> </Head> {/* Contenido de la página */} <main> {/* Aquí va el contenido de tu página */} </main> </div> );};export const getStaticProps: GetStaticProps<HomePageProps> = async ({ params}) => { const locale = params?.locale as string; const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale); const metadata = { title: t<string>({ en: "My title", fr: "Mon titre", es: "Mi título", }), description: t({ en: "My description", fr: "Ma description", es: "Mi descripción", }), }; const multilingualUrls = getMultilingualUrls("/"); return { props: { locale, metadata, multilingualUrls, }, };};export default HomePage;// ... Resto del código incluyendo getStaticPaths
Aprende más sobre la optimización de metadatos en la documentación oficial de Next.js.
(Opcional) Paso 9: Cambiar el idioma de tu contenido
Para cambiar el idioma de tu contenido en Next.js, la forma recomendada es usar el componente Link para redirigir a los usuarios a la página localizada correspondiente. El componente Link permite la precarga de la página, lo que ayuda a evitar una recarga completa.
Copiar el código al portapapeles
import { Locales, getHTMLTextDir, getLocaleName, getLocalizedUrl,} from "intlayer";import { useLocalePageRouter } from "next-intlayer";import { type FC } from "react";import Link from "next/link";const LocaleSwitcher: FC = () => { const { locale, pathWithoutLocale, availableLocales } = useLocalePageRouter(); const { setLocaleCookie } = useLocaleCookie(); return ( <div> <button popoverTarget="localePopover">{getLocaleName(locale)}</button> <div id="localePopover" popover="auto"> {availableLocales.map((localeItem) => ( <Link href={getLocalizedUrl(pathWithoutLocale, localeItem)} hrefLang={localeItem} key={localeItem} aria-current={locale === localeItem ? "page" : undefined} onClick={() => setLocaleCookie(localeItem)} > <span> {/* Localización - por ejemplo FR */} {localeItem} </span> <span> {/* Idioma en su propia localización - por ejemplo Français */} {getLocaleName(localeItem, locale)} </span> <span dir={getHTMLTextDir(localeItem)} lang={localeItem}> {/* Idioma en la configuración regional actual - por ejemplo, Francés con la configuración regional establecida en Locales.SPANISH */} {getLocaleName(localeItem)} </span> <span dir="ltr" lang={Locales.ENGLISH}> {/* Idioma en inglés - por ejemplo, French */} {getLocaleName(localeItem, Locales.ENGLISH)} </span> </Link> ))} </div> </div> );};
Una forma alternativa es usar la función setLocale proporcionada por el hook useLocale. Esta función no permitirá la precarga de la página y recargará la página.
En este caso, sin redireccionamiento usando router.push, solo tu código del lado del servidor cambiará el idioma del contenido.
Copiar el código al portapapeles
"use client";import { useRouter } from "next/navigation";import { useLocale } from "next-intlayer";import { getLocalizedUrl } from "intlayer";// ... Resto del códigoconst router = useRouter();const { setLocale } = useLocale({ onLocaleChange: (locale) => { router.push(getLocalizedUrl(pathWithoutLocale, locale)); },});return ( <button onClick={() => setLocale(Locales.FRENCH)}>Cambiar a francés</button>);
La API useLocalePageRouter es la misma que useLocale. Para aprender más sobre el hook useLocale, consulta la documentación.
Referencias de la documentación:
(Opcional) Paso 10: Creación de un Componente de Enlace Localizado
Para asegurar que la navegación de tu aplicación respete la configuración regional actual, puedes crear un componente personalizado Link. Este componente antepone automáticamente a las URLs internas el idioma actual, de modo que, por ejemplo, cuando un usuario francófono hace clic en un enlace a la página "About", es redirigido a /fr/about en lugar de /about.
Este comportamiento es útil por varias razones:
- SEO y experiencia del usuario: Las URLs localizadas ayudan a los motores de búsqueda a indexar correctamente las páginas específicas por idioma y proporcionan a los usuarios contenido en su idioma preferido.
- Consistencia: Al usar un enlace localizado en toda tu aplicación, garantizas que la navegación se mantenga dentro de la configuración regional actual, evitando cambios inesperados de idioma.
- Mantenibilidad: Centralizar la lógica de localización en un solo componente simplifica la gestión de URLs, haciendo que tu base de código sea más fácil de mantener y ampliar a medida que tu aplicación crece.
A continuación se muestra la implementación de un componente Link localizado en TypeScript:
Copiar el código al portapapeles
"use client";import { getLocalizedUrl } from "intlayer";import NextLink, { type LinkProps as NextLinkProps } from "next/link";import { useLocale } from "next-intlayer";import { forwardRef, PropsWithChildren, type ForwardedRef } from "react";/** * Función utilitaria para verificar si una URL dada es externa. * Si la URL comienza con http:// o https://, se considera externa. */export const checkIsExternalLink = (href?: string): boolean => /^https?:\/\//.test(href ?? "");/** * Un componente Link personalizado que adapta el atributo href según la configuración regional actual. * Para enlaces internos, usa `getLocalizedUrl` para anteponer la configuración regional a la URL (por ejemplo, /fr/about). * Esto asegura que la navegación se mantenga dentro del mismo contexto regional. */export const Link = forwardRef< HTMLAnchorElement, PropsWithChildren<NextLinkProps>>(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => { const { locale } = useLocale(); const isExternalLink = checkIsExternalLink(href.toString()); // Si el enlace es interno y se proporciona un href válido, obtener la URL localizada. const hrefI18n: NextLinkProps["href"] = href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href; return ( <NextLink href={hrefI18n} ref={ref} {...props}> {children} </NextLink> );});Link.displayName = "Link";
Cómo Funciona
Detección de Enlaces Externos:
La función auxiliar checkIsExternalLink determina si una URL es externa. Los enlaces externos se dejan sin cambios porque no necesitan localización.Obtención de la Configuración Regional Actual:
El hook useLocale proporciona la configuración regional actual (por ejemplo, fr para francés).Localización de la URL:
Para enlaces internos (es decir, no externos), se utiliza getLocalizedUrl para prefijar automáticamente la URL con la configuración regional actual. Esto significa que si tu usuario está en francés, pasar /about como href se transformará en /fr/about.Devolviendo el enlace:
El componente devuelve un elemento <a> con la URL localizada, asegurando que la navegación sea coherente con la configuración regional.
Al integrar este componente Link en toda tu aplicación, mantienes una experiencia de usuario coherente y consciente del idioma, además de beneficiarte de una mejor SEO y usabilidad.
(Opcional) Paso 11: Optimiza el tamaño de tu paquete
Al usar next-intlayer, los diccionarios se incluyen en el paquete para cada página por defecto. Para optimizar el tamaño del paquete, Intlayer proporciona un plugin SWC opcional que reemplaza inteligentemente las llamadas a useIntlayer usando macros. Esto asegura que los diccionarios solo se incluyan en los paquetes de las páginas que realmente los usan.
Para habilitar esta optimización, instala el paquete @intlayer/swc. Una vez instalado, next-intlayer detectará y usará automáticamente el plugin:
Copiar el código al portapapeles
npm install @intlayer/swc --save-dev
Nota: Esta optimización solo está disponible para Next.js 13 y versiones superiores.
Nota: Este paquete no se instala por defecto porque los plugins SWC aún son experimentales en Next.js. Esto podría cambiar en el futuro.
Configurar TypeScript
Intlayer utiliza la ampliación de módulos para aprovechar las ventajas de TypeScript y fortalecer tu base de código.
Asegúrate de que tu configuración de TypeScript incluya los tipos autogenerados.
Copiar el código al portapapeles
{ // ... Tus configuraciones existentes de TypeScript "include": [ // ... Tus configuraciones existentes de TypeScript ".intlayer/**/*.ts", // Incluir los tipos autogenerados ],}
Configuración de Git
Para mantener tu repositorio limpio y evitar cometer archivos generados, se recomienda ignorar los archivos creados por Intlayer.
Agrega las siguientes líneas a tu archivo .gitignore:
Copiar el código al portapapeles
# Ignorar los archivos generados por Intlayer.intlayer
Extensión de VS Code
Para mejorar tu experiencia de desarrollo con Intlayer, puedes instalar la Extensión oficial de Intlayer para VS Code.
Instalar desde el Marketplace de VS Code
Esta extensión proporciona:
- Autocompletado para las claves de traducción.
- Detección de errores en tiempo real para traducciones faltantes.
- Previsualizaciones en línea del contenido traducido.
- Acciones rápidas para crear y actualizar traducciones fácilmente.
Para más detalles sobre cómo usar la extensión, consulta la documentación de la extensión Intlayer para VS Code.
Recursos adicionales
- Documentación de Intlayer: Repositorio GitHub
- Guía del Diccionario: Diccionario
- Documentación de Configuración: Guía de Configuración
Siguiendo esta guía, puedes integrar eficazmente Intlayer en tu aplicación Next.js usando el Page Router, permitiendo un soporte de internacionalización robusto y escalable para tus proyectos web.
Ir más allá
Para profundizar, puedes implementar el editor visual o externalizar tu contenido usando el CMS.
Historial del Documento
- 5.5.10 - 2025-06-29: Historial inicial