docs/developer/extending-glossary.md

Étendre le glossaire contextuel

Le glossaire affiché dans le panneau latéral du rapport est défini en YAML, une entrée par terme, dans picarones/reports/html/glossary/{lang}.yaml.

Ajouter un terme

Éditez les deux fichiers fr.yaml et en.yaml (les tests vérifient la symétrie) :

my_new_metric:
  title: "Titre court — abréviation"
  definition: >-
    2-3 phrases de définition formelle. Tout en pur texte, pas de HTML.
  measures: >-
    Ce que la métrique mesure concrètement.
  usage: >-
    Cas d'usage factuels (pas prescriptifs : « utilisé en X » et non
    « à choisir si vous êtes Y »).
  limits: >-
    Limites connues, pièges fréquents.
  reference: >-
    Référence bibliographique canonique (auteur, année, titre).

Tous les champs (title, definition, measures, usage, limits, reference) sont obligatoires et non vides. Les tests (test_each_entry_has_required_fields) le vérifient.

Brancher l'entrée à une colonne du rapport

Dans picarones/reports/html/templates/view_ranking.html (ou un autre fichier de vue), ajoutez l'attribut data-glossary-key sur l'en-tête de colonne :

<th data-col="my_new_metric" class="sortable"
    data-glossary-key="my_new_metric"
    data-i18n="col_my_new_metric">Ma métrique</th>

Au démarrage du rapport, injectGlossaryButtons() parcourt tous les th[data-glossary-key] et ajoute un petit bouton ? cliquable.

Règles à respecter

1. Pas de HTML dans le contenu : le rendu côté JS utilise textContent pour les paragraphes (sécurité XSS). Si vous mettez du HTML, il sera affiché en clair.
2. Pas de prescription : le champ usage doit être factuel (« historiquement utilisé pour X ») et non prescriptif (« à choisir si vous voulez Y »). Picarones ne recommande jamais.
3. Référence vérifiable : citez un auteur/année réels. Les utilisateurs peuvent suivre la référence pour creuser.
4. Symétrie FR/EN : les deux fichiers doivent contenir les mêmes clés. Le test test_fr_and_en_have_same_keys casse en cas d'asymétrie.

Ajouter une langue

Créez picarones/reports/html/glossary/de.yaml avec la même structure que fr.yaml. Le loader le détecte automatiquement via Path.glob("*.yaml").

Pour qu'un utilisateur puisse choisir cette langue :

1. Ajouter picarones/reports/html/i18n/de.json (traductions de l'interface).
2. Aucune modification de code requise — load_glossary("de") marchera.

Tests

Le fichier tests/test_sprint21_glossary_customize.py couvre automatiquement :

• Chargement et fallback (langue inconnue → FR).
• Symétrie FR/EN.
• Présence des champs obligatoires.
• Termes critiques garantis (16 entrées dont CER, WER, Friedman, etc.).
• Pas de HTML dans le contenu.

Ajoutez votre nouvelle entrée à la liste critical du test test_critical_terms_are_documented si elle est référencée par une colonne du rapport — cela garantit qu'un futur refactor ne la supprime pas par accident.