Indietro
gt-i18ngt-nodedictionariesgetTranslationsi18n
BlogRegistro delle modifiche

gt-i18n 0.9.0: Traduzioni basate su dizionari

Ernest McCarter

Panoramica

gt-i18n ora fornisce traduzioni basate su dizionari per le integrazioni con i framework. Nelle applicazioni Node.js, usa l'export pubblico getTranslations() di gt-node; gt-i18n@0.9.0 non lo esporta dalla radice del proprio pacchetto.

PacchettoVersione
gt-i18n0.9.0
gt-node0.7.0

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 (npx gt translate), rileva dictionary.json nella radice del progetto e lo traduce nelle impostazioni regionali configurate.

Configura il runtime Node.js con initializeGT:

import { initializeGT } from 'gt-node';
import dictionary from './dictionary.json';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es'],
  dictionary,
});

Utilizzo

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

import { getTranslations, withGT } from 'gt-node';

await withGT('en', async () => {
  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:

// All'interno del callback withGT qui sopra:
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.