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 из NN: …)» и фиксирует ответы в progress.json — это позволяет в любой момент прервать сессию и продолжить с того же места из новой.

  1. Environment Установка Python-зависимостей, проверка, что стоковый GUI запускается. Без этого следующие стадии бессмысленны. stages/01_setup.md →
  2. Source loader Откуда грузить корпус. Для текстов из Sefaria — готовый fast-path через reference/source_loader/download_sefaria.py. Для своего источника — оператор пишет загрузчик в том же формате (JSON-параграфы по главам). stages/02_source_loader.md →
  3. Text structure Единицы чанкования: что становится «статьёй» (единицей перевода) и как параграфы режутся на чанки по бюджету символов. Для Зоара — главы → статьи → параграфы Сулама; для другого корпуса — аналогичная трёхуровневая иерархия. 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 Короткий прогон end-to-end на синтетическом мини-корпусе: проверяет, что весь pipeline (chunking → translator → resume → commit) работает на адаптированной системе за минуты, без расхода реальной подписки на полный корпус. stages/07_smoke.md →
  8. Hand-off Оператор запускает GUI на полном корпусе и мониторит через Telegram-бот. С этого момента LLM-агент развёртывания уходит, дальше работает сама система. stages/08_handoff.md →

Структура переводчика (GUI + Telegram)

Подробное описание — в ARCHITECTURE.md (9 разделов: FSM оркестратора, параллелизм, обход лимитов, chunking+resume, gh_deploy, точки расширения, recovery-скрипты). Здесь — самое важное.

  • GUI (src/gui.pyw) — главное окно с очередью батчей, статусами статей, бюджетом 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). Параграф никогда не режется посередине; крупный параграф становится собственным чанком целиком.
  • Resume — если translator упал посреди статьи (hit-limit, network, OOM), повторный запуск читает уже переведённую часть, находит последний полностью записанный параграф и продолжает с следующего. Дубликаты не пишутся, нумерация остаётся сквозной.
  • Обход лимитов — на 5-часовое окно подписки orchestrator ставит батч в 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.