zohar-translator

Un sistema di traduzione LLM di lungo formato: decine di migliaia di paragrafi, aggiramento dei limiti dell'abbonamento, pubblicazione automatica. Il deployment avviene tramite RUN_ME.md, letto dall'agente LLM dell'operatore.

Cos'è e a cosa serve

Tradurre il commentario di 1700 pagine «Perush ha-Sulam» al Libro dello Zohar dall'ebraico e dall'aramaico al russo, vincolati solo dal proprio abbonamento Claude (modello Opus 4.7) — si è rivelato possibile. zohar-translator è il nucleo di quello stesso sistema che esegue tale traduzione e che ora funziona con qualsiasi corpus lungo e qualsiasi coppia linguistica.

In ingresso — un catalogo testuale (capitoli → articoli → paragrafi) e un abbonamento Claude. In uscita — un sito statico con il corpus tradotto, numerazione continua dei paragrafi, capitoli e note. Tra di essi si colloca l'orchestrator: taglia gli articoli in chunk per budget di caratteri, esegue gli agenti translator in parallelo, aggira le finestre di abbonamento di 5 ore e settimanali, e committa il risultato su GitHub Pages alla chiusura di ogni capitolo.

Un riferimento operativo è la nostra traduzione del Libro dello Zohar: imyavel.github.io/zohar-sulam (licenza CC BY 4.0, indicata sul sito). Sotto il cofano c'è esattamente l'insieme di componenti che potete distribuire voi stessi.

Per distribuire il sistema sul proprio corpus, l'operatore installa Claude Code e gli dice «leggi RUN_ME.md e guidami passo passo». Da lì l'agente LLM lo accompagna attraverso 8 fasi di adattamento; non è richiesta alcuna esperienza tecnica.

Fasi del deployment

Ogni fase è descritta in un proprio file stages/NN_*.md. L'agente LLM dell'operatore li carica uno per uno, pone all'operatore domande nella forma «(Q N di NN: …)» e registra le risposte in progress.json — questo permette di interrompere una sessione in qualsiasi momento e di riprenderla da una nuova esattamente dallo stesso punto.

  1. Environment Installazione delle dipendenze Python e verifica che la GUI di base si avvii. Senza questo, le fasi successive sono prive di senso. stages/01_setup.md →
  2. Source loader Da dove caricare il corpus. Per i testi su Sefaria — un fast-path già pronto tramite reference/source_loader/download_sefaria.py. Per la propria sorgente, l'operatore scrive un loader nello stesso formato (paragrafi JSON raggruppati per capitolo). stages/02_source_loader.md →
  3. Text structure Unità di chunking: cosa diventa «articolo» (l'unità di traduzione) e come i paragrafi vengono tagliati in chunk per budget di caratteri. Per lo Zohar — capitoli → articoli → paragrafi del Sulam; per un altro corpus — una gerarchia analoga a tre livelli. stages/03_text_structure.md →
  4. Glossary Glossario dei termini. Potete prendere il nostro glossario dello Zohar come punto di partenza (per tradurre lo Zohar stesso), oppure prendere solo la struttura del file e la metodologia (l'agente translator lavora con il glossario tramite uno strumento CLI, anziché esserne caricato con l'intero contenuto). stages/04_glossary.md →
  5. Prompt template Stile di traduzione (letterale / letterario / misto), regole di formattazione, come contrassegnare i passaggi «creativi» con note del traduttore. Il template in templates/translation_prompt.md viene adattato dall'agente LLM in base alle scelte dell'operatore. stages/05_prompt.md →
  6. Publish target Dove viene pubblicato il risultato: GitHub Pages tramite il nostro template (auto-deploy tramite src/gh_deploy.py), un proprio canale (S3 / GitLab / un proprio server), oppure solo in locale senza pubblicazione. stages/06_publish.md →
  7. Smoke run Una breve esecuzione end-to-end su un mini-corpus sintetico: verifica che l'intera pipeline (chunking → translator → resume → commit) funzioni sul sistema adattato in pochi minuti, senza consumare abbonamento reale sull'intero corpus. stages/07_smoke.md →
  8. Hand-off L'operatore avvia la GUI sull'intero corpus e la monitora tramite il bot Telegram. Da questo momento l'agente LLM di deployment si ritira, da qui in avanti lavora il sistema stesso. stages/08_handoff.md →

Struttura del translator (GUI + Telegram)

Una descrizione dettagliata si trova in ARCHITECTURE.md (9 sezioni: FSM dell'orchestrator, parallelismo, aggiramento dei limiti, chunking+resume, gh_deploy, punti di estensione, script di recovery). Qui — l'essenziale.

  • GUI (src/gui.pyw) — la finestra principale con la coda dei batch, gli stati degli articoli, il budget di chunking e i pulsanti start/stop. Questo è il punto di ingresso dell'operatore.
  • Bot Telegram (src/bot.py) — notifiche sulla chiusura dei capitoli, hit-limit (5h), weekly-limit ed errori. Comandi per il resume e per la verifica dello stato. Opzionale (avvio con --no-bot).
  • Orchestrator (src/orchestrator.py) — una FSM con stati PREPARING → RUNNING → COMPLETED / HIT_LIMIT / WEEKLY_LIMIT / FAILED. Gestisce i retry, ripristina lo stato dopo i crash, governa il parallelismo degli agenti translator.
  • Chunking — i paragrafi vengono raggruppati in chunk per budget di caratteri del testo sorgente (~7500 per default). Un paragrafo non viene mai tagliato a metà; un paragrafo grande diventa per intero un proprio chunk.
  • Resume — se il translator si interrompe a metà di un articolo (hit-limit, network, OOM), l'esecuzione successiva legge la parte già tradotta, individua l'ultimo paragrafo scritto integralmente e prosegue dal successivo. Non vengono scritti duplicati, la numerazione resta continua.
  • Aggiramento dei limiti — sulla finestra di abbonamento di 5 ore, l'orchestrator mette il batch in WAITING, dorme fino al reset della finestra e prosegue. Sul limite settimanale — pausa fino al reset con notifica TG. Non è richiesto alcun lavoro manuale dell'operatore tra le finestre.
  • gh_deploy (src/gh_deploy.py) — dopo ogni capitolo chiuso esegue commit + push su main; GitHub Pages lo intercetta e aggiorna il sito pubblico. I capitoli pronti appaiono sul sito man mano che la traduzione procede, non è necessario attendere la fine dell'intero corpus.

Feedback

Poiché questo meccanismo di deployment non è ancora stato collaudato su altre macchine e in altre mani, sarò grato ai primi volontari che decideranno di utilizzarlo e di affrontare in autonomia il processo di installazione e adattamento al proprio corpus, per ogni feedback su asperità riscontrate, punti non sufficientemente chiari o errori veri e propri nelle istruzioni — scrivetemi a imyavel@gmail.com.

I sorgenti, RUN_ME e le issue si trovano su github.com/imyavel/zohar-translator. Licenza — MIT per codice e documentazione; la traduzione di riferimento dello Zohar — CC BY 4.0.