zohar-translator

長文LLM翻訳システム：数万段落、サブスクリプション制限の回避、 自動公開。デプロイは RUN_ME.md を通じて行われ、これをオペレーターのLLMエージェントが読みます。

これは何か、何のためにあるか

1700ページに及ぶ『ゾハル書』への注釈「ペルーシュ・ハ・スラム」を、 ヘブライ語およびアラム語からロシア語へ、自分のClaudeサブスクリプション （Opus 4.7 モデル）だけを制約として翻訳すること――それが可能であることが判明しました。 zohar-translator は、まさにその翻訳を実行したシステムの 中核であり、現在はあらゆる長文コーパス・あらゆる言語ペアで動作します。

入力はテキストカタログ（章 → 記事 → 段落）とClaudeサブスクリプション。 出力は翻訳済みコーパス、通し番号付きの段落、章、脚注を備えた 静的サイト。その間に位置するのが orchestrator で、記事を文字数 バジェットに従ってチャンクに分割し、translator エージェントを並列 実行し、5時間および週次のサブスクリプションウィンドウを回避し、 章が完成するごとに結果を GitHub Pages にコミットします。

実働するリファレンスは、私たちによる『ゾハル書』の翻訳です： imyavel.github.io/zohar-sulam （CC BY 4.0ライセンス、サイトに明記）。その内部で動いているのは、 あなた自身がデプロイできるのとまったく同じ構成です。

自分のコーパス向けにシステムをデプロイするには、オペレーターは Claude Code をインストールし、「RUN_ME.md を読んで、 段階的に私を案内してほしい」と告げます。あとはLLMエージェントが 8つの適応ステージを通じて導きます。技術的な経験は必要ありません。

デプロイのステージ

各ステージはそれぞれ独立したファイル stages/NN_*.md に記述されています。オペレーターのLLMエージェントはそれらを順に 読み込み、オペレーターに「(Q N of NN: …)」形式の質問を行い、 回答を progress.json に記録します――これにより、 セッションをいつでも中断し、新しいセッションから同じ場所で 再開できます。

  1. Environment Python依存関係のインストールと、標準のGUIが起動することの確認。 これがなければ以降のステージは意味を持ちません。 stages/01_setup.md →
  2. Source loader コーパスをどこから読み込むか。Sefariaのテキストには、 reference/source_loader/download_sefaria.py による 既製のfast-pathが用意されています。独自のソースの場合は、 オペレーターが同じ形式（章ごとにグループ化されたJSON段落）で ローダーを書きます。 stages/02_source_loader.md →
  3. Text structure chunkingの単位：何が「記事」（翻訳の単位）にあたり、段落が どのように文字数バジェットでチャンクに分割されるか。ゾハルの 場合：章 → 記事 → スラムの段落。他のコーパスでは、同様の 三階層構造になります。 stages/03_text_structure.md →
  4. Glossary 用語集。私たちのゾハル用語集を出発点として用いることもできます （同じゾハルを翻訳する場合）。あるいは、ファイル構造と方法論 のみを参考にすることもできます（translatorエージェントは 内容全体を読み込まれるのではなく、CLIツール経由で用語集を 扱います）。 stages/04_glossary.md →
  5. Prompt template 翻訳スタイル（逐語訳／文学的／混合）、表記規則、「創造的」な 箇所を訳者注として明記する方法。templates/translation_prompt.md のテンプレートは、オペレーターの選択に応じてLLMエージェントが 適応させます。 stages/05_prompt.md →
  6. Publish target 結果の公開先：私たちのテンプレートによるGitHub Pages （src/gh_deploy.py 経由の自動デプロイ）、独自の チャネル（S3／GitLab／自前サーバー）、または公開せずローカルのみ。 stages/06_publish.md →
  7. Smoke run 合成ミニコーパスでの短いエンドツーエンド実行：パイプライン全体 （chunking → translator → resume → commit）が、適応済みシステム 上で数分で動作することを、実コーパスに対する実サブスクリプション を消費せずに検証します。 stages/07_smoke.md →
  8. Hand-off オペレーターは完全なコーパスでGUIを起動し、Telegramボットで 監視します。この時点でデプロイ用LLMエージェントは退き、あとは システム自身が動作します。 stages/08_handoff.md →

翻訳器の構造（GUI + Telegram）

詳細な説明は ARCHITECTURE.md にあります（9セクション：orchestratorのFSM、並列性、制限回避、 chunking+resume、gh_deploy、拡張ポイント、リカバリースクリプト）。 ここでは要点のみを示します。

  • GUI（src/gui.pyw）—— バッチキュー、 記事ステータス、chunkingバジェット、開始／停止ボタンを備えた メインウィンドウ。オペレーターの操作起点です。
  • Telegramボット（src/bot.py）—— 章の完成、hit-limit（5h）、weekly-limit、エラーに関する通知。 再開やステータス確認のためのコマンドを提供します。オプション （--no-bot で無効化可能）。
  • Orchestrator（src/orchestrator.py） —— PREPARING → RUNNING → COMPLETED / HIT_LIMIT / WEEKLY_LIMIT / FAILED の各状態を持つFSM。リトライを処理し、クラッシュ後に 状態を復元し、translatorエージェントの並列性を管理します。
  • Chunking —— 段落は原文の文字数バジェット （デフォルトで約7500）に従ってチャンクにまとめられます。段落 が途中で切られることはなく、大きな段落はまるごと一つのチャンク になります。
  • Resume —— translatorが記事の途中で停止した 場合（hit-limit、ネットワーク、OOM）、再実行時にはすでに 翻訳済みの部分を読み取り、完全に書き込まれた最後の段落を 特定して、その次から続行します。重複は書き込まれず、番号付け は通しのまま保たれます。
  • 制限回避 —— 5時間のサブスクリプション ウィンドウでは、orchestratorがバッチをWAITINGに置き、ウィンドウ のリセットまで休止してから続行します。週次制限の場合は、 リセットまでTG通知付きで一時停止します。ウィンドウ間で オペレーターの手作業は一切不要です。
  • gh_deploy（src/gh_deploy.py）—— 章が完成するごとに main へcommit + pushを実行 します。GitHub Pagesがこれを取り込み、公開サイトを更新します。 完成した章は翻訳の進行に合わせてサイトに現れるため、コーパス 全体の終了を待つ必要はありません。

フィードバック

このデプロイ機構自体はまだ他のマシンや他の人の手で実地に試されて いないため、これを利用してインストールと自分のコーパスへの 適応プロセスを自力で進めることを決めた最初のボランティアの 方々には、説明書に見つかった粗、言い足りない箇所、あるいは 明確な誤りについてのフィードバックを大いに歓迎します―― ご連絡は imyavel@gmail.com まで。

ソースコード、RUN_ME、issues は github.com/imyavel/zohar-translator にあります。ライセンスは、コードとドキュメントについてはMIT、 リファレンスとしてのゾハル翻訳はCC BY 4.0です。