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

    Migrazione da @nuxtjs/i18n a Intlayer

    Perché migrare da @nuxtjs/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

    Dato che @nuxtjs/i18n utilizza sotto il cofano vue-i18n, ci sono due strategie complementari per migrare a Intlayer:

    1. Adattatore di compatibilità (consigliato per app esistenti) — Installa @intlayer/vue-i18n e nuxt-intlayer. Questi espongono esattamente la stessa API di vue-i18n ma delegano tutto il lavoro di traduzione a Intlayer. Mantieni intatte le chiamate esistenti a $t, useI18n() e il routing Nuxt — l'unica cosa che cambia è l'inizializzazione.

    2. Migrazione completa — Sostituisci gradualmente le API di @nuxtjs/i18n con gli hook nativi 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 Nuxt 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 nuxt-intlayer @intlayer/vue-i18n @intlayer/sync-json-pluginnpx intlayer init
      Puoi mantenere in modo sicuro l'installazione di @nuxtjs/i18n durante la migrazione (lo rimuoveremo dalla configurazione di Nuxt a breve).

    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 ai 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 }) => `./locales/${locale}.json`,
      location: "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. Aggiornare la Configurazione Nuxt

      Sostituisci il modulo @nuxtjs/i18n con nuxt-intlayer in nuxt.config.ts. Il plugin Intlayer inietta automaticamente alias di moduli in modo che le tue importazioni esistenti di import { useI18n } from 'vue-i18n' vengano reindirizzate fluidamente a @intlayer/vue-i18n.

      nuxt.config.ts
      export default defineNuxtConfig({
  // Rimuovi '@nuxtjs/i18n'
  modules: ["nuxt-intlayer"],
});
      Non hai più bisogno di definire un oggetto di configurazione i18n per Nuxt. Intlayer compila tutti i dizionari a tempo di build (build-time), gestendo il rilevamento del locale, il routing e il caricamento dei dizionari senza soluzione di continuità.

    Questo è tutto per la migrazione rapida. La tua app Nuxt ora è in esecuzione su Intlayer pur mantenendo intatte tutte le chiamate a $t e useI18n().

    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'

      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 }) => `./locales/${locale}.json`,
      location: "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 @nuxtjs/i18n può essere cancellato:

    File / Modello Perché non è più necessario
    Configurazione i18n in nuxt.config.ts Intlayer gestisce internamente il routing, il caricamento dei dizionari e il locale di default.
    @nuxtjs/i18n nel package.json Sostituito completamente da nuxt-intlayer.
    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?