Migrazione da next-i18next a Intlayer

Perché migrare da next-i18next a Intlayer?

Strategie di migrazione

Dato che next-i18next avvolge sotto il cofano react-i18next e i18next, ci sono due strategie complementari per migrare a Intlayer:

1. Adattatore di compatibilità (consigliato per app esistenti) — Installa @intlayer/next-i18next, @intlayer/react-i18next e @intlayer/i18next. Questi pacchetti espongono esattamente la stessa API dei rispettivi originali ma delegano tutto il lavoro di traduzione a Intlayer. Mantieni intatte le chiamate esistenti a useTranslation, appWithTranslation, serverSideTranslations e il page routing di Next.js — l'unica modifica riguarda la configurazione e l'inizializzazione.

2. Migrazione completa — Sostituisci gradualmente le API di next-i18next con 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 Next.js Pages Router esistente su Intlayer, senza modifiche al codice di pagine e componenti.

1. 1

   Installare le Dipendenze

   Installa i pacchetti principali di Intlayer e gli adattatori di compatibilità:

   npm install intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   npx intlayer init

   pnpm add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   pnpm intlayer init

   yarn add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   yarn intlayer init

   bun add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   bun x intlayer init

   Puoi mantenere in modo sicuro l'installazione di next-i18next, react-i18next e i18next durante la migrazione finché non vengono configurati gli alias.

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 ai tuoi file di messaggi di next-i18next (tipicamente situati in public/locales):

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

   source mappa un locale e un namespace (key) al percorso del file JSON. location dice al watcher di Intlayer quale cartella monitorare per le modifiche. L'opzione format: 'i18next' assicura che i placeholder di next-i18next vengano interpretati correttamente.

3. 3

   Aggiornare la Configurazione Next.js

   Avvolgi la tua next.config.ts (o .js) esistente con createNextI18nPlugin da @intlayer/next-i18next/plugin. Questo wrapper applica withIntlayer e inietta gli alias per next-i18next / react-i18next / i18next → @intlayer/*, così che le chiamate esistenti a import { useTranslation } from 'next-i18next' vengano reindirizzate trasparentemente a tempo di build. Non sono necessarie modifiche ai file sorgente.

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   // L'importazione della configurazione i18n da next-i18next.config.js può essere rimossa
   // import { i18n } from './next-i18next.config';
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     // Intlayer gestisce nativamente il routing i18n di Next.js sotto il cofano,
     // quindi non è più necessario passare l'oggetto i18n qui.
   };
   
   export default withIntlayer(nextConfig);

   Il file next-i18next.config.js non è più necessario. 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à.

   Preferisci usare il puro plugin withIntlayer da next-intlayer/server? Questo compila i dizionari ma non aggiunge gli alias di next-i18next / react-i18next / i18next — dovresti quindi rinominare manualmente le importazioni a @intlayer/* (vedi Passaggio 4).

Questo è tutto per la migrazione rapida. La tua app Next.js ora è in esecuzione su Intlayer pur mantenendo intatte tutte le chiamate a useTranslation, serverSideTranslations e appWithTranslation.

Chiavi di traduzione tipizzate — automaticamente. Una volta che Intlayer ha compilato i tuoi dizionari, useTranslation e getFixedT sono tipizzati in base ai tuoi contenuti reali. Le chiavi si autocompleteranno nel tuo IDE e percorsi invalidi produrranno errori TypeScript a tempo di compilazione — nessuna configurazione aggiuntiva necessaria.

// Pages Router — 'about' è un namespace dizionario registrato
const { t } = useTranslation("about");
t("counter.label"); // ✓ autocompletato
t("does.not.exist"); // ✗ Errore TypeScript

// getStaticProps / getServerSideProps (istanza i18next)
const tAbout = i18n.getFixedT(null, "about");
tAbout("counter.label"); // ✓ tipizzato

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

   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:

   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 { serverSideTranslations } from 'next-i18next/serverSideTranslations'	import { serverSideTranslations } from '@intlayer/next-i18next'
   import { appWithTranslation } from 'next-i18next'	import { appWithTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'next-i18next'	import { useTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-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:

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

   pnpm intlayer test
   pnpm intlayer fill

   yarn intlayer test
   yarn intlayer fill

   bun x intlayer test
   bun x intlayer fill

   Aggiungi la configurazione dell'IA in 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: "i18next",
         source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/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 next-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 al tuo MyComponent.tsx, 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:

{
  // ... 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
• Intlayer con Next.js (Pages Router) — Guida completa all'installazione per Next.js: intlayerwithnextjspagerouter.md