hd2-bilingual-doc-verify
English / 简体中文
Confiance : vérifié ici ; ses deux modes d'échec ont été provoqués délibérément.
scripts/verify_translations.py vérifie les éléments qu'une traduction ne doit pas modifier, afin que l'attention de la relecture puisse se porter sur la prose plutôt que sur l'exactitude d'un exemple de code.
Écrit après que ce dépôt s'est doté d'une paire anglais/chinois pour chaque document : six paires de X.md / X_cn.md, où un bloc de code obsolète dans la copie chinoise est un bogue que personne ne remarque.
Prérequis
| Besoin | Pourquoi | Si absent |
|---|---|---|
| Python 3.8+ | le script | — |
lupa | recompile les blocs Lua traduits sur un vrai LuaJIT (vérification 1) | les cinq autres vérifications sont quand même exécutées ; le script affiche ce qu'il a ignoré |
| les paires, dans une structure de dépôt | la découverte trouve tout X.md avec un X_cn.md à côté, n'importe où dans l'arborescence | pointez-le avec --root |
Rien d'autre : pas de jeu, pas d'outils de chargement, pas de réseau. Il n'écrit rien.
Utilisation
python -B scripts/verify_translations.py # analyse la racine du dépôt
python -B scripts/verify_translations.py --root <repo> # ou pointez vers un dépôt
python -B scripts/verify_translations.py --no-luajit # force le mode dégradé
Code de sortie 0 = chaque paire a réussi ; non nul = au moins une a échoué, avec le nom de la paire.
Les neuf vérifications
-
Le Lua traduit se compile toujours sur LuaJIT — extrait chaque bloc
luade la traduction et le compile. Détecte une traduction qui a touché au code. -
Les blocs de code correspondent à la source après suppression de tous les commentaires —
--et--[[ ]]pour Lua,#pour shell/PowerShell et Python (un commentaire# …en ligne est un texte traduisible),;pour le pseudo-code. Les commentaires sont traduits ; le code ne l'est pas. -
Les blocs de documentation sont comparés en tant que documentation — un bloc est considéré comme de la documentation lorsqu'il ne contient pas de code exécutable, c'est-à-dire une arborescence de dossiers / une structure de package, un bloc
textde prose, ou un bloc de code qui ne contient qu'une docstring ou des commentaires. Les arborescences sont comparées par squelette (glyphes, indentation, premier jeton par ligne), ce qui détecte toujours une branche supprimée ou un chemin renommé ; la prose est comparée uniquement par nombre de lignes, car chaque mot est traduit. -
La structure des titres correspond — nombre et niveaux, dans l'ordre. Détecte une section supprimée.
-
Chaque lien relatif est repris, ou est délibérément redirigé vers un homologue
_cn(signalé comme une note, pas un échec). La source pointant vers un fichier_cnque la traduction est est également une note. -
Le frontmatter est intact — mêmes clés,
name:inchangé (c'est un identifiant), etdescription:traduit (c'est ce qu'un lecteur voit lors du choix de la compétence). -
Le sélecteur de langue existe, une fois, et pointe vers la contrepartie — dans le bloc d'en-tête des deux côtés, avec la langue actuelle non liée :
English / [简体中文](https://github.com/Puipipi/HD2-Agent-Skills/blob/main/README_cn.md) [English](https://github.com/Puipipi/HD2-Agent-Skills/blob/main/README.md) / 简体中文Les URL absolues sont délibérées — copiées des propres dépôts de DeepSeek, car le sélecteur est le seul lien dont un lecteur a besoin avant de pouvoir naviguer dans le reste. Il est vérifié plutôt que supposé fiable : en supprimer un, le pointer vers le mauvais fichier, ou en laisser deux dans l'en-tête font tous échouer l'exécution.
-
Chaque fichier de compétence porte son propre sélecteur, même sans traduction encore — vérifié pour chaque
SKILL.mdetSKILL_cn.mdsousskills/, indépendamment de l'appariement. La boucle d'appariement ne s'exécute que lorsque les deux côtés existent, donc une compétence avec un fichier anglais et pas de traduction y échappe complètement : c'est exactement ainsi que cinq compétences anglaises se sont retrouvées sans sélecteur alors que leurs fichiers chinois en avaient un. -
Les cibles d'URL GitHub absolues doivent être résolubles — signalé par
check_absolute_targets(), car les sélecteurs utilisent des URL absolues par convention et un homologue manquant est autrement un lien mort sur la page rendue que personne ne remarque.
Deux leçons tirées de l'expérience
- Un vérificateur qui suppose une structure évidente signale de faux échecs. La première version ne supprimait que les commentaires de ligne entière, donc chaque bloc de code contenant un commentaire
--en fin de ligne semblait être une divergence. Corriger le vérificateur, et non les traductions, était la bonne décision — et cela n'était évident que parce que le nombre d'échecs était invraisemblablement élevé. La même chose s'est ensuite produite deux fois de plus : un commentaire#en ligne dans un bloc Python (le suppresseur ne connaissait que le shell), et un blocpythonqui ne contenait qu'une docstring (pas de code exécutable du tout, donc tout le bloc est de la prose). Chaque correction a rendu la vérification 3 plus précise et plus fiable : comparer le code en tant que code, et la documentation en tant que documentation, et décider cela à partir du contenu plutôt que du libellé du bloc. - La vérification 3 existe à cause d'un faux positif également. Quatre blocs de "code" dans une nouvelle compétence étaient des arborescences de dossiers ; traiter leurs annotations traduites comme un changement de code aurait obligé le traducteur à laisser la prose en anglais.
Lorsqu'un vérificateur signale des échecs, regardez les échecs avant de toucher à la traduction. Dans les trois cas ci-dessus, les traductions étaient correctes — y compris celle où le "code" était une docstring expliquant l'incident de déploiement, traduite intentionnellement. Un linter qui a tort coûte plus cher que pas de linter du tout : il apprend aux gens à l'ignorer.
Limitations
- Il prouve une correspondance structurelle, pas que la traduction est correcte. Une phrase mal traduite réussit tous les contrôles. Lisez la prose.
- La vérification 3 ignore intentionnellement le texte d'annotation dans l'empreinte structurelle, donc une traduction qui a remplacé la description d'un chemin par quelque chose d'erroné n'est pas détectée.
- Il ne connaît que les structures définies dans
discover_pairs(); un dépôt organisé différemment nécessite d'étendre cette fonction.
Voir aussi
writing-mod-tools (dégradation honnête, codes de sortie, mention de ce qu'un outil ne peut pas faire).