Migrazione da i18next a Intlayer

Perché migrare da i18next a Intlayer?

Strategie di migrazione

Ci sono due strategie complementari per migrare da i18next a Intlayer:

1. Adattatore di compatibilità (consigliato per app esistenti) — Installa @intlayer/i18next. Questo pacchetto espone esattamente la stessa API di i18next ma delega tutto il lavoro di traduzione dietro le quinte a Intlayer. Mantieni intatte le chiamate esistenti a i18next.t(), i18next.changeLanguage() e createInstance() — l'unica cosa che cambia è il percorso di importazione e l'inizializzazione.

2. Migrazione completa — Sostituisci gradualmente le API di i18next con strumenti Intlayer nativi e co-localizza i contenuti nei file .content.ts.

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 i18next esistente su Intlayer, senza modifiche al codice sorgente.

1. 1

   Installare le Dipendenze

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

   bash

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

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

   Puoi mantenere installato i18next in modo sicuro — l'adattatore di compatibilità lo usa come devDependency / peerDependency per i tipi TypeScript.

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

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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 i18next: {{name}}
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;

   source mappa un locale al percorso del suo file JSON. location dice al watcher di Intlayer quale cartella monitorare per le modifiche. L'opzione format: 'i18next' assicura che i placeholder come {{name}} vengano interpretati correttamente.

3. 3

   Aggiornare l'Alias del Bundler (Opzionale)

   Se stai utilizzando un bundler (Vite, Webpack, esbuild), puoi iniettare un alias di modulo in modo che import ... from 'i18next' venga risolto automaticamente in @intlayer/i18next. Ciò rimuove la necessità di modificare manualmente le importazioni nell'intera codebase.

   Per Vite:

   vite.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

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

   i18nextVitePlugin() avvolge il plugin intlayer() da vite-intlayer e aggiunge automaticamente l'alias i18next → @intlayer/i18next per te. 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/i18next (vedi passaggio successivo).

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

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

   Rinominare Esplicitamente le Importazioni (Opzionale)

   Opzionale

   Se preferisci rendere esplicita la dipendenza nei tuoi file sorgente o non usi un plugin di bundler per creare l'alias delle importazioni, puoi rinominare le importazioni manualmente:

   Mostra tutto il contenuto della tabella

   Mostra tutto il contenuto della tabella

   Apri la tabella in una finestra modale per visualizzare tutti i dati in modo chiaro

   Prima	Dopo
   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'

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

2. 5

   Abilitare l'Automazione della Traduzione IA

   Opzionale

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

   bash

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   # 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

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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;

   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 i18next può essere cancellato:

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 alla logica associata, 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 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:

{  // ... 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:

# Ignora i file generati da Intlayer.intlayer

Esplora oltre

• Editor Visivo — Gestisci le traduzioni in modo visivo nel tuo browser: Intlayer Visual Editor
• CMS — Esternalizza e gestisci i contenuti da remoto: Intlayer CMS
• Estensione VS Code — Ottieni il completamento automatico delle traduzioni e il rilevamento degli errori in tempo reale: Intlayer VS Code Extension
• Riferimento CLI — Elenco completo dei comandi CLI: Intlayer CLI