Retour
gt-i18ngt-nodedictionariesgetTranslationsi18n
BlogJournal des modifications

gt-i18n 0.9.0: Traductions basées sur un dictionnaire

Ernest McCarter

Vue d’ensemble

gt-i18n fournit désormais des traductions basées sur un dictionnaire pour les intégrations de frameworks. Dans les applications Node.js, utilisez l’export public getTranslations() de gt-node ; gt-i18n@0.9.0 ne l’exporte pas depuis la racine de son paquet.

PaquetVersion
gt-i18n0.9.0
gt-node0.7.0

Configuration

Créez un fichier dictionary.json à la racine de votre projet, contenant vos chaînes source (en anglais) :

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

Lorsque vous exécutez la CLI (npx gt translate), elle détecte dictionary.json à la racine du projet et le traduit pour les paramètres régionaux configurés.

Configurez le runtime Node.js avec initializeGT :

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

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

Utilisation

À partir du dictionnaire source ci-dessus, appelez getTranslations() pour obtenir une fonction t qui récupère les entrées de votre dictionnaire :

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

await withGT('en', async () => {
  const t = await getTranslations();

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

Sous-dictionnaires avec t.obj()

t() renvoie une seule chaîne de caractères. t.obj() renvoie tout un sous-arbre du dictionnaire sous forme d’objet :

// Dans le callback withGT ci-dessus :
t('errors.notFound'); // "Page not found"

const errors = t.obj('errors');
// { notFound: "Page not found", unauthorized: "Access denied" }

Lorsqu’un dictionnaire traduit contient des clés manquantes, les entrées absentes sont complétées à partir du dictionnaire source. Autrement dit, des traductions partielles ne provoqueront pas d’erreurs à l’exécution — les clés non traduites utilisent le texte source par défaut.

Comportement de résolution

Deux règles régissent la façon dont les recherches sont résolues :

  1. Traduction manquante → contenu de secours du paramètre régional par défaut. Si une clé existe dans le dictionnaire source mais n'a pas de traduction pour le paramètre régional actuel, t() renvoie le texte source.
  2. Entrée source manquante → erreur. Si une clé n'existe pas du tout dans le dictionnaire source, t() génère une erreur. C'est intentionnel : si une clé n'est pas définie dans votre source, c'est un bug, pas une traduction manquante. Ce comportement sera appliqué à toutes les bibliothèques GT dans une prochaine refactorisation.

La deuxième règle suppose que les dictionnaires traduits reprennent la structure de votre dictionnaire source, ce qui permet à GT de générer automatiquement les traductions.

Liens