PTC
Registrati Passa a Pro Il tuo account

Come tradurre un'app React con react-i18next

Configura react-i18next, traduci en.json in 40+ lingue con l'IA, lascia poi che l'estensione del browser di PTC (Private Translation Cloud) revisioni l'app React in esecuzione a ogni release. Questa guida copre l'internazionalizzazione di React da cima a fondo: configurare react-i18next, gestire i plurali e il contenuto dinamico, tradurre i tuoi en.json in 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 indipendente, vedi tradurre file JSON online con l'IA.

Come si presenta un'app React localizzata

Un'app React dove:

  • Tutte le stringhe visibili all'utente si trovano in file di traduzione JSON sotto 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 ciascuna lingua di destinazione.
  • I file .json tradotti sono generati da PTC, non scritti a mano.

Step 1: Genera un'app React + TypeScript con Vite

Questa guida usa un'app React + TypeScript creata con Vite. Se stai aggiungendo react-i18next a un'app esistente, passa allo Step 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.

Step 2: Installa react-i18next e sostituisci le stringhe hardcoded con t()

npm install i18next react-i18next

Crea la struttura delle cartelle i18n per 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 codice.

Step 3: Carica automaticamente ogni JSON del 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 fa in modo che ogni file .json aggiunto a src/i18n/locales/ venga 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 che la tua app venga renderizzata. 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 step, t() restituirà le chiavi di traduzione invece del testo tradotto.

Interpola 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 desideri sostituire. Puoi inserire tutte le variabili di cui hai bisogno.

Pluralizza con i suffissi delle chiavi _one / _other

Usa il pattern con suffisso _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 inoltre le lingue con più di due forme plurali (polacco, arabo, russo) senza configurazioni aggiuntive.

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 su 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, permettendo al contempo ai traduttori di riordinare il testo circostante in modo naturale.

Formatta date, numeri e valute con Intl

Usa i formattatori Intl invece di incorporare stringhe di formattazione 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>

Passo 5: traduci 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 lingua di origine. La prova copre 20.000 parole in 2 lingue, senza carta di credito.
  2. Carica en.json. PTC analizza la struttura annidata, 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, stesso annidamento, stessi segnaposto. Valori tradotti.
  5. Inserisci i file in src/i18n/locales/. Grazie al caricamento automatico di import.meta.glob che hai configurato nel Passo 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 nelle lingue di destinazione.

Passo 6: verifica 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 utente si aggiorni immediatamente. Nessun ricaricamento della pagina.

Rileva 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'],
    },
  });

Carica in modo differito le 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 serviti come asset statici:

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

Passando al francese, ora /locales/fr/translation.json viene recuperato su richiesta invece di essere raggruppato. Il bundle iniziale rimane leggero, indipendentemente dal numero di lingue supportate.

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

Dopo che PTC ha tradotto il tuo en.json, devi ancora verificare l'app React in esecuzione. Un'etichetta tradotta potrebbe causare un overflow in un pulsante in tedesco. “Save” (Salva) potrebbe essere tradotto come sostantivo in francese quando l'interfaccia aveva bisogno di un verbo. Una stringa hardcoded in inglese al di fuori di t() verrà visualizzata non tradotta, indipendentemente da quante lingue tu 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 al di fuori di 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: review-as-a-CI-step (revisione come step della CI). Ogni release viene rilasciata con una verifica visiva in tutte le lingue di destinazione, senza colli di bottiglia umani.

Traduci note di rilascio, pagine di marketing ed email per i clienti

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

Traduci commenti degli utenti, post e 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, senza carta di credito. Due percorsi:

  • Manuale: carica src/i18n/locales/en.json sulla pagina di traduzione JSON.
  • Basato su CI: collega il tuo repository Git tramite l'API PTC e un push che modifica le tue stringhe di origine tornerà tradotto.

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