Migrazione da next-intl a Intlayer

Perché migrare da next-intl a Intlayer?

Strategia di Migrazione

L'approccio raccomandato per le applicazioni esistenti è l'adattatore di compatibilità: Installa @intlayer/next-intl. Questo adattatore espone esattamente la stessa API di next-intl, ma delega tutto il lavoro di traduzione dietro le quinte a Intlayer.

Mantenere intatti i tuoi file esistenti useTranslations, getTranslations, NextIntlClientProvider e altri — l'unico cambiamento necessario è il percorso di importazione. Nessuna necessità di refactoring delle firme di chiamata, delle props o della struttura dei componenti.

Nel tempo, potrai opzionalmente migrare singoli file verso il formato più ricco .content.ts di Intlayer per sbloccare l'editor visivo, il CMS e lo scoping a livello di componente — ma questo passaggio è completamente opzionale e può essere fatto in modo incrementale.

Indice

Migrazione rapida

I seguenti passaggi rappresentano il minimo indispensabile per far funzionare la tua app next-intl esistente su Intlayer, senza modifiche al codice sorgente.

1. 1

   Installare le Dipendenze

   Installa i pacchetti principali di Intlayer e l'adattatore di compatibilità @intlayer/next-intl:

   bash

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   npm install intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-pluginnpx intlayer init

   Tieni installato next-intl — è ancora richiesto per il routing degli URL (createNavigation, createMiddleware, Link, redirect, usePathname, useRouter). L'adattatore di compatibilità non sostituisce il layer di routing.

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:

   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({
         // 'icu' corrisponde alla sintassi dei placeholder ICU di next-intl: {name}, {count, plural, ...}
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   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: 'icu' assicura che i placeholder ICU come {name} e {count, plural, one {# item} other {# items}} vengano analizzati correttamente.

   Vedi la Documentazione di Configurazione per un elenco completo delle opzioni disponibili.

3. 3

   Integrare il plugin Intlayer in Next.js

   Avvolgi la tua configurazione esistente in Next.js usando createNextIntlPlugin da @intlayer/next-intl/plugin. Questo wrapper applica withIntlayer e registra automaticamente l'alias next-intl → @intlayer/next-intl:

   next.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {
     /* Le tue opzioni di configurazione esistenti */
   };
   
   export default withIntlayer(nextConfig);

   createNextIntlPlugin() avvolge withIntlayer, rileva automaticamente Webpack o Turbopack, si collega al watch dei contenuti, compila i dizionari e, soprattutto, inietta alias per moduli, così che le chiamate esistenti a import … from 'next-intl' vengano reindirizzate trasparentemente a @intlayer/next-intl a tempo di build. L'entry point di routing next-intl/routing continuerà a puntare al pacchetto reale. Non sono necessarie modifiche ai file sorgente.

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

   getRequestConfig o loadMessages non sono più necessari. Con next-intl era necessario scrivere un file src/i18n.ts che caricasse i messaggi JSON per ogni richiesta usando getRequestConfig. Intlayer compila tutti i dizionari a tempo di build (build-time), eliminando il passaggio di caricamento a runtime. Puoi eliminare tranquillamente questo file (oppure mantenere solo le parti di routing se continui a usare createNavigation).

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

Chiavi di traduzione tipizzate — automaticamente. Una volta che Intlayer compila i tuoi dizionari, useTranslations e getTranslations sono tipizzati sul tuo contenuto effettivo. Le chiavi si autocompleteranno nel tuo IDE e i percorsi non validi restituiranno errori TypeScript al momento della build, senza alcuna configurazione extra richiesta.

tsx

Copia contenuto

Copiare il codice

Copiare il codice nella clipboard

// Componente Client — 'about' è una chiave registrata nel dizionarioconst t = useTranslations("about");t("counter.label"); // ✓ autocompletatot("does.not.exist"); // ✗ Errore TypeScript// Componente Serverconst t = await getTranslations("about");t("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 wrapper createNextIntlPlugin() gestisce già l'aliasing di next-intl → @intlayer/next-intl a livello di bundler. Se preferisci rendere la dipendenza esplicita nei tuoi file di codice (e usare invece il puro plugin withIntlayer), 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 { useTranslations } from 'next-intl'	import { useTranslations } from '@intlayer/next-intl'
   import { useLocale } from 'next-intl'	import { useLocale } from '@intlayer/next-intl'
   import { NextIntlClientProvider } from 'next-intl'	import { NextIntlClientProvider } from '@intlayer/next-intl'
   import { getTranslations } from 'next-intl/server'	import { getTranslations } from '@intlayer/next-intl/server'
   import { getLocale } from 'next-intl/server'	import { getLocale } from '@intlayer/next-intl/server'
   import { setLocale } from 'next-intl/server'	import { setLocale } from '@intlayer/next-intl/server'
   import { getMessages } from 'next-intl/server'	import { getMessages } from '@intlayer/next-intl/server'

   Mantieni sempre le importazioni di routing dal vero next-intl — l'adattatore di compatibilità non sostituisce il layer di routing URL:

   ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   // ✅ Mantieni queste dal vero 'next-intl'import { createNavigation } from "next-intl/routing";import { createMiddleware } from "next-intl/server";import { defineRouting } from "next-intl/routing";

   In alternativa, usare defineRouting da @intlayer/next-intl/routing permetterà l'unione automatica delle tue impostazioni locali in intlayer.config.ts.

2. 5

   Abilitare l'Automazione della Traduzione IA

   Opzionale

   Una volta configurato Intlayer, usa la CLI per inserire automaticamente le traduzioni mancanti usando l'LLM di tua scelta:

   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 OPENAI_API_KEY (o la chiave del tuo fornitore preferito) al tuo file .env ed estendi il tuo 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: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
     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 configurato @intlayer/next-intl, il seguente boilerplate standard di next-intl 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 about.content.ts proprio accanto al tuo about/page.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 — Guida completa all'installazione per Next.js: intlayerwithnextjs_16.md