HD2-雙語文檔驗證工具 是做什麼的?
English / 繁體中文
可靠度: 已在此驗證;兩個失敗模式皆經刻意觸發。
scripts/verify_translations.py 檢查翻譯不可變更的項目,讓審閱者能專注於文字品質,而非檢查程式碼範例是否仍然正確。
本工具誕生於此儲存庫為每個文件建立英文/中文成對的時候:六對 X.md / X_cn.md,其中中文版本中過時的程式碼區塊是沒人注意到的錯誤。
先決條件
| 需求 | 原因 | 若缺少時的情況 |
|---|---|---|
| Python 3.8+ | 執行腳本 | — |
lupa | 在真實 LuaJIT 上重新編譯翻譯後的 Lua 區塊(檢查 1) | 其餘五項檢查仍會執行;腳本會印出跳過的項目 |
| 文件成對,且位於儲存庫佈局中 | 探索會找到任何 X.md 及其旁邊的 X_cn.md,無論在樹狀結構的何處 | 可使用 --root 指定 |
無其他需求:無需遊戲、無需載入工具、無需網路連線。它不會寫入任何內容。
使用方式
python -B scripts/verify_translations.py # 掃描儲存庫根目錄
python -B scripts/verify_translations.py --root <repo> # 或指定一個目錄
python -B scripts/verify_translations.py --no-luajit # 強制降級模式
退出碼 0 = 所有成對文件通過;非零 = 至少一個失敗,並會顯示失敗的成對檔案名稱。
九項檢查
-
翻譯後的 Lua 仍可在 LuaJIT 上編譯 — 從翻譯版中提取每個
lua區塊並進行編譯。可捕獲在翻譯時誤動到程式碼的情況。 -
移除所有註解後,程式碼區塊與原始來源相符 — Lua 的
--和--[[ ]],shell/PowerShell 以及 Python 的#(行內# …註解是可翻譯的文字),偽程式碼的;。註解會被翻譯;程式碼則不會。 -
文件區塊作為文件進行比較 — 當一個區塊沒有可執行的程式碼時,即視為文件區塊,例如目錄樹/套件佈局、文字內容的
text區塊,或只包含 docstring 或註解的程式碼區塊。目錄樹按骨架比較(圖形符號、縮排、每行第一個詞彙),仍能捕獲遺漏的分支或重新命名的路徑;文字內容僅按行數比較,因為每個詞彙都會被翻譯。 -
標題結構相符 — 計算標題的數量與層級,並檢查順序。可捕獲遺漏的章節。
-
每個相對連結都被保留,或被刻意重新導向至
_cn的對應檔案(會回報為註記,而非失敗)。原始來源指向_cn檔案而翻譯版正是該_cn檔案的情況同樣會回報為註記。 -
Frontmatter 保持完整 — 相同的鍵值,
name:保持不變(它是一個識別碼),而description:被翻譯(這是讀者選擇技能時看到的內容)。 -
語言切換器存在、僅出現一次,並指向對應版本 — 在雙方的開頭區塊中,當前語言不帶連結:
繁體中文 / [简体中文](https://github.com/Puipipi/HD2-Agent-Skills/blob/main/README_cn.md) [English](https://github.com/Puipipi/HD2-Agent-Skills/blob/main/README.md) / 繁體中文使用絕對 URL 是刻意為之——複製自 DeepSeek 自己的儲存庫,因為切換器是讀者在瀏覽其他內容之前所需的第一個連結。此項檢查是強制執行而非僅是信任:移除它、指向錯誤的檔案,或在開頭區塊中留下兩個,都會導致執行失敗。
-
每個技能檔案都帶有自己的切換器,即使尚未有翻譯版本 — 對
skills/下的每個SKILL.md和SKILL_cn.md進行獨立檢查,不依賴成對關係。成對迴圈僅在雙方的檔案都存在時執行,因此若一個技能只有英文檔案而無翻譯版本,則會完全逃過此檢查:這正是五個英文技能檔案沒有切換器,而其對應的中文檔案卻有的原因。 -
絕對 GitHub URL 目標必須可解析 — 由
check_absolute_targets()回報,因為切換器慣例上使用絕對 URL,而缺少對應版本會導致渲染頁面上出現無人注意的死連結。
內建的兩項經驗教訓
- 一個假設佈局顯而易見的驗證器會回報虛假失敗。 第一個版本只會移除整行註解,因此每個包含尾部
--註解的程式碼區塊看起來都不匹配。修正驗證器而非翻譯是正確的做法——而且只有在失敗次數高得不合理時才會顯而易見。同樣的情況隨後又發生了兩次:一個Python區塊中的行內#註解(移除器只知道 shell),以及一個只引用了docstring的python區塊(完全沒有可執行的程式碼,因此整個區塊都是文字內容)。每次修正都讓檢查 3 變得更精確、更真實:將程式碼作為程式碼比較,將文件作為文件比較,並根據內容而非區塊標籤來決定比較方式。 - 檢查 3 的存在同樣是因為一個虛假失敗。 一個新技能中的四個「程式碼」區塊實際上是目錄樹;將其翻譯後的註釋視為程式碼變更會迫使譯者將文字內容保留為英文。
當驗證器回報失敗時,請先查看失敗原因,再修改翻譯。 在上述三個案例中,翻譯都是正確的——包括其中一個「程式碼」是解釋部署事件的 docstring,且被刻意翻譯的情況。一個出錯的 linter 比沒有 linter 更糟糕:它會讓人學會忽略它。
限制
- 它驗證的是結構一致性,而非翻譯是否正確。錯誤翻譯的句子會通過所有檢查。請閱讀文字內容。
- 檢查 3 的結構指紋設計上會忽略註釋文字,因此若翻譯將路徑的描述替換為錯誤內容,將無法被發現。
- 它僅能識別
discover_pairs()中定義的佈局;組織方式不同的儲存庫需要擴展該函數。
另請參閱
writing-mod-tools(誠實的降級、退出碼、說明工具無法做到的事)。