Revayat — 英語 → ペルシア語 書籍翻訳
以下の9つのステップを順番に実行してください。各ステップはコマンドと、その出力に対して何を行うかのルールで構成されています。順序を変えたり、前のステップが問題なさそうに見えてもステップをスキップしたりしないでください。
2つの変数を一度設定し、その後はすべての場所でそれらを使用します。
SKILL_DIR— このファイルが置かれているフォルダ。Claude Codeプラグインの場合は${CLAUDE_PLUGIN_ROOT}/skills/revayatです。WORK— この書籍の作業フォルダ（例：work/）。
すべてのコマンドは python3 $SKILL_DIR/scripts/revayat.py <stage> … です。
絶対に破ってはいけない5つのルール
- ペルシア語のテキストを逆順にしないでください。 方向はビルダーによって設定されます。逆順にすると、1つのビューアでのみ正しく表示され、他のすべての場所で壊れたファイルが生成されます。
@@ idヘッダーを新しく作成したり、削除したり、結合、分割、並べ替えたりしないでください。 与えられたものをそのまま返してください。[[fn:…]]、**bold**、*italic*、`verbatim`のマーカーを決して削除しないでください。 これらはカウントされており、不一致があるとQAが失敗します。- 翻訳を修正するために
book.jsonを手動で編集しないでください。 ワークシートを修正してマージを再実行してください。 - 書籍を短縮しないでください。 要約、難しい文のスキップ、表現の緩和は一切禁止です。ステップがコンテンツの欠落を報告した場合は、そのチャンクを再実行してください。
ステップ 1 — ツールの確認
python3 $SKILL_DIR/scripts/revayat.py doctor
"ready": true→ 続行。"ready": false→pip install -r $SKILL_DIR/requirements.txtを実行し、その後doctorを再度実行します。optional_toolsにnot foundと表示されていても、今は問題ありません。ステップ2でOCRが実際に必要かどうかがわかります。
ステップ 2 — 抽出
python3 $SKILL_DIR/scripts/revayat.py extract "<入力ファイル>" --out $WORK
ペルシア語のソースの場合は、--ocr-lang fas を追加します。他の言語の場合は、Tesseractのコード（deu、fra、ara、…）を使用します。
出力されるJSONを読み、以下の表に従ってください。
| 表示内容 | 対処方法 |
|---|---|
"kind": "digital" | 何もしない。OCRは不要でした。 |
"kind": "scanned" または "mixed" | OCRが自動的に実行されました。 ocr.probe_after.text_share が 0.7 を超えていることを確認してください。 |
| OCRmyPDFを指定するエラー | メッセージの指示に従ってインストールし、このステップを再実行してください。 |
clean_scan.cleaned が0より大きい | カラーウォーターマークがそのページ数分削除されました。 |
ocr.warning がnullではない | 内容を読んでください。ファイルはまだ使用可能なので、続行してください。 |
page_scans_dropped が0より大きい | その数だけの全ページラスター画像が、スキャン自体（つまり写真ではなく）として認識されました。 |
クリーナーはあなたのファイルを編集しません。元のファイルはそのまま残り、クリーニングされたコピーが $WORK/cleaned.pdf に書き込まれ、各ページごとに clean_scan に何が削除され、何がそのまま残されたかの記録が残ります。--clean-scan off を指定すると完全にスキップし、--clean-scan force を指定するとスタンプが残っている場合に強制的に適用します。
スキャンされた書籍の場合、今すぐ以下の2つの追加パスを実行してください。
認識信頼度 — これがないと、誤認識された単語と正しい単語の区別がつきません。どちらも流暢なペルシア語だからです。
python3 $SKILL_DIR/scripts/revayat.py ocr-sidecar --pdf $WORK/ocr.pdf --out $WORK --lang fas --book $WORK/book.json
これにより、source.ocr.json（単語、行、ブロック、ページごとに、ボックス、信頼度、読み順、実行された前処理）と source.ocr.txt が書き込まれ、book.json 内の各ブロックに、その領域の信頼度がスタンプされます。low と評価されたブロックは、qa check によって ocr-low-confidence として報告され、それを受け入れるということは、そのページ画像を確認することを意味します。しきい値はデフォルトで85と60であり、--high / --low で変更できます。
スキャン内のイラスト — スキャンされたページは1つのフラットな画像であるため、その上の写真は、何かが見つけるまでは独立した画像として扱われません。
mineru -p $WORK/cleaned.pdf -o $WORK/mineru -b pipeline -l arabic
python3 $SKILL_DIR/scripts/revayat.py extract "<入力ファイル>" --out $WORK --figures-from-mineru $WORK/mineru
元のファイルではなく cleaned.pdf に対してMinerUを実行してください。そうしないと、ウォーターマークを図として切り取ってしまいます。MinerUからは画像のみを取得してください。 MinerU自身が認識したペルシア語テキストは、単語とその中の文字が逆順になって返ってきます。Tesseractは fas で同じページを正しく読み取るため、テキストはそのまま残ります。MinerUがページ範囲に対して実行された場合は、--figures-page-offset N を使用してください。
次に、先に進む前に結果を確認してください。
python3 $SKILL_DIR/scripts/revayat.py qa check --book $WORK/book.json --allow-incomplete
ここでは untranslated-block は無視してください。まだ何も翻訳されていません。探しているのは asset-missing です。実際の書籍で stats.text_blocks が20未満の場合、抽出に失敗しています。references/extraction.md を参照してください。
ステップ 3 — 用語集
python3 $SKILL_DIR/scripts/revayat.py glossary scan \
--book $WORK/book.json --out $WORK/glossary.json
レポートには needs_persian がリストされ、頻度の高い順に表示されます。$WORK/glossary.json を開き、最初の20エントリのそれぞれについて、以下の4つのフィールドを記入してください。
"target": "الیزابت بنت",
"later_form": "الیزابت بنت",
"first_form": "الیزابت بنت (Elizabeth Bennet)",
"locked": true
first_block_id はそのままにしてください。パイプラインはこれを使用して、どの単一チャンクが名前を導入するかを決定します。編集したり、自分で最初の言及を決定したりしないでください。
実際の名前ではないエントリは削除してください。その後続行します。
ステップ 4 — チャンク分割
python3 $SKILL_DIR/scripts/revayat.py chunk build \
--book $WORK/book.json --out $WORK/chunks --glossary $WORK/glossary.json
チャンクの数に注意してください。それぞれが1つの翻訳タスクになります。
すでにいくつかのワークシートを翻訳しており、入力が変更された場合、これは静かにワークシートを渡すのではなく、"refused": "stale-worksheets" というエラーで拒否します。その理由を再度読み、既存の翻訳がまだ有効であると判断した場合にのみ --force を追加してください。
ステップ 5 — 翻訳
$WORK/chunks/chunkNNNN.md ごとに、$WORK/chunks/out_chunkNNNN.md を生成します。ランタイムがサポートしている場合は、チャンクごとに個別のサブエージェントを、一度に8つ使用します。サポートしていない場合は、1つずつ実行してください。結果は同じですが、遅くなります。
サブエージェントには、次の内容を正確に与えてください。
$WORK/chunks/chunkNNNN.mdを読み、$WORK/chunks/out_chunkNNNN.mdに書き込んでください。ペルシア語に翻訳してください。まず
$SKILL_DIR/references/translation-policy.mdを読み、それに従ってください。出力形式 — これは機械的な作業です。正確に行ってください。
- 各
@@ <id> <kind>行を変更せずに、同じ順序でコピーしてください。- その下の行にペルシア語の翻訳を配置してください。
- それ以外は出力しないでください。前置き、英語、解説、要約は一切不要です。
ルール:
- 「名前」テーブルは拘束力があります。行に「初出の場合はここで導入する」とある場合は、その長い形式を使用してください。その他のすべての場所では短い形式を使用してください。この決定を自分で行わないでください。テーブルがすでに行っています。
- 「周囲のテキスト」はコンテキストのみです。決して翻訳したり、書き出したりしないでください。
**bold**、*italic*、`verbatim`、[[fn:…]]を、対応するペルシア語の単語の周囲に正確に保持してください。追加したり削除したりしないでください。- すべての単位を完全に翻訳してください。決して要約したりスキップしたりしないでください。
- 自分で脚注を追加するには: 文中に
[[fn:tr-01]]と書き、最後に@@ tr-01 footnoteブロックを追加してそのテキストを記述してください。これは、真に文化的な言及や言葉遊びの場合にのみ使用してください。
任意の時点で残りを確認します。
python3 $SKILL_DIR/scripts/revayat.py chunk status --chunks $WORK/chunks
ステップ 6 — マージ
python3 $SKILL_DIR/scripts/revayat.py merge --book $WORK/book.json --chunks $WORK/chunks
| フィールド | 意味 | アクション |
|---|---|---|
"ok": true | すべてが配置されました | ステップ7に進む |
missing_outputs | それらのチャンクは翻訳されていません | 翻訳する |
missing_units | ヘッダーが削除されました | それらのチャンクを再実行する |
unknown_units | ヘッダーが新しく作成されました | それらのチャンクを再実行する |
修正後にマージを再実行しても常に安全です。
ステップ 7 — ペルシア語の組版
python3 $SKILL_DIR/scripts/revayat.py falint fix --book $WORK/book.json
機械的な処理のみで、2回実行しても安全です。書籍でラテン数字を保持する必要がある場合は、--digits keep を追加してください。
ステップ 8 — ゲートチェック、そしてビルド
python3 $SKILL_DIR/scripts/revayat.py qa check \
--book $WORK/book.json --assets $WORK/assets --glossary $WORK/glossary.json
"ok" が false の間はビルドしないでください。 エラーコードに従って修正してください。
| コード | 意味 | アクション |
|---|---|---|
untranslated-block | ブロックにペルシア語がありません | そのチャンクを翻訳する |
footnote-marker-lost | [[fn:…]] が削除されました | そのチャンクを再実行する |
footnote-marker-invented | マーカーが何も指していません | そのチャンクを再実行する |
possible-omission | ターゲットがソースよりはるかに短い | 内容を読む。通常は節の欠落 |
untranslated | ペルシア語の中に英語が残っている | そのチャンクを再実行する |
asset-missing / asset-modified | 画像がなくなったか、変更された | 再抽出する |
copied-source-run | ソースの節がペルシア語内にそのまま存在する | そのチャンクを再実行する |
duplicate-translation | 2つの異なるソースが同じペルシア語になった | ワークシートの返信が2回貼り付けられました。両方を再実行する |
first-mention-repeated | 名前が複数の場所で導入されている | 最初のものを保持し、残りを削除する |
image-order | パッケージ内の画像の順序が間違っている | 再ビルドする |
bookmarks-missing / bookmark-duplicate | 目次がどこにもリンクしないか、間違った場所にリンクする | 再ビルドする |
emphasis-parity (警告) | 太字/斜体の数が変更されました | 1つ確認する。多くの場合問題ありません |
glossary-drift (警告) | ロックされた名前が異なる形でレンダリングされました | そのチャンクを再実行する |
ocr-low-confidence (警告) | エンジンがこのブロックの認識に自信がありませんでした | ページ画像を開いて比較する |
出版作業の場合は、--strict を追加して、最後の3つもブロッキングエラーにします。
書籍のタイトルと著者を book.json の meta.title_target と meta.author_target に翻訳してください。これが例外的に許可される唯一の手動編集です。なぜなら、これらに対応するワークシートがないからです。
次にビルドします。
python3 $SKILL_DIR/scripts/revayat.py build \
--book $WORK/book.json --assets $WORK/assets --out out/book.fa.docx \
--font "Vazirmatn" --size 11.5
便利なフラグ: ペルシア語フォントがないマシンでファイルをレンダリングする必要がある場合は --font Tahoma、元の見出しのポイントサイズを再現するには --heading-size source、既存のWordファイルからスタイルを継承するには --template ref.docx。完全なリストは references/docx-and-ooxml.md にあります。
ステップ 9 — 確認とレポート
python3 $SKILL_DIR/scripts/revayat.py qa docx --file out/book.fa.docx --book $WORK/book.json
"ok": false の場合は、ユーザーにファイルの準備ができたと伝える前に修正してください。
次にレポートします。ファイルの場所、章/画像/脚注の数、QAがフラグを立てたが対処しないことを選択した項目、そして以下の制限事項です。
Wordはテキストをリフローするため、編集可能なペルシア語文書はソースPDFとページ単位で同一にすることはできません。画像のバイトデータと物理サイズ、章構成、強調、脚注、章リンクは正確です。
参考文献
ステップがそれらを指している場合にのみ読んでください。
references/translation-policy.md— 翻訳サブエージェントに与えるものreferences/persian-typography.md— RTL、ZWNJ、句読点、混合スクリプトreferences/extraction.md— OCRルーティング、ウォーターマーク、難しい書籍references/glossary-and-voice.md— 命名ポリシー、エイリアス、キャラクターボイスreferences/docx-and-ooxml.md— すべてのビルドオプションとその出力references/troubleshooting.md— 遭遇する可能性が最も高い障害