Inizia a Internazionalizzare (i18n) con Intlayer e Next.js utilizzando il Page Router

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, incluso il suo tradizionale Page Router.

Con Intlayer, puoi:

• Gestire facilmente le traduzioni utilizzando dizionari dichiarativi a livello di componente.
• Localizzare dinamicamente i metadati, le rotte e il contenuto.
• Garantire supporto TypeScript con tipi generati automaticamente, migliorando il completamento automatico e la rilevazione degli errori.
• Beneficiare di funzionalità avanzate, come la rilevazione e il cambio dinamico della lingua.

Intlayer è compatibile con Next.js 12, 13, 14 e 15. Se stai utilizzando il Next.js App Router, fai riferimento alla guida all'App Router. Per Next.js 15, segui questa guida.

Guida Passo Passo per Configurare Intlayer in un'Applicazione Next.js Utilizzando il Page Router

Passo 1: Installa le Dipendenze

Installa i pacchetti necessari utilizzando il tuo gestore pacchetti preferito:

npm install intlayer next-intlayer

• intlayer

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

• next-intlayer

  Il pacchetto che integra Intlayer con Next.js. Fornisce fornitori di contesto e hook per l'internazionalizzazione di Next.js. Inoltre, include il plugin di Next.js per integrare Intlayer con Webpack o Turbopack, nonché middleware per rilevare la lingua preferita dell'utente, gestire i cookie e gestire il reindirizzamento degli URL.

Passo 2: Configura il Tuo Progetto

Crea un file di configurazione per definire le lingue supportate dalla tua applicazione:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Aggiungi le altre lingue qui    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Attraverso questo file di configurazione, puoi impostare URL localizzati, reindirizzamento middleware, nomi dei cookie, posizione ed estensione delle tue dichiarazioni di contenuto, disabilitare i log di Intlayer nella console e altro ancora. Per un elenco completo dei parametri disponibili, fai riferimento alla documentazione di configurazione.

Passo 3: Integra Intlayer con la Configurazione di Next.js

Modifica la tua configurazione Next.js per incorporare Intlayer:

import { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = {  // La tua configurazione esistente di Next.js};export default withIntlayer(nextConfig);

Il plugin withIntlayer() di Next.js viene utilizzato per integrare Intlayer con Next.js. Assicura la costruzione di file di dichiarazione dei contenuti e li monitora in modalità sviluppo. Definisce le variabili ambientali di Intlayer all'interno degli ambienti Webpack o Turbopack. Inoltre, fornisce alias per ottimizzare le prestazioni e garantire compatibilità con i componenti del server.

Passo 4: Configura il Middleware per la Rilevazione della Lingua

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

export { intlayerMiddleware as middleware } from "next-intlayer/middleware";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};

Adatta il parametro matcher per corrispondere alle rotte della tua applicazione. Per ulteriori dettagli, fai riferimento alla documentazione di Next.js sulla configurazione del matcher.

Passo 5: Definisci Rotte Dinamiche per la Lingua

Implementa il routing dinamico per servire contenuti localizzati in base alla lingua dell'utente.

1. Crea Pagine Specifiche per Lingua:

   Rinomina il tuo file della pagina principale per includere il segmento dinamico [locale].

   bash

   mv src/pages/index.tsx src/pages/[locale]/index.tsx

2. Aggiorna _app.tsx per Gestire la Localizzazione:

   Modifica il tuo _app.tsx per includere i fornitori di Intlayer.

   src/pages/_app.tsx

   import type { FC } from "react";import type { AppProps } from "next/app";import { IntlayerClientProvider } from "next-intlayer";const App: FC<AppProps> = ({ Component, pageProps }) => {  const { locale } = pageProps;  return (    <IntlayerClientProvider locale={locale}>      <Component {...pageProps} />    </IntlayerClientProvider>  );};export default MyApp;

3. Configura getStaticPaths e getStaticProps:

   Nel tuo [locale]/index.tsx, definisci i percorsi e le proprietà per gestire le diverse lingue.

   src/pages/[locale]/index.tsx

   import type { FC } from "react";import type { GetStaticPaths, GetStaticProps } from "next";import { type Locales, getConfiguration } from "intlayer";const HomePage: FC = () => <div>{/* Il tuo contenuto qui */}</div>;export const getStaticPaths: GetStaticPaths = () => {  const { internationalization } = getConfiguration();  const { locales } = internationalization;  const paths = locales.map((locale) => ({    params: { locale },  }));  return { paths, fallback: false };};export const getStaticProps: GetStaticProps = ({ params }) => {  const locale = params?.locale as string;  return {    props: {      locale,    },  };};export default HomePage;

getStaticPaths e getStaticProps garantiscono che la tua applicazione precompili le pagine necessarie per tutte le lingue nel Page Router di Next.js. Questo approccio riduce il calcolo a runtime e porta a un'esperienza utente migliorata. Per ulteriori dettagli, fai riferimento alla documentazione di Next.js su getStaticPaths e getStaticProps.

Passo 6: Dichiara i Tuoi Contenuti

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

import { t, type DeclarationContent } from "intlayer";const homeContent = {  key: "home",  content: {    title: t({      en: "Benvenuto nel mio sito web",      fr: "Bienvenue sur mon site Web",      es: "Bienvenido a mi sitio web",    }),    description: t({      en: "Inizia modificando questa pagina.",      fr: "Commencez par éditer cette page.",      es: "Comience por editar esta página.",    }),  },} satisfies DeclarationContent;export default homeContent;

Per ulteriori informazioni sulla dichiarazione dei contenuti, fai riferimento alla guida alla dichiarazione dei contenuti.

Passo 7: Utilizza i Contenuti nel Tuo Codice

Accedi ai tuoi dizionari di contenuti in tutta la tua applicazione per visualizzare contenuti tradotti.

import type { FC } from "react";import { useIntlayer } from "next-intlayer";import { ComponentExample } from "@components/ComponentExample";const HomePage: FC = () => {  const content = useIntlayer("home");  return (    <div>      <h1>{content.title}</h1>      <p>{content.description}</p>      <ComponentExample />      {/* Componenti aggiuntivi */}    </div>  );};// ... Il resto del codice, inclusi getStaticPaths e getStaticPropsexport default HomePage;

import type { FC } from "react";import { useIntlayer } from "next-intlayer";export const ComponentExample: FC = () => {  const content = useIntlayer("component-example"); // Assicurati di avere una dichiarazione di contenuto corrispondente  return (    <div>      <h2>{content.title}</h2>      <p>{content.content}</p>    </div>  );};

Quando utilizzi le traduzioni negli attributi string (ad es., alt, title, href, aria-label), chiama il valore della funzione come segue:

jsx

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

Per saperne di più sul hook useIntlayer, fai riferimento alla documentazione.

(Opzionale) Passo 8: Internazionalizza i Tuoi Metadati

Per internazionalizzare i metadati come i titoli delle pagine e le descrizioni, utilizza la funzione getStaticProps in combinazione con la funzione getTranslationContent di Intlayer.

import { GetStaticPaths, GetStaticProps } from "next";import { type IConfigLocales, getTranslationContent, Locales } from "intlayer";import { useIntlayer } from "next-intlayer";interface HomePageProps {  locale: string;  metadata: Metadata;}const HomePage = ({ metadata }: HomePageProps) => {  // I metadati possono essere utilizzati nell'intestazione o in altri componenti secondo necessità  return (    <div>      <Head>        <title>{metadata.title}</title>        <meta name="description" content={metadata.description} />      </Head>      {/* Contenuto aggiuntivo */}    </div>  );};export const getStaticProps: GetStaticProps = async ({ params }) => {  const locale = params?.locale as string;  const t = <T,>(content: IConfigLocales<T>) =>    getTranslationContent(content, locale);  const metadata = {    title: t({      en: "Il mio sito web",      fr: "Mon Site Web",      es: "Mi Sitio Web",    }),    description: t({      en: "Benvenuto nel mio sito web.",      fr: "Bienvenue sur mon site Web.",      es: "Bienvenido a mi sitio web.",    }),  };  return {    props: {      locale,      metadata,    },  };};export default HomePage;// ... Il resto del codice inclusi getStaticPaths

(Opzionale) Passo 9: Cambia la Lingua dei Tuoi Contenuti

Per consentire agli utenti di cambiare lingua dinamicamente, utilizza la funzione setLocale fornita dall'hook useLocale.

import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocalePageRouter } from "next-intlayer";import { type FC } from "react";const LocaleSwitcher: FC = () => {  const { locale, pathWithoutLocale, availableLocales, setLocale } =    useLocalePageRouter();  return (    <ol>      {availableLocales.map((localeItem) => (        <li key={localeItem}>          <a            href={getLocalizedUrl(pathWithoutLocale, localeItem)}            hrefLang={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={(e) => {              e.preventDefault();              setLocale(localeItem);            }}          >            <span>              {/* Lingua nel proprio Locale - es. Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Lingua nel Locale corrente - es. Francés con locale corrente impostato su Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Lingua in inglese - es. French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>            <span>              {/* Lingua nel proprio Locale - es. FR */}              {localeItem}            </span>          </a>        </li>      ))}    </ol>  );};

L'API useLocalePageRouter è la stessa di useLocale. Per saperne di più sull'hook useLocale, fai riferimento alla documentazione.

Riferimenti alla documentazione:

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

2. Esempio dei Vantaggi di TypeScript:

   

   

Configurazione di Git

Per mantenere il tuo repository pulito ed evitare di compromettere i file generati, è consigliato ignorare i file creati da Intlayer.

Aggiungi le seguenti righe al tuo file .gitignore:

# Ignora i file generati da Intlayer.intlayer

Risorse Aggiuntive

• Documentazione Intlayer: Repository GitHub
• Guida alla Dichiarazione dei Contenuti: Dichiarazione dei Contenuti
• Documentazione di Configurazione: Guida alla Configurazione

Seguendo questa guida, puoi integrare efficacemente Intlayer nella tua applicazione Next.js utilizzando il Page Router, abilitando un supporto di internazionalizzazione robusto e scalabile per i tuoi progetti web.