Panoramica

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

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

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

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

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

Nessun hook, niente async, senza bisogno di un albero di componenti.

Perché questo approccio

L'idea alla base di questa PR è sperimentare un'alternativa all'approccio alla traduzione basato sul contesto React. Operando al di fuori dell'albero dei componenti, t() consente pattern più interessanti — in particolare, la traduzione a livello di modulo. Le stringhe possono essere tradotte nel punto in cui vengono definite, non in quello in cui vengono renderizzate.

Questo comporta alcuni 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 del rendering dell'app.
• Ricaricamento completo della pagina per cambiare lingua. Poiché le traduzioni vengono risolte al caricamento del modulo, cambiare impostazione regionale richiede di rieseguire i moduli, quindi un refresh completo della pagina. Non è possibile cambiare lingua al volo durante la sessione.

D'altra parte, l'esperienza di sviluppo migliora notevolmente. Niente hook per avvolgere le stringhe, niente logica a livello di componente, niente boundary asincroni — solo una chiamata di funzione.

Gli approcci esistenti basati sul contesto React (useGT, <T>, ecc.) non scompariranno. Questa è un'opzione aggiuntiva per i progetti in cui questi compromessi hanno senso.

Come funziona

t() risolve le traduzioni in modo sincrono da quelle caricate in anticipo. Queste traduzioni vengono inizializzate da bootstrap(), una nuova funzione di setup asincrona che carica tutte le traduzioni per l'impostazione regionale corrente prima che la tua app venga renderizzata.

Devi modificare l'entry point della tua app in modo da eseguire prima bootstrap(). Di solito è main.tsx, ma puoi cambiare l'entry point nel tuo index.html.

// bootstrap.tsx (new entry point)
import gtConfig from '../gt.config.json';
import { bootstrap } from 'gt-react/browser';

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

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

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

La funzione loadTranslations è asincrona: prima carica le traduzioni, poi l'app React viene importata ed eseguita. È così che t() è accessibile 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, per cambiare impostazione regionale è necessario ricaricare completamente la 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 che:

• 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. Per la traduzione lato server, dovresti usare hook basati sul contesto React come useGT.

Note di progettazione

t() è disponibile solo nel browser. Se viene chiamato sul server (dove window non è definito), genera un avviso e usa come fallback la stringa di origine. È intenzionale: per la traduzione lato server dovresti usare gli hook esistenti basati sul contesto React.

Riferimento API

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