Migrar de react-i18next / i18next a Intlayer

¿Por qué migrar de react-i18next / i18next a Intlayer?

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.

1. 1

   Instalar Dependencias

   Instala los paquetes principales de Intlayer y los adaptadores de compatibilidad:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npm install intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-pluginnpx 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.

2. 2

   Configurar Intlayer

   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:

   intlayer.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   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.

3. 3

   Añadir el Plugin de Intlayer a tu Bundler

   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:

   vite.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   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

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   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):

   next.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   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

Copiar contenido

Copiar código

Copiar el código al portapapeles

// 'about' es una clave de diccionario registrada → t() solo acepta rutas válidasconst { t } = useTranslation("about");t("counter.label"); // ✓ autocompletadot("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.

1. 4

   Renombrar importaciones explícitamente (opcional)

   Opcional

   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:

   Mostrar todo el contenido de la tabla

   Mostrar todo el contenido de la tabla

   Abrir la tabla en una ventana flotante para ver todo el contenido claramente

   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):

   Mostrar todo el contenido de la tabla

   Mostrar todo el contenido de la tabla

   Abrir la tabla en una ventana flotante para ver todo el contenido claramente

   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'

2. 5

   Activar la Automatización de Traducción con IA

   Opcional

   Una vez que Intlayer esté configurado, utiliza su CLI para llenar automáticamente las traducciones faltantes:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   # Probar traducciones faltantes (agregar al CI)npx intlayer test# Llenar traducciones faltantes con IAnpx intlayer fill

   Añade la configuración de IA a intlayer.config.ts:

   intlayer.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   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 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:

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:

{  // ... 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:

# Ignorar los archivos generados por Intlayer.intlayer

Profundizar Más

• Editor Visual — Gestiona las traducciones visualmente en tu navegador: Editor Visual de Intlayer
• CMS — Externaliza y gestiona contenido de forma remota: Intlayer CMS
• 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
• Referencia del CLI — Lista completa de comandos CLI: Intlayer CLI
• Intlayer con React — Guía de configuración completa para React: intlayerwithvite+react.md
• Intlayer con Next.js — Guía de configuración completa para Next.js: intlayerwithnextjs_16.md