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

    Traduci il tuo sito Next.js 16 (senza [locale] nel percorso della pagina) usando Intlayer | Internazionalizzazione (i18n)

    www.youtube.com

    Vedi il template dell'applicazione su GitHub.

    Indice

    Perché Intlayer rispetto alle alternative?

    Rispetto alle soluzioni principali come next-intl o i18next, Intlayer è una soluzione dotata di ottimizzazioni integrate come:

    Intlayer è ottimizzato per funzionare con Componenti server per un rendering efficiente ed è completamente compatibile con Turbopack. Non blocca il rendering statico e offre middleware e tutte le funzionalità necessarie per scalare l'internazionalizzazione (i18n).

    Intlayer è compatibile con Next.js 12, 13, 14, 15 e 16. Se stai utilizzando Next.js Pages Router, puoi fare riferimento a questa guida. Il routing per locale è utile per SEO, dimensioni del pacchetto e prestazioni. Se non ti serve, puoi fare riferimento a questa guida. Per Next.js 12, 13, 14 e 15 con App Router, fare riferimento a questa guida.

    Invece di caricare enormi file JSON nelle tue pagine, carica solo il contenuto necessario. Intlayer aiuta a ridurre le dimensioni del bundle e della pagina fino al 50%.

    L'ambito del contenuto dell'applicazione facilita la manutenzione per applicazioni su larga scala. Puoi duplicare o eliminare una singola cartella di funzionalità senza l'onere mentale di rivedere l'intera codebase dei contenuti. Inoltre, Intlayer è completamente tipizzato (fully typed) per garantire l'accuratezza dei tuoi contenuti.

    La co-localizzazione dei contenuti riduce il contesto necessario dai Large Language Models (LLM). Intlayer viene fornito anche con una suite di strumenti, come una CLI per verificare le traduzioni mancanti,LSP, MCP e capacità dell'agente, per rendere l'esperienza dello sviluppatore (DX) ancora più fluida per gli agenti IA.

    Utilizza l'automazione per tradurre nella tua pipeline CI/CD utilizzando il LLM di tua scelta al costo del tuo provider di intelligenza artificiale. Intlayer offre anche un compilatore per automatizzare l'estrazione dei contenuti, nonché una piattaforma web per aiutare a tradurre in background.

    La connessione di enormi file JSON ai componenti può portare a problemi di prestazioni e reattività. Intlayer ottimizza il caricamento dei contenuti in fase di compilazione.

    Più di una semplice soluzione i18n, Intlayer fornisce un editor visivo self-hosted e un CMS completo per aiutarti gestisci i tuoi contenuti multilingue in tempo reale, semplificando la collaborazione con traduttori, copywriter e altri membri del team. I contenuti possono essere archiviati localmente e/o in remoto.

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

    1. Installa le dipendenze

      Installa i pacchetti necessari usando npm:

      bash
      npm install intlayer next-intlayernpx intlayer init

      • intlayer

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

      • next-intlayer

      Il pacchetto che integra Intlayer con Next.js. Fornisce provider di contesto e hook per l'internazionalizzazione in Next.js. Inoltre include il plugin per Next.js per integrare Intlayer con Webpack o Turbopack, oltre a un proxy per rilevare la locale preferita dall'utente, gestire i cookie e gestire il reindirizzamento degli URL.

    2. Configura il tuo progetto

      Ecco la struttura finale che creeremo:

      bash
      .├── src│   ├── app│   │   ├── layout.tsx│   │   ├── page.content.ts│   │   └── page.tsx│   ├── components│   │   ├── clientComponentExample│   │   │   ├── client-component-example.content.ts│   │   │   └── ClientComponentExample.tsx│   │   ├── localeSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   └── serverComponentExample│   │       ├── server-component-example.content.ts│   │       └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json
      Se non vuoi il routing delle localizzazioni, intlayer può essere utilizzato come semplice provider / hook. Consulta questa guida per maggiori dettagli.

      Crea un file di configurazione per impostare le lingue della tua applicazione:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Le tue altre localizzazioni
    ],
    defaultLocale: Locales.ENGLISH,
  },
  routing: {
    mode: "search-params", // oppure `no-prefix` - Utile per il rilevamento nel middleware
  },
};

export default config;
      Attraverso questo file di configurazione, puoi impostare URL localizzati, reindirizzamenti proxy, nomi dei cookie, la posizione e l'estensione delle tue dichiarazioni di contenuto, disabilitare i log di Intlayer nella console e altro. Per l'elenco completo dei parametri disponibili, fai riferimento alla documentazione di configurazione.

    3. Integra Intlayer nella tua configurazione Next.js

      Configura il progetto Next.js per utilizzare 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 Next.js withIntlayer() viene utilizzato per integrare Intlayer con Next.js. Garantisce la generazione dei file di dichiarazione dei contenuti e il loro monitoraggio in modalità di sviluppo. Definisce le variabili d'ambiente di Intlayer negli ambienti Webpack o Turbopack. Inoltre fornisce alias per ottimizzare le prestazioni e assicura la compatibilità con i server components.

      La funzione withIntlayer() è una funzione che restituisce una Promise. Permette di preparare i dizionari di Intlayer prima dell'inizio della build. Se vuoi usarla con altri plugin, puoi metterla in await. Esempio:

      ts
      const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

      Se vuoi usarlo in modo sincrono, puoi usare la funzione withIntlayerSync(). Esempio:

      ts
      const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

      Intlayer rileva automaticamente se il tuo progetto utilizza webpack o Turbopack in base ai flag della riga di comando --webpack, --turbo o --turbopack, oltre che alla tua versione corrente di Next.js.

      Dal momento che next>=16, se stai usando Rspack, devi forzare esplicitamente Intlayer a usare la configurazione webpack disabilitando Turbopack:

      ts
      withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));

    4. Definire le rotte locali dinamiche

      Rimuovi tutto da RootLayout e sostituiscilo con il codice seguente:

      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;

    5. Dichiarare i tuoi contenuti

      Crea e gestisci le tue dichiarazioni di contenuto per memorizzare le traduzioni:

      src/app/metadata.content.ts
      import { t, type Dictionary } from "intlayer";
import { Metadata } from "next";

const metadataContent = {
  key: "metadata",
  content: {
    title: t({
      it: "Il Titolo del mio Progetto",
      en: "My Project Title",
      fr: "Le Titre de mon Projet",
      es: "El Título de mi Proyecto",
    }),

    description: t({
      it: "Scopri la nostra piattaforma innovativa progettata per semplificare il tuo flusso di lavoro e aumentare la produttività.",
      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",
      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",
      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",
    }),

    keywords: t({
      it: ["innovazione", "produttività", "flusso di lavoro", "SaaS"],
      en: ["innovation", "productivity", "workflow", "SaaS"],
      it: ["innovazione", "produttività", "flusso di lavoro", "SaaS"],
      fr: ["innovation", "productivité", "flux de travail", "SaaS"],
      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],
    }),
  },
} as Dictionary<Metadata>;

export default metadataContent;
      src/app/page.content.ts
      import { t, type Dictionary } from "intlayer";

const pageContent = {
  key: "page",
  content: {
    getStarted: {
      main: t({
        it: "Inizia modificando",
        en: "Get started by editing",
        fr: "Commencez par éditer",
        es: "Comience por editar",
      }),
      pageLink: "src/app/page.tsx",
    },
  },
} satisfies Dictionary;

export default pageContent;
      Le dichiarazioni di contenuto possono essere definite in qualsiasi punto della tua applicazione non appena vengono incluse nella directory contentDir (per impostazione predefinita, ./src). E devono corrispondere all'estensione dei file di dichiarazione del contenuto (per impostazione predefinita, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).
      Per maggiori dettagli, consulta la documentazione sulle dichiarazioni di contenuto.

    6. Utilizzare il contenuto nel codice

      Accedi ai tuoi dizionari di contenuto in tutta l'applicazione:

      src/app/page.tsx
      import type { FC } from "react";
import { ClientComponentExample } from "@components/clientComponentExample/ClientComponentExample";
import { ServerComponentExample } from "@components/serverComponentExample/ServerComponentExample";
import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
import { NextPage } from "next";
import { getLocale } from "next-intlayer/server";
import { headers, cookies } from "next/headers";

const PageContent: FC = () => {
  const content = useIntlayer("page");

  return (
    <>
      <p>{content.getStarted.main}</p>
      <code>{content.getStarted.pageLink}</code>
    </>
  );
};

const Page: NextPage = async () => {
  const locale = await getLocale();

  return (
    <IntlayerServerProvider locale={locale}>
      <PageContent />
      <ServerComponentExample />
      <ClientComponentExample />
    </IntlayerServerProvider>
  );
};

export default Page;
      • IntlayerClientProvider è usato per fornire la locale ai componenti lato client. Può essere posizionato in qualsiasi componente genitore, incluso il layout. Tuttavia, posizionarlo in un layout è consigliato perché Next.js condivide il codice del layout tra le pagine, rendendolo più efficiente. Usando IntlayerClientProvider nel layout, eviti di reinizializzarlo per ogni pagina, migliorando le prestazioni e mantenendo un contesto di localizzazione coerente in tutta l'applicazione.

      • IntlayerServerProvider viene utilizzato per fornire la locale ai componenti figli lato server. Non può essere impostato nel layout.

        Layout e pagina non possono condividere un contesto server comune perché il sistema di contesto server si basa su un archivio di dati per richiesta (tramite il meccanismo della cache di React), causando la ricreazione di ogni "context" per segmenti diversi dell'applicazione. Posizionare il provider in un layout condiviso romperebbe questo isolamento, impedendo la corretta propagazione dei valori del contesto server ai tuoi componenti server.
      src/components/clientComponentExample/ClientComponentExample.tsx
      "use client";

import type { FC } from "react";
import { useIntlayer } from "next-intlayer";

export const ClientComponentExample: FC = () => {
  const content = useIntlayer("client-component-example"); // Crea la dichiarazione del contenuto correlato

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};
      src/components/serverComponentExample/ServerComponentExample.tsx
      import type { FC } from "react";
import { useIntlayer } from "next-intlayer/server";

export const ServerComponentExample: FC = () => {
  const content = useIntlayer("server-component-example"); // Crea la dichiarazione di contenuto correlata

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};
      Se vuoi utilizzare il tuo contenuto in un attributo di tipo string, come alt, title, href, aria-label, ecc., devi invocare il valore della funzione, ad esempio:
      html
      <img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />
      Per saperne di più sull'hook useIntlayer, consulta la documentazione.

    7. Configurare il proxy per il rilevamento della locale

      Opzionale

      Configura il proxy per rilevare la locale preferita dell'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).*)",
};
      Il intlayerProxy viene usato per rilevare la locale preferita dell'utente e reindirizzarlo all'URL appropriato come specificato nella configurazione. Inoltre, permette di salvare la locale preferita dell'utente in un cookie.
      Se hai bisogno di concatenare più proxy insieme (per esempio, intlayerProxy con autenticazione o proxy personalizzati), Intlayer fornisce ora un helper chiamato multipleProxies.
      ts
      import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

    8. Cambiare la lingua del tuo contenuto

      Opzionale

      Per cambiare la lingua dei tuoi contenuti in Next.js, il modo consigliato è utilizzare il componente Link per reindirizzare gli utenti alla pagina localizzata appropriata. Il componente Link abilita il prefetching della pagina, il che aiuta a evitare un 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>
              {/* Codice locale - es. FR */}
              {localeItem}
            </span>
            <span>
              {/* Nome della lingua nella propria lingua - es. Français */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Nome della lingua nella lingua corrente - es. Francés con la locale corrente impostata su Locales.SPANISH */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Lingua in inglese - es. Francese */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </button>
        ))}
      </div>
    </div>
  );
};
      Un modo alternativo è usare la funzione setLocale fornita dall'hook useLocale. Questa funzione non permette il prefetch della pagina. Vedi la documentazione dell'hook useLocale per maggiori dettagli.

      Riferimenti alla documentazione:

    9. Ottenere la locale corrente nelle Server Actions

      Opzionale

      Se hai bisogno della locale attiva all'interno di una Server Action (es., per localizzare email o eseguire logica dipendente dalla locale), chiama getLocale da next-intlayer/server:

      src/app/actions/getLocale.ts
      "use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // Esegui qualcosa con la locale};

      La funzione getLocale segue una strategia a cascata per determinare la locale dell'utente:

      1. Per prima cosa, controlla gli header della richiesta per un valore di locale che potrebbe essere stato impostato dal proxy
      2. Se non viene trovata una locale negli header, cerca una locale memorizzata nei cookie
      3. Se non viene trovato alcun cookie, tenta di rilevare la lingua preferita dell'utente dalle impostazioni del browser
      4. Come ultima risorsa, ricorre alla locale predefinita configurata nell'applicazione

      Questo garantisce che venga selezionata la locale più appropriata in base al contesto disponibile.

    10. Ottimizza la dimensione del bundle

      Opzionale

      Quando usi next-intlayer, i dizionari vengono inclusi nel bundle per ogni pagina per impostazione predefinita. Per ottimizzare la dimensione del bundle, Intlayer fornisce un plugin SWC opzionale che sostituisce in modo intelligente le chiamate a useIntlayer usando delle macro. Questo assicura che i dizionari vengano inclusi solo nei bundle delle pagine che li utilizzano effettivamente.

      Per abilitare questa ottimizzazione, installa il pacchetto @intlayer/swc. Una volta installato, next-intlayer rileverà e userà automaticamente il plugin:

      bash
      npm install @intlayer/swc --save-dev
      Nota: Questa ottimizzazione è disponibile solo per Next.js 13 e versioni successive.
      Nota: Questo pacchetto non è installato di default perché i plugin SWC sono ancora sperimentali su Next.js. Potrebbe cambiare in futuro.

      Nota: Se imposti l'opzione come importMode: 'dynamic' o importMode: 'fetch' (in the dictionary configuration), si baserà su Suspense, quindi dovrai avvolgere le chiamate a useIntlayer in un boundary Suspense. Ciò significa che non potrai utilizzare useIntlayer direttamente a livello superiore del tuo componente Page/Layout.

    Monitorare le modifiche dei dizionari con Turbopack

    Quando usi Turbopack come server di sviluppo con il comando next dev, le modifiche ai dizionari non verranno rilevate automaticamente per impostazione predefinita.

    Questa limitazione si verifica perché Turbopack non può eseguire in parallelo i plugin di webpack per monitorare le modifiche nei file di contenuto. Per aggirare questo problema, dovrai usare il comando intlayer watch per eseguire simultaneamente sia il server di sviluppo che il watcher di build di Intlayer.

    package.json
    {  // ... Le tue configurazioni esistenti di package.json  "scripts": {    // ... Le tue configurazioni esistenti degli script    "dev": "intlayer watch --with 'next dev'",  },}
    Se stai usando next-intlayer@<=6.x.x, devi mantenere il flag --turbopack affinché l'applicazione Next.js 16 funzioni correttamente con Turbopack. Raccomandiamo di usare next-intlayer@>=7.x.x per evitare questa limitazione.

    Configurare TypeScript

    Intlayer usa il module augmentation per ottenere i benefici di TypeScript e rendere la tua codebase più solida.

    Completamento automatico

    Errore di traduzione

    Assicurati che la tua configurazione TypeScript includa i tipi autogenerati.

    tsconfig.json
    {  // ... Le tue configurazioni TypeScript esistenti  "include": [    // ... Le tue configurazioni TypeScript esistenti    ".intlayer/**/*.ts", // Includi i tipi generati automaticamente  ],}

    Configurazione Git

    Si consiglia di ignorare i file generati da Intlayer. Questo ti permette di evitare di committarli nel tuo repository Git.

    Per farlo, puoi aggiungere le seguenti istruzioni al file .gitignore:

    .gitignore
    # Ignora i file generati da Intlayer.intlayer

    Estensione VS Code

    Per migliorare la tua esperienza di sviluppo con Intlayer, puoi installare l'estensione ufficiale Intlayer per VS Code.

    Installa dal Marketplace di VS Code

    Questa estensione offre:

    • Autocompletion per le chiavi di traduzione.
    • Rilevamento errori in tempo reale per traduzioni mancanti.
    • Anteprime inline del contenuto tradotto.
    • Azioni rapide per creare e aggiornare facilmente le traduzioni.

    Per maggiori dettagli su come usare l'estensione, consulta la documentazione dell'Intlayer VS Code Extension.

    Approfondisci

    Per approfondire, puoi implementare il visual editor o esternalizzare il tuo contenuto usando il CMS.

    Next.js 15
    Next.js e Page Router