Localizzazione React con i18next

Costruire 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 testato in battaglia. Questa guida ti accompagna in tutto ciò che devi sapere per localizzare la tua app React, dalla configurazione iniziale all'automazione pronta per la produzione con la traduzione basata su AI.

Perché scegliere react-i18next per la localizzazione React?

react-i18next è lo standard di fatto per l'internazionalizzazione React, scelto da 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 re-rendering automatico al cambio di lingua.
• Ricco ecosistema - Plugin per il rilevamento della lingua, backend HTTP, caching e altro ancora. Estendi la funzionalità senza reinventare la ruota.
• Formato di traduzione JSON - Utilizza file JSON standard facili da modificare, controllare nelle versioni e integrare con strumenti di traduzione e servizi AI.
• Supporto Namespace - Organizza le traduzioni in gruppi logici (autenticazione, dashboard, errori) per una migliore manutenibilità e caricamento lazy.
• Pronto per SSR e Next.js - Funziona perfettamente con il rendering lato server, i componenti server React e il router App di Next.js.
• Supporto TypeScript - Completa sicurezza dei tipi per le chiavi di traduzione con completamento automatico, rilevando 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 modalità 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 {{nomeVariabile}} per valori dinamici che vengono inseriti in fase di esecuzione.
• 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 per genere quando necessario.

Configurazione di i18next

i18next supporta due approcci principali per il caricamento delle traduzioni: backend HTTP (caricamento lazy) 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 piccolo il tuo bundle iniziale 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 nella tua app

Importa il file di configurazione i18n nel punto di ingresso della tua app prima di eseguire il rendering di qualsiasi componente. Questo assicura 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>
);

Traduzione dei componenti React

react-i18next fornisce due API principali per la traduzione dei 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 automaticamente le forme plurali in base alle regole plurali ICU per ogni lingua. Passa un parametro di conteggio e i18next seleziona 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 tue chiavi di traduzione per l'inglese
• Per le 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 consentono di dividere le traduzioni in file separati per funzionalità o dominio. Questo migliora la manutenibilità e abilita il caricamento lazy 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 utilizzano useTranslation vengono 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 caricamento lazy

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 con sicurezza dei tipi TypeScript

i18next supporta l'integrazione completa 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 il router App, puoi utilizzare i18next sia sui componenti server che 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 Next.js complesse

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 dozzine di file JSON è lento, costoso e soggetto a errori. La traduzione basata su AI cambia le regole del gioco.

Perché usare l10n.dev per React i18next?

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

• Supporto JSON nativo — Carica il tuo translation.json e ricevi file JSON perfettamente formattati e pronti all'uso
• AI consapevole del contesto — Comprende il dominio della tua app, preservando i termini tecnici e la voce del marchio 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 simultaneamente in pochi secondi, non giorni
• Integrazione CI/CD — Automatizza le traduzioni come parte della tua pipeline di distribuzione continua con il pacchetto npm ai-l10n

Flusso di lavoro di traduzione AI

1. Scrivi il tuo translation.json di origine in inglese (o nella tua lingua di base)
2. Carica 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 AI 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 build

Aggiungi l'automazione della traduzione alla tua pipeline di distribuzione continua 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 consente 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 di origine
3. Fai clic con il tasto destro e seleziona 'Traduci con l10n.dev'
4. Scegli le tue lingue di destinazione e ottieni file tradotti istantaneamente

Inizia oggi a localizzare la tua app React

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