React Internazionalizzazione (i18n) con react-i18next e Intlayer

Panoramica

• Intlayer ti aiuta a gestire le traduzioni tramite file di dichiarazione del contenuto a livello di componente.
• react-i18next è un'integrazione popolare di React per i18next che fornisce hook come useTranslation per recuperare stringhe localizzate nei tuoi componenti.

Quando combinati, Intlayer può esportare dizionari in JSON compatibile con i18next in modo che react-i18next possa consumare questi dizionari in fase di esecuzione.

Perché Usare Intlayer con react-i18next?

I file di dichiarazione del contenuto di Intlayer offrono una migliore esperienza per gli sviluppatori perché sono:

1. Flessibili nella Posizione dei File
   Metti ogni file di dichiarazione del contenuto accanto al componente che ne ha bisogno. Questa struttura ti consente di mantenere le traduzioni co-locate, impedendo traduzioni orfane quando i componenti si spostano o vengono eliminati.

   bash

   .└── src    └── components        └── MyComponent            ├── index.content.ts # File di dichiarazione del contenuto            └── index.tsx

2. Traduzioni Centralizzate
   Un singolo file di dichiarazione del contenuto raccoglie tutte le traduzioni necessarie per un componente, rendendo più facile rilevare traduzioni mancanti.
   Con TypeScript, ricevi anche errori di compilazione se le traduzioni sono mancanti.

Installazione

In un progetto Create React App, installa queste dipendenze:

# Con npmnpm install intlayer react-i18next i18next i18next-resources-to-backend

# Con yarnyarn add intlayer react-i18next i18next i18next-resources-to-backend

# Con pnpmpnpm add intlayer react-i18next i18next i18next-resources-to-backend

Cosa Sono Questi Pacchetti?

• intlayer – La CLI e la libreria principale per gestire le configurazioni i18n, le dichiarazioni di contenuto e costruire output di dizionari.
• react-intlayer – Integrazione specifica di React per Intlayer, che fornisce notevolmente qualche script per automatizzare la costruzione dei dizionari.
• react-i18next – Libreria di integrazione specifica di React per i18next, incluso l'hook useTranslation.
• i18next – Il framework sottostante per la gestione delle traduzioni.
• i18next-resources-to-backend – Un backend i18next che importa dinamicamente risorse JSON.

Configurare Intlayer per Esportare Dizionari i18next

Crea (o aggiorna) il tuo intlayer.config.ts nella radice del tuo progetto:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    // Aggiungi quante più lingue desideri    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },  content: {    // Dì a Intlayer di creare JSON compatibile con i18next    dictionaryOutput: ["i18next"],    // Scegli una directory di output per le risorse generate    // Questa cartella verrà creata se non esiste ancora.    i18nextResourcesDir: "./i18next/resources",  },};export default config;

Nota: Se non stai usando TypeScript, puoi creare questo file di configurazione come .cjs, .mjs o .js (vedi la documentazione di Intlayer per dettagli).

Costruire le Risorse i18next

Una volta che le tue dichiarazioni di contenuto sono pronte (sezione successiva), esegui il comando di build di Intlayer:

# Con npmnpx run intlayer build

# Con yarnyarn intlayer build

# Con pnpmpnpm intlayer build

Questo genererà le tue risorse i18next all'interno della directory ./i18next/resources per impostazione predefinita.

Un output tipico potrebbe apparire così:

.└── i18next    └── resources       ├── en       │   └── my-content.json       ├── fr       │   └── my-content.json       └── es           └── my-content.json

Dove ogni chiave di dichiarazione di Intlayer viene utilizzata come un namespace di i18next (ad esempio, my-content.json).

Importare Dizionari nella Tua Configurazione react-i18next

Per caricare dinamicamente queste risorse in fase di esecuzione, usa i18next-resources-to-backend. Ad esempio, crea un file i18n.ts (o .js) nel tuo progetto:

import i18next from "i18next";import { initReactI18next } from "react-i18next";import resourcesToBackend from "i18next-resources-to-backend";i18next  // plugin react-i18next  .use(initReactI18next)  // carica dinamicamente le risorse  .use(    resourcesToBackend((language: string, namespace: string) => {      // Regola il percorso di importazione alla tua directory delle risorse      return import(`../i18next/resources/${language}/${namespace}.json`);    })  )  // Inizializza i18next  .init({    // Lingua di fallback    fallbackLng: "en",    // Puoi aggiungere altre opzioni di configurazione di i18next qui, vedere:    // https://www.i18next.com/overview/configuration-options  });export default i18next;

import i18next from "i18next";import { initReactI18next } from "react-i18next";import resourcesToBackend from "i18next-resources-to-backend";i18next  .use(initReactI18next)  .use(    resourcesToBackend(      (language, namespace) =>        import(`../i18next/resources/${language}/${namespace}.json`)    )  )  .init({    fallbackLng: "en",  });export default i18next;

Poi, nel tuo file root o index (ad esempio, src/index.tsx), importa questa configurazione i18n prima di rendere l'App:

import React from "react";import ReactDOM from "react-dom/client";// Inizializza i18n prima di qualsiasi altra cosaimport "./i18n";import App from "./App";ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(  <React.StrictMode>    <App />  </React.StrictMode>);

Creare e Gestire le Tue Dichiarazioni di Contenuto

Intlayer estrae le traduzioni dai “file di dichiarazione del contenuto” situati ovunque sotto ./src (per impostazione predefinita).
Ecco un esempio minimale in TypeScript:

import { t, type DeclarationContent } from "intlayer";const content = {  // La "chiave" sarà il tuo namespace i18next (ad esempio, "my-component")  key: "my-component",  content: {    // Ogni chiamata "t" è un nodo di traduzione separato    heading: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola Mundo",    }),    description: t({      en: "My i18n description text...",      fr: "Ma description en i18n...",      es: "Mi descripción en i18n...",    }),  },} satisfies DeclarationContent;export default content;

Se preferisci JSON, .cjs, o .mjs, fai riferimento alla documentazione di Intlayer.

Per impostazione predefinita, le dichiarazioni di contenuto valide corrispondono al modello di estensione del file:
*.content.{ts,tsx,js,jsx,mjs,cjs,json}

Usare le Traduzioni nei Componenti React

Dopo aver costruito le tue risorse Intlayer e configurato react-i18next, puoi usare direttamente l'hook useTranslation di react-i18next.
Ad esempio:

import { FC } from "react";import { useTranslation } from "react-i18next";/** * Il "namespace" di i18next è la `chiave` di Intlayer da "MyComponent.content.ts" * quindi passeremo "my-component" a useTranslation(). */const MyComponent: FC = () => {  const { t } = useTranslation("my-component");  return (    <div>      <h1>{t("heading")}</h1>      <p>{t("description")}</p>    </div>  );};export default MyComponent;

Nota che la funzione t fa riferimento a chiavi nel tuo JSON generato. Per un'inserzione di contenuto di Intlayer chiamata heading, utilizzerai t("heading").

Opzionale: Integrare con gli Script di Create React App (CRACO)

react-intlayer fornisce un approccio basato su CRACO per build personalizzate e configurazione del server di sviluppo. Se desideri che il passaggio di build di Intlayer sia integrato senza problemi, puoi:

1. Installare react-intlayer (se non lo hai già fatto): bash npm install react-intlayer --save-dev

2. Regolare i tuoi script di package.json per utilizzare gli script di react-intlayer:

   jsonc

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

   Gli script di react-intlayer sono basati su CRACO. Puoi anche implementare il tuo setup basato sul plugin craco di intlayer. Vedi esempio qui.

Ora, eseguendo npm run build, yarn build, o pnpm build attiva sia le build di Intlayer che quelle di CRA.

Configurazione di TypeScript

Intlayer fornisce definizioni di tipo autogenerate per il tuo contenuto. Per assicurarti che TypeScript le riconosca, aggiungi types (o types se hai configurato diversamente) all'array include del tuo tsconfig.json:

{  "compilerOptions": {    // ...  },  "include": ["src", "types"],}

Questo consentirà a TypeScript di dedurre la struttura delle tue traduzioni per migliori autocompletamenti e detection degli errori.

Configurazione Git

Si consiglia di ignorare file e cartelle autogenerati da Intlayer. Aggiungi questa riga al tuo .gitignore:

# Ignora i file generati da Intlayer.intlayeri18next

In genere non committi queste risorse o artefatti di build interni .intlayer, poiché possono essere rigenerati ad ogni build.