zohar-translator

מערכת תרגום LLM ליצירות ארוכות: עשרות אלפי פסקאות, עקיפת מגבלות המנוי, פרסום אוטומטי. הפריסה מתבצעת דרך RUN_ME.md, שאותו קורא סוכן ה-LLM של המפעיל.

מהי המערכת ולשם מה היא נועדה

לתרגם את הפירוש בן 1700 העמודים "פירוש הסולם" לספר הזוהר מעברית ומארמית לרוסית, כשהמגבלה היחידה היא מנוי Claude האישי (במודל Opus 4.7) — התברר כאפשרי. zohar-translator הוא הליבה של אותה מערכת שמבצעת תרגום זה, וכיום היא פועלת על כל קורפוס ארוך ובכל זוג שפות.

הקלט הוא קטלוג טקסט (פרקים ← מאמרים ← פסקאות) ומנוי Claude. הפלט הוא אתר סטטי עם הקורפוס המתורגם, מספור רציף של פסקאות, פרקים והערות שוליים. ביניהם פועל orchestrator: הוא חותך מאמרים לצ׳אנקים לפי תקציב תווים, מריץ סוכני translator במקביל, עוקף את חלונות המנוי בני 5 שעות והשבועיים, ומבצע commit של התוצאה ל-GitHub Pages עם סיומו של כל פרק.

רפרנס פעיל הוא התרגום שלנו לספר הזוהר: imyavel.github.io/zohar-sulam (רישיון CC BY 4.0, מצוין באתר). מתחת למכסה — בדיוק אותה חבילה שניתן לפרוס אצלך.

כדי לפרוס את המערכת על הקורפוס שלך, המפעיל מתקין Claude Code ואומר לו "קרא את RUN_ME.md והובל אותי שלב אחר שלב". מכאן והלאה סוכן ה-LLM מלווה אותו דרך 8 שלבי התאמה; אין צורך ברקע טכני.

שלבי הפריסה

כל שלב מתואר בקובץ נפרד stages/NN_*.md. סוכן ה-LLM של המפעיל טוען אותם בזה אחר זה, שואל את המפעיל שאלות בנוסח "(Q N מתוך NN: …)" ושומר את התשובות בקובץ progress.json — כך ניתן להפסיק את הסשן בכל רגע ולהמשיך מאותה הנקודה בסשן חדש.

  1. Environment התקנת תלויות Python ובדיקה שה-GUI הסטוקי עולה. בלי זה השלבים הבאים חסרי משמעות. stages/01_setup.md →
  2. Source loader מאיפה לטעון את הקורפוס. עבור טקסטים מ-Sefaria קיים fast-path מוכן דרך reference/source_loader/download_sefaria.py. עבור מקור משלך — המפעיל כותב טוען באותו פורמט (פסקאות JSON מקובצות לפי פרקים). stages/02_source_loader.md →
  3. Text structure יחידות החיתוך: מה נחשב ל"מאמר" (יחידת התרגום) וכיצד פסקאות נחתכות לצ׳אנקים לפי תקציב תווים. עבור הזוהר — פרקים ← מאמרים ← פסקאות הסולם; עבור קורפוס אחר — היררכיה אנלוגית בת שלוש רמות. stages/03_text_structure.md →
  4. Glossary מילון מונחים. ניתן לקחת את מילון הזוהר שלנו כנקודת התחלה (לתרגום הזוהר עצמו), או לקחת רק את מבנה הקובץ והמתודולוגיה (סוכן ה-translator עובד מול המילון דרך כלי CLI, ואינו נטען עם כל התוכן). stages/04_glossary.md →
  5. Prompt template סגנון התרגום (מילולי / ספרותי / מעורב), כללי עיצוב, כיצד לסמן קטעים "יצירתיים" בהערות שוליים של המתרגם. התבנית בקובץ templates/translation_prompt.md מותאמת על-ידי סוכן ה-LLM לפי בחירות המפעיל. stages/05_prompt.md →
  6. Publish target לאן מפורסמת התוצאה: GitHub Pages לפי התבנית שלנו (פריסה אוטומטית דרך src/gh_deploy.py), ערוץ משלך (S3 / GitLab / שרת משלך), או מקומי בלבד ללא פרסום. stages/06_publish.md →
  7. Smoke run הרצת end-to-end קצרה על מיני-קורפוס סינתטי: מאמתת שכל ה-pipeline (chunking ← translator ← resume ← commit) עובד על המערכת המותאמת תוך דקות, בלי לשרוף מנוי אמיתי על הקורפוס המלא. stages/07_smoke.md →
  8. Hand-off המפעיל מפעיל את ה-GUI על הקורפוס המלא ומנטר דרך בוט הטלגרם. מנקודה זו סוכן ה-LLM של הפריסה פורש, והמערכת עובדת בעצמה. stages/08_handoff.md →

מבנה המתרגם (GUI + Telegram)

תיאור מפורט נמצא בקובץ ARCHITECTURE.md (9 פרקים: FSM של ה-orchestrator, מקביליות, עקיפת מגבלות, chunking+resume, gh_deploy, נקודות הרחבה, סקריפטי recovery). כאן מובא העיקר.

  • GUI (src/gui.pyw) — החלון הראשי עם תור הבאצ׳ים, סטטוסי מאמרים, תקציב ה-chunking וכפתורי הפעלה/עצירה. זוהי נקודת הכניסה של המפעיל.
  • בוט טלגרם (src/bot.py) — התראות על סיום פרקים, hit-limit (5 שעות), weekly-limit ושגיאות. פקודות לחידוש ולבדיקת סטטוס. אופציונלי (הפעלה עם --no-bot).
  • Orchestrator (src/orchestrator.py) — FSM עם המצבים PREPARING ← RUNNING ← COMPLETED / HIT_LIMIT / WEEKLY_LIMIT / FAILED. מטפל בניסיונות חוזרים, משחזר את המצב לאחר קריסות ומנהל את המקביליות של סוכני ה-translator.
  • Chunking — פסקאות מקובצות לצ׳אנקים לפי תקציב תווי הטקסט המקורי (~7500 כברירת מחדל). פסקה אינה נחתכת אף פעם באמצע; פסקה גדולה הופכת לצ׳אנק עצמאי בשלמותה.
  • Resume — אם ה-translator נופל באמצע מאמר (hit-limit, רשת, OOM), ההרצה הבאה קוראת את החלק שכבר תורגם, מאתרת את הפסקה האחרונה שנכתבה במלואה, וממשיכה מהפסקה הבאה. שכפולים אינם נכתבים, והמספור נשאר רציף.
  • עקיפת מגבלות — בחלון מנוי בן 5 שעות ה-orchestrator מעביר את הבאץ׳ למצב WAITING, ישן עד סוף החלון וממשיך. במגבלה השבועית — הפסקה עד לאיפוס עם התראת TG. אין צורך בעבודה ידנית של המפעיל בין החלונות.
  • gh_deploy (src/gh_deploy.py) — לאחר כל פרק שנסגר מבוצע commit + push ל-main; GitHub Pages קולט את העדכון ומרענן את האתר הציבורי. פרקים מוכנים מופיעים באתר תוך כדי התרגום, ואין צורך להמתין לסיום הקורפוס כולו.

משוב

מאחר שמנגנון פריסה זה טרם נוסה על מכונות אחרות ובידיים אחרות, אודה למתנדבים הראשונים שיבחרו לעשות בו שימוש ולעבור את תהליך ההתקנה וההתאמה לקורפוס שלהם בעצמם — על משוב לגבי חספוסים, חוסרים או טעויות גלויות בהוראות — כתבו לי לכתובת imyavel@gmail.com.

קוד המקור, RUN_ME ו-issues נמצאים ב- github.com/imyavel/zohar-translator. רישיון: MIT לקוד ולתיעוד; תרגום-הרפרנס של הזוהר — CC BY 4.0.