zohar-translator

长篇 LLM 翻译系统:数万段落、绕开订阅额度限制、自动发布。部署流程通过 RUN_ME.md 进行,由操作员的 LLM 代理读取该文件并引导整个过程。

这是什么,为什么需要它

把 1700 页的《佐哈尔》注释《佩鲁什·哈苏拉姆》从希伯来语和阿拉米语 译成俄语,且仅依赖一个人自己的 Claude 订阅(使用 Opus 4.7 模型)—— 事实证明这是可行的。 zohar-translator 正是完成这项翻译的那套系统的核心, 如今它已能处理任意语言对的任意长篇语料。

输入端是一份文本目录(章 → 文 → 段)和一个 Claude 订阅。 输出端是一个静态网站,包含已翻译的语料、贯通的段落编号、 章节结构以及脚注。中间则是 orchestrator:它按字符预算把文章 切分成 chunk,并行驱动 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 的现成 快速通道。若使用自己的来源,操作员需按照相同格式 (按章组织的 JSON 段落)编写一个加载器。 stages/02_source_loader.md →
  3. Text structure chunking 的基本单位:什么算一篇「文章」(翻译单元), 以及段落如何按字符预算切分为 chunk。对于《佐哈尔》: 章 → 文 → 苏拉姆段落;对于其他语料,则建立类似的三级层次结构。 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 在一个合成的小型语料上跑一次端到端的简短流程:验证整条 pipeline(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、扩展点、recovery 脚本)。 这里只列要点。

  • GUI(src/gui.pyw)—— 主窗口, 包含 batch 队列、文章状态、chunking 预算以及启动/停止按钮。 这是操作员的入口。
  • Telegram 机器人(src/bot.py)—— 负责章节完成、hit-limit(5h)、weekly-limit 及错误的通知。 提供恢复运行和状态查询的命令。可选组件 (使用 --no-bot 启动即可关闭)。
  • Orchestrator(src/orchestrator.py) —— 一个 FSM,状态为 PREPARING → RUNNING → COMPLETED / HIT_LIMIT / WEEKLY_LIMIT / FAILED。负责处理重试、在崩溃后 恢复状态,并管理 translator 代理之间的并行。
  • Chunking —— 段落按源文本的字符预算 (默认约 7500)被组合成 chunk。段落绝不会从中间被截断; 过长的段落会单独构成一个完整的 chunk。
  • Resume —— 若 translator 在文章中途中断 (hit-limit、网络、OOM),再次运行时会读取已翻译的部分, 找到最后一个完整写入的段落,并从下一个段落继续。 不会写入重复内容,编号保持贯通。
  • 额度绕行 —— 遇到 5 小时订阅窗口时, orchestrator 把 batch 置为 WAITING,休眠至窗口结束后继续。 遇到每周限额时 —— 暂停至重置,并通过 TG 发送通知。 两次窗口之间无需操作员做任何手动干预。
  • gh_deploy(src/gh_deploy.py) —— 每一章完成后,执行一次 commit + push 到 main; GitHub Pages 自动拾取并刷新公开网站。已完成的章节会随着翻译 进度陆续出现在网站上,无需等待整部语料译完。

反馈

鉴于这套部署机制尚未在他人的机器和他人的手中真正磨合过, 对于率先愿意自行使用它、独立完成安装并把它适配到自己语料的 志愿者,如果您能就发现的粗糙之处、表述含糊或文档中直接的 错误反馈给我,我将不胜感激 —— 请写信至 imyavel@gmail.com。

源码、RUN_ME 与 issues 均在 github.com/imyavel/zohar-translator。 许可证 —— 代码和文档采用 MIT;作为参考的《佐哈尔》译本采用 CC BY 4.0。