Autore:
    Aymeric PINEAU
    Creazione:2024-12-06Ultimo aggiornamento:2026-06-23

    Traduci il tuo sito web Next.js 15 usando Intlayer | Internazionalizzazione (i18n)

    Tabella dei Contenuti

    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 agent skills, 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

    www.youtube.com
    ide.intlayer.org
    next-15-intlayer-template-xt83.vercel.app

    Vedi Application Template su GitHub.

    1. Installa le dipendenze

      Installa i pacchetti necessari usando npm:

      bash
      npx intlayer init --interactive
      il flag --interactive è opzionale. Usa intlayer-cli init se sei un agente IA.
      Questo comando rileverà il tuo ambiente e installerà i pacchetti richiesti. Ad esempio:
      bash
      npm install intlayer next-intlayer

      • intlayer

        Il pacchetto principale che fornisce strumenti di internazionalizzazione per la gestione della configurazione, la traduzione, la dichiarazione dei contenuti, la traspilazione 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 Next.js per integrare Intlayer con Webpack o Turbopack, così come middleware per rilevare la lingua preferita dall'utente, gestire i cookie e gestire il reindirizzamento degli URL.

    2. Configura il tuo progetto

      Here is the final structure that we will make:

      bash
      .
├── src
│   ├── app
│   │   ├── [locale]
│   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider
│   │   │   ├── page.content.ts
│   │   │   └── page.tsx
│   │   └── layout.tsx                # Root layout for style and global providers
│   ├── components
│   │   ├── client-component-example.content.ts
│   │   ├── ClientComponentExample.tsx
│   │   ├── LocaleSwitcher
│   │   │   ├── localeSwitcher.content.ts
│   │   │   └── LocaleSwitcher.tsx
│   │   ├── server-component-example.content.ts
│   │   └── ServerComponentExample.tsx
│   └── middleware.ts
├── intlayer.config.ts
├── next.config.ts
├── package.json
└── tsconfig.json
      If you don't want locale routing, intlayer can be used as a simple provider / hook. See this guide for more details.

      Crea un file di configurazione per configurare 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,
  },
};

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

    3. Integrare Intlayer nella tua configurazione Next.js

      Configura il tuo setup 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 li monitora in modalità sviluppo. Definisce le variabili d'ambiente di Intlayer all'interno degli ambienti Webpack o Turbopack. Inoltre, fornisce alias per ottimizzare le prestazioni e assicura la compatibilità con i componenti server.

      La funzione withIntlayer() è una funzione promise. Consente di preparare i dizionari intlayer prima che inizi la build. Se vuoi usarla con altri plugin, puoi attendere il risultato. Esempio:

      tsx
      const nextConfig = await withIntlayer(nextConfig);
const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);

export default nextConfigWithOtherPlugins;

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

      tsx
      const nextConfig = withIntlayerSync(nextConfig);
const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);

export default nextConfigWithOtherPlugins;

    4. Definire le Rotte Dinamiche per le Localizzazioni

      Rimuovi tutto da RootLayout e sostituiscilo con il seguente codice:

      src/app/layout.tsx
      import type { PropsWithChildren, FC } from "react";
import "./globals.css";

const RootLayout: FC<PropsWithChildren> = ({ children }) => children;

export default RootLayout;
      Mantenere il componente RootLayout vuoto permette di impostare gli attributi lang e dir al tag <html>.

      Per implementare il routing dinamico, fornisci il percorso per la localizzazione aggiungendo un nuovo layout nella tua directory [locale]:

      src/app/[locale]/layout.tsx
      import { type NextLayoutIntlayer } from "next-intlayer";
import { IntlayerProvider } from "next-intlayer/server";
import { Inter } from "next/font/google";
import { getHTMLTextDir } from "intlayer";

const inter = Inter({ subsets: ["latin"] });

const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
  const { locale } = await params;
  return (
    <html lang={locale} dir={getHTMLTextDir(locale)}>
      <body className={inter.className}>
        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
      </body>
    </html>
  );
};

export default LocaleLayout;
      Un singolo IntlayerProvider copre entrambi i lati dell'albero: fornisce il contesto server con scope di richiesta letto dagli hook server, e monta il provider client in modo che i componenti client ricevano la stessa locale.
      src/app/[locale]/layout.tsx
      import { type NextLayoutIntlayer, IntlayerClientProvider } from "next-intlayer";
import { Inter } from "next/font/google";
import { getHTMLTextDir } from "intlayer";

const inter = Inter({ subsets: ["latin"] });

const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
  const { locale } = await params;
  return (
    <html lang={locale} dir={getHTMLTextDir(locale)}>
      <body className={inter.className}>
        <IntlayerClientProvider locale={locale}>
          {children}
        </IntlayerClientProvider>
      </body>
    </html>
  );
};

export default LocaleLayout;
      Il segmento di percorso [locale] viene utilizzato per definire la localizzazione. Esempio: /en-US/about si riferirà a en-US e /fr/about a fr.
      A questo punto, incontrerai l'errore: Error: Missing <html> and <body> tags in the root layout.. Questo è previsto perché il file /app/page.tsx non è più utilizzato e può essere rimosso. Invece, il segmento di percorso [locale] attiverà la pagina /app/[locale]/page.tsx. Di conseguenza, le pagine saranno accessibili tramite percorsi come /en, /fr, /es nel tuo browser. Per impostare la localizzazione predefinita come pagina radice, fai riferimento alla configurazione del middleware nel passaggio 7.

      Quindi, implementa la funzione generateStaticParams nel Layout della tua applicazione.

      src/app/[locale]/layout.tsx
      tsx;
export { generateStaticParams } from "next-intlayer"; // Riga da inserire

const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
  /*... Resto del codice */
};

export default LocaleLayout;
      generateStaticParams garantisce che la tua applicazione precompili le pagine necessarie per tutte le localizzazioni, riducendo il calcolo a runtime e migliorando l'esperienza utente. Per maggiori dettagli, consulta la documentazione Next.js su generateStaticParams.
      Intlayer funziona con export const dynamic = 'force-static'; per garantire che le pagine siano pre-costruite per tutte le lingue.

    5. Dichiara il Tuo Contenuto

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

      src/app/[locale]/page.content.ts
      import { t, type Dictionary } from "intlayer";

const pageContent = {
  key: "page",
  content: {
    getStarted: {
      main: t({
        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 ovunque nella tua applicazione non appena sono incluse nella directory contentDir (di default, ./src). E devono corrispondere all'estensione del file di dichiarazione del contenuto (di default, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).
      Per maggiori dettagli, consulta la documentazione sulla dichiarazione del contenuto.

    6. Utilizza il Contenuto nel Tuo Codice

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

      src/app/[locale]/page.tsx
      import type { FC } from "react";
import { ClientComponentExample } from "@components/ClientComponentExample";
import { ServerComponentExample } from "@components/ServerComponentExample";
import { type NextPageIntlayer, useIntlayer } from "next-intlayer";

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

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

const Page: NextPageIntlayer = () => (
  <>
    <PageContent />
    <ServerComponentExample />

    <ClientComponentExample />
  </>
);

export default Page;
      • IntlayerProvider è montato una sola volta, nel layout locale. Fornisce la locale sia ai componenti server che ai componenti client, quindi le pagine non si avvolgono più su se stesse.
      • Gli hook server risolvono la locale in questo ordine: la locale passata al sito di chiamata, quindi il contesto server seeded dal provider, quindi la locale trasportata dalla richiesta (l'header x-intlayer-locale impostato dal proxy Intlayer, quindi il cookie locale). Questo ultimo passaggio è quello che mantiene il contenuto corretto su una navigazione lato client che ri-renderizza solo il segmento di pagina, dove il layout — e con esso il provider — non viene rieseguito.

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

      src/app/[locale]/page.tsx
      import type { FC } from "react";
import { ClientComponentExample } from "@components/ClientComponentExample";
import { ServerComponentExample } from "@components/ServerComponentExample";
import { type NextPageIntlayer } from "next-intlayer";
import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";

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

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

const Page: NextPageIntlayer = async ({ params }) => {
  const { locale } = await params;

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

      <ClientComponentExample />
    </IntlayerServerProvider>
  );
};

export default Page;
      • IntlayerClientProvider viene utilizzato per fornire la localizzazione ai componenti lato client. Può essere posizionato in qualsiasi componente genitore, incluso il layout. Tuttavia, si consiglia di posizionarlo in un layout perché Next.js condivide il codice del layout tra le pagine, rendendo il processo più efficiente. Utilizzando IntlayerClientProvider nel layout, si evita 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 localizzazione ai componenti server figli. 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 dati per richiesta (tramite il meccanismo React's cache), causando la ricreazione di ogni "contesto" per segmenti diversi dell'applicazione. Posizionare il provider in un layout condiviso romperebbe questa isolamento, impedendo la corretta propagazione dei valori del contesto server ai componenti server.
        Layout e pagina non possono condividere un contesto server comune perché il sistema di contesto server si basa su un archivio dati per richiesta (tramite il meccanismo React's cache), causando la ricreazione di ogni "contesto" per diversi segmenti dell'applicazione. Posizionare il provider in un layout condiviso romperebbe questa isolazione, impedendo la corretta propagazione dei valori del contesto server ai tuoi componenti server.
      src/components/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.tsx
      import type { FC } from "react";
import { useIntlayer } from "next-intlayer";

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

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};
      next-intlayer è il percorso di importazione isomorfo: la condizione di esportazione react-server fornisce ai componenti server l'implementazione ambient-locale, mentre i componenti client ottengono quella basata su context. La stessa chiamata funziona su entrambi i lati.
      src/components/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 del contenuto correlato

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};
      Se vuoi usare il tuo contenuto in un attributo di tipo string, come alt, title, href, aria-label, ecc., devi chiamare 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 Middleware per il Rilevamento della Locale

      Opzionale

      Configura il middleware per rilevare la locale preferita dall'utente:

      src/middleware.ts
      export { intlayerMiddleware as middleware } from "next-intlayer/middleware";

export const config = {
  matcher:
    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
};
      Il intlayerMiddleware viene utilizzato per rilevare la lingua preferita dall'utente e reindirizzarlo all'URL appropriato come specificato nella configurazione. Inoltre, consente di salvare la lingua preferita dell'utente in un cookie.
      A partire da Intlayer v9, questo middleware rispetta l'opzione routing.enableProxy (true per impostazione predefinita). Imposta routing.enableProxy: false nella tua configurazione per trasformarlo in un pass-through senza rimuovere questo file. Vedi le note sulla versione v9.
      Se hai bisogno di concatenare più middlewares insieme (ad esempio, intlayerMiddleware con autenticazione o middlewares personalizzati), Intlayer ora fornisce un helper chiamato multipleMiddlewares.
      ts
      import {
  multipleMiddlewares,
  intlayerMiddleware,
} from "next-intlayer/middleware";
import { customMiddleware } from "@utils/customMiddleware";

export const middleware = multipleMiddlewares([
  intlayerMiddleware,
  customMiddleware,
]);

    8. Internazionalizzazione dei tuoi metadata

      Opzionale

      Nel caso in cui desideri internazionalizzare i tuoi metadata, come il titolo della tua pagina, puoi utilizzare la funzione generateMetadata fornita da Next.js. All'interno, puoi recuperare il contenuto dalla funzione getIntlayer per tradurre i tuoi metadata.

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

const metadataContent = {
  key: "page-metadata",
  content: {
    title: t({
      en: "Create Next App",
      fr: "Créer une application Next.js",
      es: "Crear una aplicación Next.js",
    }),
    description: t({
      en: "Generated by create next app",
      fr: "Généré par create next app",
      es: "Generado por create next app",
    }),
  },
} satisfies Dictionary<Metadata>;

export default metadataContent;
      src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx
      import { getIntlayer, getMultilingualUrls } from "intlayer";
import type { Metadata } from "next";
import type { LocalPromiseParams } from "next-intlayer";

export const generateMetadata = async ({
  params,
}: LocalPromiseParams): Promise<Metadata> => {
  const { locale } = await params;

  const metadata = getIntlayer("page-metadata", locale);

  /**
   * Genera un oggetto contenente tutti gli URL per ogni locale.
   *
   * Esempio:
   * ```ts
   *  getMultilingualUrls('/about');
   *
   *  // Restituisce
   *  // {
   *  //   en: '/about',
   *  //   fr: '/fr/about',
   *  //   es: '/es/about',
   *  // }
   * ```
   */
  const multilingualUrls = getMultilingualUrls("/");
  const localizedUrl =
    multilingualUrls[locale as keyof typeof multilingualUrls];

  return {
    ...metadata,
    alternates: {
      canonical: localizedUrl,
      languages: { ...multilingualUrls, "x-default": "/" },
    },
    openGraph: {
      url: localizedUrl,
    },
  };
};

// ... Resto del codice
      Nota che la funzione getIntlayer importata da next-intlayer restituisce il tuo contenuto racchiuso in un IntlayerNode, permettendo l'integrazione con l'editor visuale. Al contrario, la funzione getIntlayer importata da intlayer restituisce il tuo contenuto direttamente senza proprietà aggiuntive.
      Scopri di più sull'ottimizzazione dei metadata nella documentazione ufficiale di Next.js.

    9. Internazionalizzazione del tuo sitemap.xml e robots.txt

      Opzionale

      Per internazionalizzare il tuo sitemap.xml e robots.txt, puoi utilizzare la funzione getMultilingualUrls fornita da Intlayer. Questa funzione ti permette di generare URL multilingue per la tua sitemap.

      src/app/sitemap.ts
      import { getMultilingualUrls } from "intlayer";
import type { MetadataRoute } from "next";

const sitemap = (): MetadataRoute.Sitemap => [
  {
    url: "https://example.com",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com"),
        "x-default": "https://example.com",
      },
    },
  },
  {
    url: "https://example.com/login",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/login"),
        "x-default": "https://example.com/login",
      },
    },
  },
  {
    url: "https://example.com/register",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/register"),
        "x-default": "https://example.com/register",
      },
    },
  },
];

export default sitemap;
      src/app/robots.ts
      import type { MetadataRoute } from "next";
import { getMultilingualUrls } from "intlayer";

const getAllMultilingualUrls = (urls: string[]) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);

// Funzione per ottenere tutte le URL multilingue da un array di URL
const robots = (): MetadataRoute.Robots => ({
  rules: {
    userAgent: "*",
    allow: ["/"], // Permetti l'accesso a tutte le pagine
    disallow: getAllMultilingualUrls(["/login", "/register"]), // Blocca l'accesso alle pagine di login e registrazione in tutte le lingue
  },
  host: "https://example.com",
  sitemap: `https://example.com/sitemap.xml`,
});

export default robots;
      Scopri di più sull'ottimizzazione della sitemap nella documentazione ufficiale di Next.js. Scopri di più sull'ottimizzazione del robots.txt nella documentazione ufficiale di Next.js.

    10. Cambiare la lingua del tuo contenuto

      Opzionale

      Per cambiare la lingua del tuo contenuto 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.tsx
      "use client";

import type { FC } from "react";
import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "next-intlayer";
import Link from "next/link";

export const LocaleSwitcher: FC = () => {
  const { locale, pathWithoutLocale, availableLocales, setLocale } =
    useLocale();

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <Link
            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
            hrefLang={localeItem}
            key={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={() => setLocale(localeItem)}
          >
            <span>
              {/* Località - es. FR */}
              {localeItem}
            </span>
            <span>
              {/* Lingua nella propria località - es. Français */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Lingua nella località corrente - es. Francés con località corrente impostata su Locales.SPANISH */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Lingua in inglese - es. French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </Link>
        ))}
      </div>
    </div>
  );
};
      Un modo alternativo è utilizzare la funzione setLocale fornita dal hook useLocale. Questa funzione non permetterà il prefetching della pagina e ricaricherà la pagina.
      In questo caso, senza reindirizzamento usando router.push, solo il codice lato server cambierà la locale del contenuto.
      src/components/LocaleSwitcher.tsx
      "use client";

import { useRouter } from "next/navigation";
import { useLocale } from "next-intlayer";
import { getLocalizedUrl } from "intlayer";

// ... Resto del codice

const router = useRouter();
const { setLocale } = useLocale({
  onLocaleChange: (locale) => {
    router.push(getLocalizedUrl(pathWithoutLocale, locale));
  },
});

return (
  <button onClick={() => setLocale(Locales.FRENCH)}>Cambia in francese</button>
);

      Riferimenti alla documentazione:

    11. Creare un Componente Link Localizzato

      Opzionale

      Per garantire che la navigazione della tua applicazione rispetti la lingua corrente, puoi creare un componente Link personalizzato. Questo componente aggiunge automaticamente il prefisso della lingua corrente agli URL interni. Ad esempio, quando un utente francofono clicca su un link alla pagina "About", viene reindirizzato a /fr/about invece che a /about.

      Questo comportamento è utile per diversi motivi:

      • SEO e esperienza utente: Gli URL localizzati aiutano i motori di ricerca a indicizzare correttamente le pagine specifiche per lingua e forniscono agli utenti contenuti nella loro lingua preferita.
      • Coerenza: Utilizzando un link localizzato in tutta l'applicazione, garantisci che la navigazione rimanga all'interno della lingua corrente, evitando cambiamenti di lingua imprevisti.
      • Manutenibilità: Centralizzare la logica di localizzazione in un unico componente semplifica la gestione degli URL, rendendo il tuo codice più facile da mantenere ed estendere man mano che la tua applicazione cresce.

      Di seguito è riportata l'implementazione di un componente Link localizzato in TypeScript:

      src/components/Link.tsx
      "use client";

import { getLocalizedUrl } from "intlayer";
import NextLink, { type LinkProps as NextLinkProps } from "next/link";
import { useLocale } from "next-intlayer";
import type { PropsWithChildren, FC } from "react";

/**
 * Funzione di utilità per verificare se un URL è esterno.
 * Se l'URL inizia con http:// o https://, è considerato esterno.
 */
export const checkIsExternalLink = (href?: string): boolean =>
  /^https?:\/\//.test(href ?? "");

/**
 * Un componente Link personalizzato che adatta l'attributo href in base alla locale corrente.
 * Per i link interni, utilizza `getLocalizedUrl` per aggiungere il prefisso della locale all'URL (es. /fr/about).
 * Questo garantisce che la navigazione rimanga all'interno dello stesso contesto di locale.
 */
export const Link: FC<PropsWithChildren<NextLinkProps>> = ({
  href,
  children,
  ...props
}) => {
  const { locale } = useLocale();
  const isExternalLink = checkIsExternalLink(href.toString());

  // Se il link è interno e viene fornito un href valido, ottieni l'URL localizzato.
  const hrefI18n: NextLinkProps["href"] =
    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;

  return (
    <NextLink href={hrefI18n} {...props}>
      {children}
    </NextLink>
  );
};

      Come Funziona

      • Rilevamento dei Link Esterni:
        La funzione di supporto checkIsExternalLink determina se un URL è esterno. I link esterni vengono lasciati invariati perché non necessitano di localizzazione.

      • Recupero della Locale Corrente:
        L'hook useLocale fornisce la locale corrente (ad esempio, fr per francese).

      • Localizzazione dell'URL:
        Per i link interni (cioè non esterni), getLocalizedUrl viene utilizzato per aggiungere automaticamente il prefisso della locale corrente all'URL. Ciò significa che se l'utente è in francese, passando /about come href verrà trasformato in /fr/about.

      • Restituzione del Link:
        Il componente restituisce un elemento <a> con l'URL localizzato, garantendo che la navigazione sia coerente con la locale.

      Integrando questo componente Link in tutta la tua applicazione, mantieni un'esperienza utente coerente e consapevole della lingua, beneficiando anche di un miglior SEO e usabilità.

    12. Ottimizza la dimensione del bundle

      Opzionale

      Se hai bisogno della locale attiva all'interno di una Server Action (ad es., per localizzare email o eseguire logica consapevole della 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();

  // Fai 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 middleware
      2. Se nessuna locale viene trovata negli header, cerca una locale memorizzata nei cookie
      3. Se nessun cookie viene trovato, tenta di rilevare la lingua preferita dell'utente dalle impostazioni del browser
      4. Come ultimo ricorso, ricade alla locale predefinita configurata dell'applicazione

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

    13. Ottimizza la dimensione del tuo bundle

      Opzionale

      Quando usi next-intlayer, i dizionari sono inclusi nel bundle per ogni pagina di default. Per ottimizzare la dimensione del bundle, Intlayer fornisce un plugin SWC opzionale che sostituisce in modo intelligente le chiamate a useIntlayer usando macro. Questo assicura che i dizionari siano 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à automaticamente e utilizzerà 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.

      14. Nota: Se imposti l'opzione come importMode: 'dynamic' o importMode: 'fetch' (nella configurazione dictionary), si affiderà a Suspense, quindi dovrai avvolgere le tue chiamate useIntlayer in un boundary Suspense. Ciò significa che non potrai usare useIntlayer direttamente al livello superiore del tuo componente Page / Layout. </Step>

    Monitorare le modifiche ai dizionari su Turbopack

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

    Questa limitazione si verifica perché Turbopack non può eseguire plugin webpack in parallelo per monitorare le modifiche nei file di contenuto. Per ovviare a questo problema, sarà necessario utilizzare il comando intlayer watch per eseguire contemporaneamente il server di sviluppo e l'osservatore di compilazione Intlayer.

    package.json
    {
  // ... Le tue configurazioni package.json esistenti
  "scripts": {
    // ... Le tue configurazioni di script esistenti
    "dev": "intlayer watch --with 'next dev --turbopack'",
  },
}

    Configurare TypeScript

    Intlayer utilizza l'augmentation dei moduli per sfruttare i vantaggi di TypeScript e rendere il tuo codice più robusto.

    Autocompletion

    Translation error

    Assicurati che la tua configurazione di TypeScript includa i tipi generati automaticamente.

    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 tuo 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:

    • Completamento automatico 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 utilizzare l'estensione, consulta la documentazione dell'estensione Intlayer per VS Code.

    Approfondimenti

    Per approfondire, puoi implementare l'editor visuale o esternalizzare i tuoi contenuti utilizzando il CMS.

    Next.js 14 e App RouterNext.js senza locale URL