Documentation

Ambiente

Intlayer con Next.js

Iniziare l'internazionalizzazione (i18n) con Intlayer e Next.js 15 App Router

Cos'è Intlayer?

Intlayer è una libreria open-source innovativa di internazionalizzazione (i18n) progettata per semplificare il supporto multilingue nelle moderne applicazioni web. Intlayer si integra senza soluzione di continuità con il più recente framework Next.js 15, incluso il potente App Router. È ottimizzato per lavorare con i Server Components per un rendering efficiente ed è completamente compatibile con Turbopack.

Con Intlayer, puoi:

Gestire facilmente le traduzioni utilizzando dizionari dichiarativi a livello di componente.
Localizzare dinamicamente i metadati, le rotte e il contenuto.
Accedere alle traduzioni sia nei componenti lato client sia in quelli lato server.
Assicurare 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 della lingua dinamico.

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

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

Passo 1: Installa le dipendenze

Installa i pacchetti necessari utilizzando npm:

bash

1npm install intlayer next-intlayer

bash

1yarn add intlayer next-intlayer

bash

1pnpm add intlayer next-intlayer

Passo 2: Configura il tuo progetto

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

typescript

1// intlayer.config.ts
2
3import { Locales, type IntlayerConfig } from "intlayer";
4
5const config: IntlayerConfig = {
6  internationalization: {
7    locales: [
8      Locales.ENGLISH,
9      Locales.FRENCH,
10      Locales.SPANISH,
11      // Le tue altre lingue
12    ],
13    defaultLocale: Locales.ENGLISH,
14  },
15};
16
17export 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 Next.js per utilizzare Intlayer:

typescript

1// next.config.mjs
2import { withIntlayer } from "next-intlayer/server";
3
4/** @type {import('next').NextConfig} */
5const nextConfig = {};
6
7export default withIntlayer(nextConfig);

Passo 4: Configura il Middleware per il rilevamento della lingua

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

typescript

1// src/middleware.ts
2export { intlayerMiddleware as middleware } from "next-intlayer/middleware";
3
4export const config = {
5  matcher: "/((?!api|static|.*\\..*|_next).*)",
6};

Passo 5: Definisci le route dinamiche per le lingue

Implementa il routing dinamico per il contenuto localizzato:

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

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

tsx

1// src/app/layout.tsx
2
3import type { ReactNode } from "react";
4import "./globals.css";
5
6export { generateStaticParams } from "next-intlayer"; // Riga da inserire
7
8const RootLayout = ({
9  children,
10}: Readonly<{
11  children: ReactNode;
12}>) => children;
13
14export default RootLayout;

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

tsx

1// src/app/[locale]/layout.tsx
2
3import { type NextLayoutIntlayer } from "next-intlayer";
4import { Inter } from "next/font/google";
5import { getHTMLTextDir } from "intlayer";
6
7const inter = Inter({ subsets: ["latin"] });
8
9const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
10  const { locale } = await params;
11  return (
12    <html lang={locale} dir={getHTMLTextDir(locale)}>
13      <body className={inter.className}>{children}</body>
14    </html>
15  );
16};
17
18export default LocaleLayout;

Passo 6: Dichiara il tuo contenuto

Crea e gestisci i tuoi dizionari di contenuto:

tsx

1// src/app/[locale]/page.content.ts
2import { t, type DeclarationContent } from "intlayer";
3
4const pageContent = {
5  key: "page",
6  content: {
7    getStarted: {
8      main: t({
9        en: "Get started by editing",
10        fr: "Commencez par éditer",
11        es: "Comience por editar",
12      }),
13      pageLink: "src/app/page.tsx",
14    },
15  },
16} satisfies DeclarationContent;
17
18export default pageContent;

Guarda come dichiarare i tuoi file di dichiarazione Intlayer.

Passo 7: Utilizza il contenuto nel tuo codice

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

tsx

1// src/app/[locale]/page.ts
2
3import { ClientComponentExample } from "@component/ClientComponentExample";
4import { LocaleSwitcher } from "@component/LangSwitcherDropDown";
5import { NestedServerComponentExample } from "@component/NestedServerComponentExample";
6import { ServerComponentExample } from "@component/ServerComponentExample";
7import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
8import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
9
10const PageContent = () => {
11  const { title, content } = useIntlayer("page");
12
13  return (
14    <>
15      <p>{content.getStarted.main}</p>
16      <code>{content.getStarted.pageLink}</code>
17    </>
18  );
19};
20
21const Page: NextPageIntlayer = async ({ params }) => {
22  const { locale } = await params;
23
24  return (
25    <>
26      {/**
27       *   IntlayerServerProvider è utilizzato per fornire la lingua ai figli server
28       *   Non funziona se impostato nel layout
29       */}
30      <IntlayerServerProvider locale={locale}>
31        <PageContent />
32        <ServerComponentExample />
33      </IntlayerServerProvider>
34      {/**
35       *   IntlayerClientProvider è utilizzato per fornire la lingua ai figli client
36       *   Può essere impostato in qualsiasi componente padre, incluso il layout
37       */}
38      <IntlayerClientProvider locale={locale}>
39        <ClientComponentExample />
40      </IntlayerClientProvider>
41    </>
42  );
43};
44
45export default Page;

tsx

1// src/components/ClientComponentExample.tsx
2
3"use client";
4
5import { useIntlayer } from "next-intlayer";
6
7export const ClientComponentExample = () => {
8  const content = useIntlayer("client-component-example"); // Crea la dichiarazione di contenuto correlata
9
10  return (
11    <div>
12      <h2>{content.title} </h2>
13      <p>{content.content}</p>
14    </div>
15  );
16};

tsx

1// src/components/ServerComponentExample.tsx
2
3import { useIntlayer } from "next-intlayer/server";
4
5export const ServerComponentExample = () => {
6  const content = useIntlayer("server-component-example"); // Crea la dichiarazione di contenuto correlata
7
8  return (
9    <div>
10      <h2>{content.title} </h2>
11      <p>{content.content}</p>
12    </div>
13  );
14};

Nota: Se vuoi usare il tuo contenuto in un attributo string, come alt, title, href, aria-label, ecc., devi chiamare il valore della funzione, come:
tsx
1<img src={content.image.src.value} alt={content.image.value} />

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

(Opzionale) Passo 8: Internazionalizzazione dei tuoi metadati

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

typescript

1// src/app/[locale]/layout.tsx o src/app/[locale]/page.tsx
2
3import {
4  type IConfigLocales,
5  getTranslationContent,
6  getMultilingualUrls,
7} from "intlayer";
8import type { Metadata } from "next";
9import type { LocalParams } from "next-intlayer";
10
11export const generateMetadata = ({
12  params: { locale },
13}: LocalParams): Metadata => {
14  const t = <T>(content: IConfigLocales<T>) =>
15    getTranslationContent(content, locale);
16
17  /**
18   * Genera un oggetto contenente tutti gli url per ogni lingua.
19   *
20   * Esempio:
21   * ```ts
22   *  getMultilingualUrls('/about');
23   *
24   *  // Ritorna
25   *  // {
26   *  //   en: '/about',
27   *  //   fr: '/fr/about',
28   *  //   es: '/es/about',
29   *  // }
30   * ```
31   */
32  const multilingualUrls = getMultilingualUrls("/");
33
34  return {
35    title: t<string>({
36      en: "My title",
37      fr: "Mon titre",
38      es: "Mi título",
39    }),
40    description: t({
41      en: "My description",
42      fr: "Ma description",
43      es: "Mi descripción",
44    }),
45    alternates: {
46      canonical: url,
47      languages: { ...multilingualUrls, "x-default": "/" },
48    },
49    openGraph: {
50      url: multilingualUrls[locale],
51    },
52  };
53};
54
55// ... Il resto del codice

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

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

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

tsx

1// src/app/sitemap.ts
2
3import { getMultilingualUrls } from "intlayer";
4import type { MetadataRoute } from "next";
5
6const sitemap = (): MetadataRoute.Sitemap => [
7  {
8    url: "https://example.com",
9    alternates: {
10      languages: getMultilingualUrls("https://example.com"),
11    },
12  },
13  {
14    url: "https://example.com/login",
15    alternates: {
16      languages: getMultilingualUrls("https://example.com/login"),
17    },
18  },
19  {
20    url: "https://example.com/register",
21    alternates: {
22      languages: getMultilingualUrls("https://example.com/register"),
23    },
24  },
25];
26
27export default sitemap;

tsx

1// src/app/robots.ts
2import type { MetadataRoute } from "next";
3import { getMultilingualUrls } from "intlayer";
4
5const getAllMultilingualUrls = (urls: string[]) =>
6  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
7
8const robots = (): MetadataRoute.Robots => ({
9  rules: {
10    userAgent: "*",
11    allow: ["/"],
12    disallow: getAllMultilingualUrls(["/login", "/register"]),
13  },
14  host: "https://example.com",
15  sitemap: `https://example.com/sitemap.xml`,
16});
17
18export 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.

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

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

tsx

1import { Locales } from "intlayer";
2import { useLocale } from "next-intlayer";
3
4const MyComponent = () => {
5  const { setLocale } = useLocale();
6
7  return (
8    <button onClick={() => setLocale(Locales.English)}>Cambia lingua</button>
9  );
10};

Configura TypeScript

Intlayer utilizza l'augmentation del modulo per ottenere i benefici di TypeScript e rendere il tuo codice più robusto.

alt text

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

json5

1// tsconfig.json
2
3{
4  // tua configurazione personalizzata
5  include: [
6    "src",
7    "types", // <- Includi i tipi generati automaticamente
8  ],
9}

Configurazione Git

È consigliato ignorare i file generati da Intlayer. Questo consente di evitare di commetterli nel tuo repository Git.

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

gitignore

1# Ignora i file generati da Intlayer
2.intlayer

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

Collegamento GitHub alla documentazione

Recupero funzione Next.js 14 e App Router

Iniziare l'internazionalizzazione (i18n) con Intlayer e Next.js 15 App Router

Cos'è Intlayer?

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

Passo 1: Installa le dipendenze

Passo 2: Configura il tuo progetto

Passo 3: Integra Intlayer nella tua configurazione Next.js

Passo 4: Configura il Middleware per il rilevamento della lingua

Passo 5: Definisci le route dinamiche per le lingue

Passo 6: Dichiara il tuo contenuto

Passo 7: Utilizza il contenuto nel tuo codice

(Opzionale) Passo 8: Internazionalizzazione dei tuoi metadati

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

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

Configura TypeScript

Configurazione Git

In questa pagina