PTC
Registrati Passa a Pro Il tuo account

Come tradurre un'app React con react-i18next

Configura react-i18next, traduci en.json in oltre 40 lingue con l'IA, quindi lascia che l'estensione del browser di PTC (Private Translation Cloud) esegua la revisione dell'app React in esecuzione a ogni release. Questa guida copre l'internazionalizzazione di React dall'inizio alla fine: configurare react-i18next, gestire i plurali e il contenuto dinamico, tradurre i tuoi en.json in oltre 40 lingue con PTC e cambiare lingua a runtime. Alla fine avrai una configurazione di localizzazione React funzionante e pronta da rilasciare. Per una panoramica dello strumento di traduzione JSON autonomo, consulta tradurre file JSON online con l'IA.

Come si presenta un'app React localizzata

Un'app React in cui:

  • Tutte le stringhe rivolte all'utente si trovano nei file di traduzione JSON in src/i18n/locales/ (o public/locales/).
  • Un selettore di lingua permette di passare tra inglese, spagnolo, francese e tedesco.
  • Il contenuto dinamico (nomi utente, conteggi, date) viene interpolato correttamente per ogni locale.
  • I plurali seguono le regole di ogni lingua di destinazione.
  • I file .json tradotti sono prodotti da PTC, non scritti a mano.

Passaggio 1: Generare la struttura di un'app React + TypeScript con Vite

Questa guida utilizza un'app React + TypeScript creata con Vite. Se stai aggiungendo react-i18next a un'app esistente, passa al Passaggio 2.

npm create vite@latest react-localization-demo -- --template react-ts
cd react-localization-demo
npm install
npm run dev

Questo avvia un server di sviluppo e apre la pagina predefinita di Vite + React nel tuo browser.

Passaggio 2: Installare react-i18next e sostituire le stringhe hardcoded con t()

npm install i18next react-i18next

Crea la struttura delle cartelle i18n di React:

src/
  i18n/
    locales/
      en.json

Aggiungi le tue stringhe in inglese a src/i18n/locales/en.json:

{
  "welcome": "Welcome",
  "description": "This is a localization demo.",
  "clickMe": "Click me"
}

Un tipico componente React con stringhe hardcoded:

function App() {
  return (
    <div>
      <h1>Welcome</h1>
      <p>This is a localization demo.</p>
      <button onClick={() => alert('Click me')}>Click me</button>
    </div>
  );
}

Sostituisci il testo hardcoded con l'hook useTranslation:

import { useTranslation } from 'react-i18next';

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

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

useTranslation() restituisce:

  • t() - cerca una stringa in base alla chiave.
  • i18n - ti permette di cambiare lingua a livello di programmazione.

Passaggio 3: Caricare automaticamente ogni JSON di locale con import.meta.glob

Crea src/i18n/index.ts per configurare i18next e caricare automaticamente i file di traduzione. Il pattern import.meta.glob significa che ogni file .json che aggiungi a src/i18n/locales/ viene rilevato automaticamente. Nessuna importazione manuale quando aggiungi nuove lingue:

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

type TranslationResources =
  | string
  | { [k: string]: TranslationResources }
  | TranslationResources[];

const modules = import.meta.glob<{ default: Record<string, TranslationResources> }>(
  './locales/*.json',
  { eager: true }
);

const resources: Record<string, { translation: Record<string, TranslationResources> }> = {};
for (const path in modules) {
  const lang = path.match(/\.\/locales\/(.*)\.json$/)?.[1];
  if (lang) {
    resources[lang] = { translation: modules[path].default };
  }
}

i18n
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    interpolation: { escapeValue: false },
  });

export default i18n;

Importa i18n prima del rendering della tua app. Apri src/main.tsx e aggiungi l'importazione:

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';
import './i18n'; // <- add this

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

Se salti questo passaggio, t() restituirà le chiavi di traduzione anziché il testo tradotto.

Interpolare le variabili con {{variableName}}

Usa la sintassi {{variableName}} nel tuo JSON e passa il valore a t(). Aggiorna en.json:

{
  "welcome": "Welcome",
  "userGreeting": "Welcome back, {{firstName}}!",
  "description": "This is a localization demo.",
  "clickMe": "Click me"
}
const user = { firstName: 'Sarah' };
<p>{t('userGreeting', { firstName: user.firstName })}</p>

Il secondo argomento di t() è un oggetto con i valori che vuoi sostituire. Tutte le variabili di cui hai bisogno.

Pluralizzare con i suffissi delle chiavi _one / _other

Usa il pattern di suffissi _one / _other. La variabile deve chiamarsi count:

{
  "newMessages_one": "You have {{count}} new message.",
  "newMessages_other": "You have {{count}} new messages."
}
<p>{t('newMessages', { count: messageCount })}</p>

i18next seleziona automaticamente la forma plurale corretta. Gestisce anche le lingue con più di due forme plurali (polacco, arabo, russo) senza configurazione aggiuntiva.

Per le traduzioni che contengono elementi HTML come link o testo in grassetto, usa il componente Trans:

{
  "termsText": "I agree to the <1>Terms of Service</1> and <3>Privacy Policy</3>."
}

I tag <1> e <3> sono segnaposto basati sull'indice che corrispondono agli elementi figlio (contando da 0):

import { Trans } from 'react-i18next';

<Trans i18nKey="termsText">
  I agree to the <a href="/terms">Terms of Service</a> and <a href="/privacy">Privacy Policy</a>.
</Trans>

Questo mantiene i tuoi elementi JSX nel componente, pur permettendo ai traduttori di riordinare il testo circostante in modo naturale.

Formattare date, numeri e valute con Intl

Usa i formattatori Intl anziché incorporare stringhe di formato nelle tue traduzioni:

const formatDate = (date: Date, locale: string) =>
  new Intl.DateTimeFormat(locale, { dateStyle: 'long' }).format(date);

const formatCurrency = (amount: number, locale: string, currency: string) =>
  new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount);

const { i18n } = useTranslation();
<p>{formatDate(new Date(), i18n.language)}</p>
<p>{formatCurrency(199.99, i18n.language, 'EUR')}</p>

Passaggio 5: Tradurre i file JSON con PTC in 5 passaggi

Ora hai en.json e devi produrre es.json, fr.json, de.json, ecc. PTC è progettato esattamente per questo.

  1. Inizia un progetto PTC e scegli l'inglese come origine. La prova copre 20.000 parole in 2 lingue, nessuna carta di credito.
  2. Carica en.json. PTC analizza la struttura nidificata, riconosce i segnaposto di i18next ({{name}}, {{count}}) e rileva i suffissi plurali (_one, _other).
  3. Aggiungi una breve descrizione della tua app React e del suo pubblico. PTC usa questo contesto per adattare il tono e la terminologia in ogni lingua.
  4. Scegli le lingue di destinazione e conferma. PTC produce un .json tradotto per ogni lingua di destinazione, strutturalmente identico all'origine. Stesse chiavi, stessa nidificazione, stessi segnaposto. Valori tradotti.
  5. Inserisci i file in src/i18n/locales/. Grazie al caricamento automatico di import.meta.glob che hai configurato nel Passaggio 3, i nuovi file funzionano immediatamente senza modifiche al codice.

Una volta tradotto il tuo primo file con PTC, puoi passare a un processo automatizzato. Collega il tuo repository GitHub, GitLab o Bitbucket tramite l'integrazione Git, oppure usa l'API PTC per inserire la traduzione nella tua pipeline CI/CD. Le nuove stringhe in en.json attivano la traduzione automatica. PTC apre una merge request con i file aggiornati nella lingua di destinazione.

Passaggio 6: Verificare la configurazione con un selettore di lingua

Aggiungi dei pulsanti per la lingua per verificare che la tua configurazione di react-i18next funzioni:

import { useTranslation } from 'react-i18next';

function App() {
  const { t, i18n } = useTranslation();

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <button onClick={() => i18n.changeLanguage('en')}>EN</button>
      <button onClick={() => i18n.changeLanguage('fr')}>FR</button>
    </div>
  );
}

i18n.changeLanguage() attiva un nuovo rendering di ogni componente che usa useTranslation(), in modo che l'intera interfaccia si aggiorni immediatamente. Nessun ricaricamento della pagina.

Rilevare automaticamente la lingua dell'utente con i18next-browser-languagedetector

Installa i18next-browser-languagedetector per caricare automaticamente la lingua corretta dalle impostazioni del browser dell'utente, dall'URL o dalle preferenze salvate:

npm install i18next-browser-languagedetector
import LanguageDetector from 'i18next-browser-languagedetector';

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    supportedLngs: ['en', 'fr', 'de', 'ar'],
    interpolation: { escapeValue: false },
    detection: {
      order: ['querystring', 'localStorage', 'cookie', 'navigator'],
      caches: ['localStorage', 'cookie'],
    },
  });

Caricamento differito delle traduzioni con i18next-http-backend

Per impostazione predefinita, tutti i file di traduzione vengono raggruppati al momento della build. Per le app con molte lingue, usa i18next-http-backend per recuperare solo la lingua di cui l'utente ha effettivamente bisogno:

npm install i18next-http-backend
import Backend from 'i18next-http-backend';

i18n
  .use(Backend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    supportedLngs: ['en', 'fr'],
    interpolation: { escapeValue: false },
    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' },
  });

Sposta i tuoi file di traduzione in public/locales/ in modo che vengano forniti come asset statici:

public/
  locales/
    en/translation.json
    fr/translation.json

Passando al francese ora viene recuperato /locales/fr/translation.json su richiesta anziché raggrupparlo. Il bundle iniziale rimane leggero indipendentemente da quante lingue supporti.

Revisione visiva della traduzione della tua app React in esecuzione: rilascia senza QA manuale a ogni release

Dopo che PTC ha tradotto i tuoi en.json, devi ancora verificare l'app React in esecuzione. Un'etichetta tradotta potrebbe andare in overflow su un pulsante in tedesco. “Save” potrebbe essere tradotto come sostantivo in francese quando l'interfaccia richiedeva un verbo. Una stringa hardcoded in inglese al di fuori di t() verrà visualizzata non tradotta, indipendentemente da quante lingue rilasci.

L'AI Visual QA di PTC sostituisce il ciclo di QA manuale. Per le app basate su browser come React, la variante giusta è l'estensione del browser. Installala una volta e registra un breve percorso guidato dei flussi utente critici della tua app React (accesso, funzionalità principale, impostazioni). Da quel momento in poi, PTC riproduce la registrazione in ogni lingua di destinazione dopo ogni aggiornamento della traduzione, acquisisce ogni schermata e ispeziona il risultato renderizzato:

  • Correzioni nei file di traduzione quando PTC li controlla. PTC ritraduce una parte del discorso errata, sceglie un sinonimo più corto che si adatta a un pulsante, rigenera una forma plurale.
  • Prompt per Cursor / Claude Code quando il problema si trova nel codice del tuo componente. Una stringa hardcoded in inglese fuori da t(), una frase costruita tramite concatenazione di stringhe invece di t('key', { var }), un componente Trans mancante per le traduzioni in rich-text.

Il risultato: la review-as-a-CI-step (revisione come step della CI). Ogni release viene rilasciata con una verifica visiva in ogni lingua di destinazione, senza colli di bottiglia umani.

Tradurre le note di rilascio, le pagine di marketing e le email dei clienti

Le tue note di rilascio, le pagine di marketing, le landing page e le email dei clienti si trovano fuori da en.json. Il Paste to Translate di PTC gestisce questi testi nello stesso progetto. Incolla il testo di origine nel pannello di controllo PTC, scegli le lingue di destinazione e ottieni traduzioni che usano lo stesso glossario e la stessa voce del brand delle stringhe dell'interfaccia di React.

Tradurre i commenti degli utenti, i post e i risultati di ricerca con l'API PTC

I commenti degli utenti, i post, i risultati di ricerca e qualsiasi altro contenuto generato dagli utenti che la tua app React gestisce necessitano di traduzione non appena arrivano. L'API REST PTC traduce questi contenuti su richiesta con autenticazione tramite token Bearer, usando lo stesso glossario e la stessa voce del brand delle tue traduzioni en.json.

Ora traduci il tuo file en.json

Inizia la tua prova di 30 giorni: 20.000 parole in 2 lingue, nessuna carta di credito. Due percorsi:

  • Manuale: carica src/i18n/locales/en.json nella pagina di traduzione JSON.
  • Basato su CI: collega il tuo repository Git tramite l'API PTC e le traduzioni avvengono automaticamente a ogni push.

In ogni caso, installa l'estensione del browser e lascia che l'AI Visual QA verifichi la tua app React in esecuzione in ogni lingua prima di rilasciare.