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) revisioni l'app React in esecuzione a ogni rilascio. Questa guida copre l'internazionalizzazione di React end-to-end: configurazione di react-i18next, gestione dei plurali e dei contenuti dinamici, traduzione del tuo en.json in oltre 40 lingue con PTC e cambio della lingua a runtime. Al termine, avrai una configurazione di localizzazione React funzionante e pronta per la produzione. Per una panoramica dello strumento di traduzione JSON autonomo, vedi 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 risiedono 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.
  • I contenuti dinamici (nomi utente, conteggi, date) sono interpolati 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: Crea 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 punto 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: 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 tramite chiave.
  • i18n: ti permette di cambiare lingua programmaticamente.

Passaggio 3: Carica automaticamente ogni JSON 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 sì 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 l'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 passaggio, 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 vuoi sostituire. Puoi usare tutte le variabili di cui hai bisogno.

Pluralizza con i suffissi delle chiavi _one / _other

Usa il pattern dei 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 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 sull'indice che mappano agli elementi figli (partendo 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, consentendo comunque ai traduttori di riordinare il testo circostante in modo naturale.

Formatta date, numeri e valute con Intl

Usa i formattatori Intl invece di inserire 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>

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

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

  1. Avvia un progetto PTC e scegli l'inglese come origine. La prova gratuita copre 20.000 parole in 2 lingue, senza carta di credito.
  2. Carica en.json. PTC analizza la struttura nidificata, riconosce i segnaposto 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 import.meta.glob impostato al passaggio 3, i nuovi file funzioneranno immediatamente senza modifiche al codice.

Dopo aver 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 di PTC per inserire la traduzione nella tua pipeline CI/CD. Le nuove stringhe in en.json attivano la traduzione automatica. PTC apre una pull request con i file aggiornati nelle lingue di destinazione.

Passaggio 6: Verifica la configurazione con un selettore di lingua

Aggiungi dei pulsanti per le lingue per verificare che la 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 utilizza useTranslation(), quindi l'intera interfaccia utente si aggiorna immediatamente. Senza ricaricare la 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'],
    },
  });

Caricamento differito delle traduzioni con i18next-http-backend

Per impostazione predefinita, tutti i file di traduzione vengono inclusi nel bundle al momento della compilazione. Per 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 siano serviti come asset statici:

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

Passando al francese, l'app recupererà /locales/fr/translation.json su richiesta invece di includerlo nel bundle. Il bundle iniziale rimarrà leggero indipendentemente dal numero di lingue supportate.

Revisione visiva della traduzione della tua app React in esecuzione: distribuisci ogni rilascio senza QA manuale

Dopo che PTC ha tradotto il tuo en.json, devi comunque verificare l'app React in esecuzione. Un'etichetta tradotta potrebbe causare un overflow in un pulsante in tedesco. “Save” potrebbe essere tradotto come sostantivo in francese quando l'interfaccia utente richiedeva un verbo. Una stringa inglese hardcoded al di fuori di t() verrà renderizzata non tradotta, indipendentemente dalle lingue supportate.

L'AI Visual QA di PTC sostituisce il passaggio di QA manuale. Per le app basate su browser come React, la soluzione ideale è 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 corregge una categoria grammaticale errata, sceglie un sinonimo più breve che si adatti a un pulsante, rigenera una forma plurale.
  • Prompt per Cursor / Claude Code quando il problema risiede nel codice del tuo componente. Una stringa inglese hardcoded fuori da t(), una frase costruita tramite concatenazione di stringhe invece di t('key', { var }), un componente Trans mancante per traduzioni rich-text.

Il risultato: la revisione come passaggio della CI. Ogni rilascio viene pubblicato con 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 vivono al di fuori di en.json. La funzione Incolla per tradurre di PTC gestisce quei testi nello stesso progetto. Incolla il testo di origine nel pannello di controllo di PTC, scegli le lingue di destinazione e ottieni traduzioni che utilizzano lo stesso glossario e la stessa voce del brand delle stringhe dell'interfaccia utente React.

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

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

Ora traduci il tuo file en.json

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

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

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 della pubblicazione.