zohar-translator

Sistema de traducción LLM de textos extensos: decenas de miles de párrafos, elusión de los límites de suscripción, publicación automática. El despliegue se realiza mediante RUN_ME.md, que es leído por el agente LLM del operador.

Qué es y para qué sirve

Traducir el comentario de 1700 páginas «Perush ha-Sulam» al Libro del Zóhar desde el hebreo y el arameo al ruso, limitado únicamente por la propia suscripción a Claude (con el modelo Opus 4.7) — resultó ser posible. zohar-translator es el núcleo de ese mismo sistema que realiza tal traducción y que ahora funciona con cualquier corpus extenso en cualquier par de idiomas.

La entrada es un catálogo de texto (capítulos → artículos → párrafos) y una suscripción a Claude. La salida es un sitio estático con el corpus traducido, numeración continua de párrafos, capítulos y notas al pie. Entre ambos se sitúa el orchestrator: corta los artículos en chunks según un presupuesto de caracteres, lanza translator-agents en paralelo, elude las ventanas de suscripción de 5 horas y semanales, y commitea el resultado en GitHub Pages a medida que se cierra cada capítulo.

La referencia funcional es nuestra traducción del Libro del Zóhar: imyavel.github.io/zohar-sulam (licencia CC BY 4.0, indicada en el sitio). Bajo el capó está exactamente el mismo conjunto que usted puede desplegar por su cuenta.

Para desplegar el sistema con su propio corpus, el operador instala Claude Code y le dice: «lee RUN_ME.md y guíame paso a paso». A partir de ahí, el agente LLM lo conducirá a través de 8 etapas de adaptación; no se requiere experiencia técnica.

Etapas del despliegue

Cada etapa está descrita en su propio archivo stages/NN_*.md. El agente LLM del operador los carga por turno, le hace al operador preguntas del tipo «(Q N de NN: …)» y registra las respuestas en progress.json — esto permite interrumpir la sesión en cualquier momento y continuar desde el mismo punto en una nueva.

  1. Environment Instalación de las dependencias de Python y verificación de que el GUI estándar arranca. Sin esto, las etapas siguientes carecen de sentido. stages/01_setup.md →
  2. Source loader De dónde se carga el corpus. Para textos de Sefaria — un fast-path ya listo mediante reference/source_loader/download_sefaria.py. Para una fuente propia, el operador escribe un cargador en el mismo formato (párrafos JSON agrupados por capítulo). stages/02_source_loader.md →
  3. Text structure Unidades de chunking: qué se considera un «artículo» (la unidad de traducción) y cómo se cortan los párrafos en chunks según el presupuesto de caracteres. Para el Zóhar: capítulos → artículos → párrafos del Sulam; para otro corpus, una jerarquía análoga de tres niveles. stages/03_text_structure.md →
  4. Glossary Glosario de términos. Puede tomar nuestro glosario del Zóhar como punto de partida (para traducir el propio Zóhar), o quedarse solo con la estructura del archivo y la metodología (el translator-agent trabaja con el glosario a través de una herramienta CLI, y no se carga con todo su contenido). stages/04_glossary.md →
  5. Prompt template Estilo de traducción (literal / literario / mixto), reglas de formato, cómo marcar los pasajes «creativos» mediante notas al pie del traductor. La plantilla en templates/translation_prompt.md es adaptada por el agente LLM según las decisiones del operador. stages/05_prompt.md →
  6. Publish target Dónde se publica el resultado: GitHub Pages mediante nuestra plantilla (auto-deploy a través de src/gh_deploy.py), un canal propio (S3 / GitLab / su propio servidor), o solo en local sin publicación. stages/06_publish.md →
  7. Smoke run Una ejecución corta end-to-end sobre un mini-corpus sintético: comprueba que todo el pipeline (chunking → translator → resume → commit) funciona en el sistema adaptado en cuestión de minutos, sin consumir suscripción real sobre el corpus completo. stages/07_smoke.md →
  8. Hand-off El operador lanza el GUI sobre el corpus completo y lo monitoriza a través del bot de Telegram. A partir de este momento el agente LLM de despliegue se retira; el sistema continúa por sí solo. stages/08_handoff.md →

Estructura del traductor (GUI + Telegram)

La descripción detallada está en ARCHITECTURE.md (9 secciones: FSM del orchestrator, paralelismo, elusión de límites, chunking+resume, gh_deploy, puntos de extensión, scripts de recovery). Aquí está lo esencial.

  • GUI (src/gui.pyw) — la ventana principal con la cola de batches, los estados de los artículos, el presupuesto de chunking y los botones de start/stop. Es el punto de entrada del operador.
  • Bot de Telegram (src/bot.py) — notificaciones sobre el cierre de capítulos, hit-limit (5h), weekly-limit y errores. Comandos para reanudar y comprobar el estado. Opcional (lanzamiento con --no-bot).
  • Orchestrator (src/orchestrator.py) — una FSM con estados PREPARING → RUNNING → COMPLETED / HIT_LIMIT / WEEKLY_LIMIT / FAILED. Gestiona los reintentos, restaura el estado tras caídas y dirige el paralelismo de los translator-agents.
  • Chunking — los párrafos se agrupan en chunks según el presupuesto de caracteres del texto original (~7500 por defecto). Un párrafo nunca se corta por la mitad; un párrafo grande se convierte en su propio chunk íntegro.
  • Resume — si el translator cae en mitad de un artículo (hit-limit, red, OOM), el siguiente arranque lee lo ya traducido, localiza el último párrafo escrito por completo y continúa desde el siguiente. No se escriben duplicados, la numeración se mantiene continua.
  • Elusión de límites — ante una ventana de suscripción de 5 horas, el orchestrator pone el batch en WAITING, duerme hasta que la ventana se reinicia y continúa. Ante el límite semanal — pausa hasta el reseteo con notificación por TG. No se requiere intervención manual del operador entre ventanas.
  • gh_deploy (src/gh_deploy.py) — tras cada capítulo cerrado realiza commit + push a main; GitHub Pages lo recoge y actualiza el sitio público. Los capítulos terminados van apareciendo en el sitio a medida que avanza la traducción; no hay que esperar al final del corpus completo.

Comentarios

Dado que este mecanismo de despliegue todavía no ha sido rodado en máquinas y manos ajenas, a los primeros voluntarios que decidan utilizarlo y atravesar por su cuenta el proceso de instalación y adaptación a su propio corpus, les estaré agradecido por sus comentarios sobre las asperezas detectadas, los puntos no explicados o los errores directos en las instrucciones — escríbanme a imyavel@gmail.com.

El código fuente, RUN_ME y los issues están en github.com/imyavel/zohar-translator. Licencia: MIT para el código y la documentación; la traducción de referencia del Zóhar — CC BY 4.0.