Panoramica

gt-i18n ora supporta le traduzioni basate su dizionari tramite getTranslations(). In questo modo, gt-i18n si allinea a gt-next, gt-react e ad altre librerie i18n che usano i dizionari come approccio principale alla traduzione.

Configurazione

Crea un file dictionary.json nella radice del progetto con le stringhe sorgente (in inglese):

{
  "greeting": {
    "hello": "Hello!"
  },
  "user": {
    "welcome": "Welcome, {name}!"
  },
  "errors": {
    "notFound": "Page not found",
    "unauthorized": "Access denied"
  }
}

Quando esegui la CLI di GT (npx gtx translate), rileva automaticamente dictionary.json nella radice del progetto e lo traduce nelle impostazioni regionali configurate.

Utilizzo

Dato il dizionario sorgente sopra, chiama getTranslations() per ottenere una funzione t che risolve le voci del dizionario:

import { getTranslations } from 'gt-i18n';

const t = await getTranslations();

t('greeting.hello'); // "Ciao!"
t('user.welcome', { name: 'Alice' }); // "Benvenuta, Alice!"

Sottodizionari con t.obj()

t() restituisce una singola stringa. t.obj() restituisce un intero sottoalbero del dizionario sotto forma di oggetto:

const t = await getTranslations();

t('errors.notFound'); // "Pagina non trovata"

const errors = t.obj('errors');
// { notFound: "Pagina non trovata", unauthorized: "Accesso negato" }

Quando in un dizionario tradotto mancano delle chiavi, le voci mancanti vengono recuperate dal dizionario sorgente. Questo significa che le traduzioni parziali non causeranno errori in fase di runtime: per le chiavi non tradotte verrà usato come fallback il testo sorgente.

Comportamento dei lookup

Due regole disciplinano la risoluzione dei lookup:

1. Traduzione mancante → fallback all'impostazione regionale predefinita. Se una chiave esiste nel dizionario sorgente ma non ha una traduzione per l'impostazione regionale corrente, t() restituisce il testo sorgente.
2. Voce sorgente mancante → errore. Se una chiave non esiste affatto nel dizionario sorgente, t() genera un errore. È intenzionale: se una chiave non è definita nella sorgente, è un bug, non una traduzione mancante. Questo comportamento verrà applicato a tutte le librerie GT in un prossimo refactoring.

La seconda regola presuppone che i dizionari tradotti corrispondano alla struttura del dizionario sorgente, ed è così che GT genera automaticamente le traduzioni.

Link

• PR #1359
• Riferimento API per getTranslations
• Guida ai dizionari