Communitygithub.com

Puipipi/HD2-Agent-Skills

バイリンガルドキュメントセットの整合性を検証します。翻訳されたMarkdownファイルがソースと一致しているか、Luaブロックの再コンパイル、コードフェンスの比較、見出し構造やリンクのチェック、ディレクトリツリーの構造比較などを行います。翻訳編集の後や、翻訳がコードからずれてきたときに使用します。

HD2-Agent-Skills とは?

このスキルは、英語と中国語のバイリンガルドキュメントペア(例:`X.md`と`X_cn.md`)の整合性を自動検証するツール`scripts/verify_translations.py`を提供します。翻訳によってLuaコードブロックが変更されていないか(LuaJITで再コンパイル)、コードフェンスがコメント除去後に一致するか、見出し構造や相対リンクが保持されているか、ドキュメント用フェンス(ディレクトリツリーやプローズ)が構造的に正しく翻訳されているかなど、9つのチェックを実行します。また、言語切り替えリンクの存在確認や絶対URLの到達性チェックも行います。スキルはcheck 3で「コードはコードとして、ドキュメントはドキュメントとして」比較するという設計思想を持ち、偽陽性を減らす工夫がされています。検証失敗時は翻訳を修正する前に出力を確認するよう促します。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

hd2-bilingual-doc-verify

English / 简体中文

信頼性: ここで検証済み。両方の障害モードは意図的に誘発されました。

scripts/verify_translations.py は翻訳が変更してはならない項目をチェックするため、レビュー担当者はコードサンプルが正しいかどうかではなく、文章に注意を集中できます。

このリポジトリがすべてのドキュメントに英語/中国語のペアを持つようになった(X.md / X_cn.md のペアが6つ)後に作成されました。中国語版のコードブロックが古いままだと、誰も気づかないバグになります。

前提条件

必要なもの理由欠けている場合
Python 3.8+スクリプトそのもの—
lupa翻訳されたLuaブロックを実際のLuaJITで再コンパイル(チェック1)他の5つのチェックは実行され、スクリプトはスキップした内容を表示します
ペア、リポジトリ構造内探索により、ツリー内の任意の場所にある 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 = すべてのペアが合格。非ゼロ = 少なくとも1つのペアが失敗し、そのペア名が表示されます。

9つのチェック

  1. 翻訳されたLuaがLuaJITでコンパイルできる — 翻訳からすべての lua フェンスを抽出してコンパイルします。翻訳がコードに触れた場合に検出します。
  2. すべてのコメントを削除した後、コードフェンスがソースと一致する — Luaの -- と --[[ ]]、シェル/PowerShellおよびPythonの #(インラインの # … コメントは翻訳可能なテキストです)、疑似コードの ;。コメントは翻訳されますが、コードは翻訳されません。
  3. ドキュメンテーションフェンスはドキュメントとして比較される — フェンスが実行可能コードを含まない場合(ディレクトリツリー/パッケージレイアウト、プローズの text ブロック、ドキュメント文字列またはコメントのみを引用するコードフェンス)、ドキュメントとしてカウントされます。ツリーは骨格(グリフ、インデント、行の最初のトークン)で比較され、ブランチの欠落やパスの名前変更を検出します。プローズは単語数でのみ比較されます。すべての単語が翻訳されるためです。
  4. 見出し構造が一致する — 数とレベルを順番に比較します。セクションの欠落を検出します。
  5. すべての相対リンクが引き継がれているか、意図的に _cn の対応物にリダイレクトされている(ノートとして報告され、失敗ではありません)。ソースが _cn ファイルを指している場合、翻訳がそのファイルであることもノートとして報告されます。
  6. フロントマターがそのままである — 同じキー、name: は変更されていない(識別子です)、description: は翻訳されている(スキル選択時に読者が見るものです)。
  7. 言語切り替えリンクが存在し、一度だけ表示され、対応する言語を指している — 両方のファイルのヘッダーブロックにあり、現在の言語はリンクなしで表示されます:
    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) / 简体中文
    
    絶対URLは意図的です — DeepSeek自身のリポジトリからコピーされました。切り替えリンクは読者が他の場所に移動する前に必要とする唯一のリンクだからです。チェックは信頼ではなく検証です:リンクを削除する、間違ったファイルを指す、ヘッダーに2つ残す、いずれもテストに失敗します。
  8. すべてのスキルファイルは、まだ翻訳がなくても独自の切り替えリンクを持つ — ペアリングとは無関係に、skills/ 以下のすべての SKILL.md および SKILL_cn.md に対してチェックされます。ペアループは両方のファイルが存在する場合のみ実行されるため、英語ファイルのみで翻訳がないスキルは完全にチェックを免れます:まさにそのようにして、中国語ファイルには切り替えリンクがある一方で、5つの英語スキルが切り替えリンクなしで終わっていました。
  9. 絶対的なGitHub URLのターゲットが解決可能である — check_absolute_targets() によって報告されます。なぜなら、切り替えリンクは慣例的に絶対URLを使用しており、対応するファイルがないとレンダリングされたページでデッドリンクになり、誰も気づかないからです。

組み込まれた2つの教訓

  • 明白なレイアウトを想定する検証ツールは誤った失敗を報告する。 最初のバージョンは行全体のコメントのみを削除していたため、末尾に -- コメントがあるコードブロックはすべて不一致に見えました。翻訳ではなく検証ツールを修正するのが正しい判断でした。失敗数が信じがたいほど多かったからです。同様のことがさらに2回発生しました:Python フェンス内のインライン # コメント(削除ツールはシェルしか知らなかった)、およびドキュメント文字列のみを引用した python フェンス(実行可能コードがまったくないため、ブロック全体がプローズ)。それぞれの修正により、チェック3はより狭く、より正確になりました:コードはコードとして、ドキュメントはドキュメントとして比較し、フェンスラベルではなく内容から判断する。
  • チェック3は偽陽性のためにも存在します。 新しいスキルの4つの「コード」フェンスはディレクトリツリーでした。その翻訳された注釈をコード変更として扱うと、翻訳者は文章を英語のままにせざるを得なくなっていたでしょう。

検証ツールが失敗を報告した場合、翻訳に触れる前に失敗を確認してください。 上記の3つのケースすべてで翻訳は正しく、その中には「コード」がデプロイインシデントを説明するドキュメント文字列で、意図的に翻訳されたケースも含まれます。間違ったリンターはリンターがないより悪いです:人々にそれを無視するように教えてしまいます。

制限事項

  • 構造的な対応関係を証明するものであって、翻訳が正しいことを証明するものではありません。誤訳された文はすべてのチェックを通過します。文章を読んでください。
  • チェック3の構造的フィンガープリントは注釈テキストを意図的に無視するため、パスの説明を間違ったものに置き換えた翻訳は検出されません。
  • discover_pairs() で定義されたレイアウトのみを認識します。異なる構成のリポジトリでは、その関数を拡張する必要があります。

関連項目

writing-mod-tools(誠実な劣化、終了コード、ツールができないことを明記すること)

関連スキル