i18n

Comment fonctionne la traduction de l’interface dans tous les clients

Table des matières

Aperçu

Chaque texte de l’interface Pankosmia est recherché par une clé dans un arbre de traduction partagé, de sorte que tous les clients (tableau de bord, paramètres, gestionnaires de contenu…) suivent la même langue. Une clé comporte trois parties reliées par des deux-points : <catégorie>:<section>:<nom>, par exemple pages:core-settings:title. La valeur associée à une clé contient une traduction par code de langue (en, fr, es, id…). Lorsqu’une clé est introuvable, c’est la clé elle-même qui est affichée.

Structure de l’arbre de traduction

Catégorie Contenu
pages Une section par client, nommée d’après l’id du client, alimentée par l’objet i18n de son pankosmia_metadata.json. Exemple : pages:core-settings:title.
library Textes des bibliothèques partagées comme la RCL. Exemple : library:pankosmia-rcl:required_field.
components Textes des éléments d’interface partagés (en-tête, messages du framework…). Exemple : components:framework:no_entry_if_offline.
branding Identité du produit. Exemple : branding:software:name.
scripture Noms des livres et des versifications.
munchers, crunchers, flavors, server, fonts Autres catégories du modèle, utilisées par certains gestionnaires de contenu et fonctions du serveur.

D’où viennent les textes

  • Le modèle : le fichier de base i18n.json de resource-core/templates. Le build de l’application de bureau le copie dans lib/templates/i18n.json. Il contient library, components, branding, scripture…
  • Chaque client : l’objet i18n de son pankosmia_metadata.json. Une clé title du client core-settings devient pages:core-settings:title.
  • Le produit : i18nPatch.json et i18n-overrides.json dans les globalBuildResources de l’application de bureau (voir plus bas).

Comment un client charge les traductions

Au démarrage d’un client, le composant SpSpa de la RCL demande /api/i18n/flat au serveur et conserve le résultat dans le contexte i18n. La réponse est une table plate clé vers texte, pour la langue choisie par l’utilisateur dans le client Paramètres (enregistrée via /api/settings/languages). Les composants la lisent avec i18nRef.current et recherchent une clé avec doI18n.

Utiliser les traductions dans le code

Les deux fonctions viennent de pankosmia-lib/i18n. doI18n(clé, source) renvoie le texte, ou la clé elle-même si elle est absente. doInterpolatedI18n(clé, valeurs, source) remplace les marqueurs %1%, %2%… d’un texte par un tableau de chaînes.

import { useContext } from "react";
import { i18nContext } from "pankosmia-rcl";
import { doI18n, doInterpolatedI18n } from "pankosmia-lib/i18n";

const { i18nRef } = useContext(i18nContext);

doI18n("pages:core-settings:title", i18nRef.current);

// "greeting": { "en": "Hello %1%, you have %2% books" }
doInterpolatedI18n(
  "pages:my-client:greeting",
  ["Ada", "3"],
  i18nRef.current,
);

doInterpolatedI18n est plus strict que doI18n : il lève une erreur si la clé est absente, si une valeur n’est pas une chaîne, si le nombre de valeurs diffère du nombre de marqueurs, ou si un marqueur est mal formé.

Ajouter un texte à un client

  1. Ajoutez la clé dans l’objet i18n du pankosmia_metadata.json du client, avec au moins la traduction en.
  2. Utilisez-la dans le code sous la forme pages:<id du client>:<clé>.
  3. Reconstruisez le client. Les autres langues peuvent être ajoutées dans le fichier ou avec l’éditeur de localisation.
{
  "id": "my-client",
  "i18n": {
    "title": { "en": "My client", "fr": "Mon client" }
  }
}

Éditeur de localisation

Le client core-client-i18n-editor (id i18n-editor) modifie tout l’arbre de traduction. Il le lit depuis /api/i18n/raw et l’enregistre par un POST vers /api/i18n. Il permet seulement de modifier les textes et d’ajouter ou supprimer des codes de langue. Il exige le mode débogage (require.debug vaut true) ; il est donc listé dans la section Débogage du menu.

Personnalisation au niveau du produit

Une application de bureau peut ajuster des textes sans toucher aux clients, avec deux fichiers de ses globalBuildResources :

  • i18nPatch.json : appliqué au build par buildCommon.js par-dessus templates/i18n.json. Chaque entrée doit déjà exister dans le modèle, sinon le build échoue. En pratique il ne contient que le nom du produit (branding.software.name.en), que le script app_setup maintient égal à APP_NAME.
  • i18n-overrides.json : copié vers app_resources/product/i18n-overrides.json. Il a le même rôle, avec la forme { "pages": { } } (vide par défaut).