Migrar de i18next a Intlayer

¿Por qué migrar de i18next a Intlayer?

Estrategias de migración

Existen dos estrategias complementarias para migrar de i18next a Intlayer:

1. Adaptador de compatibilidad (recomendado para aplicaciones existentes) — Instala @intlayer/i18next. Este paquete expone exactamente la misma API que i18next pero delega todo el trabajo de traducción a Intlayer en segundo plano. Mantienes tus llamadas existentes a i18next.t(), i18next.changeLanguage() y createInstance() — el único cambio es la ruta de importación y la inicialización.

2. Migración completa — Reemplaza gradualmente las APIs de i18next por herramientas nativas de Intlayer y colocaliza el contenido en archivos .content.ts.

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 i18next existente funcione sobre Intlayer sin cambios en el código.

1. 1

   Instalar Dependencias

   Instala los paquetes principales de Intlayer y el adaptador de compatibilidad:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npm install intlayer @intlayer/i18next @intlayer/sync-json-pluginnpx intlayer init

   Puedes mantener i18next instalado — el adaptador de compatibilidad lo usa como devDependency / peerDependency para los tipos de TypeScript.

2. 2

   Configurar Intlayer

   El comando intlayer init crea un archivo inicial intlayer.config.ts. Actualízalo para que coincida con tus idiomas (locales) 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 de 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

   Actualizar los alias del Bundler (Opcional)

   Si estás usando un empaquetador (Vite, Webpack, esbuild), puedes inyectar un alias de módulo para que import ... from 'i18next' se resuelva automáticamente a @intlayer/i18next. Esto elimina la necesidad de cambiar manualmente cualquier importación en tu base de código.

   Para Vite:

   vite.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { defineConfig } from "vite";
   import i18nextVitePlugin from "@intlayer/i18next/plugin";
   
   export default defineConfig({
     plugins: [i18nextVitePlugin()],
   });

   i18nextVitePlugin() envuelve el plugin intlayer() de vite-intlayer y añade el alias i18next → @intlayer/i18next por ti. Usar el plugin simple intlayer() de vite-intlayer compila los diccionarios pero no añade el alias — entonces tendrías que renombrar las importaciones a @intlayer/i18next manualmente (ver el siguiente paso).

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 i18next.

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

   Si prefieres hacer la dependencia explícita en tus archivos fuente, o si no usas un plugin de bundler para alias de importación, 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 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'

   Estos son reemplazos directos — no se requieren cambios en las firmas de llamada, argumentos o tipos de retorno.

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 el adaptador de compatibilidad esté en su lugar, el siguiente código repetitivo de 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 lógica y 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 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