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

Vedi il template dell'applicazione su GitHub.

Indice

Cos'è Intlayer?

Intlayer è una libreria innovativa e open-source per l'internazionalizzazione (i18n) progettata per semplificare il supporto multilingue nelle applicazioni web moderne. Intlayer si integra perfettamente con il più recente framework Next.js 16, incluso il potente App Router. È ottimizzata per funzionare con i Server Components per un rendering efficiente ed è pienamente compatibile con Turbopack.

Con Intlayer puoi:

• Gestire facilmente le traduzioni usando dizionari dichiarativi a livello di componente.
• Localizzare dinamicamente metadati, route e contenuti.
• Accedere alle traduzioni sia nei componenti client-side che server-side.
• Garantire il supporto a TypeScript con tipi generati automaticamente, migliorando l'autocompletamento e il rilevamento degli errori.
• Approfitta di funzionalità avanzate, come il rilevamento e il cambio dinamico della locale.

Intlayer è compatibile con Next.js 12, 13, 14 e 16. Se stai usando il Next.js Page Router, puoi fare riferimento a questa guida. Per Next.js 12, 13, 14 con App Router, consulta questa guida.

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

Passo 1: Installa le dipendenze

Installa i pacchetti necessari usando npm:

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.

Passo 2: Configura il tuo progetto

Ecco la struttura finale che creeremo:

.├── 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:

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.

Passo 3: Integra Intlayer nella tua configurazione Next.js

Configura il progetto Next.js per utilizzare Intlayer:

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:

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

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

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:

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

Passo 4: Definire le rotte locali dinamiche

Rimuovi tutto da RootLayout e sostituiscilo con il codice seguente:

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 ({  params,}: LocalPromiseParams): Promise<Metadata> => {  const { locale } = await params;  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;

Passo 5: Dichiarare i tuoi contenuti

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

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;

import { t, type Dictionary } from "intlayer";/** @type {import('intlayer').Dictionary<import('next').Metadata>} */const metadataContent = {  key: "metadata",  content: {    title: t({      it: "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"],      fr: ["innovation", "productivité", "flux de travail", "SaaS"],      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],    }),  },};export default metadataContent;

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,mjx,cjs,cjx}).

Per maggiori dettagli, consulta la documentazione sulle dichiarazioni di contenuto.

Passaggio 6: Utilizzare il contenuto nel codice

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

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.

"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>  );};

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:

<img src={content.image.src.value} alt={content.image.value} />

Per saperne di più sull'hook useIntlayer, consulta la documentazione.

(Opzionale) Passo 7: Configurare il proxy per il rilevamento della locale

Configura il proxy per rilevare la locale preferita dell'utente:

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.

import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

(Opzionale) Passo 8: Cambiare la lingua del tuo contenuto

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.

"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({    onChange: () => window.location.reload(),  });  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:

• useLocale hook
• getLocaleName hook
• getLocalizedUrl hook
• getHTMLTextDir hook
• hrefLang attribute
• lang attribute
• dir attribute
• aria-current attribute

(Opzionale) Passo 9: Ottenere la locale corrente nelle Server Actions

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:

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

(Opzionale) Passo 10: Ottimizza la dimensione del bundle

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:

npm install @intlayer/swc --save-devnpx intlayer init

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: 'live', 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.

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

Assicurati che la tua configurazione TypeScript includa i tipi autogenerati.

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

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