Utilisation

Initialiser

import Hermes from '@fca.gg/hermes';

Hermes.init();

init() ne prend pas d'argument : il lit hermes.config.js s'il existe, puis le fichier translations.json du dossier de build. Lancez donc hermes build avant. Appeler init() une seconde fois lève une erreur.

La langue par défaut est la première de fallbackChains.default (en-US si vous ne la changez pas). Si elle ne figure pas dans les traductions, init() lève une erreur.

Obtenir un contexte

Une traduction se lit toujours à travers le contexte d'une langue :

const ctx = Hermes.getContext('en-US');

ctx.t('hello'); // "Hello World!"
ctx.t('nested.key'); // "This is a nested key"
ctx.lang; // "en-US"

• getContext('default') renvoie le contexte de la langue par défaut.
• Une langue absente des traductions retombe sur la langue par défaut.
• t() est un alias de translate().

Clé introuvable

Si une clé n'existe pas dans la langue du contexte, t() lève une erreur. Le build complète déjà les clés manquantes avec les langues de repli et vous prévient des manques : gardez checkTranslations activé.

Passer des variables

Le second argument de t() fournit les valeurs des variables et des expressions :

ctx.t('greeting', {name: 'Alice'});

La syntaxe complète est décrite dans le formatage.

Portée

Le second argument de getContext() fixe une portée : un préfixe ajouté à toutes les clés, pratique pour un module ou une commande.

const ctx = Hermes.getContext('en-US', 'nested');

ctx.t('key'); // équivaut à 'nested.key'

La portée est jointe à la clé par un point.

Fichiers imbriqués

Une langue peut être répartie dans un dossier, sur plusieurs niveaux :

locales/
  en-US.json
  fr.json
  en-GB/
    common.json
    auth.json
    features/
      feature1.json
      feature2.json

Le build fusionne ces fichiers en une seule structure à plat. Les clés reprennent le chemin des fichiers :

const ctx = Hermes.getContext('en-GB');

ctx.t('common.key');
ctx.t('features.feature1.key');

Le séparateur dépend de l'option keys.

Objets localisés

getLocalizedObject() renvoie la valeur d'une clé dans toutes les langues qui la contiennent. C'est le format attendu par Discord pour les noms et descriptions de commandes localisés.

const names = Hermes.getLocalizedObject('commands.ping.name');
// { "en-US": "ping", "fr": "ping", "de": "ping", ... }

Le type renvoyé est LocalizedObject, soit Partial<Record<Langs, string>>. Si aucune langue ne contient la clé, la méthode lève une erreur.