hd2-bilingual-doc-verify
Englisch / 简体中文
Vertrauenswürdigkeit: hier verifiziert; beide Fehlermodi wurden bewusst provoziert.
scripts/verify_translations.py überprüft die Dinge, die eine Übersetzung nicht ändern darf, damit die Review-Aufmerksamkeit der Prosa gelten kann, statt der Frage, ob ein Codebeispiel noch korrekt ist.
Geschrieben, nachdem dieses Repository für jedes Dokument ein englisch/chinesisches Paar bekam: sechs Paare von X.md / X_cn.md, bei denen ein veralteter Codeblock in der chinesischen Kopie ein Fehler ist, den niemand bemerkt.
Voraussetzungen
| Benötigt | Warum | Falls fehlend |
|---|---|---|
| Python 3.8+ | das Skript | — |
lupa | kompiliert die übersetzten Lua-Blöcke auf echtem LuaJIT (Prüfung 1) | die anderen fünf Prüfungen laufen trotzdem; das Skript gibt aus, was es übersprungen hat |
| die Paare, in einem Repository-Layout | die Erkennung findet jedes X.md mit einem danebenliegenden X_cn.md, irgendwo im Baum | mit --root darauf zeigen |
Sonst nichts: kein Spiel, keine Lade-Werkzeuge, kein Netzwerk. Es schreibt nichts.
Verwendung
python -B scripts/verify_translations.py # Repository-Stamm scannen
python -B scripts/verify_translations.py --root <repo> # oder auf ein bestimmtes zeigen
python -B scripts/verify_translations.py --no-luajit # abgeschwächten Modus erzwingen
Exit 0 = jedes Paar bestanden; ungleich Null = mindestens eines fehlgeschlagen, mit Nennung des Paars.
Die neun Prüfungen
-
Übersetztes Lua lässt sich noch auf LuaJIT kompilieren – extrahiert jeden
lua-Fence aus der Übersetzung und kompiliert ihn. Erwischt eine Übersetzung, die Code berührt hat. -
Code-Fences stimmen mit dem Quelltext überein, nachdem alle Kommentare entfernt wurden –
--und--[[ ]]für Lua,#für Shell/PowerShell und Python (ein inline# …-Kommentar ist übersetzbarer Text),;für Pseudocode. Kommentare werden übersetzt; Code nicht. -
Dokumentations-Fences werden als Dokumentation verglichen – ein Fence gilt als Dokumentation, wenn er keinen ausführbaren Code enthält, also ein Verzeichnisbaum / Paketlayout, ein
text-Block aus Prosa oder ein Code-Fence, der nur einen Docstring oder Kommentare zitiert. Bäume werden anhand des Skeletts verglichen (Glyphen, Einrückung, erstes Token pro Zeile), was immer noch einen fehlenden Ast oder einen umbenannten Pfad erwischt; Prosa wird nur anhand der Zeilenanzahl verglichen, weil jedes Wort übersetzt ist. -
Überschriftenstruktur stimmt überein – Anzahl und Ebenen, in der Reihenfolge. Erwischt einen fehlenden Abschnitt.
-
Jeder relative Link wird übernommen oder absichtlich auf einen
_cn-Partner umgeleitet (als Hinweis gemeldet, nicht als Fehler). Der Quelltext, der auf eine_cn-Datei zeigt, die die Übersetzung ist, ist ebenfalls ein Hinweis. -
Frontmatter ist intakt – gleiche Schlüssel,
name:unverändert (es ist ein Identifikator), unddescription:übersetzt (es ist das, was ein Leser sieht, wenn er die Fähigkeit auswählt). -
Der Sprachumschalter existiert, einmal, und zeigt auf das Gegenstück – im Kopfblock beider Seiten, wobei die aktuelle Sprache unverlinkt bleibt:
Englisch / [简体中文](https://github.com/Puipipi/HD2-Agent-Skills/blob/main/README_cn.md) [English](https://github.com/Puipipi/HD2-Agent-Skills/blob/main/README.md) / 简体中文Absolute URLs sind beabsichtigt – aus DeepSeek-eigenen Repositories kopiert, weil der Umschalter der eine Link ist, den ein Leser braucht, bevor er etwas anderes navigieren kann. Er wird geprüft, nicht vertraut: Entfernen, auf die falsche Datei zeigen oder zwei im Kopf belassen – alles führt zum Fehlschlagen des Durchlaufs.
-
Jede Fähigkeitsdatei trägt ihren eigenen Umschalter, auch ohne Übersetzung – geprüft für jede
SKILL.mdundSKILL_cn.mdunterskills/, unabhängig von der Paarbildung. Die Paarschleife läuft nur, wenn beide Seiten existieren, sodass eine Fähigkeit mit einer englischen Datei und ohne Übersetzung ihr vollständig entgeht: Genau so endeten fünf englische Fähigkeiten ohne Umschalter, während ihre chinesischen Dateien einen hatten. -
Absolute GitHub-URL-Ziele müssen auflösbar sein – gemeldet von
check_absolute_targets(), weil die Umschalter konventionsgemäß absolute URLs verwenden und ein fehlendes Gegenstück sonst ein toter Link auf der gerenderten Seite ist, den niemand bemerkt.
Zwei daraus gelernte Lektionen
- Ein Verifizierer, der das offensichtliche Layout annimmt, meldet falsche Fehlschläge. Die erste Version entfernte nur ganze Zeilen-Kommentare, sodass jeder Codeblock mit einem nachgestellten
---Kommentar wie eine Abweichung aussah. Den Verifizierer zu korrigieren, nicht die Übersetzungen, war die richtige Entscheidung – und sie war nur offensichtlich, weil die Fehleranzahl unglaubwürdig hoch war. Dasselbe passierte dann noch zweimal: ein inline#-Kommentar in einem Python-Fence (der Stripper kannte nur Shell) und einpython-Fence, der nur einen Docstring zitierte (überhaupt kein ausführbarer Code, also ist der ganze Block Prosa). Jede Korrektur machte Prüfung 3 enger und wahrer: Code als Code vergleichen, Dokumentation als Dokumentation, und das anhand des Inhalts entscheiden, nicht anhand der Fence-Beschriftung. - Prüfung 3 existiert wegen eines weiteren Fehlalarms. Vier „Code“-Fences in einer neuen Fähigkeit waren Verzeichnisbäume; ihre übersetzten Anmerkungen als Code-Änderung zu behandeln, hätte den Übersetzer gezwungen, Prosa auf Englisch zu lassen.
Wenn ein Verifizierer Fehlschläge meldet, betrachten Sie die Fehlschläge, bevor Sie die Übersetzung anfassen. In allen drei oben genannten Fällen waren die Übersetzungen korrekt – einschließlich des einen, bei dem der „Code“ ein Docstring war, der den Bereitstellungsvorfall erklärte, absichtlich übersetzt. Ein Linter, der falsch liegt, kostet mehr als kein Linter: Er lehrt die Leute, ihn zu ignorieren.
Einschränkungen
- Es beweist strukturelle Übereinstimmung, nicht dass die Übersetzung korrekt ist. Ein falsch übersetzter Satz besteht jede Prüfung. Lesen Sie die Prosa.
- Der strukturelle Fingerabdruck von Prüfung 3 ignoriert bewusst Annotationstext, sodass eine Übersetzung, die die Beschreibung eines Pfades durch etwas Falsches ersetzt hat, nicht erwischt wird.
- Es kennt nur die Layouts in
discover_pairs(); ein anders organisiertes Repository benötigt eine Erweiterung dieser Funktion.
Siehe auch
writing-mod-tools (ehrliche Degradierung, Exit-Codes, Angabe, was ein Werkzeug nicht kann).