Iniziare con l'internazionalizzazione (i18n) usando Intlayer e React Router v7

Questa guida dimostra come integrare Intlayer per un'internazionalizzazione senza soluzione di continuità nei progetti React Router v7 con routing consapevole della localizzazione, supporto TypeScript e pratiche di sviluppo moderne.

Cos'è Intlayer?

Intlayer è una libreria innovativa e open-source per l'internazionalizzazione (i18n) progettata per semplificare il supporto multilingue nelle applicazioni web moderne.

Con Intlayer, puoi:

• Gestire facilmente le traduzioni utilizzando dizionari dichiarativi a livello di componente.
• Localizzare dinamicamente metadati, rotte e contenuti.
• Garantire il supporto TypeScript con tipi generati automaticamente, migliorando l'autocompletamento e il rilevamento degli errori.
• Beneficiare di funzionalità avanzate, come il rilevamento e il cambio dinamico della localizzazione.
• Abilitare il routing consapevole della localizzazione con il sistema di routing basato su configurazione di React Router v7.

Guida passo-passo per configurare Intlayer in un'applicazione React Router v7

Passo 1: Installare le dipendenze

Installa i pacchetti necessari utilizzando il tuo gestore di pacchetti preferito:

npm install intlayer react-intlayernpm install vite-intlayer --save-dev

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

• react-intlayer Il pacchetto che integra Intlayer con l'applicazione React. Fornisce provider di contesto e hook per l'internazionalizzazione in React.

• vite-intlayer Include il plugin Vite per integrare Intlayer con il bundler Vite, oltre a middleware per rilevare la localizzazione preferita dall'utente, gestire i cookie e gestire il reindirizzamento degli URL.

Passo 2: Configurazione del tuo progetto

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

import { type IntlayerConfig, Locales } from "intlayer";const config: IntlayerConfig = {  internationalization: {    defaultLocale: Locales.ENGLISH,    locales: [Locales.ENGLISH, Locales.TURKISH],  },  middleware: {    prefixDefault: true, // Prefissa sempre la lingua predefinita negli URL  },};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.

Passo 3: Configurare le Rotte di React Router v7

Configura la tua configurazione di routing con rotte consapevoli della localizzazione:

import { layout, route, type RouteConfig } from "@react-router/dev/routes";export default [  layout("routes/layout.tsx", [    route("/", "routes/page.tsx"), // Pagina radice - reindirizza alla localizzazione    route("/:lang", "routes/[lang]/page.tsx"), // Pagina iniziale localizzata    route("/:lang/about", "routes/[lang]/about/page.tsx"), // Pagina "about" localizzata  ]),] satisfies RouteConfig;

Passo 4: Integrare Intlayer nella Configurazione di Vite

Aggiungi il plugin intlayer nella tua configurazione:

import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayerMiddlewarePlugin, intlayer } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({  plugins: [    reactRouter(),    tsconfigPaths(),    intlayer(),    intlayerMiddlewarePlugin(),  ],});

Il plugin Vite intlayer() viene utilizzato per integrare Intlayer con Vite. Garantisce la creazione dei file di dichiarazione del contenuto e li monitora in modalità sviluppo. Definisce le variabili d'ambiente di Intlayer all'interno dell'applicazione Vite. Inoltre, fornisce alias per ottimizzare le prestazioni.

Passo 5: Creare i Componenti Layout

Configura il layout principale e i layout specifici per la localizzazione:

Layout Principale

tsx fileName="app/routes/layout.tsx" codeFormat="typescript"// app/routes/layout.tsximport { Outlet } from "react-router";import { IntlayerProvider } from "react-intlayer";export default function RootLayout() {  return (    <IntlayerProvider>      <Outlet />    </IntlayerProvider>  );}

Passo 6: Dichiara il Tuo Contenuto

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

import { t, type Dictionary } from "intlayer";const pageContent = {  key: "page",  content: {    title: t({      en: "Welcome to React Router v7 + Intlayer",      tr: "React Router v7 + Intlayer'a Hoş Geldiniz",    }),    description: t({      en: "Build multilingual applications with ease using React Router v7 and Intlayer.",      tr: "React Router v7 e Intlayer per creare facilmente applicazioni multilingue.",    }),    aboutLink: t({      en: "Scopri di noi",      tr: "Hakkımızda Öğrenin",    }),    homeLink: t({      en: "Home",      tr: "Ana Sayfa",    }),  },} satisfies Dictionary;export default pageContent;

Le tue dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione non appena sono incluse nella directory contentDir (di default, ./app). E devono corrispondere all'estensione del file di dichiarazione del contenuto (di default, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Per maggiori dettagli, consulta la documentazione sulla dichiarazione del contenuto.

Passo 7: Crea Componenti Consapevoli della Locale

Crea un componente LocalizedLink per una navigazione consapevole della localizzazione:

// app/components/localized-link.tsximport { getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";import React from "react";import { Link, useLocation } from "react-router";type RouterLinkProps = React.ComponentProps<typeof Link>;export default function LocalizedLink({ to, ...props }: RouterLinkProps) {  const { locale } = useLocale();  const location = useLocation();  const isExternal = (path: string) =>    /^([a-z][a-z0-9+.-]*:)?\/\//i.test(path) || path.startsWith("mailto:");  if (typeof to === "string") {    if (to.startsWith("/") && !isExternal(to)) {      return <Link to={getLocalizedUrl(to, locale)} {...props} />;    }    return <Link to={to} {...props} />;  }  if (to && typeof to === "object") {    const pathname = (to as { pathname?: string }).pathname;    if (pathname && pathname.startsWith("/") && !isExternal(pathname)) {      return (        <Link          to={{ ...to, pathname: getLocalizedUrl(pathname, locale) }}          {...props}        />      );    }    return <Link to={to} {...props} />;  }  return (    <Link      to={getLocalizedUrl(location.pathname + location.search, locale)}      {...props}    />  );}

Passo 8: Utilizza Intlayer nelle Tue Pagine

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

Pagina di Reindirizzamento Root

// app/routes/page.tsximport { useLocale } from "react-intlayer";import { Navigate } from "react-router";export default function Page() {  const { locale } = useLocale();  return <Navigate replace to={locale} />;}

Pagina Home Localizzata

import { useIntlayer } from "react-intlayer";import LocalizedLink from "~/components/localized-link";export default function Page() {  const content = useIntlayer("page");  return (    <div style={{ padding: "2rem", textAlign: "center" }}>      <h1>{content.title}</h1>      <p>{content.description}</p>      <nav style={{ marginTop: "2rem" }}>        <LocalizedLink          to="/about"          style={{            display: "inline-block",            padding: "0.5rem 1rem",            backgroundColor: "#007bff",            color: "white",            textDecoration: "none",            borderRadius: "4px",          }}        >          {content.aboutLink}        </LocalizedLink>      </nav>    </div>  );}

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

Passo 9: Crea un componente per il selettore di lingua

Crea un componente per permettere agli utenti di cambiare lingua:

import { getLocalizedUrl, getLocaleName } from "intlayer";import { useLocale } from "react-intlayer";import { useLocation, useNavigate } from "react-router";export default function LocaleSwitcher() {  const { locale, availableLocales, setLocale } = useLocale();  const location = useLocation();  const navigate = useNavigate();  const handleLocaleChange = (newLocale: string) => {    const localizedUrl = getLocalizedUrl(      location.pathname + location.search,      newLocale    );    setLocale(newLocale);    navigate(localizedUrl);  };  return (    <div style={{ margin: "1rem 0" }}>      <label htmlFor="locale-select">Scegli la lingua: </label>      <select        id="locale-select"        value={locale}        onChange={(e) => handleLocaleChange(e.target.value)}        style={{ padding: "0.25rem", marginLeft: "0.5rem" }}      >        {availableLocales.map((availableLocale) => (          <option key={availableLocale} value={availableLocale}>            {getLocaleName(availableLocale)}          </option>        ))}      </select>    </div>  );}

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

Passo 10: Aggiungere la Gestione degli Attributi HTML (Opzionale)

Crea un hook per gestire gli attributi lang e dir dell'HTML:

// app/hooks/useI18nHTMLAttributes.tsximport { getHTMLTextDir } from "intlayer";import { useEffect } from "react";import { useLocale } from "react-intlayer";export const useI18nHTMLAttributes = () => {  const { locale } = useLocale();  useEffect(() => {    document.documentElement.lang = locale;    document.documentElement.dir = getHTMLTextDir(locale);  }, [locale]);};

Quindi usalo nel tuo componente root:

// app/routes/layout.tsximport { Outlet } from "react-router";import { IntlayerProvider } from "react-intlayer";import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // importa il hookexport default function RootLayout() {  useI18nHTMLAttributes(); // chiama il hook  return (    <IntlayerProvider>      <Outlet />    </IntlayerProvider>  );}

Passo 11: Compila ed Esegui la Tua Applicazione

Costruisci i dizionari di contenuto e avvia la tua applicazione:

# Costruisci i dizionari di Intlayernpm run intlayer:build# Avvia il server di svilupponpm run dev

Passo 12: Configura TypeScript (Opzionale)

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

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

{  compilerOptions: {    // ... le tue configurazioni TypeScript esistenti  },  include: [    // ... i tuoi include 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:

# Ignora i file generati da Intlayer.intlayer

Distribuzione in Produzione

Quando distribuisci la tua applicazione:

1. Compila la tua applicazione:

   bash

   Copiare il codice

   Copiare il codice nella clipboard

   npm run build

2. Compila i dizionari di Intlayer:

   bash

   Copiare il codice

   Copiare il codice nella clipboard

   npm run intlayer:build

3. Sposta vite-intlayer nelle dipendenze se usi il middleware in produzione:

   bash

   Copiare il codice

   Copiare il codice nella clipboard

   npm install vite-intlayer --save

La tua applicazione supporterà ora:

• Struttura URL: /en, /en/about, /tr, /tr/about
• Rilevamento automatico della lingua basato sulle preferenze del browser
• Routing consapevole della lingua con React Router v7
• Supporto TypeScript con tipi generati automaticamente
• Rendering lato server con gestione corretta della lingua

Estensione VS Code

Per migliorare la tua esperienza di sviluppo con Intlayer, puoi installare la Estensione ufficiale Intlayer per VS Code.

Installa dal Marketplace di VS Code

Questa estensione offre:

• Completamento automatico per le chiavi di traduzione.
• Rilevamento in tempo reale degli errori per traduzioni mancanti.
• Anteprime inline dei contenuti tradotti.
• 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.

Vai oltre

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

Riferimenti alla documentazione

• Documentazione Intlayer
• Documentazione React Router v7
• Hook useIntlayer
• useLocale hook
• Dichiarazione del Contenuto
• Configurazione

Questa guida completa fornisce tutto il necessario per integrare Intlayer con React Router v7 per un'applicazione completamente internazionalizzata con routing consapevole della localizzazione e supporto TypeScript.

Cronologia della Documentazione