zohar-translator

Un système de traduction LLM longue forme : des dizaines de milliers de paragraphes, contournement des limites d'abonnement, publication automatique. Le déploiement passe par RUN_ME.md, lu par l'agent LLM de l'opérateur.

De quoi s'agit-il et à quoi ça sert

Traduire le commentaire « Perouch ha-Soulam » de 1700 pages sur le Livre du Zohar depuis l'hébreu et l'araméen vers le russe, en ne s'appuyant que sur son propre abonnement Claude (modèle Opus 4.7) — s'est révélé possible. zohar-translator est le cœur de ce système même, qui effectue une telle traduction et qui fonctionne désormais avec tout long corpus et toute paire de langues.

En entrée — un catalogue de texte (chapitres → articles → paragraphes) et un abonnement Claude. En sortie — un site statique avec le corpus traduit, une numérotation continue des paragraphes, des chapitres et des notes de bas de page. Entre les deux se trouve l'orchestrator : il découpe les articles en chunks selon un budget de caractères, lance des agents traducteurs en parallèle, contourne les fenêtres d'abonnement de 5 heures et hebdomadaires, et commit le résultat sur GitHub Pages au fur et à mesure de la clôture des chapitres.

Une référence opérationnelle — notre traduction du Livre du Zohar : imyavel.github.io/zohar-sulam (licence CC BY 4.0, indiquée sur le site). Sous le capot — exactement l'ensemble que vous pouvez déployer chez vous.

Pour déployer le système sur votre propre corpus, l'opérateur installe Claude Code et lui dit « lis RUN_ME.md et guide-moi pas à pas ». Ensuite, l'agent LLM le conduira à travers 8 étapes d'adaptation ; aucune expérience technique n'est requise.

Étapes de déploiement

Chaque étape est décrite dans son propre fichier stages/NN_*.md. L'agent LLM de l'opérateur les charge l'une après l'autre, pose à l'opérateur des questions de la forme « (Q N sur NN : …) » et enregistre les réponses dans progress.json — cela permet d'interrompre la session à tout moment et de la reprendre depuis le même endroit dans une nouvelle.

  1. Environment Installation des dépendances Python, vérification que le GUI standard se lance. Sans cela, les étapes suivantes n'ont aucun sens. stages/01_setup.md →
  2. Source loader D'où charger le corpus. Pour les textes de Sefaria — un fast-path prêt à l'emploi via reference/source_loader/download_sefaria.py. Pour sa propre source, l'opérateur écrit un loader dans le même format (paragraphes JSON regroupés par chapitres). stages/02_source_loader.md →
  3. Text structure Unités de chunking : ce qui devient « article » (unité de traduction) et comment les paragraphes sont découpés en chunks selon un budget de caractères. Pour le Zohar — chapitres → articles → paragraphes du Soulam ; pour un autre corpus — une hiérarchie analogue à trois niveaux. stages/03_text_structure.md →
  4. Glossary Glossaire des termes. Vous pouvez prendre notre glossaire du Zohar comme point de départ (pour traduire ce même Zohar), ou n'en reprendre que la structure du fichier et la méthodologie (l'agent traducteur travaille avec le glossaire via un outil CLI, plutôt que d'en charger tout le contenu). stages/04_glossary.md →
  5. Prompt template Style de traduction (littéral / littéraire / mixte), règles de mise en forme, comment marquer les passages « créatifs » par des notes du traducteur. Le modèle dans templates/translation_prompt.md est adapté par l'agent LLM selon les choix de l'opérateur. stages/05_prompt.md →
  6. Publish target Où le résultat est publié : GitHub Pages selon notre modèle (auto-déploiement via src/gh_deploy.py), votre propre canal (S3 / GitLab / votre propre serveur), ou uniquement en local sans publication. stages/06_publish.md →
  7. Smoke run Un court passage end-to-end sur un mini-corpus synthétique : vérifie que tout le pipeline (chunking → translator → resume → commit) fonctionne sur le système adapté en quelques minutes, sans consommer un véritable abonnement sur le corpus complet. stages/07_smoke.md →
  8. Hand-off L'opérateur lance le GUI sur le corpus complet et le surveille via le bot Telegram. À partir de ce moment, l'agent LLM de déploiement se retire ; la suite, c'est le système lui-même qui la prend en charge. stages/08_handoff.md →

Architecture du traducteur (GUI + Telegram)

Description détaillée — dans ARCHITECTURE.md (9 sections : FSM de l'orchestrator, parallélisme, contournement des limites, chunking+resume, gh_deploy, points d'extension, scripts de récupération). Ici — l'essentiel.

  • GUI (src/gui.pyw) — fenêtre principale avec la file des batches, les statuts des articles, le budget de chunking, les boutons start/stop. C'est le point d'entrée de l'opérateur.
  • Bot Telegram (src/bot.py) — notifications sur la clôture des chapitres, hit-limit (5h), weekly-limit, erreurs. Commandes pour reprendre et vérifier le statut. Optionnel (lancement avec --no-bot).
  • Orchestrator (src/orchestrator.py) — un FSM avec les états PREPARING → RUNNING → COMPLETED / HIT_LIMIT / WEEKLY_LIMIT / FAILED. Gère les reprises, restaure l'état après les crashs, pilote le parallélisme des agents traducteurs.
  • Chunking — les paragraphes sont regroupés en chunks selon le budget de caractères du texte source (~7500 par défaut). Un paragraphe n'est jamais coupé en son milieu ; un gros paragraphe devient son propre chunk en entier.
  • Resume — si le translator s'arrête au milieu d'un article (hit-limit, réseau, OOM), un nouveau lancement lit la partie déjà traduite, trouve le dernier paragraphe entièrement écrit et reprend à partir du suivant. Aucun doublon n'est écrit, la numérotation reste continue.
  • Contournement des limites — sur une fenêtre d'abonnement de 5 heures, l'orchestrator met le batch en WAITING, dort jusqu'à la fin de la fenêtre, puis continue. Pour la limite hebdomadaire — pause jusqu'au reset avec notification TG. Aucun travail manuel de l'opérateur n'est requis entre les fenêtres.
  • gh_deploy (src/gh_deploy.py) — après chaque chapitre clos, effectue un commit + push sur main ; GitHub Pages le reprend et met à jour le site public. Les chapitres terminés apparaissent sur le site au fil de la traduction, sans attendre la fin du corpus entier.

Retour d'expérience

Étant donné que ce mécanisme de déploiement n'a pas encore été rodé sur d'autres machines et entre d'autres mains, je serai reconnaissant aux premiers volontaires qui décideront de l'utiliser et de mener eux-mêmes le processus d'installation et d'adaptation à leur corpus — pour tout retour sur les aspérités, les non-dits ou les erreurs manifestes dans les instructions — écrivez-moi à imyavel@gmail.com.

Sources, RUN_ME et issues — sur github.com/imyavel/zohar-translator. Licence : MIT pour le code et la documentation ; la traduction de référence du Zohar — CC BY 4.0.