Panoramica

gt-react ora esporta una funzione t() per la traduzione sincrona di stringhe a livello di modulo nel browser.

Finora, per tradurre le stringhe in gt-react servivano hook basati sul context di React, come useGT. Gli hook funzionano bene all'interno dei componenti, ma non coprono un caso comune: tradurre stringhe a livello di modulo, cioè fuori dai componenti React, prima di renderizzare, in semplici file di utilità.

t() colma questa lacuna. È una funzione sincrona che puoi chiamare ovunque nel codice del browser:

import { t } from 'gt-react/browser';

const greeting = t('Hello, world!');

Non servono hook, async né un albero dei componenti.

Perché questo approccio

L'idea alla base di questa PR è sperimentare un allontanamento dall'approccio alla traduzione basato sul context di React. Operando al di fuori dell'albero dei componenti, t() abilita pattern più interessanti — in particolare, la traduzione a livello di modulo. Le stringhe possono essere tradotte dove vengono definite, non dove vengono renderizzate.

Questo comporta dei compromessi:

• Solo lato client. t() funziona solo nelle applicazioni React lato client. Si basa sull'esecuzione dei moduli nel browser per caricare le traduzioni prima che l'app venga renderizzata.
• Ricaricamento completo della pagina per cambiare lingua. Poiché le traduzioni vengono risolte al caricamento del modulo, cambiare locale richiede di rieseguire i moduli, quindi un refresh completo della pagina. Non è possibile cambiare lingua a caldo durante la sessione.

D'altra parte, la developer experience migliora notevolmente. Non bisogna racchiudere le stringhe negli hook, né gestire il plumbing a livello di componente, né avere a che fare con boundary asincroni — basta una chiamata di funzione.

Gli approcci esistenti basati sul context di React (useGT, <T>, ecc.) non andranno da nessuna parte. Questa è un'opzione aggiuntiva per i progetti in cui questi compromessi hanno senso.

Come funziona

t() recupera le traduzioni in modo sincrono da quelle caricate in anticipo. Queste traduzioni vengono inizializzate da bootstrap(), una nuova funzione di configurazione asincrona che carica tutte le traduzioni per la locale corrente prima del rendering della tua app.

Devi modificare il punto di ingresso della tua app per eseguire prima bootstrap(). In genere si tratta di main.tsx, ma puoi cambiare il punto di ingresso nel tuo index.html.

// bootstrap.tsx (nuovo punto di ingresso)
import gtConfig from '../gt.config.json';
import { bootstrap } from 'gt-react/browser';

async function getTranslations(locale: string) {
  return import(`./_gt/${locale}.json`);
}

await bootstrap({
  ...gtConfig,
  getTranslations,
});

await import('./main.tsx');

La funzione getTranslations è asincrona: prima carica le traduzioni, poi importa ed esegue l'app React. È così che t() può essere usata a livello di modulo: quando un modulo chiama t(), le traduzioni sono già disponibili.

Questo funziona solo nelle app React lato client, perché il codice a livello di modulo viene rieseguito quando viene caricato nel browser. E poiché per aggiornare il contenuto tradotto dobbiamo rieseguire i moduli, il cambio di locale richiede un ricaricamento completo della pagina.

Variabili

t() supporta l'interpolazione delle variabili, come msg():

import { t } from 'gt-react/browser';

t('Hello, {name}!', { name: 'John' });  // → "Hola, John!"

Dove si colloca

t() è la scelta giusta quando hai bisogno di traduzioni al di fuori dell'albero dei componenti React — file di costanti, funzioni di utilità, oggetti di configurazione, definizioni del router o qualsiasi elemento eseguito a livello di modulo nel browser.

Tieni presente:

• Questo non si integra ancora con il resto del sistema gt-react. Devi eseguire la configurazione iniziale descritta sopra. È un approccio autonomo.
• Solo lato client. La traduzione lato server dovrebbe usare hook basati sul context di React, come useGT.

Note di progettazione

t() è utilizzabile solo nel browser. Se viene chiamato sul server (dove window è undefined), emette un avviso e ripiega sulla stringa sorgente. È voluto: la traduzione lato server dovrebbe usare gli hook esistenti basati sul context di React.

Riferimento API

Consulta il riferimento completo dell'API t() per i parametri, i tipi restituiti e i dettagli di configurazione.