Migrar de @nuxtjs/i18n a Intlayer

¿Por qué migrar de @nuxtjs/i18n a Intlayer?

Estrategias de migración

Dado que @nuxtjs/i18n está impulsado internamente por vue-i18n, existen dos estrategias complementarias para migrar hacia Intlayer:

1. Adaptador de compatibilidad (recomendado para aplicaciones existentes) — Instala @intlayer/vue-i18n y nuxt-intlayer. Esto 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 el enrutamiento de Nuxt sin cambios — el único cambio es la inicialización.

2. Migración completa — Reemplaza gradualmente las APIs de @nuxtjs/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 Nuxt 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 nuxt-intlayer @intlayer/vue-i18n @intlayer/sync-json-pluginnpx intlayer init

   Puedes mantener de forma segura @nuxtjs/i18n instalado durante la migración, aunque en breve lo eliminarás de tu configuración de Nuxt.

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 de vue-i18n: {name}
         format: "icu",
         source: ({ locale }) => `./locales/${locale}.json`,
         location: "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

   Actualizar la Configuración de Nuxt

   Reemplaza el módulo @nuxtjs/i18n por nuxt-intlayer en tu nuxt.config.ts. El plugin de Intlayer inyecta automáticamente los alias de módulo, lo que significa que tus llamadas a import { useI18n } from 'vue-i18n' se redirigen transparentemente a @intlayer/vue-i18n.

   nuxt.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   export default defineNuxtConfig({
     // Elimina '@nuxtjs/i18n'
     modules: ["nuxt-intlayer"],
   });

   Ya no necesitas definir los objetos de configuración i18n de Nuxt. Intlayer compila todos los diccionarios en tiempo de compilación, gestionando la detección del idioma, el enrutamiento y la carga de diccionarios de forma impecable.

Eso es todo para la migración rápida. Tu aplicación Nuxt ahora funciona sobre Intlayer mientras mantiene intactas todas las llamadas a $t y useI18n().

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'

   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 }) => `./locales/${locale}.json`,
         location: "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 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 Nuxt — Guía de configuración completa para Nuxt: intlayerwithnuxt.md
• Intlayer con Vue — Guía de configuración completa para Vue: intlayerwithvite+vue.md