Vue d’ensemble

gt-i18n prend désormais en charge les traductions basées sur un dictionnaire via getTranslations(). gt-i18n s’aligne ainsi sur gt-next, gt-react et les autres bibliothèques d’i18n qui utilisent les dictionnaires comme principal mode de traduction.

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 de GT (npx gtx translate), elle détecte automatiquement dictionary.json à la racine du projet et le traduit pour les paramètres régionaux configurés.

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 } from 'gt-i18n';

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 :

const t = await getTranslations();

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

• PR #1359
• Référence de l’API getTranslations
• Guide des dictionnaires