Skip to content

i18n.md

Latest commit

 

History

History
96 lines (76 loc) · 4.23 KB

i18n.md

File metadata and controls

96 lines (76 loc) · 4.23 KB
Raw

Internationalisation (gettext)

Introduite par l'issue #50, sur le modèle de Gcm4 (mêmes 29 langues).

Principe

  • Langue source : le français. Les chaînes destinées à l'utilisateur (aide de la CLI, messages de journal info/warning/error, messages d'exception) sont écrites en français et passent par _() de oxo_hep_bridge.i18n (ngettext() pour les pluriels).
  • Comportement par défaut inchangé : sans catalogue pour la langue demandée, ou sans traduction d'une chaîne, le texte français d'origine est affiché (gettext.translation(..., fallback=True)).
  • Choix de la langue : variables standard LANGUAGE, LC_ALL, LC_MESSAGES, LANG (ex. LANGUAGE=de_DE oxo-hep-bridge --help).
  • Paramètres nommés : une chaîne avec variables s'écrit _("Longueur de chunk invalide : {length}").format(length=n) (jamais une f-string, que xgettext ne sait pas extraire), afin que le traducteur puisse déplacer les variables. Les messages de journal gardent les {} positionnels de loguru.
  • Les messages debug() ne sont pas traduits (diagnostic développeur).
  • tests/test_i18n.py échoue si une chaîne utilisateur littérale n'est pas enveloppée dans _().

Fichiers

Fichier Rôle
lang/LINGUAS Seule liste des langues maintenues (une par ligne)
lang/messages.pot Modèle extrait des sources par xgettext
lang/<langue>.po Catalogue d'une langue (édité par les traducteurs)
src/oxo_hep_bridge/locale/<langue>/LC_MESSAGES/oxo-hep-bridge.mo Catalogue compilé, embarqué dans le paquet ([tool.setuptools.package-data])
tools/i18n.py Outillage : extract, update, compile, check, report
.github/workflows/i18n.yml Vérification en CI, rapport, PR de mise à jour optionnelle

Aucune liste de langues n'est codée dans le paquet : il charge ce que contient locale/, et tools/i18n.py lit lang/LINGUAS.

Commandes

Les outils GNU gettext sont nécessaires (apt-get install gettext).

make i18n-update   # extrait les chaînes, fusionne chaque .po, compile les .mo
make i18n-check    # échoue si .pot/.po/.mo ne sont pas à jour ou invalides
make i18n-report   # taux de traduction

Après avoir ajouté ou modifié une chaîne utilisateur dans le code : lancer make i18n-update et committer lang/ et src/oxo_hep_bridge/locale/. Les nouvelles chaînes arrivent avec msgstr "" dans toutes les langues : aucune traduction automatique, une chaîne reste en français tant qu'une personne ne l'a pas traduite. update ne réécrit pas un fichier dont les messages n'ont pas changé (les dates d'en-tête sont ignorées), donc pas de diff parasite.

make i18n-check (lancé par la CI) signale :

  • un .po invalide (msgfmt --check : syntaxe, formats incohérents) ;
  • un messages.pot qui ne correspond plus aux sources (chaîne ajoutée, modifiée ou supprimée) ;
  • un .po non synchronisé avec les sources, ou qui référence un fichier supprimé ;
  • une langue déclarée dans LINGUAS sans .po, ou un .po absent de LINGUAS ;
  • un .mo absent ou périmé par rapport à son .po.

Ajouter une langue

  1. Ajouter son code (ex. es_ES) sur une ligne de lang/LINGUAS.
  2. make i18n-update : crée lang/es_ES.po (en-tête et Plural-Forms remplis par msginit, tous les msgstr vides) et son .mo.
  3. Traduire les msgstr de lang/es_ES.po (Poedit, Lokalize ou un éditeur de texte), puis relancer make i18n-update.
  4. Committer lang/LINGUAS, lang/es_ES.po et src/oxo_hep_bridge/locale/es_ES/.

Traduire

Éditer lang/<langue>.po, remplir les msgstr, conserver les variables ({length}, {}) telles quelles, puis make i18n-update et make i18n-check. Retirer la marque #, fuzzy d'une entrée après l'avoir vérifiée.

Workflow i18n

.github/workflows/i18n.yml tourne sur les push et PR vers dev et main :

  1. publie le rapport (langues, messages, traduits, non traduits, fuzzy, catalogues valides) dans le résumé du run ;
  2. échoue si tools/i18n.py check signale un problème.

En déclenchement manuel (workflow_dispatch, case « Ouvrir une PR »), un second job lance update + compile sur dev et ouvre une PR vers dev si les catalogues ont changé.