--- createdAt: 2026-06-05 updatedAt: 2026-06-05 title: "Migrar de react-i18next / i18next a Intlayer | Internacionalización (i18n)" description: "Aprende cómo migrar tu aplicación React o Next.js de react-i18next o i18next a Intlayer — paso a paso, sin romper tu código existente. Utiliza los adaptadores de compatibilidad @intlayer/react-i18next y @intlayer/i18next para una transición sin interrupciones." keywords: - react-i18next - i18next - intlayer - migración - internacionalización - i18n - Next.js - React - JavaScript slugs: - doc - migration - react-i18next history: - version: 8.13.0 date: 2026-06-05 changes: "Init history" --- # Migrar de react-i18next / i18next a Intlayer ## ¿Por qué migrar de react-i18next / i18next a Intlayer? En lugar de cargar archivos JSON masivos en tus páginas, carga solo el contenido necesario. Intlayer ayuda a **reducir el tamaño de tu bundle y tus páginas hasta en un 50 %**. Establecer un alcance al contenido de tu aplicación **facilita el mantenimiento** para aplicaciones a gran escala. Puedes duplicar o eliminar una carpeta de función completa sin la carga mental de revisar todo el código de tu contenido. Además, Intlayer está **completamente tipado** para asegurar la precisión de tu contenido. Intlayer es también la solución con el **desarrollo más activo** en el ecosistema i18n — los problemas se solucionan rápidamente, nuevos adaptadores de framework se añaden regularmente y la API principal se refina continuamente basándose en retroalimentación real de producción. Colocalizar el contenido **reduce el contexto necesario** para los Grandes Modelos de Lenguaje (LLM). Intlayer también incluye una suite de herramientas, como un **CLI** para probar traducciones faltantes, **[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/mcp_server.md)** y **[habilidades de agente](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/agent_skills.md)**, para que la experiencia del desarrollador (DX) sea aún más fluida para los agentes de IA. Usa la automatización para traducir en tu flujo de CI/CD utilizando el LLM de tu elección al costo de tu proveedor de IA. Intlayer también ofrece un **compilador** para automatizar la extracción de contenido, así como una [plataforma web](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md) para ayudar a **traducir en segundo plano**. Conectar archivos JSON masivos a los componentes puede llevar a problemas de rendimiento y reactividad. Intlayer optimiza la carga de tu contenido en tiempo de compilación. Más que una simple solución de i18n, Intlayer proporciona un **[editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_visual_editor.md)** autohospedado y un **[CMS completo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md)** para ayudarte a gestionar tu contenido multilingüe en **tiempo real**, haciendo la colaboración con traductores, redactores y otros miembros del equipo fluida. El contenido se puede almacenar local y/o remotamente. --- ## Estrategias de migración Existen dos estrategias complementarias para migrar de `react-i18next` / `i18next` a Intlayer: 1. **Adaptador de compatibilidad (recomendado para aplicaciones existentes)** — Instala `@intlayer/react-i18next` (para componentes React) y/o `@intlayer/i18next` (para la instancia core de `i18n`). Estos paquetes exponen **exactamente la misma API** que `react-i18next` / `i18next` pero delegan todo el trabajo de traducción a Intlayer. Mantienes tus llamadas existentes a `useTranslation`, `Trans`, `withTranslation`, `i18next.t()` — el único cambio es la ruta de importación. 2. **Migración completa** — Reemplaza gradualmente las APIs de `react-i18next` por hooks nativos de Intlayer (`useIntlayer`, `IntlayerProvider`) y colocaliza el contenido en archivos `.content.ts` junto a tus componentes. Esta guía cubre primero la **Estrategia 1** (adaptador de compatibilidad de fácil uso), y luego revisa la migración completa opcional. --- ## Tabla de Contenidos --- ## Migración rápida Los siguientes pasos son el mínimo requerido para que tu aplicación `react-i18next` existente funcione sobre Intlayer con cero cambios en el código. Instala los paquetes principales de Intlayer y los adaptadores de compatibilidad: ```bash packageManager="npm" npm install intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin npx intlayer init ``` ```bash packageManager="pnpm" pnpm add intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin pnpm intlayer init ``` ```bash packageManager="yarn" yarn add intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin yarn intlayer init ``` ```bash packageManager="bun" bun add intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin bun x intlayer init ``` > Puedes mantener `react-i18next` e `i18next` instalados — los adaptadores de compatibilidad los usan como `devDependencies` / `peerDependencies` opcionales para los tipos de TypeScript. No necesitas cambiar ningún peer de tu `package.json`. El comando `intlayer init` crea un archivo inicial `intlayer.config.ts`. Actualízalo para que coincida con tus idiomas existentes y apunta el plugin `syncJSON` a tus archivos de mensajes: ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]} import { Locales, type IntlayerConfig } from "intlayer"; import { syncJSON } from "@intlayer/sync-json-plugin"; const config: IntlayerConfig = { internationalization: { locales: [ Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, // Agrega todos tus idiomas existentes aquí ], defaultLocale: Locales.ENGLISH, }, plugins: [ syncJSON({ // coincide con la sintaxis de marcador de posición react-i18next: {{name}} format: "i18next", source: ({ locale }) => `./src/locales/${locale}.json`, location: "src/locales", }), ], }; export default config; ``` > **`source`** asigna un idioma a su ruta de archivo JSON. **`location`** le indica al observador de Intlayer qué carpeta monitorear en busca de cambios. La opción `format: 'i18next'` asegura que los marcadores de posición como `{{name}}` se analicen correctamente. Envuelve tu configuración de empaquetador existente con el plugin de compatibilidad. Este compone el plugin principal de Intlayer, vincula el monitoreo de contenido, y — críticamente — **inyecta alias de módulos** para que tus llamadas existentes a `import … from 'react-i18next'` (y `'i18next'`) sean redirigidas transparentemente a `@intlayer/react-i18next` / `@intlayer/i18next` en tiempo de compilación. No se requieren cambios en los archivos fuente. **Para Vite:** ```typescript fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]} import { defineConfig } from "vite"; import react from "@vitejs/plugin-react"; import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin"; export default defineConfig({ plugins: [react(), reactI18nextVitePlugin()], }); ``` > `reactI18nextVitePlugin()` envuelve el plugin `intlayer()` de `vite-intlayer` y añade los alias de `react-i18next` / `i18next`. Usar el plugin regular `intlayer()` de `vite-intlayer` compila los diccionarios pero **no** añade los alias — tendrías que renombrar las importaciones a `@intlayer/*` manualmente (ver el Paso 4). **Para Next.js:** Si utilizas `next-i18next` (integración con Pages Router), instala `@intlayer/next-i18next` y `next-intlayer`: ```bash packageManager="npm" npm install @intlayer/next-i18next next-intlayer ``` Luego, agrega el plugin de compatibilidad a tu `next.config.ts` (inyecta los alias `next-i18next` / `react-i18next` / `i18next`): ```typescript fileName="next.config.ts" codeFormat={["typescript", "esm", "commonjs"]} import type { NextConfig } from "next"; import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin"; const withIntlayer = createNextI18nPlugin(); const nextConfig: NextConfig = { /* tus opciones */ }; export default withIntlayer(nextConfig); ``` > **Ya no necesitas `i18next.init()` ni configuración manual del provider.** Intlayer compila todos los diccionarios **en tiempo de compilación**, por lo que no hay paso de carga en tiempo de ejecución. El proveedor aliasado maneja la inicialización por ti. Eso es todo para la migración rápida. Tu aplicación ahora funciona sobre Intlayer mientras mantiene intactas todas las importaciones y APIs de `react-i18next`. > **Claves de traducción tipadas — automáticas.** Una vez que Intlayer compila tus diccionarios, `useTranslation` y `getFixedT` quedan tipados en relación a tu contenido real. Las claves se autocompletan en tu IDE y las rutas inválidas provocan errores de TypeScript en tiempo de compilación — sin configuraciones adicionales requeridas. > > ```tsx > // 'about' es una clave de diccionario registrada → t() solo acepta rutas válidas > const { t } = useTranslation("about"); > t("counter.label"); // ✓ autocompletado > t("does.not.exist"); // ✗ Error de TypeScript > > // Lado del servidor (instancia i18next) > const tAbout = i18n.getFixedT(null, "about"); > tAbout("counter.label"); // ✓ tipado > ``` --- ## Migración completa Los pasos a continuación son opcionales y pueden hacerse incrementalmente. Desbloquean todas las funcionalidades de Intlayer: editor visual, CMS, archivos de contenido tipados, automatización de traducción con IA y más. Los plugins de Intlayer ya manejan los alias a nivel del empaquetador. Si prefieres hacer la dependencia explícita en tus archivos de origen, puedes renombrar las importaciones manualmente: | Antes | Después | | -------------------------------------------------- | ------------------------------------------------------------ | | `import { useTranslation } from 'react-i18next'` | `import { useTranslation } from '@intlayer/react-i18next'` | | `import { Trans } from 'react-i18next'` | `import { Trans } from '@intlayer/react-i18next'` | | `import { withTranslation } from 'react-i18next'` | `import { withTranslation } from '@intlayer/react-i18next'` | | `import { I18nextProvider } from 'react-i18next'` | `import { I18nextProvider } from '@intlayer/react-i18next'` | | `import { initReactI18next } from 'react-i18next'` | `import { initReactI18next } from '@intlayer/react-i18next'` | | `import i18next from 'i18next'` | `import i18next from '@intlayer/i18next'` | | `import { createInstance } from 'i18next'` | `import { createInstance } from '@intlayer/i18next'` | | `import { t } from 'i18next'` | `import { t } from '@intlayer/i18next'` | Para Next.js (`next-i18next`): | Antes | Después | | ------------------------------------------------------------------------------ | ----------------------------------------------------------------- | | `import { serverSideTranslations } from 'next-i18next/serverSideTranslations'` | `import { serverSideTranslations } from '@intlayer/next-i18next'` | | `import { appWithTranslation } from 'next-i18next'` | `import { appWithTranslation } from '@intlayer/next-i18next'` | | `import { useTranslation } from 'next-i18next'` | `import { useTranslation } from '@intlayer/next-i18next'` | Una vez que Intlayer esté configurado, utiliza su CLI para llenar automáticamente las traducciones faltantes: ```bash packageManager="npm" # Probar traducciones faltantes (agregar al CI) npx intlayer test # Llenar traducciones faltantes con IA npx intlayer fill ``` ```bash packageManager="pnpm" pnpm intlayer test pnpm intlayer fill ``` ```bash packageManager="yarn" yarn intlayer test yarn intlayer fill ``` ```bash packageManager="bun" bun x intlayer test bun x intlayer fill ``` Añade la configuración de IA a `intlayer.config.ts`: ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]} import { Locales, type IntlayerConfig } from "intlayer"; import { syncJSON } from "@intlayer/sync-json-plugin"; const config: IntlayerConfig = { internationalization: { locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], defaultLocale: Locales.ENGLISH, }, plugins: [ syncJSON({ format: "i18next", source: ({ locale }) => `./src/locales/${locale}.json`, location: "src/locales", }), ], ai: { apiKey: process.env.OPENAI_API_KEY, // provider: "openai", // default // model: "gpt-4o-mini", // default }, }; export default config; ``` > Consulta la [documentación de CLI de Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/index.md) para ver todas las opciones disponibles. --- ## Qué puedes eliminar tras la migración Una vez que los adaptadores de compatibilidad estén en su lugar, el siguiente código repetitivo de `react-i18next` / `i18next` se puede eliminar: | Archivo / patrón | Por qué ya no es necesario | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Llamadas a `i18next.init()` | El proveedor de Intlayer inicializa todo automáticamente; no hay paso de carga en tiempo de ejecución. | | `I18nextProvider` / `initReactI18next` | El plugin de Intlayer maneja la inyección de manera interna. | | Bundles de idiomas JSON (`locales/*.json`) | Los bundles JSON solo son necesarios si aún utilizas el plugin `syncJSON`. Una vez que migres a archivos `.content.ts`, puedes borrar la carpeta JSON. | Cuando estés listo para ir más allá, Intlayer **descubre automáticamente todos los archivos `.content.ts` y `.content.json` en cualquier lugar de tu código base** (por defecto, en cualquier lugar dentro de `./src`). Puedes colocar un archivo `my-component.content.ts` directamente junto a tu `MyComponent.tsx` e Intlayer lo tomará al momento de compilación sin configuración adicional — sin importaciones, sin registro, sin necesidad de un archivo índice centralizado. Esto hace que la co-localización de traducciones con páginas y componentes sea completamente fluida. --- ## Configurar TypeScript Intlayer usa el aumento de módulos para ofrecer autocompletado completo de TypeScript para tus claves de traducción. Asegúrate de que tu `tsconfig.json` incluya los tipos generados automáticamente: ```json5 fileName="tsconfig.json" { // ... Tus configuraciones de TypeScript existentes "include": [ // ... Tus configuraciones de TypeScript existentes ".intlayer/**/*.ts", // Incluir los tipos generados automáticamente ], } ``` --- ## Configuración de Git Añade el directorio generado por Intlayer a tu `.gitignore`: ```plaintext fileName=".gitignore" # Ignorar los archivos generados por Intlayer .intlayer ``` --- ## Profundizar Más - **Editor Visual** — Gestiona las traducciones visualmente en tu navegador: [Editor Visual de Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_visual_editor.md) - **CMS** — Externaliza y gestiona contenido de forma remota: [Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md) - **Extensión de VS Code** — Obtén autocompletado y detección de errores de traducción en tiempo real: [Extensión de VS Code de Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/vs_code_extension.md) - **Referencia del CLI** — Lista completa de comandos CLI: [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/index.md) - **Intlayer con React** — Guía de configuración completa para React: [intlayer_with_vite+react.md](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_with_vite+react.md) - **Intlayer con Next.js** — Guía de configuración completa para Next.js: [intlayer_with_nextjs_16.md](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_with_nextjs_16.md)