Introduzione all'Internazionalizzazione (i18n) con Intlayer e React Create App

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, percorsi e contenuti.
• Garantire il supporto TypeScript con tipi autogenerati, migliorando l'autocompletamento e il rilevamento degli errori.
• Beneficiare di funzionalità avanzate, come il rilevamento e il cambio dinamico della lingua.

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

Passo 1: Installa le dipendenze

Installa i pacchetti necessari utilizzando npm:

npm install intlayer react-intlayer react-scripts-intlayer

• intlayer

  Il pacchetto principale che fornisce strumenti di internazionalizzazione per la gestione delle configurazioni, traduzioni, dichiarazione dei contenuti, transpilation e comandi CLI.

• react-intlayer

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

• react-scripts-intlayer

  Include i comandi e i plugin react-scripts-intlayer per integrare Intlayer con l'applicazione basata su Create React App. Questi plugin sono basati su craco e includono configurazioni aggiuntive per il bundler Webpack.

Passo 2: Configurazione del progetto

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

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

Tramite questo file di configurazione, puoi configurare URL localizzati, reindirizzamenti middleware, nomi dei cookie, la posizione e l'estensione delle dichiarazioni dei contenuti, disabilitare i log di Intlayer nella console e altro. Per un elenco completo dei parametri disponibili, consulta la documentazione di configurazione.

Passo 3: Integra Intlayer nella configurazione CRA

Modifica i tuoi script per utilizzare react-intlayer

  "scripts": {    "build": "react-scripts-intlayer build",    "start": "react-scripts-intlayer start",    "transpile": "intlayer build"  },

Gli script react-scripts-intlayer sono basati su CRACO. Puoi anche implementare la tua configurazione basata sul plugin craco di Intlayer. Vedi esempio qui.

Passo 4: Dichiarare i tuoi contenuti

Crea e gestisci le dichiarazioni dei tuoi contenuti per memorizzare le traduzioni:

import { t, type Dictionary } from "intlayer";import React, { type ReactNode } from "react";const appContent = {  key: "app",  content: {    getStarted: t<ReactNode>({      en: (        <>          Edit <code>src/App.tsx</code> and save to reload        </>      ),      fr: (        <>          Éditez <code>src/App.tsx</code> et enregistrez pour recharger        </>      ),      es: (        <>          Edita <code>src/App.tsx</code> y guarda para recargar        </>      ),      it: (        <>          Modifica <code>src/App.tsx</code> e salva per ricaricare        </>      ),    }),    reactLink: {      href: "https://reactjs.org",      content: t({        en: "Learn React",        fr: "Apprendre React",        es: "Aprender React",        it: "Impara React",      }),    },  },} satisfies Dictionary;export default appContent;

Le dichiarazioni dei tuoi contenuti possono essere definite ovunque nella tua applicazione purché siano incluse nella directory contentDir (di default, ./src). E corrispondano all'estensione del file di dichiarazione dei contenuti (di default, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}). Per maggiori dettagli, consulta la documentazione sulla dichiarazione dei contenuti. Se il tuo file di contenuti include codice TSX, considera di importare import React from "react"; nel tuo file di contenuti.

Passo 5: Utilizza Intlayer nel tuo codice

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

import logo from "./logo.svg";import "./App.css";import type { FC } from "react";import { IntlayerProvider, useIntlayer } from "react-intlayer";const AppContent: FC = () => {  const content = useIntlayer("app");  return (    <div className="App">      <img src={logo} className="App-logo" alt="logo" />      {content.getStarted}      <a        className="App-link"        href={content.reactLink.href.value}        target="_blank"        rel="noopener noreferrer"      >        {content.reactLink.content}      </a>    </div>  );};const App: FC = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;

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

jsx

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

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

(Opzionale) Passo 6: Cambia la lingua dei tuoi contenuti

Per cambiare la lingua dei tuoi contenuti, puoi utilizzare la funzione setLocale fornita dall'hook useLocale. Questa funzione ti consente di impostare la lingua dell'applicazione e aggiornare i contenuti di conseguenza.

import { Locales } from "intlayer";import { useLocale } from "react-intlayer";const LocaleSwitcher = () => {  const { setLocale } = useLocale();  return (    <button onClick={() => setLocale(Locales.English)}>      Cambia lingua in Inglese    </button>  );};

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

(Opzionale) Passo 7: Aggiungi routing localizzato alla tua applicazione

Lo scopo di questo passaggio è creare percorsi univoci per ogni lingua. Questo è utile per la SEO e per URL SEO-friendly. Esempio:

- https://example.com/about- https://example.com/es/about- https://example.com/fr/about

Di default, i percorsi non sono prefissati per la lingua predefinita. Se desideri prefissare la lingua predefinita, puoi impostare l'opzione middleware.prefixDefault su true nella tua configurazione. Consulta la documentazione di configurazione per maggiori informazioni.

[Continua con il resto del contenuto...]