Communitygithub.com

Puipipi/HD2-Agent-Skills

Garantir la cohérence d'un ensemble de documents bilingues — vérifier qu'un fichier Markdown traduit correspond toujours à sa source en recompilant ses blocs Lua sur LuaJIT, en comparant les blocs de code après suppression des commentaires, en faisant correspondre la structure des titres et des liens, et en comparant les arborescences de dossiers par structure plutôt que par texte. À utiliser après avoir modifié l'un des deux fichiers d'une paire de documentation, ou lorsque les traductions commencent à dériver du code.

Qu'est-ce que HD2-Agent-Skills ?

Cette compétence propose un script de vérification (`scripts/verify_translations.py`) conçu pour maintenir l'intégrité structurelle entre des paires de documents Markdown bilingues (par exemple, `X.md` et `X_cn.md`). Elle exécute neuf contrôles automatisés pour s'assurer que la traduction n'altère pas les éléments techniques essentiels : les blocs de code Lua sont recompilés sur un vrai interpréteur LuaJIT (via `lupa`), les blocs de code sont comparés après suppression des commentaires traduisibles, la structure des titres et des liens relatifs est préservée, et les arborescences de dossiers sont comparées par squelette plutôt que par texte. Le script peut fonctionner en mode dégradé si `lupa` n'est pas installé, et il ne modifie aucun fichier sur le disque. Il est particulièrement utile pour les dépôts où la documentation bilingue (anglais et chinois simplifié) doit rester synchronisée, comme dans le cadre du projet HD2-Agent-Skills. Les échecs de vérification indiquent des problèmes structurels, pas des erreurs de traduction du contenu textuel ; ainsi, l'attention des réviseurs peut se concentrer sur la qualité de la prose.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Puipipi/HD2-Agent-Skills/tree/HEAD/skills/hd2-bilingual-doc-verify

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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

BesoinPourquoiSi absent
Python 3.8+le script—
luparecompile 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ôtla découverte trouve tout X.md avec un X_cn.md à côté, n'importe où dans l'arborescencepointez-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

  1. Le Lua traduit se compile toujours sur LuaJIT — extrait chaque bloc lua de la traduction et le compile. Détecte une traduction qui a touché au code.

  2. 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.

  3. 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 text de 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.

  4. La structure des titres correspond — nombre et niveaux, dans l'ordre. Détecte une section supprimée.

  5. 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 _cn que la traduction est est également une note.

  6. Le frontmatter est intact — mêmes clés, name: inchangé (c'est un identifiant), et description: traduit (c'est ce qu'un lecteur voit lors du choix de la compétence).

  7. 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.

  8. Chaque fichier de compétence porte son propre sélecteur, même sans traduction encore — vérifié pour chaque SKILL.md et SKILL_cn.md sous skills/, 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.

  9. 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 bloc python qui 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).

Skills associés