zohar-translator

Ein System für LLM-Langtextübersetzung: Zehntausende von Absätzen, Umgehung der Abonnement-Limits, automatische Veröffentlichung. Die Inbetriebnahme erfolgt über RUN_ME.md, die vom LLM-Agenten des Operators gelesen wird.

Was es ist und wozu es dient

Den 1700-seitigen Kommentar «Perusch ha-Sulam» zum Buch Sohar aus dem Hebräischen und Aramäischen ins Russische zu übersetzen, allein mit dem eigenen Claude-Abonnement (Modell Opus 4.7) als Ressourcenbeschränkung — hat sich als machbar erwiesen. zohar-translator ist der Kern eben jenes Systems, das diese Übersetzung leistet und nun mit beliebigen langen Korpora in beliebigen Sprachpaaren arbeitet.

Eingabe: ein Textkatalog (Kapitel → Artikel → Absätze) und ein Claude-Abonnement. Ausgabe: eine statische Website mit dem übersetzten Korpus, durchlaufender Absatznummerierung, Kapiteln und Fußnoten. Dazwischen sitzt der Orchestrator: er zerlegt Artikel anhand eines Zeichenbudgets in Chunks, lässt Translator-Agenten parallel laufen, umgeht die 5-Stunden- und Wochenfenster des Abonnements und committet das Ergebnis nach Abschluss jedes Kapitels auf GitHub Pages.

Eine fertige Referenz ist unsere Übersetzung des Buches Sohar: imyavel.github.io/zohar-sulam (Lizenz CC BY 4.0, auf der Website angegeben). Unter der Haube arbeitet exakt dasselbe Bündel, das auch Sie bei sich aufsetzen können.

Um das System für den eigenen Korpus in Betrieb zu nehmen, installiert der Operator Claude Code und sagt ihm: «lies RUN_ME.md und führe mich Schritt für Schritt durch». Von da an leitet der LLM-Agent ihn durch 8 Anpassungsstufen; technische Vorkenntnisse sind nicht erforderlich.

Stufen der Inbetriebnahme

Jede Stufe ist in einer eigenen Datei stages/NN_*.md beschrieben. Der LLM-Agent des Operators lädt sie der Reihe nach, stellt dem Operator Fragen in der Form «(Q N von NN: …)» und hält die Antworten in progress.json fest — so kann die Sitzung jederzeit unterbrochen und aus einer neuen heraus an derselben Stelle fortgesetzt werden.

  1. Environment Installation der Python-Abhängigkeiten und Prüfung, dass die ausgelieferte GUI startet. Ohne diesen Schritt sind die folgenden Stufen sinnlos. stages/01_setup.md →
  2. Source loader Woher der Korpus geladen wird. Für Texte aus Sefaria gibt es einen fertigen Fast-Path über reference/source_loader/download_sefaria.py. Für eine eigene Quelle schreibt der Operator einen Loader im gleichen Format (JSON-Absätze gruppiert nach Kapiteln). stages/02_source_loader.md →
  3. Text structure Chunking-Einheiten: was als «Artikel» (Übersetzungseinheit) gilt und wie Absätze nach Zeichenbudget in Chunks zerlegt werden. Für den Sohar: Kapitel → Artikel → Sulam-Absätze; für einen anderen Korpus eine analoge dreistufige Hierarchie. stages/03_text_structure.md →
  4. Glossary Glossar der Fachbegriffe. Sie können unser Sohar-Glossar als Ausgangspunkt nehmen (für die Übersetzung des Sohar selbst) oder nur die Dateistruktur und die Methodik übernehmen (der Translator-Agent arbeitet mit dem Glossar über ein CLI-Werkzeug und wird nicht mit dem gesamten Inhalt geladen). stages/04_glossary.md →
  5. Prompt template Übersetzungsstil (wörtlich / literarisch / gemischt), Formatierungsregeln, wie «kreative» Stellen mit Übersetzerfußnoten zu kennzeichnen sind. Die Vorlage in templates/translation_prompt.md wird vom LLM-Agenten entsprechend den Entscheidungen des Operators angepasst. stages/05_prompt.md →
  6. Publish target Wohin das Ergebnis veröffentlicht wird: GitHub Pages nach unserer Vorlage (Auto-Deploy über src/gh_deploy.py), ein eigener Kanal (S3 / GitLab / eigener Server) oder nur lokal ohne Veröffentlichung. stages/06_publish.md →
  7. Smoke run Ein kurzer End-to-End-Durchlauf auf einem synthetischen Mini-Korpus: prüft, dass die gesamte Pipeline (chunking → translator → resume → commit) auf dem angepassten System in Minuten läuft, ohne reales Abonnement am vollen Korpus zu verbrauchen. stages/07_smoke.md →
  8. Hand-off Der Operator startet die GUI auf dem vollen Korpus und überwacht sie über den Telegram-Bot. Ab diesem Punkt tritt der LLM-Agent für die Inbetriebnahme zurück; das System läuft danach von selbst. stages/08_handoff.md →

Aufbau des Übersetzers (GUI + Telegram)

Eine ausführliche Beschreibung findet sich in ARCHITECTURE.md (9 Abschnitte: FSM des Orchestrators, Parallelität, Umgehung der Limits, chunking+resume, gh_deploy, Erweiterungspunkte, Recovery-Skripte). Hier das Wesentliche.

  • GUI (src/gui.pyw) — das Hauptfenster mit der Batch-Warteschlange, Artikelstatus, Chunking-Budget und Start/Stop-Schaltflächen. Dies ist der Einstiegspunkt des Operators.
  • Telegram-Bot (src/bot.py) — Benachrichtigungen über Kapitelabschlüsse, Hit-Limit (5h), Wochenlimit und Fehler. Befehle zum Fortsetzen und zur Statusprüfung. Optional (Start mit --no-bot).
  • Orchestrator (src/orchestrator.py) — eine FSM mit den Zuständen PREPARING → RUNNING → COMPLETED / HIT_LIMIT / WEEKLY_LIMIT / FAILED. Verwaltet Wiederholungen, stellt den Zustand nach Abstürzen wieder her und steuert die Parallelität der Translator-Agenten.
  • Chunking — Absätze werden anhand des Zeichenbudgets des Ausgangstextes (standardmäßig ~7500) zu Chunks gruppiert. Ein Absatz wird niemals in der Mitte geschnitten; ein großer Absatz bildet einen eigenen Chunk als Ganzes.
  • Resume — wenn ein Translator mitten in einem Artikel abbricht (hit-limit, Netzwerk, OOM), liest der erneute Lauf den bereits übersetzten Teil, findet den letzten vollständig geschriebenen Absatz und setzt mit dem nächsten fort. Duplikate werden nicht geschrieben, die Nummerierung bleibt durchgehend.
  • Umgehung der Limits — beim 5-Stunden-Fenster des Abonnements setzt der Orchestrator den Batch in WAITING, schläft bis zum Ende des Fensters und fährt fort. Beim Wochenlimit pausiert er bis zum Zurücksetzen mit TG-Benachrichtigung. Zwischen den Fenstern ist keine manuelle Arbeit des Operators erforderlich.
  • gh_deploy (src/gh_deploy.py) — nach jedem abgeschlossenen Kapitel erfolgt ein commit + push nach main; GitHub Pages übernimmt es und aktualisiert die öffentliche Website. Fertige Kapitel erscheinen während der Übersetzung auf der Website; man muss nicht das Ende des gesamten Korpus abwarten.

Rückmeldung

Da dieser Inbetriebnahme-Mechanismus selbst noch nicht auf fremden Maschinen und in fremden Händen erprobt wurde, wäre ich den ersten Freiwilligen, die ihn nutzen und den Installations- und Anpassungsprozess für ihren eigenen Korpus selbständig durchlaufen möchten, dankbar für Rückmeldungen zu entdeckten Unstimmigkeiten, Lücken oder direkten Fehlern in der Anleitung — schreiben Sie mir an imyavel@gmail.com.

Quellen, RUN_ME und Issues liegen auf github.com/imyavel/zohar-translator. Lizenz: MIT für Code und Dokumentation; die Sohar-Referenz­übersetzung steht unter CC BY 4.0.