Localizzazione React con i18next

Creare un'applicazione React per un pubblico globale richiede una solida strategia di internazionalizzazione (i18n). react-i18next è la libreria di localizzazione React più popolare, costruita sopra il framework i18next, collaudato sul campo. Questa guida ti accompagna attraverso tutto ciò che serve per localizzare la tua app React, dalla configurazione iniziale all'automazione pronta per la produzione con la traduzione basata sull'IA.

Perché scegliere react-i18next per la localizzazione React?

react-i18next è lo standard de facto per l'internazionalizzazione di React, di cui si fidano migliaia di applicazioni in produzione in tutto il mondo. Ecco perché gli sviluppatori lo scelgono:

• API basata su Hook - L'hook useTranslation() fornisce un'integrazione React pulita e idiomatica con il re-rendering automatico al cambio di lingua.
• Ecosistema ricco - Plugin per il rilevamento della lingua, backend HTTP, caching e altro ancora. Estendi le funzionalità senza reinventare la ruota.
• Formato di traduzione JSON - Utilizza file JSON standard facili da modificare, gestire con il controllo versione e integrare con strumenti di traduzione e servizi di IA.
• Supporto per i namespace - Organizza le traduzioni in gruppi logici (auth, dashboard, errori) per una migliore manutenibilità e lazy loading.
• Pronto per SSR e Next.js - Funziona perfettamente con il rendering lato server, i React Server Components e il router App di Next.js.
• Supporto TypeScript - Piena sicurezza dei tipi per le chiavi di traduzione con completamento automatico, rilevando le chiavi mancanti in fase di compilazione.

Installazione

Installa react-i18next e la libreria core i18next:

npm install react-i18next i18next

Plugin opzionali

Questi popolari plugin migliorano la tua configurazione i18next con il rilevamento automatico della lingua e traduzioni caricate in modo lazy:

# Language detector (auto-detects user language)
npm install i18next-browser-languagedetector

# HTTP backend (load translations from server)
npm install i18next-http-backend

Struttura del progetto consigliata

Una struttura di progetto ben organizzata mantiene le tue traduzioni manutenibili man mano che aggiungi più lingue:

src/
├── i18n/
│   └── i18n.ts                  ← i18next configuration
├── locales/
│   ├── en/
│   │   └── translation.json     ← English (source)
│   ├── fr/
│   │   └── translation.json     ← French
│   ├── de/
│   │   └── translation.json     ← German
│   ├── ja/
│   │   └── translation.json     ← Japanese
│   └── es/
│       └── translation.json     ← Spanish
├── components/
├── App.tsx
└── index.tsx

Formato file JSON di traduzione

react-i18next utilizza file JSON annidati per le traduzioni. Le chiavi supportano la notazione a punti, l'interpolazione con {{variabili}} e la pluralizzazione integrata:

// locales/en/translation.json
{
  "welcome": {
    "title": "Welcome to our platform",
    "greeting": "Hello, {{name}}!",
    "description": "Explore features and get started."
  },
  "nav": {
    "home": "Home",
    "dashboard": "Dashboard",
    "settings": "Settings",
    "logout": "Log out"
  },
  "cart": {
    "empty": "Your cart is empty",
    "item_one": "{{count}} item in your cart",
    "item_other": "{{count}} items in your cart",
    "checkout": "Proceed to checkout"
  }
}

• Chiavi annidate - Organizza le traduzioni gerarchicamente (es. welcome.title, nav.home) per una struttura chiara.
• Interpolazione - Usa la sintassi {{variableName}} per valori dinamici che vengono inseriti in fase di runtime.
• Pluralizzazione - Aggiungi i suffissi _one e _other (o _zero, _two, _few, _many per lingue complesse) per la gestione automatica del plurale.
• Contesto - Usa i suffissi _male, _female per traduzioni specifiche di genere quando necessario.

Configurazione di i18next

i18next supporta due approcci principali per il caricamento delle traduzioni: backend HTTP (lazy loading) e risorse in bundle. Scegli in base alle esigenze della tua app.

Backend HTTP (consigliato per app di grandi dimensioni)

Carica le traduzioni su richiesta dai file JSON sul tuo server. Questo mantiene il bundle iniziale piccolo ed è ideale per app con molte lingue o file di traduzione di grandi dimensioni:

// src/i18n/i18n.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import HttpBackend from "i18next-http-backend";

i18n
  .use(HttpBackend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de", "ja", "es"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false, // React already escapes by default
    },
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json",
    },
    detection: {
      order: ["localStorage", "navigator", "htmlTag"],
      caches: ["localStorage"],
    },
  });

export default i18n;

Risorse in bundle (approccio semplice)

Importa le traduzioni direttamente nel bundle. Ideale per app più piccole o quando hai bisogno che le traduzioni siano disponibili immediatamente senza richieste di rete:

// src/i18n/i18n.ts — Bundled approach (no HTTP backend)
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

import en from "../locales/en/translation.json";
import fr from "../locales/fr/translation.json";
import de from "../locales/de/translation.json";

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false,
    },
    resources: {
      en: { translation: en },
      fr: { translation: fr },
      de: { translation: de },
    },
  });

export default i18n;

Inizializzazione nell'app

Importa il file di configurazione i18n nel punto di ingresso dell'app prima di renderizzare qualsiasi componente. Ciò garantisce che le traduzioni vengano caricate prima che la tua UI venga renderizzata:

// src/index.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./i18n/i18n"; // Initialize i18next before rendering

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Tradurre componenti React

react-i18next fornisce due API principali per tradurre i componenti: l'hook useTranslation per l'accesso programmatico e il componente Trans per testo ricco con JSX.

Hook useTranslation

L'hook useTranslation è il modo più comune per accedere alle traduzioni nei componenti funzionali. Fornisce la funzione t() e viene renderizzato automaticamente quando la lingua cambia:

import { useTranslation } from "react-i18next";

function WelcomeBanner() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t("welcome.title")}</h1>
      <p>{t("welcome.greeting", { name: "Alice" })}</p>
      <p>{t("welcome.description")}</p>
    </div>
  );
}

Componente Trans per testo ricco

Quando le traduzioni contengono elementi HTML o JSX (grassetto, link, ecc.), usa il componente Trans. Preserva il tuo albero dei componenti React all'interno delle traduzioni:

import { Trans } from "react-i18next";

function RichTextExample() {
  return (
    <p>
      <Trans i18nKey="richText.welcome">
        Welcome to <strong>our platform</strong>.
        Visit your <a href="/dashboard">dashboard</a> to get started.
      </Trans>
    </p>
  );
}

// In the translation file:
// "richText.welcome": "Welcome to <1>our platform</1>. Visit your <3>dashboard</3> to get started."

Gestione della pluralizzazione

i18next gestisce le forme plurali automaticamente in base alle regole di pluralizzazione ICU per ogni lingua. Passa un parametro count e i18next selezionerà la forma plurale corretta:

// In translation JSON:
// "cart.item_one": "{{count}} item in your cart"
// "cart.item_other": "{{count}} items in your cart"

import { useTranslation } from "react-i18next";

function CartSummary({ itemCount }: { itemCount: number }) {
  const { t } = useTranslation();

  return (
    <p>{t("cart.item", { count: itemCount })}</p>
  );
}

// itemCount=0 → "0 items in your cart"
// itemCount=1 → "1 item in your cart"
// itemCount=5 → "5 items in your cart"

• Aggiungi i suffissi _one e _other alle chiavi di traduzione per l'inglese
• Per lingue con regole plurali complesse (arabo, polacco, russo), aggiungi i suffissi _zero, _two, _few, _many come necessario
• i18next seleziona automaticamente la forma corretta in base alle regole plurali CLDR della lingua di destinazione

Organizzazione con i namespace

I namespace ti permettono di dividere le traduzioni in file separati per funzionalità o dominio. Questo migliora la manutenibilità e abilita il lazy loading dei bundle di traduzione:

// src/i18n/i18n.ts
i18n.init({
  defaultNS: "common",
  ns: ["common", "dashboard", "auth", "errors"],
  backend: {
    loadPath: "/locales/{{lng}}/{{ns}}.json",
  },
});

// Usage in components:
import { useTranslation } from "react-i18next";

function DashboardPage() {
  // Load specific namespace
  const { t } = useTranslation("dashboard");

  return <h1>{t("title")}</h1>;
}

function LoginForm() {
  // Load multiple namespaces
  const { t } = useTranslation(["auth", "common"]);

  return (
    <form>
      <h2>{t("auth:login.title")}</h2>
      <button>{t("common:submit")}</button>
    </form>
  );
}

Cambio lingua dinamico

react-i18next rende il cambio di lingua fluido. Chiama i18n.changeLanguage() e tutti i componenti che usano useTranslation verranno renderizzati automaticamente con la nuova lingua:

import { useTranslation } from "react-i18next";

const LANGUAGES = [
  { code: "en", label: "English" },
  { code: "fr", label: "Français" },
  { code: "de", label: "Deutsch" },
  { code: "ja", label: "日本語" },
  { code: "es", label: "Español" },
];

function LanguageSwitcher() {
  const { i18n } = useTranslation();

  const changeLanguage = (lng: string) => {
    i18n.changeLanguage(lng);
  };

  return (
    <select
      value={i18n.language}
      onChange={(e) => changeLanguage(e.target.value)}
    >
      {LANGUAGES.map(({ code, label }) => (
        <option key={code} value={code}>
          {label}
        </option>
      ))}
    </select>
  );
}

React Suspense e lazy loading

react-i18next si integra con React Suspense per gestire il caricamento asincrono delle traduzioni in modo elegante. Quando si utilizza il backend HTTP, Suspense fornisce uno stato di caricamento pulito mentre le traduzioni vengono recuperate:

import { Suspense } from "react";
import { useTranslation } from "react-i18next";

// i18next supports React Suspense for async translation loading
function App() {
  return (
    <Suspense fallback={<div>Loading translations...</div>}>
      <MainContent />
    </Suspense>
  );
}

function MainContent() {
  const { t, ready } = useTranslation();

  // With Suspense, 'ready' is always true here
  return <h1>{t("welcome.title")}</h1>;
}

Chiavi di traduzione Type-Safe con TypeScript

i18next supporta una piena integrazione con TypeScript. Aumentando il modulo i18next, ottieni il completamento automatico e il controllo in fase di compilazione per tutte le chiavi di traduzione, prevenendo errori di battitura e traduzioni mancanti:

// src/i18n/types.ts
import "i18next";
import translation from "../locales/en/translation.json";

declare module "i18next" {
  interface CustomTypeOptions {
    defaultNS: "translation";
    resources: {
      translation: typeof translation;
    };
  }
}

// Now t() calls are fully type-safe:
// t("welcome.title")       ✅ Autocomplete works
// t("welcome.greeting")    ✅ Valid key
// t("invalid.key")         ❌ TypeScript error

Rendering lato server con Next.js

Per le applicazioni Next.js che utilizzano l'App Router, puoi utilizzare i18next sia sui componenti server che su quelli client. Crea un'istanza i18next separata per le traduzioni lato server per evitare di condividere lo stato tra le richieste:

// next-i18next.config.js (Next.js App Router)
// For Next.js 13+ with App Router, use next-intl or i18next directly

// src/i18n/server.ts
import { createInstance } from "i18next";
import { initReactI18next } from "react-i18next/initReactI18next";

export async function getServerTranslation(lng: string) {
  const i18nInstance = createInstance();
  await i18nInstance.use(initReactI18next).init({
    lng,
    fallbackLng: "en",
    resources: {
      [lng]: {
        translation: (await import(`../locales/${lng}/translation.json`)).default,
      },
    },
  });
  return i18nInstance;
}

// In a Server Component:
export default async function Page({ params }: { params: { lng: string } }) {
  const i18n = await getServerTranslation(params.lng);
  const t = i18n.t.bind(i18n);

  return <h1>{t("welcome.title")}</h1>;
}

• Crea una nuova istanza i18next per richiesta sul server per evitare perdite di stato tra gli utenti
• Usa gli stessi file JSON di traduzione sia per il rendering lato server che lato client
• Considera i18next-resources-to-backend o next-intl come alternative per configurazioni complesse di Next.js

Accelera la traduzione con l'IA

Configurare react-i18next è solo metà dell'opera: hai ancora bisogno di traduzioni di alta qualità per ogni lingua di destinazione. Tradurre manualmente decine di file JSON è lento, costoso e soggetto a errori. La traduzione basata sull'IA cambia le regole del gioco.

Perché usare l10n.dev per React i18next?

l10n.dev è progettato appositamente per i flussi di lavoro di localizzazione degli sviluppatori. Comprende nativamente i tuoi file di traduzione JSON e produce traduzioni che sembrano naturali, non generate da una macchina:

• Supporto JSON nativo — Carica il tuo translation.json e ottieni file JSON perfettamente formattati e pronti all'uso
• IA consapevole del contesto — Comprende il dominio della tua app, preservando i termini tecnici e la voce del brand in tutte le lingue
• Sicuro per l'interpolazione — Preserva {{variabili}}, suffissi plurali (_one, _other) e strutture di chiavi annidate
• Traduzione in batch — Traduci in oltre 10 lingue contemporaneamente in pochi secondi, non giorni
• Integrazione CI/CD — Automatizza le traduzioni come parte della tua pipeline di build con il pacchetto npm ai-l10n

Flusso di lavoro di traduzione IA

1. Scrivi il tuo translation.json sorgente in inglese (o nella tua lingua base)
2. Caricalo su l10n.dev o esegui la CLI ai-l10n per tradurre
3. L'IA genera traduzioni contestualmente accurate per tutte le lingue di destinazione
4. Inserisci i file JSON tradotti nella tua directory locales/ e distribuisci

Automatizza le traduzioni con la CLI ai-l10n

Il pacchetto npm ai-l10n integra la traduzione IA direttamente nel tuo flusso di lavoro di sviluppo. Traduci i tuoi file JSON dalla riga di comando:

# Install the l10n.dev CLI
npm install ai-l10n

# Translate your JSON files to multiple languages at once
npx ai-l10n translate src/locales/en/translation.json \
  --languages fr,de,ja,es,ko,zh-CN

Integrazione nella build

Aggiungi l'automazione della traduzione alla tua pipeline di build in modo che le traduzioni siano sempre aggiornate:

Script package.json

{
  "scripts": {
    "translate": "ai-l10n translate src/locales/en/translation.json --languages fr,de,ja,es,ko --update",
    "pretranslate": "npm run translate",
    "dev": "vite",
    "build": "npm run translate && vite build"
  }
}

Makefile

LANGUAGES = fr,de,ja,es,ko,zh-CN

translate:
	npx ai-l10n translate src/locales/en/translation.json --languages $(LANGUAGES) --update

dev: translate
	npx vite

build: translate
	npx vite build

Per maggiori dettagli sull'integrazione CI/CD e l'automazione, consulta la nostra Guida all'automazione della localizzazione

Estensione VS Code per la traduzione JSON

Traduci i tuoi file JSON di React i18next direttamente da VS Code. L'estensione l10n.dev ti permette di tradurre i file senza lasciare il tuo editor:

Come funziona

1. Installa l'estensione l10n.dev dal Marketplace di VS Code
2. Apri il tuo file translation.json sorgente
3. Fai clic con il tasto destro e seleziona 'Translate with l10n.dev'
4. Scegli le tue lingue di destinazione e ottieni i file tradotti istantaneamente

Inizia a localizzare la tua app React oggi stesso

Ora hai tutto ciò che ti serve per creare un'applicazione React completamente localizzata con react-i18next. Combina la potenza del maturo ecosistema di i18next con la traduzione basata sull'IA per distribuire la tua app in qualsiasi lingua, velocemente.