Migrar de vue-i18n a Intlayer

¿Por qué migrar de vue-i18n a Intlayer?

Estrategias de migración

Existen dos estrategias complementarias para migrar de vue-i18n a Intlayer:

1. Adaptador de compatibilidad (recomendado para aplicaciones existentes) — Instala @intlayer/vue-i18n (para los componentes de Vue). Este paquete expone exactamente la misma API que vue-i18n pero delega todo el trabajo de traducción a Intlayer. Mantienes tus llamadas existentes a $t, useI18n(), y <i18n-t> — el único cambio es la ruta de importación y la inicialización.

2. Migración completa — Reemplaza gradualmente las APIs de vue-i18n por hooks nativos de Intlayer (useIntlayer) 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 vue-i18n existente funcione sobre Intlayer con cero cambios en el código de tus componentes.

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 vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-pluginnpx intlayer init

   Puedes mantener vue-i18n 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 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 vue-i18n: {name}
         format: "icu",
         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: 'icu' asegura que los marcadores de posición se analicen correctamente para vue-i18n.

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 un alias de módulo para que tus llamadas a import … from 'vue-i18n' sean redirigidas de forma transparente a @intlayer/vue-i18n 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 vue from "@vitejs/plugin-vue";
   import { vueI18nVitePlugin } from "@intlayer/vue-i18n/plugin";
   
   export default defineConfig({
     plugins: [vue(), vueI18nVitePlugin()],
   });

   vueI18nVitePlugin() envuelve el plugin intlayer() de vite-intlayer y añade el alias vue-i18n. Usar el plugin regular intlayer() de vite-intlayer compila los diccionarios pero no añade el alias — tendrías que renombrar las importaciones a @intlayer/vue-i18n manualmente (ver el Paso 4).

   Para Nuxt:

   Si estás usando @nuxtjs/i18n (integración con Nuxt), instala nuxt-intlayer y añádelo a tu nuxt.config.ts:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npm install nuxt-intlayer

   nuxt.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   export default defineNuxtConfig({
     modules: ["nuxt-intlayer"],
     // Puedes eliminar @nuxtjs/i18n de tus módulos
   });

   Ya no necesitas createI18n() 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 vue-i18n.

Claves de traducción tipadas — automáticas. Una vez que Intlayer compila tus diccionarios, useI18n queda tipado en relación a tu contenido real al pasar una opción namespace. 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.

ts

Copiar contenido

Copiar código

Copiar el código al portapapeles

// 'about' es una clave de diccionario registradaconst { t } = useI18n({ namespace: "about" });t("counter.label"); // ✓ autocompletadot("does.not.exist"); // ✗ Error de TypeScript

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 { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'
   import { createI18n } from 'vue-i18n'	import { createI18n } from '@intlayer/vue-i18n'

   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: "icu",
         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 vue-i18n 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.vue 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 Vue — Guía de configuración completa para Vue: intlayerwithvite+vue.md
• Intlayer con Nuxt — Guía de configuración completa para Nuxt: intlayerwithnuxt.md