# gt-react: General Translation React SDK: t URL: https://generaltranslation.com/it/docs/react/api/strings/t-function.mdx --- title: t description: Riferimento API per t(), la funzione sincrona di traduzione delle stringhe --- ## Panoramica La funzione `t` è una funzione sincrona di traduzione delle stringhe a livello di modulo per applicazioni React lato client. ```jsx import { t } from 'gt-react/browser'; const greeting = t('Hello, world!'); ``` `t` può anche essere usato come tagged template literal: ```jsx import { t } from 'gt-react/browser'; const greeting = t`Hello, ${name}!`; ``` A differenza di `useGT` (che richiede il contesto React) o `msg` (che codifica le stringhe per risolverle in un secondo momento), `t()` restituisce direttamente la stringa tradotta. Può essere usata ovunque nel codice del browser, incluso a livello di modulo, al di fuori dei componenti React. **Sperimentale:** `t()` è una funzionalità sperimentale. È pensata per applicazioni React solo lato client e non si integra ancora con il contesto React (ad es. ``, `useGT`). Se viene chiamata sul server, emette un avviso e restituisce la stringa sorgente. *** ## Setup `t()` dipende da `bootstrap()` per caricare le traduzioni prima del rendering dell'app. Devi modificare il punto di ingresso dell'app in modo da eseguire prima `bootstrap()`. In genere, il punto di ingresso è `main.tsx`. Crea un nuovo file (ad esempio `bootstrap.tsx`) e fai puntare invece a quello il tuo `index.html`. ### 1. Crea il punto di ingresso per il bootstrap ```tsx // bootstrap.tsx 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'); ``` Per impostazione predefinita, `bootstrap()` aggiorna automaticamente gli attributi `lang` e `dir` dell'elemento `` in base all'impostazione regionale corrente. Puoi configurare questo comportamento con `htmlTagOptions`: ```tsx await bootstrap({ ...gtConfig, loadTranslations, htmlTagOptions: { updateHtmlLangTag: true, // predefinito: true updateHtmlDirTag: false, // predefinito: true }, }); ``` Puoi anche aggiornare manualmente questi attributi in qualsiasi momento tramite le funzioni helper `updateHtmlTagLang` e `updateHtmlTagDir` di `gt-react/browser`. ### 2. Aggiorna il file `index.html` Nel file `index.html`, aggiorna il punto di ingresso del modulo in modo che punti al nuovo file di bootstrap anziché a `main.tsx`: ``` src="/src/bootstrap.tsx" ``` ### 3. Usa `t()` ovunque ```tsx import { t } from 'gt-react/browser'; // A livello di modulo — eseguito al momento dell'importazione const navItems = [ { label: t('Home'), path: '/' }, { label: t('About'), path: '/about' }, { label: t('Contact'), path: '/contact' }, ]; export default function Nav() { return ( ); } ``` **Setup autonomo:** `t()` al momento non si integra con il resto del sistema `gt-react` (ad esempio ``, `useGT`). Devi usare il setup di bootstrap descritto sopra. *** ## Tagged template literal `t` può essere usato come tagged template literal, per una sintassi più naturale: ```tsx import { t } from 'gt-react/browser'; // Questi sono equivalenti: t('Hello, {name}!', { name: 'Alice' }); t`Hello, ${name}!`; ``` La forma tagged template literal elimina la necessità di segnaposto in stile ICU e di oggetti di opzioni: le variabili vengono interpolate direttamente nell'espressione del template. ### Registrazione globale Invece di importare `t` in ogni file, puoi registrarlo a livello globale: ```tsx // Nel punto di ingresso della tua app import "gt-react/macros"; ``` Questo definisce `globalThis.t`, rendendo disponibile ovunque il tagged template literal senza bisogno di un'importazione esplicita: ```tsx // Nessun import necessario const labels = { save: t`Save`, cancel: t`Cancel`, }; ``` *** ## Riferimento ### Parametri | Nome | Tipo | Descrizione | | ---------- | -------- | ------------------------------------------------------------------------------------- | | `message` | `string` | La stringa da tradurre. | | `options?` | `object` | Facoltativo. Un oggetto contenente i valori delle variabili per l'interpolazione. | ### Valore restituito `string` — La stringa tradotta per l'impostazione regionale attuale, oppure la stringa sorgente se non è disponibile alcuna traduzione. *** ## Variabili Puoi passare le variabili usando la sintassi con parentesi graffe: ```tsx import { t } from 'gt-react/browser'; const message = t('Hello, {name}!', { name: 'Alice' }); // → "Hola, Alice!" (in spagnolo) ``` Oppure usa la forma tagged template literal, che gestisce automaticamente le interpolazioni: ```tsx import { t } from 'gt-react/browser'; const message = t`Hello, ${name}!`; // → "Hola, Alice!" (in spagnolo, quando name = 'Alice') ``` I valori delle variabili non vengono tradotti — viene tradotto solo il template della stringa circostante. *** ## Comportamento ### Come funziona `bootstrap()` carica in modo asincrono tutte le traduzioni per l'impostazione regionale corrente prima che vengano importati i moduli dell'app. Una volta caricate, `t()` legge i dati di traduzione in modo sincrono, senza overhead. Poiché le traduzioni vengono risolte durante il caricamento dei moduli: * **Per cambiare impostazione regionale è necessario ricaricare completamente la pagina.** Il browser deve rieseguire tutti i moduli per applicare le nuove traduzioni. * **Questo funziona solo nelle app lato client.** Il codice a livello di modulo viene rieseguito quando viene caricato nel browser, ed è questo che rende possibile questo pattern. ### Comportamento lato server Se `t()` viene chiamato in un ambiente server (dove `window` è `undefined`), emette un avviso e restituisce la stringa sorgente originale. Per la traduzione lato server, usa hook basati su React context come `useGT`. *** ## Esempio ### File di costanti ```tsx // constants.ts import { t } from 'gt-react/browser'; export const ERROR_MESSAGES = { notFound: t('Page not found'), unauthorized: t('You do not have permission to view this page'), serverError: t('Something went wrong. Please try again later.'), }; ``` ### Definizioni del router ```tsx // routes.ts import { t } from 'gt-react/browser'; export const routes = [ { path: '/', label: t('Home') }, { path: '/dashboard', label: t('Dashboard') }, { path: '/settings', label: t('Settings') }, ]; ``` *** ## Note * `t()` viene importato da `gt-react/browser`, non direttamente da `gt-react`. * Richiede che `bootstrap()` venga chiamato prima del caricamento di qualsiasi modulo che usi `t()`. * **Sperimentale.** Non si integra ancora con `` o altre funzionalità di `gt-react` basate sul contesto. * Per cambiare impostazione regionale è necessario ricaricare completamente la pagina. ## Log di sviluppo * [gt-react@10.12.0](/devlog/gt-react_v10_12_0) — introduzione della funzione `t()` * [gt-react@10.13.0](/devlog/gt-react_v10_13_0) — supporto per le tagged template literal ## Passaggi successivi * Consulta [`useGT`](/docs/react/api/strings/use-gt) per tradurre le stringhe all'interno dei componenti React. * Consulta [`msg`](/docs/react/api/strings/msg) per codificare le stringhe da tradurre in seguito.