Creation:2026-01-10Last update:2026-05-31

    Come rendere multilingue (i18n) un'applicazione Next.js esistente (guida i18n 2026)

    www.youtube.com

    Vedi il Template dell'Applicazione su GitHub.

    Sommario

    Perché è difficile internazionalizzare un'applicazione esistente?

    Se hai mai provato ad aggiungere più lingue a un'app nata per una sola, conosci la fatica. Non è solo "difficile", è noioso. Devi passare al setaccio ogni file, scovare ogni stringa di testo e spostarla in file dizionario separati.

    Poi arriva la parte rischiosa: sostituire tutto quel testo con hook di codice senza rompere layout o logica. È il tipo di lavoro che blocca lo sviluppo di nuove funzionalità per settimane e sembra un refactoring infinito.

    Cos'è l'Intlayer Compiler?

    L'Intlayer Compiler è stato creato per saltare questo lavoro manuale. Invece di costringerti a estrarre le stringhe a mano, il compilatore lo fa per te. Scansiona il codice, trova il testo e usa l'IA per generare i dizionari dietro le quinte. Quindi, modifica il codice durante la build per iniettare gli hook i18n necessari. In sostanza, continui a scrivere l'app come se fosse monolingua, e il compilatore gestisce automaticamente la trasformazione multilingue.

    Doc Compilatore: /it/doc/compiler

    Limitazioni

    Dato che il compilatore esegue l'analisi e la trasformazione del codice (inserendo hook e generando dizionari) a tempo di compilazione, può rallentare il processo di build dell'applicazione.

    Per mitigare l'impatto durante lo sviluppo, puoi configurare il compilatore in modalità 'build-only' o disabilitarlo quando non necessario.

    Guida passo dopo passo per configurare Intlayer in un'applicazione Next.js

    1. Installare le dipendenze

      Installa i pacchetti necessari utilizzando npm:

      bash
      npm install intlayer next-intlayernpm install @intlayer/babel --save-devnpx intlayer init

      • intlayer

        Il pacchetto core che fornisce strumenti di internazionalizzazione per gestione della configurazione, traduzione, dichiarazione dei contenuti, transpilazione e comandi CLI.

      • next-intlayer

        Il pacchetto che integra Intlayer con Next.js. Fornisce context provider e hook per l'internazionalizzazione di Next.js. Include inoltre il plugin Next.js per integra web Intlayer con Webpack o Turbopack, oltre a un proxy per rilevare la lingua preferita dell'utente, gestire i cookie e i reindirizzamenti URL.

    2. Configurare il progetto

      Crea un file di configurazione per definire le lingue dell'applicazione:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.ITALIAN],    defaultLocale: Locales.ITALIAN,  },  routing: {    mode: "search-params",  },  compiler: {    /**     * Indica se il compilatore deve essere abilitato.     */    enabled: true,    /**     * Directory di output per i dizionari ottimizzati.     */    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,    /**     * Inserisci solo il contenuto nel file generato, senza chiave.     */    noMetadata: false,    /**     * Prefisso chiave dizionario     */    dictionaryKeyPrefix: "", // Remove base prefix    /**     * Indica se i componenti devono essere salvati dopo essere stati trasformati.     * In questo modo, il compilatore può essere eseguito una sola volta per trasformare l'app e poi rimosso.     */    saveComponents: false,  },  ai: {    provider: "openai",    model: "gpt-5-mini",    apiKey: process.env.OPEN_AI_API_KEY,    applicationContext: "Questa applicazione è un'app di mappe",  },};export default config;
      Nota: Assicurati di avere OPEN_AI_API_KEY impostata nelle variabili d'ambiente.
      Tramite questo file, puoi configurare URL localizzati, reindirizzamenti proxy, nomi dei cookie, posizione ed estensione delle dichiarazioni di contenuto, disabilitare i log di Intlayer e altro. Per l'elenco completo dei parametri, consulta la documentazione della configurazione.

    3. Integrare Intlayer nella configurazione Next.js

      Configura il setup Next.js per usare Intlayer:

      next.config.ts
      import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = {  /* opzioni di configurazione qui */};export default withIntlayer(nextConfig);
      Il plugin withIntlayer() integra Intlayer con Next.js. Assicura la creazione dei file di dichiarazione dei contenuti e li monitora in modalità sviluppo. Definisce le variabili d'ambiente Intlayer negli ambienti Webpack o Turbopack. Inoltre, fornisce alias per ottimizzare le prestazioni e garantisce compatibilità con i Server Components.

    4. Configurare Babel

      L'Intlayer Compiler richiede Babel per estrarre e ottimizzare i contenuti. Aggiorna il file babel.config.js (o babel.config.json) per includere i plugin Intlayer:

      babel.config.js
      const {  intlayerExtractBabelPlugin,  intlayerOptimizeBabelPlugin,  getExtractPluginOptions,  getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = {  presets: ["next/babel"],  plugins: [    [intlayerExtractBabelPlugin, getExtractPluginOptions()],    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],  ],};

    5. Rilevare la lingua nelle pagine

      Rimuovi tutto dal RootLayout e sostituiscilo con questo codice:

      src/app/layout.tsx
      import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";import { getHTMLTextDir, getIntlayer } from "intlayer";import { getLocale } from "next-intlayer/server";export { generateStaticParams } from "next-intlayer";export const generateMetadata = async (): Promise<Metadata> => {  const locale = await getLocale();  const { title, description, keywords } = getIntlayer("metadata", locale);  return {    title,    description,    keywords,  };};const RootLayout = async ({  children,}: Readonly<{  children: ReactNode;}>) => {  const locale = await getLocale();  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

    6. Compilare i componenti

      Con il compilatore abilitato, non devi più dichiarare manualmente i dizionari (come i file .content.ts).

      Puoi scrivere i contenuti direttamente nel codice come stringhe. Intlayer analizzerà il codice, genererà le traduzioni usando l'IA e sostituirà le stringhe con i contenuti localizzati durante la compilazione.

      Scrivi i componenti con stringhe "hardcoded" nella lingua predefinita. Il compilatore farà il resto.

      Esempio di come apparirà la pagina:

      src/app/page.tsx
      import type { FC } from "react";import { IntlayerServerProvider } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {return (  <>    <p>Inizia a modificare</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}
      • IntlayerClientProvider serve per fornire la lingua ai componenti client.

      • IntlayerServerProvider serve per fornire la lingua ai componenti server figli.

        Layout and page cannot share a common server context because the server context system is based on a per-request data store (via React's cache mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.

    7. Completare le traduzioni mancanti

      Opzionale

      Intlayer offre uno strumento CLI per completare le traduzioni mancanti. Usa il comando intlayer per testare e riempire le lacune nel codice.

      bash
      npx intlayer test         # Verifica traduzioni mancanti
      bash
      npx intlayer fill         # Completa traduzioni mancanti
      Per maggiori dettagli, fare riferimento alla documentazione CLI

    8. Configurare il Proxy per il rilevamento lingua

      Opzionale

      Imposta un proxy per rilevare la lingua preferita dall'utente:

      src/proxy.ts
      export { intlayerProxy as proxy } from "next-intlayer/proxy";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};
      intlayerProxy rileva la lingua dell'utente e reindirizza all'URL corretto basandosi sulla configurazione. Consente anche di salvare la preferenza in un cookie.

    9. Cambiare la lingua del contenuto

      Opzionale

      Per cambiare lingua in Next.js, si consiglia di usare il componente Link per reindirizzare alla pagina localizzata. Link permette il prefetching, evitando il ricaricamento completo della pagina.

      src/components/localeSwitcher/LocaleSwitcher.tsx
      "use client";import type { FC } from "react";import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";import { useLocale } from "next-intlayer";export const LocaleSwitcher: FC = () => {  const { locale, availableLocales, setLocale } = useLocale();  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocale(localeItem)}          >            <span>              {/* Lingua - es. IT */}              {localeItem}            </span>            <span>              {/* Lingua nel proprio Locale - es. Italiano */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Lingua nel locale corrente - es. Francés se il locale è Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Lingua in inglese - es. Italian */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};
      In alternativa, puoi usare setLocale dall'hook useLocale, ma non permetterà il prefetching. Consulta la documentazione di useLocale.

    10. Ottimizzare il bundle

      Opzionale

      Con next-intlayer, i dizionari sono inclusi di default in ogni pagina. Per ottimizzare il bundle, Intlayer offre un plugin SWC opzionale che sostituisce le chiamate useIntlayer con macro. Così i dizionari appaiono solo dove servono davvero.

      Installa @intlayer/swc. next-intlayer lo rileverà e userà automaticamente:

      bash
      npm install @intlayer/swc --save-dev
      Nota: Solo per Next.js 13+.
      Nota: Non installato di default perché i plugin SWC in Next.js sono ancora sperimentali.

      Nota: Se usi importMode: 'dynamic' o 'fetch', dovrai avvolgere le chiamate useIntlayer in un Suspense. Non potrai usarlo al livello superiore di Pagina / Layout.

    11. Estrarre il contenuto dei tuoi componenti

      Opzionale

      Se hai una base di codice esistente, trasformare migliaia di file può richiedere molto tempo.

      Per facilitare questo processo, Intlayer propone un compilatore / estrattore per trasformare i tuoi componenti ed estrarre il contenuto.

      Per configurarlo, puoi aggiungere una sezione compiler nel tuo file intlayer.config.ts:

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Resto della tua configurazione
  compiler: {
    /**
     * Indica se il compilatore deve essere abilitato.
     */
    enabled: true,

    /**
     * Definisce il percorso dei file di output
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Indica se i componenti devono essere salvati dopo essere stati trasformati. In questo modo, il compilatore può essere eseguito solo una volta per trasformare l'app e poi rimosso.
     */
    saveComponents: false,

    /**
     * Prefisso chiave dizionario
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      Esegui l'estrattore per trasformare i tuoi componenti ed estrarre il contenuto

      bash
      npx intlayer extract

    Configurare TypeScript

    Intlayer usa la module augmentation per potenziare TypeScript.

    Autocompletamento

    Errore traduzione

    Assicurati che tsconfig.json includa i tipi generati.

    tsconfig.json
    {  // ... Config TS esistenti  "include": [    // ... Config TS esistenti    ".intlayer/**/*.ts", // Includi i tipi autogenerati  ],}

    Configurazione Git

    Ignora i file generati da Intlayer per evitare di includerli nel repository.

    Nel file .gitignore:

    .gitignore
    # Ignora i file generati da Intlayer.intlayer

    Estensione VS Code

    Per una migliore esperienza, installa l'Estensione ufficiale Intlayer per VS Code.

    Installa dal Marketplace

    Caratteristiche:

    • Autocompletamento chiavi.
    • Rilevamento errori in tempo reale.
    • Anteprime inline.
    • Azioni rapide per creare/aggiornare traduzioni.

    Consulta la documentazione dell'estensione per i dettagli.

    Vai oltre

    Puoi implementare l' editor visuale o esternalizzare i contenuti col CMS.

    Next.js e Page Router
    Tanstack Start