Getting Started internationalizing (i18n) with Intlayer and Next.js 14 with App Router

    Che cos'è Intlayer?

    Intlayer è una libreria innovativa e open-source di internazionalizzazione (i18n) progettata per semplificare il supporto multilingue nelle moderne applicazioni web. Intlayer si integra perfettamente con il più recente framework Next.js 14, incluso il suo potente App Router. È ottimizzato per funzionare con i Server Components per un rendering efficiente ed è completamente compatibile con Turbopack (da Next.js >= 15).

    Con Intlayer, puoi:

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

    Nota: Intlayer è compatibile con Next.js 12, 13, 14 e 15. Se stai utilizzando il Next.js Page Router, puoi fare riferimento a questa guida. Per Next.js 15 con o senza turbopack, fai riferimento a questa guida.

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

    Passo 1: Installa le dipendenze

    Installa i pacchetti necessari usando npm:

    bash
    npm install intlayer next-intlayer
    bash
    yarn add intlayer next-intlayer
    bash
    pnpm add intlayer next-intlayer

    Passo 2: Configura il tuo progetto

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

    typescript
    // intlayer.config.ts

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ITALIAN,
      Locales.FRENCH,
      Locales.SPANISH,
      // Le tue altre lingue
    ],
    defaultLocale: Locales.ITALIAN,
  },
};

export default config;

    Per vedere tutti i parametri disponibili, fai riferimento alla documentazione di configurazione qui.

    Passo 3: Integra Intlayer nella tua configurazione Next.js

    Configura il tuo setup di Next.js per usare Intlayer:

    typescript
    // next.config.mjs
import { withIntlayer } from "next-intlayer/server";

/** @type {import('next').NextConfig} */
const nextConfig = {};

export default withIntlayer(nextConfig);

    Passo 4: Configura Middleware per il rilevamento della lingua

    Imposta il middleware per rilevare la lingua preferita dell'utente:

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

export const config = {
  matcher: "/((?!api|static|.*\\..*|_next).*)",
};

    Passo 5: Definisci rotte dinamiche per le lingue

    Implementa il routing dinamico per contenuti localizzati:

    Cambia src/app/page.ts in src/app/[locale]/page.ts

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

    tsx
    // src/app/layout.tsx

import type { ReactNode } from "react";
import "./globals.css";

export { generateStaticParams } from "next-intlayer"; // Riga da inserire

const RootLayout = ({
  children,
}: Readonly<{
  children: ReactNode;
}>) => children;

export default RootLayout;

    Poi aggiungi un nuovo layout nella tua directory [locale]:

    tsx
    // src/app/[locale]/layout.tsx

import { type Next14LayoutIntlayer } from "next-intlayer";
import { Inter } from "next/font/google";
import { getHTMLTextDir } from "intlayer";

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

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

export default LocaleLayout;

    Passo 6: Dichiara i tuoi contenuti

    Crea e gestisci i tuoi dizionari di contenuti:

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

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

export default pageContent;

    Vedi come dichiarare i tuoi file di dichiarazione Intlayer.

    Passo 7: Utilizza il contenuto nel tuo codice

    Accedi ai tuoi dizionari di contenuto in tutta la tua applicazione:

    tsx
    // src/app/[locale]/page.ts

import { ClientComponentExample } from "@component/ClientComponentExample";
import { LocaleSwitcher } from "@component/LangSwitcherDropDown";
import { NestedServerComponentExample } from "@component/NestedServerComponentExample";
import { ServerComponentExample } from "@component/ServerComponentExample";
import { type Next14PageIntlayer, IntlayerClientProvider } from "next-intlayer";
import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";

const Page: Next14PageIntlayer = ({ params: { locale } }) => {
  const content = useIntlayer("page", locale);

  return (
    <>
      <p>
        {content.getStarted.main}
        <code>{content.getStarted.pageLink}</code>
      </p>
      {/**
       *   IntlayerServerProvider è usato per fornire la lingua ai figli server
       *   Non funziona se impostato nel layout
       */}
      <IntlayerServerProvider locale={locale}>
        <ServerComponentExample />
      </IntlayerServerProvider>
      {/**
       *   IntlayerClientProvider è usato per fornire la lingua ai figli client
       *   Può essere impostato in qualsiasi componente padre, incluso il layout
       */}
      <IntlayerClientProvider locale={locale}>
        <ClientComponentExample />
      </IntlayerClientProvider>
    </>
  );
};

export default Page;
    tsx
    // src/components/ClientComponentExample.tsx

"use client";

import { useIntlayer } from "next-intlayer";

export const ClientComponentExample = () => {
  const content = useIntlayer("client-component-example"); // Crea dichiarazioni di contenuto correlate

  return (
    <div>
      <h2>{content.title} </h2>
      <p>{content.content}</p>
    </div>
  );
};
    tsx
    // src/components/ServerComponentExample.tsx

import { useIntlayer } from "next-intlayer/server";

export const ServerComponentExample = () => {
  const content = useIntlayer("server-component-example"); // Crea dichiarazioni di contenuto correlate

  return (
    <div>
      <h2>{content.title} </h2>
      <p>{content.content}</p>
    </div>
  );
};

    Nota: Se desideri utilizzare il tuo contenuto in un attributo string, come alt, title, href, aria-label, ecc., devi chiamare il valore della funzione, come:

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

    Per un utilizzo più dettagliato di intlayer nei componenti Client o Server, vedi l'esempio di Next.js qui.

    (Facoltativo) Passo 8: Internazionalizzazione dei tuoi metadati

    Nel caso tu voglia internazionalizzare i tuoi metadati, come il titolo della tua pagina, puoi usare la funzione generateMetadata fornita da Next.js. All'interno della funzione usa la funzione getTranslationContent per tradurre i tuoi metadati.

    typescript
    // src/app/[locale]/layout.tsx o src/app/[locale]/page.tsx

import {
  type IConfigLocales,
  getTranslationContent,
  getMultilingualUrls,
} from "intlayer";
import type { Metadata } from "next";
import type { LocalParams } from "next-intlayer";

export const generateMetadata = ({
  params: { locale },
}: LocalParams): Metadata => {
  const t = <T>(content: IConfigLocales<T>) =>
    getTranslationContent(content, locale);

  /**
   * Genera un oggetto contenente tutti gli url per ciascuna lingua.
   *
   * Esempio:
   * ```ts
   *  getMultilingualUrls('/about');
   *
   *  // Restituisce
   *  // {
   *  //   it: '/about',
   *  //   fr: '/fr/about',
   *  //   es: '/es/about',
   *  // }
   * ```
   */
  const multilingualUrls = getMultilingualUrls("/");

  return {
    title: t<string>({
      it: "Il mio titolo",
      fr: "Mon titre",
      es: "Mi título",
    }),
    description: t({
      it: "La mia descrizione",
      fr: "Ma description",
      es: "Mi descripción",
    }),
    alternates: {
      canonical: url,
      languages: { ...multilingualUrls, "x-default": "/" },
    },
    openGraph: {
      url: multilingualUrls[locale],
    },
  };
};

// ... Restante del codice

    Scopri di più sull'ottimizzazione dei metadati nella documentazione ufficiale di Next.js.

    (Facoltativo) Passo 9: Internazionalizzazione del tuo sitemap.xml e robots.txt

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

    tsx
    // 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"),
    },
  },
  {
    url: "https://example.com/login",
    alternates: {
      languages: getMultilingualUrls("https://example.com/login"),
    },
  },
  {
    url: "https://example.com/register",
    alternates: {
      languages: getMultilingualUrls("https://example.com/register"),
    },
  },
];

export default sitemap;
    tsx
    // 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[]);

const robots = (): MetadataRoute.Robots => ({
  rules: {
    userAgent: "*",
    allow: ["/"],
    disallow: getAllMultilingualUrls(["/login", "/register"]),
  },
  host: "https://example.com",
  sitemap: `https://example.com/sitemap.xml`,
});

export default robots;

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

    (Facoltativo) Passo 10: Cambia la lingua del tuo contenuto

    Per cambiare la lingua del tuo contenuto, puoi usare la funzione setLocale fornita dal hook useLocale. Questa funzione ti consente di impostare la lingua dell'applicazione e aggiornare il contenuto di conseguenza.

    tsx
    import { Locales } from "intlayer";
import { useLocale } from "next-intlayer";

const MyComponent = () => {
  const { setLocale } = useLocale();

  return (
    <button onClick={() => setLocale(Locales.ITALIAN)}>Cambia lingua</button>
  );
};

    Configura TypeScript

    Intlayer utilizza l'augumentazione dei moduli per ottenere vantaggi da TypeScript e rendere il tuo codice più robusto.

    alt text

    alt text

    Assicurati che la tua configurazione TypeScript includa i tipi autogenerati.

    json5
    // tsconfig.json

{
  // la tua configurazione personalizzata
  include: [
    "src",
    "types", // <- Includi i tipi generati automaticamente
  ],
}

    Configurazione Git

    Si raccomanda di ignorare i file generati da Intlayer. Questo consente di evitare di impegnarli nel tuo repository Git.

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

    gitignore
    # Ignora i file generati da Intlayer
.intlayer

    Se hai un’idea per migliorare questa documentazione, non esitare a contribuire inviando una pull request su GitHub.

    Collegamento GitHub alla documentazione
    Intlayer con Next.jsNext.js e Page Router