Traduzione React con react-i18next: Guida Completa

Scopri come tradurre un’app React con react-i18next, inclusa l’internazionalizzazione React, i plurali, i contenuti dinamici e la traduzione di file JSON.

Alla fine di questa guida, avrai una configurazione di localizzazione React funzionante che cambia lingua in tempo reale ed è pronta per tutte le lingue di cui hai bisogno.

Esempio di Internazionalizzazione React

I passaggi seguenti illustrano un esempio completo di i18n React, inclusa l’inizializzazione di i18next, la traduzione del testo, la gestione della pluralizzazione e l’aggiunta di un selettore di lingua.

Puoi seguire la demo completa di localizzazione React su GitHub.

Configura la tua app React

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

Per creare una nuova app React + TypeScript, esegui:

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

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.

Installa e configura react-i18next

Installa le librerie:

npm install i18next react-i18next

npm install i18next react-i18next

Crea la struttura delle cartelle per i18n React:

src/
 i18n/
 locales/
 en.json

src/
  i18n/
    locales/
      en.json

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

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

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

Ogni chiave (welcome, description, clickMe) corrisponde al testo che desideri visualizzare nell’interfaccia utente.

Prepara i Tuoi Componenti React per la Traduzione

Ecco un tipico componente React con stringhe hardcoded:

function App() {
  return (
    <div>
      <h1>Benvenuto</h1>
      <p>Questa è una demo di localizzazione.</p>
      <button onClick={() => alert('Cliccami')}>Cliccami</button>
    </div>
  );
}

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 in src/App.tsx:

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;

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() fornisce al tuo componente l’accesso a:

t() – cerca una stringa per chiave
i18n – ti consente di cambiare lingua programmaticamente

Inizializza i18next nella Tua App React

Crea src/i18n/index.ts per configurare i18next e caricare automaticamente i file di traduzione.

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;

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;

Il pattern import.meta.glob significa che ogni file .json che aggiungi a src/i18n/locales/ viene rilevato automaticamente. Non sono necessarie importazioni manuali quando aggiungi nuove lingue in seguito.

Importa i18n Prima del Rendering della Tua App

Apri src/main.tsx e importa la configurazione i18n:

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import './index.css'
import './i18n' // ← Aggiungi questo import!

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

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import './index.css'
import './i18n'  // ← Add this import!

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

Se salti questo passaggio, t() restituirà solo le chiavi di traduzione invece del testo tradotto.

Gestisci i Contenuti Dinamici nelle Traduzioni React

Le app reali richiedono più di semplici stringhe statiche. Ecco come react-i18next gestisce i pattern di contenuto dinamico più comuni.

Interpolazione (Variabili) in i18next

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

Aggiorna src/i18n/locales/en.json:

{
 "welcome": "Benvenuto",
 "userGreeting": "Bentornato, {{firstName}}!",
 "description": "Questa è una demo di localizzazione.",
 "clickMe": "Cliccami"
}

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

Usalo nel tuo componente:

import { useTranslation } from 'react-i18next';

function App() {
 const { t } = useTranslation();
 const user = { firstName: 'Sarah' };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

import { useTranslation } from 'react-i18next';

function App() {
  const { t } = useTranslation();
  const user = { firstName: 'Sarah' };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

Il secondo argomento di t() è un oggetto con i valori che vuoi sostituire. Puoi avere tutte le variabili di cui hai bisogno. Assicurati solo che ognuna compaia nelle tue traduzioni.

Pluralizzazione in React i18next

Usa il pattern del suffisso _one / _other. La variabile deve essere chiamata count:

Aggiorna src/i18n/locales/en.json:

{
 "welcome": "Benvenuto",
 "userGreeting": "Bentornato, {{firstName}}!",
 "description": "Questa è una demo di localizzazione.",
 "clickMe": "Cliccami",
 "newMessages_one": "Hai {{count}} nuovo messaggio.",
 "newMessages_other": "Hai {{count}} nuovi messaggi."
}

{
  "welcome": "Welcome",
  "userGreeting": "Welcome back, {{firstName}}!",
  "description": "This is a localization demo.",
  "clickMe": "Click me",
  "newMessages_one": "You have {{count}} new message.",
  "newMessages_other": "You have {{count}} new messages."
}

Usalo nel tuo componente:

import { useTranslation } from 'react-i18next';

function App() {
 const { t } = useTranslation();
 const user = { firstName: 'Sarah' };
 const [messageCount, setMessageCount] = useState<number>(1);

  const handleIncrement = () => {
 setMessageCount(messageCount + 1);
 };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      <button onClick={handleIncrement}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

import { useTranslation } from 'react-i18next';

function App() {
  const { t } = useTranslation();
  const user = { firstName: 'Sarah' };
  const [messageCount, setMessageCount] = useState<number>(1);

  const handleIncrement = () => {
    setMessageCount(messageCount + 1);
  };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      <button onClick={handleIncrement}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

i18next seleziona automaticamente la forma plurale corretta. Gestisce anche le lingue con più di due forme plurali (come il polacco o l’arabo) senza alcuna configurazione aggiuntiva.

Traduci Link e HTML con il Componente Trans

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

{
 "termsText": "Accetto i <1>Termini di Servizio1> e la <3>Privacy Policy3>."
}

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

I tag <1> e <3> sono placeholder basati su indice che mappano gli elementi figli (contando da 0):

import { Trans } from 'react-i18next';

<Trans i18nKey="termsText">
 Accetto i <a href="/terms">Termini di Servizio</a> e la
  <a href="/privacy">Privacy Policy</a>.
</Trans>

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.

Traduci i File JSON della Tua App React

La tua app React è ora configurata per l’internazionalizzazione. Il prossimo passaggio è produrre i file di traduzione effettivi per ogni lingua.

PTC è progettato esattamente per questo. Questo strumento di localizzazione AI si integra direttamente con il tuo repository GitHub, GitLab o Bitbucket. Legge il tuo en.json sorgente e apre una pull request con i file tradotti per ogni lingua di cui hai bisogno.

Grazie alla configurazione di caricamento automatico che hai impostato nel Passaggio 3, questi nuovi file funzionano immediatamente senza modifiche al codice.

PTC inizia con una prova gratuita di 30 giorni che ti consente di tradurre 20.000 parole in 2 lingue. Dopodiché, paghi in base all’uso senza abbonamento.

Iscriviti a PTC

Se preferisci non integrare con il tuo repository, puoi in alternativa:

Usare l’API PTC per configurare la localizzazione continua
Caricare manualmente un file JSON e ricevere un file tradotto

Testa le Traduzioni React con un Selettore di Lingua

Aggiungi i pulsanti di lingua a src/App.tsx e verifica che la tua configurazione react-i18next funzioni:

import { useTranslation } from 'react-i18next';

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

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      
      <p>
        <Trans i18nKey="termsText">
  Accetto i  <a href="/terms">Termini di servizio</a> e  <a href="/privacy">Informativa sulla privacy</a>.
        </Trans>
      </p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>

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

import { useTranslation } from 'react-i18next';

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

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      
      <p>
        <Trans i18nKey="termsText">
          I agree to the <a href="/terms">Terms of Service</a> and <a href="/privacy">Privacy Policy</a>.
        </Trans>
      </p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>

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

Esegui npm run dev e clicca sui pulsanti di lingua. Il testo dovrebbe aggiornarsi immediatamente senza ricaricare la pagina. Se lo fa, la tua configurazione i18n React funziona correttamente.

React app in English

React app in French

Prossimi Passaggi: Ottimizza la Tua Configurazione di Localizzazione React

La tua app React ora ha il supporto completo per più lingue. Ci sono alcune aggiunte da considerare prima di andare in produzione:

Rileva Automaticamente la Lingua dell’Utente

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

npm install i18next-browser-languagedetector

Aggiorna src/i18n/index.ts:

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

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(LanguageDetector) // rileva browser/localStorage/ecc.
 .use(initReactI18next)
 .init({
 resources,
 fallbackLng: "en",
 supportedLngs: ["en", "fr", "de", "ar"], // adatta alle tue lingue
 interpolation: { escapeValue: false },
 detection: {
 order: ["querystring", "localStorage", "cookie", "navigator"],
 caches: ["localStorage", "cookie"],
 }
 });

export default i18n;

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

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(LanguageDetector) // detect browser/localStorage/etc.
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de", "ar"], // adjust to your languages
    interpolation: { escapeValue: false },
    detection: {
      order: ["querystring", "localStorage", "cookie", "navigator"],
      caches: ["localStorage", "cookie"],
    }
  });

export default i18n;

Traduzioni a caricamento lento

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

npm install i18next-http-backend

npm install i18next-http-backend

Aggiorna src/i18n/index.ts:

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import Backend from "i18next-http-backend";
import LanguageDetector from "i18next-browser-languagedetector";

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

export default i18n;

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import Backend from "i18next-http-backend";
import LanguageDetector from "i18next-browser-languagedetector";

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

export default i18n;

Sposta i tuoi file di traduzione in public/locales/ in modo che vengano serviti come risorse statiche:

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

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

Con questa struttura, il passaggio al francese recupera /locales/fr/common.json su richiesta anziché includerlo nel bundle della tua app. Questo mantiene il tuo bundle iniziale leggero indipendentemente da quante lingue supporti.

Traduci React con PTC

La tua app React è pronta per l’internazionalizzazione. Ora lascia che PTC gestisca le traduzioni.

Le tue prime 20.000 parole sono gratuite, nessun abbonamento richiesto.

Prova subito PTC