Creation:2026-06-05Last update:2026-06-05

    Migrazione da vue-i18n a Intlayer

    Perché migrare da vue-i18n a Intlayer?

    Invece di caricare enormi file JSON nelle tue pagine, carica solo i contenuti necessari. Intlayer ti aiuta a ridurre la dimensione del bundle e delle pagine fino al 50%.

    Definire lo scope dei contenuti della tua applicazione facilita la manutenzione per applicazioni su larga scala. Puoi duplicare o eliminare un'intera cartella di funzionalità senza lo sforzo mentale di revisionare l'intero codice dei contenuti. Inoltre, Intlayer è completamente tipizzato per garantire la correttezza dei tuoi contenuti.

    Intlayer è anche la soluzione con lo sviluppo più attivo nell'ecosistema i18n — i problemi vengono risolti rapidamente, nuovi adattatori per framework vengono aggiunti regolarmente e l'API principale viene continuamente affinata sulla base di feedback reali in produzione.

    La co-localizzazione dei contenuti riduce il contesto necessario per i Modelli Linguistici di Grandi Dimensioni (LLM). Intlayer offre inoltre una suite di strumenti, come una CLI per testare le traduzioni mancanti, LSP, MCP, e Skill per Agenti, per rendere l'Esperienza Sviluppatore (DX) per gli agenti IA ancora più fluida.

    Utilizza l'automazione per tradurre nella tua pipeline CI/CD impiegando l'LLM di tua scelta al costo del tuo provider IA. Intlayer offre inoltre un compilatore per automatizzare l'estrazione dei contenuti, così come una piattaforma web per facilitare la traduzione in background.

    Collegare enormi file JSON ai componenti può portare a problemi di performance e reattività. Intlayer ottimizza il caricamento dei contenuti a tempo di build (build-time).

    Molto più di una semplice soluzione i18n, Intlayer fornisce un editor visivo self-hosted e un CMS completo per aiutarti a gestire i tuoi contenuti multilingue in tempo reale, rendendo fluida la collaborazione con traduttori, copywriter e altri membri del team. Il contenuto può essere archiviato localmente e/o in remoto.

    Strategie di migrazione

    Ci sono due strategie complementari per migrare da vue-i18n a Intlayer:

    1. Adattatore di compatibilità (consigliato per app esistenti) — Installa @intlayer/vue-i18n (per i componenti Vue). Questo pacchetto espone esattamente la stessa API di vue-i18n ma delega tutto il lavoro di traduzione a Intlayer. Mantieni intatte le chiamate esistenti a $t, useI18n() e <i18n-t> — le uniche cose che cambiano sono il percorso di importazione e l'inizializzazione.

    2. Migrazione completa — Sostituisci gradualmente le API di vue-i18n con l'hook nativo Intlayer (useIntlayer) e co-localizza i contenuti nei file .content.ts accanto ai tuoi componenti.

    Questa guida tratta prima la Strategia 1 (adattatore di compatibilità drop-in), e poi esamina la migrazione completa opzionale.

    Indice

    Migrazione rapida

    I seguenti passaggi rappresentano il minimo indispensabile per far funzionare la tua app vue-i18n esistente su Intlayer, senza modifiche al codice dei componenti.

    1. Installare le Dipendenze

      Installa i pacchetti principali di Intlayer e l'adattatore di compatibilità:

      bash
      npm install intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-pluginnpx intlayer init
      Puoi mantenere installato in modo sicuro vue-i18n — l'adattatore di compatibilità lo usa come devDependency / peerDependency per i tipi TypeScript.

    2. Configurare Intlayer

      Il comando intlayer init crea un file iniziale intlayer.config.ts. Aggiornalo affinché corrisponda alle tue lingue esistenti e indirizza il plugin syncJSON verso i tuoi file di messaggi:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";
import { syncJSON } from "@intlayer/sync-json-plugin";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Aggiungi qui tutti i tuoi locale esistenti
    ],
    defaultLocale: Locales.ENGLISH,
  },
  plugins: [
    syncJSON({
      // corrisponde alla sintassi dei placeholder di vue-i18n: {name}
      format: "icu",
      source: ({ locale }) => `./src/locales/${locale}.json`,
      location: "src/locales",
    }),
  ],
};

export default config;
      source mappa un locale al percorso del file JSON. location dice al watcher di Intlayer quale cartella monitorare per le modifiche. L'opzione format: 'icu' assicura che i placeholder di vue-i18n vengano interpretati correttamente.

    3. Aggiungere i plugin Intlayer al tuo bundler

      Avvolgi la configurazione del tuo bundler esistente con il plugin di compatibilità. Questo aggrega il plugin base di Intlayer, abilita l'osservazione dei contenuti e, soprattutto, inietta alias per moduli, così che le chiamate esistenti a import … from 'vue-i18n' vengano reindirizzate trasparentemente a @intlayer/vue-i18n a tempo di build. Non sono necessarie modifiche ai file sorgente.

      Per Vite:

      vite.config.ts
      import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { vueI18nVitePlugin } from "@intlayer/vue-i18n/plugin";

export default defineConfig({
  plugins: [vue(), vueI18nVitePlugin()],
});
      vueI18nVitePlugin() avvolge il plugin intlayer() da vite-intlayer e aggiunge automaticamente gli alias per vue-i18n. Usare il normale plugin intlayer() di vite-intlayer compila i dizionari ma non aggiunge l'alias — in tal caso dovrai rinominare manualmente le importazioni a @intlayer/vue-i18n (vedi passaggio 4).

      Per Nuxt:

      Se usi @nuxtjs/i18n (integrazione Nuxt), installa nuxt-intlayer e aggiungilo al tuo nuxt.config.ts:

      bash
      npm install nuxt-intlayer
      nuxt.config.ts
      export default defineNuxtConfig({
  modules: ["nuxt-intlayer"],
  // il modulo @nuxtjs/i18n può essere rimosso in modo sicuro
});
      createI18n() o il bootstrap manuale dei provider non è più necessario. Intlayer compila tutti i dizionari a tempo di build (build-time), eliminando il passaggio di caricamento a runtime. L'alias sul Provider gestisce l'inizializzazione.

    Questo è tutto per la migrazione rapida. La tua app ora è in esecuzione su Intlayer pur mantenendo intatte tutte le importazioni e le API di vue-i18n.

    Chiavi di traduzione tipizzate — automaticamente. Una volta che Intlayer ha compilato i tuoi dizionari, useI18n è tipizzato in base ai tuoi contenuti reali se gli passi l'opzione namespace. Le chiavi si autocompleteranno nel tuo IDE e percorsi invalidi produrranno errori TypeScript a tempo di compilazione — nessuna configurazione aggiuntiva necessaria.

    ts
    // 'about' è una chiave registrata nel dizionarioconst { t } = useI18n({ namespace: "about" });t("counter.label"); // ✓ autocompletatot("does.not.exist"); // ✗ Errore TypeScript

    Migrazione completa

    I passaggi seguenti sono opzionali e possono essere eseguiti in modo incrementale. Sbloccano l'intera gamma delle funzionalità di Intlayer: editor visivo, CMS, file di contenuto tipizzati, automazione della traduzione basata sull'IA e altro ancora.

    1. Rinominare Esplicitamente le Importazioni (Opzionale)

      Opzionale

      Il plugin di Intlayer gestisce già l'aliasing a livello di bundler. Se preferisci rendere esplicita la dipendenza nei tuoi file sorgente, puoi rinominare le importazioni manualmente:

      Prima Dopo
      import { useI18n } from 'vue-i18n' import { useI18n } from '@intlayer/vue-i18n'
      import { createI18n } from 'vue-i18n' import { createI18n } from '@intlayer/vue-i18n'

      Si tratta di sostituzioni dirette — non ci sono modifiche necessarie alle firme delle chiamate, agli argomenti o ai tipi di ritorno.

    2. Abilitare l'Automazione della Traduzione IA

      Opzionale

      Una volta configurato Intlayer, usa la CLI per inserire automaticamente le traduzioni mancanti:

      bash
      # Testa le traduzioni mancanti (aggiungi alla CI)npx intlayer test# Compila le traduzioni mancanti tramite IAnpx intlayer fill

      Aggiungi la configurazione dell'IA in intlayer.config.ts:

      intlayer.config.ts
      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;
      Controlla la Documentazione CLI Intlayer per esplorare tutte le opzioni disponibili.

    Cosa si può cancellare post-migrazione

    Una volta installato l'adattatore di compatibilità, il seguente boilerplate standard di vue-i18n può essere cancellato:

    File / Modello Perché non è più necessario
    Chiamate a createI18n() Intlayer Provider inizializza tutto automaticamente; non vi è alcun passaggio di caricamento a runtime.
    Registrazione del plugin Vue (app.use(i18n)) Il plugin Intlayer gestisce l'iniezione sotto il cofano.
    Bundle linguistici JSON (locales/*.json) I bundle JSON sono necessari solo se si continua a utilizzare il plugin syncJSON. Una volta migrati verso file .content.ts, puoi rimuovere la cartella JSON.

    Quando sei pronto per andare oltre, Intlayer scopre automaticamente ogni file .content.ts e .content.json ovunque nella tua codebase (per impostazione predefinita, in qualsiasi punto all'interno di ./src). Puoi posizionare un file my-component.content.ts proprio accanto al tuo MyComponent.vue, ed Intlayer lo rileverà a tempo di build senza alcuna configurazione aggiuntiva — nessuna importazione, nessuna registrazione, nessun file index centrale necessario. Questo rende la co-localizzazione delle traduzioni con pagine e componenti completamente fluida.

    Setup TypeScript

    Intlayer sfrutta l'estensione dei moduli (module augmentation) per offrire un completamento automatico (IntelliSense) TypeScript completo per le tue chiavi di traduzione. Assicurati che il tuo tsconfig.json includa i tipi generati automaticamente:

    tsconfig.json
    {  // ... Le tue configurazioni TypeScript esistenti  "include": [    // ... Le tue configurazioni TypeScript esistenti    ".intlayer/**/*.ts", // Includi i tipi auto-generati  ],}

    Configurazione Git

    Aggiungi la directory generata da Intlayer al tuo .gitignore:

    .gitignore
    # Ignora i file generati da Intlayer.intlayer

    Esplora oltre

    Perché Intlayer?