zohar-translator

Sistema de tradução LLM de longo formato: dezenas de milhares de parágrafos, contorno de limites de assinatura, publicação automática. A implantação é feita através do RUN_ME.md, lido pelo agente LLM do operador.

O que é e por que existe

Traduzir o comentário de 1700 páginas «Perush ha-Sulam» sobre o Livro do Zohar do hebraico e do aramaico para o russo, limitado apenas pela própria assinatura do Claude (com o modelo Opus 4.7) — revelou-se possível. zohar-translator é o núcleo desse mesmo sistema, que realiza essa tradução e que agora funciona com qualquer corpus longo em qualquer par linguístico.

A entrada é um catálogo de texto (capítulos → artigos → parágrafos) e uma assinatura do Claude. A saída é um site estático com o corpus traduzido, numeração contínua de parágrafos, capítulos e notas de rodapé. Entre eles fica o orchestrator: corta os artigos em chunks por orçamento de caracteres, executa agentes-tradutores em paralelo, contorna as janelas de assinatura de 5 horas e semanais, e faz commit do resultado no GitHub Pages à medida que cada capítulo é fechado.

Uma referência funcional é a nossa tradução do Livro do Zohar: imyavel.github.io/zohar-sulam (licença CC BY 4.0, indicada no site). Por baixo do capô está exatamente o mesmo conjunto que você pode implantar por conta própria.

Para implantar o sistema sobre o seu próprio corpus, o operador instala o Claude Code e diz-lhe «leia o RUN_ME.md e me conduza passo a passo». A partir daí, o agente LLM guia através de 8 estágios de adaptação; não é necessária experiência técnica.

Estágios de implantação

Cada estágio está descrito em seu próprio arquivo stages/NN_*.md. O agente LLM do operador os carrega um a um, faz ao operador perguntas no formato «(Q N de NN: …)» e registra as respostas em progress.json — isso permite interromper uma sessão a qualquer momento e retomá-la a partir do mesmo ponto numa nova.

  1. Environment Instalação das dependências Python e verificação de que a GUI padrão é iniciada. Sem isso, os estágios seguintes não fazem sentido. stages/01_setup.md →
  2. Source loader De onde carregar o corpus. Para textos do Sefaria — um fast-path pronto através de reference/source_loader/download_sefaria.py. Para uma fonte própria, o operador escreve um carregador no mesmo formato (parágrafos JSON agrupados por capítulo). stages/02_source_loader.md →
  3. Text structure Unidades de chunking: o que conta como «artigo» (unidade de tradução) e como os parágrafos são cortados em chunks por orçamento de caracteres. Para o Zohar — capítulos → artigos → parágrafos do Sulam; para outro corpus — uma hierarquia análoga de três níveis. stages/03_text_structure.md →
  4. Glossary Glossário de termos. Você pode tomar o nosso glossário do Zohar como ponto de partida (para traduzir o próprio Zohar), ou tomar apenas a estrutura do arquivo e a metodologia (o agente-tradutor trabalha com o glossário através de uma ferramenta CLI, em vez de ser carregado com todo o conteúdo). stages/04_glossary.md →
  5. Prompt template Estilo de tradução (literal / literário / misto), regras de formatação, como marcar passagens «criativas» com notas de rodapé do tradutor. O modelo em templates/translation_prompt.md é adaptado pelo agente LLM conforme as escolhas do operador. stages/05_prompt.md →
  6. Publish target Onde o resultado é publicado: GitHub Pages através do nosso template (auto-deploy via src/gh_deploy.py), um canal próprio (S3 / GitLab / servidor próprio), ou apenas localmente, sem publicação. stages/06_publish.md →
  7. Smoke run Uma execução curta end-to-end num minicorpus sintético: verifica que todo o pipeline (chunking → translator → resume → commit) funciona no sistema adaptado em minutos, sem consumir assinatura real no corpus completo. stages/07_smoke.md →
  8. Hand-off O operador inicia a GUI no corpus completo e monitora através do bot do Telegram. A partir desse ponto, o agente LLM de implantação se afasta; o sistema funciona por conta própria. stages/08_handoff.md →

Estrutura do tradutor (GUI + Telegram)

Uma descrição detalhada está em ARCHITECTURE.md (9 seções: FSM do orchestrator, paralelismo, contorno de limites, chunking+resume, gh_deploy, pontos de extensão, scripts de recovery). Aqui — o essencial.

  • GUI (src/gui.pyw) — a janela principal com a fila de batches, status dos artigos, orçamento de chunking, botões de iniciar/parar. É o ponto de entrada do operador.
  • Bot do Telegram (src/bot.py) — notificações sobre fechamento de capítulos, hit-limit (5h), weekly-limit, erros. Comandos para retomada e verificação de status. Opcional (execução com --no-bot).
  • Orchestrator (src/orchestrator.py) — uma FSM com estados PREPARING → RUNNING → COMPLETED / HIT_LIMIT / WEEKLY_LIMIT / FAILED. Trata retentativas, restaura o estado após falhas, gerencia o paralelismo dos agentes-tradutores.
  • Chunking — os parágrafos são agrupados em chunks pelo orçamento de caracteres do texto fonte (~7500 por padrão). Um parágrafo nunca é cortado no meio; um parágrafo grande torna-se um chunk inteiro por si só.
  • Resume — se um translator cai no meio de um artigo (hit-limit, network, OOM), a execução seguinte lê o que já foi traduzido, encontra o último parágrafo totalmente escrito e continua a partir do próximo. Não se escrevem duplicatas, a numeração permanece contínua.
  • Contorno de limites — na janela de assinatura de 5 horas, o orchestrator coloca o batch em WAITING, dorme até o fim da janela e prossegue. No limite semanal — pausa até o reset, com notificação no TG. Nenhum trabalho manual do operador é necessário entre as janelas.
  • gh_deploy (src/gh_deploy.py) — após cada capítulo fechado, executa commit + push para main; o GitHub Pages capta e atualiza o site público. Os capítulos prontos aparecem no site à medida que a tradução avança, não é preciso esperar o fim de todo o corpus.

Feedback

Como este mecanismo de implantação ainda não foi rodado em outras máquinas e em outras mãos, ficarei grato aos primeiros voluntários que decidirem usá-lo e passar por conta própria pelo processo de instalação e adaptação ao seu corpus — pelo feedback sobre quaisquer arestas, omissões ou erros diretos nas instruções — escrevam-me para imyavel@gmail.com.

Fontes, RUN_ME e issues estão em github.com/imyavel/zohar-translator. Licença — MIT para o código e a documentação; a tradução-referência do Zohar — CC BY 4.0.