Cómo hacer que una aplicación Next.js existente sea multilingüe (i18n) (guía i18n 2026)

Vea Plantilla de la Aplicación en GitHub.

Índice

¿Por qué es difícil internacionalizar una aplicación existente?

Si alguna vez ha intentado agregar múltiples idiomas a una aplicación que solo se construyó para uno, conoce el esfuerzo que supone. No es solo "difícil", es tedioso. Tiene que revisar cada archivo, encontrar cada cadena de texto y moverlos a archivos de diccionario separados.

Luego viene la parte arriesgada: reemplazar todo ese texto con "hooks" de código sin romper el diseño o la lógica. Es el tipo de trabajo que interrumpe el desarrollo de nuevas funciones durante semanas y se siente como una refactorización interminable.

¿Qué es el Compilador Intlayer?

El Compilador Intlayer fue diseñado para evitar ese trabajo manual. En lugar de extraer las cadenas manualmente, el compilador lo hace por usted. Escanea su código, encuentra el texto y usa IA para generar los diccionarios en segundo plano. Luego, modifica su código durante la compilación para inyectar los hooks i18n necesarios. Básicamente, usted sigue escribiendo su aplicación como si fuera en un solo idioma, y el compilador gestiona la transformación multilingüe automáticamente.

Doc Compilador: /es/doc/compiler

Limitaciones

Dado que el compilador realiza el análisis y la transformación del código (inyectando hooks y generando diccionarios) durante el tiempo de compilación, puede ralentizar el proceso de build de su aplicación.

Para mitigar este impacto durante el desarrollo, puede configurar el compilador en su modo 'build-only' o deshabilitarlo cuando no lo necesite.

Guía paso a paso para configurar Intlayer en una aplicación Next.js

Paso 1: Instalar dependencias

Instale los paquetes necesarios utilizando npm:

npm install intlayer next-intlayernpm install @intlayer/babel --save-devnpx intlayer init

• intlayer

  El paquete central que proporciona herramientas de internacionalización para la gestión de la 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 de Next.js. Además, incluye el plugin de Next.js para integrar Intlayer con Webpack o Turbopack, así como un proxy para detectar el locale preferido del usuario, gestionar cookies y manejar redireccionamientos de URL.

Paso 2: Configurar su proyecto

Cree un archivo de configuración para definir los idiomas de su aplicación:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.SPANISH],    defaultLocale: Locales.SPANISH,  },  routing: {    mode: "search-params",  },  compiler: {    /**     * Indica si el compilador debe estar habilitado.     */    enabled: true,    /**     * Directorio de salida para los diccionarios optimizados.     */    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,    /**     * Inserta solo el contenido en el archivo generado, sin clave.     */    noMetadata: false,    /**     * Prefijo de clave de diccionario     */    dictionaryKeyPrefix: "", // Eliminar el prefijo base    /**     * Indica si los componentes deben guardarse después de ser transformados.     * De esta manera, el compilador puede ejecutarse una sola vez para transformar la aplicación y luego puede eliminarse.     */    saveComponents: false,  },  ai: {    provider: "openai",    model: "gpt-5-mini",    apiKey: process.env.OPEN_AI_API_KEY,    applicationContext: "Esta aplicación es una aplicación de mapas",  },};export default config;

Nota: Asegúrese de tener su OPEN_AI_API_KEY configurada en sus variables de entorno.

A través de este archivo de configuración, puede configurar URLs localizadas, redirección de proxy, nombres de cookies, la ubicación y extensión de sus declaraciones de contenido, desactivar los registros de Intlayer en la consola, y más. Para obtener una lista completa de los parámetros disponibles, consulte la documentación de configuración.

Paso 3: Integrar Intlayer en su configuración de Next.js

Configure su configuración de Next.js para usar Intlayer:

import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = {  /* opciones de configuración aquí */};export default withIntlayer(nextConfig);

El plugin de Next.js withIntlayer() se utiliza para integrar Intlayer con Next.js. Asegura la construcción de los archivos de declaración de contenido y los monitorea en modo de desarrollo. Define las variables de entorno de Intlayer dentro de los entornos Webpack o Turbopack. Además, proporciona alias para optimizar el rendimiento y garantizar la compatibilidad con los componentes del servidor.

Paso 4: Configurar Babel

El compilador de Intlayer requiere Babel para extraer y optimizar su contenido. Actualice su babel.config.js (o babel.config.json) para incluir los plugins de Intlayer:

const {  intlayerExtractBabelPlugin,  intlayerOptimizeBabelPlugin,  getExtractPluginOptions,  getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = {  presets: ["next/babel"],  plugins: [    [intlayerExtractBabelPlugin, getExtractPluginOptions()],    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],  ],};

Paso 5: Detectar Locale en sus páginas

Elimine todo del RootLayout y reemplácelo con el siguiente código:

import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";import { getHTMLTextDir, getIntlayer } from "intlayer";import { getLocale } from "next-intlayer/server";export { generateStaticParams } from "next-intlayer";export const generateMetadata = async (): Promise<Metadata> => {  const locale = await getLocale();  const { title, description, keywords } = getIntlayer("metadata", locale);  return {    title,    description,    keywords,  };};const RootLayout = async ({  children,}: Readonly<{  children: ReactNode;}>) => {  const locale = await getLocale();  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

Paso 6: Compilar sus componentes

Con el compilador habilitado, ya no necesita declarar manualmente los diccionarios de contenido (como los archivos .content.ts).

En su lugar, puede escribir su contenido directamente en su código como cadenas de texto. Intlayer analizará su código, generará las traducciones utilizando el proveedor de IA configurado y reemplazará las cadenas con contenido localizado en tiempo de compilación.

Simplemente escriba sus componentes con cadenas de texto codificadas en su idioma predeterminado. El compilador se encarga del resto.

Ejemplo de cómo podría verse su página:

import type { FC } from "react";import { IntlayerServerProvider } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {return (  <>    <p>Comience editando</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

{key: "page-content",content: {  nodeType: "translation",  translation: {    en: {      getStartedByEditing: "Get started by editing",    },    fr: {      getStartedByEditing: "Commencez par éditer",    },    es: {      getStartedByEditing: "Comience editando",    },  }}}

import { type FC } from "react";import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {const content = useIntlayer("page-content");return (  <>    <p>{content.getStartedByEditing}</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

• IntlayerClientProvider se utiliza para proporcionar el locale a los componentes del lado del cliente.

• IntlayerServerProvider se utiliza para proporcionar el locale a los hijos del servidor.

  Layout and page cannot share a common server context because the server context system is based on a per-request data store (via React's cache mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.

(Opcional) Paso 7: Completar traducciones faltantes

Intlayer proporciona una herramienta CLI para ayudarle a completar las traducciones faltantes. Puede utilizar el comando intlayer para probar y completar las traducciones faltantes de su código.

npx intlayer test         # Probar si faltan traducciones

npx intlayer fill         # Completar traducciones faltantes

Para más detalles, consulta la documentación de la CLI

(Opcional) Paso 8: Configurar Proxy para la Detección de Locale

Configure un proxy para detectar el locale preferido del usuario:

export { intlayerProxy as proxy } from "next-intlayer/proxy";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};

El intlayerProxy se utiliza para detectar el locale preferido del usuario y redirigirlo a la URL adecuada según lo especificado en la configuración. Además, permite guardar el locale preferido del usuario en una cookie.

(Opcional) Paso 8: Cambiar el idioma de su contenido

Para cambiar el idioma de su contenido en Next.js, la forma recomendada es utilizar el componente Link para redirigir a los usuarios a la página localizada correspondiente. El componente Link permite la pre-carga de la página, lo que ayuda a evitar una recarga completa de la página.

"use client";import type { FC } from "react";import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";import { useLocale } from "next-intlayer";export const LocaleSwitcher: FC = () => {  const { locale, availableLocales, setLocale } = useLocale();  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocale(localeItem)}          >            <span>              {/* Locale - ej. ES */}              {localeItem}            </span>            <span>              {/* Idioma en su propio Locale - ej. Español */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Idioma en el Locale actual - ej. Francés con el locale actual establecido en Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Idioma en inglés - ej. French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};

Una forma alternativa es utilizar la función setLocale proporcionada por el hook useLocale. Esta función no permitirá la pre-carga de la página. Consulte la documentación del hook useLocale para más detalles.

(Opcional) Paso 10: Optimice el tamaño de su bundle

Cuando utiliza next-intlayer, los diccionarios se incluyen en el bundle para cada página de forma predeterminada. Para optimizar el tamaño del bundle, Intlayer proporciona un plugin SWC opcional que reemplaza de forma inteligente las llamadas a useIntlayer utilizando macros. Esto asegura que los diccionarios solo se incluyan en los bundles de las páginas que realmente los utilizan.

Para habilitar esta optimización, instale el paquete @intlayer/swc. Una vez instalado, next-intlayer detectará y utilizará automáticamente el plugin:

npm install @intlayer/swc --save-dev

Nota: Esta optimización solo está disponible para Next.js 13 y superiores.

Nota: Este paquete no se instala por defecto porque los plugins SWC aún son experimentales en Next.js. Puede cambiar en el futuro.

Nota: Si establece la opción como importMode: 'dynamic' o importMode: 'fetch' (en la configuración de dictionary), dependerá de Suspense, por lo que tendrá que envolver sus llamadas a useIntlayer en un límite de Suspense. Esto significa que no podrá usar useIntlayer directamente en el nivel superior de su componente Página / Layout.

(Opcional) Paso 11 : Extraer el contenido de tus componentes

Si tienes una base de código existente, transformar miles de archivos puede llevar mucho tiempo.

Para facilitar este proceso, Intlayer propone un compilador / extractor para transformar tus componentes y extraer el contenido.

Para configurarlo, puedes agregar una sección compiler en tu archivo intlayer.config.ts :

import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Resto de tu configuración
  compiler: {
    /**
     * Indica si el compilador debe estar habilitado.
     */
    enabled: true,

    /**
     * Define la ruta de los archivos de salida
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Indica si los componentes deben guardarse después de ser transformados. De esa manera, el compilador se puede ejecutar solo una vez para transformar la aplicación y luego se puede eliminar.
     */
    saveComponents: false,

    /**
     * Prefijo de clave de diccionario
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

npx intlayer extract

npm install @intlayer/babel --save-dev

const { intlayerExtractBabelPlugin, getExtractPluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Extraer contenido de los componentes en diccionarios   [intlayerExtractBabelPlugin, getExtractPluginOptions()], ],};

npm run build # O npm run dev

Configurar TypeScript

Intlayer utiliza la aumentación de módulos para obtener los beneficios de TypeScript y fortalecer su base de código.

Asegúrese de que su configuración de TypeScript incluya los tipos autogenerados.

{  // ... Sus configuraciones de TypeScript existentes  "include": [    // ... Sus configuraciones de TypeScript existentes    ".intlayer/**/*.ts", // Incluir los tipos autogenerados  ],}

Configuración de Git

Se recomienda ignorar los archivos generados por Intlayer. Esto le permite evitar subirlos a su repositorio de Git.

Para hacer esto, puede agregar las siguientes instrucciones a su archivo .gitignore:

# Ignorar los archivos generados por Intlayer.intlayer

Extensión de VS Code

Para mejorar su experiencia de desarrollo con Intlayer, puede 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 las traducciones faltantes.
• Vistas previas en línea del contenido traducido.
• Acciones rápidas para crear y actualizar traducciones fácilmente.

Para obtener más detalles sobre cómo usar la extensión, consulte la documentación de la Extensión de Intlayer para VS Code.

Ir más allá

Para ir más allá, puede implementar el editor visual o externalizar su contenido utilizando el CMS.