pdf-translate

PDF 翻訳

バンドルされた Code4Life エンジンを使用して PDF を翻訳します。ソースファイルは変更せず、同じページ構成の別の PDF を作成します。

このスキルをリポジトリ内で実行する場合は、まず agent-knowledge/index.md を読んでください。保持または レイアウト作業では、PDF エンジン、回帰テスト、検証に関する手順を読み込んでください。これらは Codex と Claude に共通するプロジェクト指示です。このエントリーポイントに重複して記載しないでください。

スキルのルートを特定する

このスキルはグローバルにインストールされている一方で、ユーザーのファイルは別の場所にある場合があります。何かを実行する前に、この SKILL.md があるディレクトリの絶対パスを特定してください。スクリプトと依存ファイルは絶対パスで指定し、現在の作業ディレクトリがスキルのディレクトリであるとは想定しないでください。

<skill-root>/.venv 内のインタープリターを使用してください。

• Windows：<skill-root>\.venv\Scripts\python.exe
• macOS/Linux：<skill-root>/.venv/bin/python

モードを選ぶ

モード	翻訳者	使用する場面
Google（デフォルト）	translate.google.com	書籍、大量の文書、初稿、またはトークン使用量を抑えたい場合
引き継ぎ	現在のエージェント	用語、文脈、または翻訳品質が重要な場合

デフォルトでは Google を使用してください。ユーザーが品質向上を求める場合、Google の結果を受け入れない場合、または短い技術文書を提供した場合は、引き継ぎを提案してください。

制限事項

• バンドルされた pdf2zh/ コアを使用してください。PyPI の pdf2zh パッケージで代用してはいけません。ランナーはバージョン 1.9.11 と保持ルールセット code4life-preservation-v1 を確認し、外部コアの使用を拒否します。
• Google モードでは、抽出した文書テキストが Google に送信されます。機密情報を含む素材を処理する前にユーザーに伝え、依頼によってすでに開示が許可されている場合を除き、明示的な確認を得てください。引き継ぎモードでは Google に接続しません。
• 対応する翻訳先は、scripts/translate_pdf.py で許可されているラテン文字のコードです。バンドルされたフォントとレイアウトエンジンでは安定して描画できないため、CJK、右から左に記述する言語、タイ語、デーヴァナーガリー文字など、複雑な字形処理が必要な翻訳先は拒否されます。
• OCR は --ocr standard|enhanced で明示的に有効にします。安全でない表、数式、図、コード、曖昧な読み取り順序が見つかった場合は処理を中止します。保持された領域はすべて部分翻訳として報告し、スキャン文書全体が翻訳されたと主張しないでください。
• 検出された表、図、目次ページ、索引、記号一覧、参考文献内のテキストは、意図的に原文のまま残る場合があります。未翻訳の領域がある場合は、部分翻訳として報告してください。
• ソースは保持してください。結果は別の出力ディレクトリに書き込んでください。置き換えの明示的な許可なしに --overwrite を渡してはいけません。

レイアウト動作の変更、保持されたページの診断、または未翻訳領域の調査を行う前に、保持に関する契約を読んでください。

実行環境を設定する

Python 3.11 または 3.12 を使用してください。環境が存在しない場合、または古くなっている場合は、<skill-root>/.venv を作成し、<skill-root>/requirements.txt をインストールしてください。この環境はユーザーのプロジェクト環境と分けてください。

ソース配布版では、初回の翻訳時にレイアウトとフォントのアセットがダウンロードされるため、初回実行時にはネットワーク接続が必要で、通常より時間がかかります。パッケージ版の Windows アプリには、これらのアセットがすでに含まれています。

Windows：

python -m venv "<skill-root>\.venv"
& "<skill-root>\.venv\Scripts\python.exe" -m pip install -r "<skill-root>\requirements.txt"

macOS/Linux：

python3 -m venv "<skill-root>/.venv"
"<skill-root>/.venv/bin/python" -m pip install -r "<skill-root>/requirements.txt"

共通のランナーオプションには、--target-language（デフォルトは vi）、--source-language auto、1 始まりのページ指定 --pages 1,3-5、--threads 1..8（デフォルトは 4。Google モードでは引き続き一度に 1 件のリクエストを送信）、--ignore-cache、--overwrite があります。--bilingual side-by-side|alternating|layers（デフォルトは off）を指定すると、ソースと翻訳済みファイルから <name>-<lang>-dual.pdf も作成されます。このオプションが翻訳済みファイルを変更することはありません。作成できない場合、ランナーは警告を出力して翻訳結果を保持します。

Google モード

ファイルごとにコマンドを1つ実行します。入力と出力ディレクトリには絶対パスを使用してください。

Windows：

& "<skill-root>\.venv\Scripts\python.exe" "<skill-root>\scripts\translate_pdf.py" "<input.pdf>" --output-dir "<output-dir>"

macOS/Linux：

"<skill-root>/.venv/bin/python" "<skill-root>/scripts/translate_pdf.py" "<input.pdf>" --output-dir "<output-dir>"

一括処理ではファイルを個別に処理し、進捗を報告してください。特定のファイルでエラーが発生しても、残りのファイルの処理は続行します。Google のブロックまたはサービス停止の長期化が発生した場合は、キュー全体を一時停止します。正常に翻訳された箇所は後で再試行できるようキャッシュされ、中断されたファイルについては未完成の PDF は公開されません。

Google モードでは、無料エンドポイントへのネットワーク負荷を避けるため、1ページのセグメントを1回のリクエストで送信し、一度に1件ずつリクエストします。複数の Google ジョブを並列で実行しないでください。

実行中に HTTP 429 または CAPTCHA が発生した場合、ランナーは文書の処理を停止し、キューを一時停止します。その後10分間は、OCR／モデル処理の前に Google の実行を拒否します。これはアプリのクールダウンであり、Google の復旧時間を予測するものではありません。ループで再実行したり、CAPTCHA を回避しようとしたりしないでください。発生したことを報告し、後で再実行する方法（完了したセグメントはキャッシュ済み）またはハンドオフモードを案内してください。

ハンドオフモード

ハンドオフでは、翻訳可能なセグメントを JSONL に抽出し、現在のエージェントに翻訳させてから、PDF を再構築します。大きな文書を開始する前に、トークンと時間のコストについて警告してください。長い文書の場合は、まず --pages 1-5 のような代表的なサンプルを提案してください。

1. 抽出

1回目のパスで生成される PDF は破棄されるため、抽出時に出力ディレクトリは必要ありません。

<python> <skill-root>/scripts/translate_pdf.py <input.pdf> --engine handoff --emit-segments <segments.jsonl>

2. 翻訳

segments.jsonl を適切なサイズのバッチに分けて読み込みます。translations.jsonl に1行につき1つの JSON オブジェクトを書き込みます。

{"src":"exact source text","dst":"translated text"}

各 src の値はそのままコピーしてください。URL、パス、識別子、引用マーカー、数字は保持してください。

<b0></b0> のような数式およびコードのプレースホルダーは変更できません。すべての開始タグと終了タグは、ソースと同じ識別子、数、順序を維持する必要があります。プレースホルダーが一致しないレコードはローダーによって拒否され、そのセグメントは未翻訳のままになります。

インライン強調マーカーは、対応する組として変更できません。<s1>...</s1> は太字、<s2>...</s2> はイタリック、<s3>...</s3> は太字とイタリックです。対応するスタイルタグの組は翻訳後のフレーズと一緒に移動できますが、削除、重複、交差した入れ子にしてはいけません。スタイルマークアップが無効な場合、強調が黙って失われるのではなく、そのセグメントは未翻訳のままになります。

3. 再構築

<python> <skill-root>/scripts/translate_pdf.py <input.pdf> --engine handoff --segments <translations.jsonl> --output-dir <output-dir> --emit-segments <still-missing.jsonl>

コマンドは、未翻訳のセグメント数を表示します。0以外の場合は、still-missing.jsonl を翻訳し、有効なレコードを translations.jsonl に追加して、再度再構築してください。0になるか、安全に翻訳できないセグメントが残るまで続けます。その場合は、残っている制限を正確に報告してください。

抽出と再構築では、それぞれレイアウト処理が実行されます。そのため、ハンドオフではエージェントによる翻訳作業に加え、Google モードのおよそ2倍のローカル PDF 処理が必要です。

提供前の確認

1. 出力が存在し、ソースが変更されずに残っていることを確認します。
2. ソースと出力のページ数が一致することを確認します。
3. ページごとにテキストを抽出し、未翻訳の文章が大量に残っていないか、数式が欠落していないか、URL が破損していないか、識別子が失われていないかを確認します。
4. ページのレンダリングまたは画像の確認が可能な場合は、出力の全ページをレンダリングし、空白ページ、グリフの欠落、クリッピング、重なり、表や図の位置ずれがないか確認します。
5. 全ページの目視確認ができない場合は、完了した確認項目を伝えてください。一部しか確認できていないファイル、または一部しか翻訳されていないファイルを、完全に仕上がったものとして提示しないでください。