Tenir une liste de ressources multilingue générée à partir de fichiers de données, sans éditer les pages à la main

## Comprendre que les pages de la liste sont générées à partir des fichiers de données Vous maintenez une base de connaissances organisée dont les sorties destinées aux humains sont **générées**, et non rédigées directement. Comprenez cette distinction avant de toucher à quoi que ce soit : - La **source de vérité** est un ensemble de fichiers de données structurées : une arborescence de catégories/sections (définissant les ancres et la table des matières) et un fichier d'entrées par section. - Les **artefacts générés** — les documents de listing lisibles par un humain (un par langue prise en charge) et tout index lisible par machine — sont produits à partir de ces données par un script générateur. Ils sont jetables et reconstruits à la demande. - Les mêmes données sous-jacentes peuvent aussi alimenter une interface d'interrogation en temps réel destinée à des agents automatisés ; la qualité des données a donc des consommateurs au-delà des documents générés. Il n'existe généralement ici ni environnement d'exécution applicatif, ni build, ni suite de tests. Chaque changement relève de l'une de ces trois catégories : données structurées, scripts d'outillage, ou documentation. Gardez ce modèle mental en tête — il évite l'erreur la plus courante et la plus dommageable : modifier une sortie qui sera écrasée. ## Modifier les données et régénérer les pages au lieu de les éditer - **Ne modifiez jamais directement un document de sortie généré.** Les modifications sont effacées à la prochaine régénération. Pour changer ce que voit un lecteur, modifiez les données sous-jacentes. - Pour ajouter ou modifier un élément, modifiez le fichier d'entrées de la section concernée. - Pour ajouter une nouvelle section, modifiez d'abord le fichier d'arborescence des catégories/sections, puis créez le fichier d'entrées correspondant. Exécutez ensuite l'outil de vérification des ancres pour confirmer qu'aucune ancre référencée en externe n'a été perdue. - Après toute modification de données, exécutez le générateur en local pour rafraîchir tous les fichiers générés avant de committer. L'intégration continue rejettera un arbre de travail qui diverge d'une sortie fraîchement générée — régénérez donc, ne devinez pas. - Ne modifiez pas l'index lisible par machine à la main ; il est entièrement régénéré par le générateur. ## Remplir les champs de chaque entrée et écrire une description d'une phrase Chaque entrée est un enregistrement structuré comportant des champs obligatoires (un identifiant unique stable, une URL, un titre, une catégorie, un type, un niveau de difficulté, un ensemble de langues, une date d'ajout, un statut) et des champs optionnels renseignés par l'automatisation (URL d'archive, horodatage de dernière vérification, empreinte du contenu). Respectez les vocabulaires contrôlés pour le type, la difficulté, la langue et le statut — n'inventez pas de valeurs. Considérez la description en texte libre accompagnant une entrée comme un **texte destiné au public, lisible par des tiers** : - **Incluez** une seule phrase factuelle décrivant ce qu'est la ressource, éventuellement suivie d'une mention de l'auteur. - **Excluez** tout ce qui est interne : références à ce projet, numéros de ticket ou de demande de changement, formulations du type « proposé à l'origine par », ou toute métadonnée historique. L'historique du contrôle de version préserve déjà l'attribution ; un lecteur extérieur ne doit pouvoir déduire aucun lien entre l'entrée et ce dépôt. - Laissez inchangées les valeurs migrées automatiquement, sauf si l'original est erroné ou obsolète. - N'excluez une entrée de l'archivage externe que lorsque l'auteur original l'a explicitement demandé (contenu payant, demande de retrait). ## Ne pas changer les noms de lien des sections pour ne pas casser les liens externes Les sites externes et la table des matières interne pointent tous deux vers des ancres nommées. Renommer ou supprimer une ancre existante casse silencieusement tous les liens entrants qui la ciblent. - **Ne renommez ni ne supprimez jamais une ancre existante.** Ajoutez plutôt de nouvelles ancres pour les nouvelles sections. - Un garde-fou d'intégration continue compare l'ensemble actuel des ancres à la référence et fait échouer le build si une ancre de référence vient à manquer. Considérez ce garde-fou comme une barrière stricte, pas une suggestion. - Comme le générateur trie les entrées de manière déterministe (par date d'ajout, puis par titre), ne réordonnez jamais les entrées en masse à la main. Pour faire remonter une entrée plus haut dans la liste, modifiez sa date d'ajout plutôt que de réarranger les enregistrements. ## Écrire le code et les notes dans une langue principale et choisir les éditions de chaque entrée Le contenu rédigé par le projet est écrit dans une langue principale unique. Plusieurs langues n'apparaissent que là où le multilinguisme est intrinsèque à l'artefact : documents de sortie traduits, surcharges localisées des titres de section, titres d'entrées préservant la langue d'origine de la ressource, et phrases déclencheuses destinées à s'activer sur des invites dans une langue non principale. Tout le reste — code, commentaires, noms de champs, modèles, sortie du pipeline, libellés, messages de commit — reste dans la langue principale. Une même entrée peut apparaître dans plusieurs éditions linguistiques, contrôlées par son ensemble de langues : - Nouvelle entrée sans indication de langue → listez-la uniquement dans la langue principale, et demandez au contributeur s'il la souhaite aussi dans d'autres éditions. - Ressource propre à une locale → étiquetez-la uniquement avec cette locale. - Ressource canonique véritablement transculturelle → étiquetez-la dans les langues pertinentes, ou utilisez le joker avec parcimonie. - Ne traduisez ni ne dupliquez jamais une entrée de force à travers les éditions dans le seul but de faire correspondre les structures. Chaque édition peut contenir des entrées que les autres n'ont pas. ## Intégrer les contributions sans perdre le crédit de leurs auteurs Les demandes entrantes se présentent sous deux formes et doivent être intégrées de façon à ce que le crédit ne soit jamais perdu : - **Proposition structurée (sans branche) :** intégrez l'entrée directement dans le modèle de données, régénérez, exécutez les vérificateurs, et committez avec une ligne de co-auteur créditant le soumetteur — cette ligne est son seul crédit. - **Demande de changement directe (le contributeur a modifié des fichiers sur sa propre branche) :** intégrez le travail *sur sa branche* afin que son changement soit fusionné avec l'attribution complète. Ne faites jamais transiter un changement direct de contributeur par un assistant de codage automatisé qui ouvrirait sa propre demande concurrente et fermerait celle du contributeur — cela détruirait son crédit de fusion. Un assistant de codage automatisé peut servir de **filet de secours asynchrone pour les propositions structurées uniquement**, lorsque le mainteneur est indisponible et que la file d'attente doit continuer d'avancer. Ce n'est pas le chemin par défaut ; un humain relit toujours le résultat avant la fusion. L'assistant fait gagner du temps de frappe, pas du jugement. ## Vérifier chaque changement automatiquement et laisser le robot de relecture seulement conseiller Pour chaque changement touchant aux données ou aux scripts du générateur, le pipeline doit : 1. Exécuter la validation du schéma et la validation des ancres. 2. Relancer le générateur et avertir si l'arbre de travail diverge d'une sortie fraîchement générée (signe que le contributeur a oublié de régénérer). 3. Invoquer un robot de revue automatisé qui note chaque nouvelle entrée selon une grille publiée, publie un commentaire structuré unique, et applique des étiquettes consultatives. Concevez le robot de revue avec prudence : détectez la langue du contributeur de manière déterministe (et non via le modèle) et transmettez-la comme directive ; en cas d'échec de l'appel au modèle, repli sur des vérifications déterministes d'accessibilité et de format sous une étiquette distincte « review-failed ». **Le robot ne fusionne jamais automatiquement et ne rejette jamais automatiquement** — il conseille, les humains décident. ## Ne jamais éditer les pages à la main et demander avant les changements non prévus Ne faites pas ce qui suit : - Modifier à la main les documents de sortie générés ou l'index lisible par machine. - Renommer ou supprimer des ancres existantes. - Introduire dans les modèles des balises au-delà de la liste blanche de balises autorisées par le projet. - Réordonner les entrées existantes en masse au lieu d'ajuster les clés de tri. - Modifier les directives de contribution, le code de conduite, ou les définitions de flux de travail sans demande explicite. - Créer des commits ou pousser des changements sans demande explicite. Lorsqu'un changement s'aventure dans un territoire que ces règles ne couvrent pas — une nouvelle édition linguistique, un nouveau champ de schéma, une nouvelle taxonomie de sections — arrêtez-vous et demandez plutôt que d'improviser. Restez fidèle à l'esprit du guide de contribution et de la grille de notation, et en cas de doute, confirmez avec un humain avant d'agir.