מדריך שורת הפקודה (CLI)¶
Co-op Translator מתקין נקודות כניסה לשורת הפקודה הבאות:
translateevaluatemigrate-linksco-op-reviewco-op-translator-mcp
הפקודות translate, evaluate, migrate-links ו-co-op-review מנותבות דרך co_op_translator.__main__, שלפיו נבחר מימוש הפקודה על פי שם הסקריפט שהופעל. שרת ה-MCP משתמש ישירות ב-co_op_translator.mcp.server.
אם אתם מתלבטים בין CLI, Python API, ו‑MCP, התחילו עם בחר את זרימת העבודה.
פלט למסוף¶
טרמינלים אינטראקטיביים משתמשים בעיצוב Rich עבור כותרת הפקודה, סרגלי ההתקדמות והסיכומים. פלט ב‑CI ובמצבים לא אינטראקטיביים חוזר אוטומטית לטקסט פשוט.
הגדר את CO_OP_TRANSLATOR_OUTPUT_STYLE=plain כדי לכפות פלט פשוט, או CO_OP_TRANSLATOR_OUTPUT_STYLE=rich כדי לכפות פלט Rich. הגדר CO_OP_TRANSLATOR_NO_PROGRESS=1 כדי לשמור על סיכומים תוך דיכוי פסי התקדמות חיים.
השתמש ב-translate --json-events progress.ndjson כאשר מערכת אחרת זקוקה ל
התקדמות הניתנת לקריאה על-ידי מכונה. ה-CLI ממשיך להציג פלט המיועד לבני אדם, בעוד
קובץ NDJSON מקבל אירועי co-op.translation.event.v1 בגרסאות עם
שדות יציבים כגון type, stage_key, completed, total, ו
current_path.
זרימת CLI בפעם הראשונה¶
התחילו כאן אם אתם משתמשים ב‑Co-op Translator מהטרמינל:
- קבעו ספק LLM כפי שמתואר ב‑תצורה.
- בחרו את סוג התוכן שברצונכם לתרגם.
- הריצו תחילה פקודה ממוקדת, כגון תרגום Markdown בלבד.
- השתמשו ב‑
--dry-runלפני שינויים משמעותיים במאגר. - השתמשו ב‑
co-op-reviewלאחר התרגום כדי לבדוק מבנה ורעננות.
| מטרה | פקודה להתחלה |
|---|---|
| תרגום מסמכי Markdown | translate -l "ko" -md |
| תרגום מחברות | translate -l "ko" -nb |
| תרגום טקסט בתמונות | translate -l "ko" -img |
| תצוגה מקדימה של העבודה ללא כתיבת קבצים | translate -l "ko" -md --dry-run |
| סקירת תרגומים קיימים | co-op-review -l "ko" |
| עדכון קישורים למחברות ו‑Markdown | migrate-links -l "ko" --dry-run |
| הנגשת כלים ללקוח MCP | קבעו את שרת MCP במקום להריץ פקודות CLI באופן ישיר. |
translate¶
תרגום קבצי Markdown, מחברות וטקסט שבתמונות לשפה אחת או יותר.
דוגמאות נפוצות¶
תרגום Markdown בלבד:
תרגום מחברות בלבד:
Translate Markdown and images:
עדכן תרגומים קיימים על ידי מחיקה ויצירה מחדש שלהם:
Run without interactive prompts:
שמירת יומנים:
כתיבת אירועי התקדמות מובנים:
אפשרויות¶
| אפשרות | נדרש | תיאור |
|---|---|---|
-l, --language-codes |
כן | קודי שפה מופרדים ברווח, כגון "es fr de", או "all". |
-r, --root-dir |
לא | ספריית שורש של הפרויקט. ברירת המחדל היא הספרייה הנוכחית. |
-u, --update |
לא | מחק תרגומים קיימים לשפות הנבחרות ויצר אותם מחדש. |
-img, --images |
לא | תרגם רק קבצי תמונה. |
-md, --markdown |
לא | תרגם רק קבצי Markdown. |
-nb, --notebook |
לא | תרגם רק קבצי Jupyter notebook. |
-d, --debug |
לא | הפעל רישום ברמת דיבוג בקונסול. |
-s, --save-logs |
לא | שמור יומני רישום ברמת DEBUG תחת <root-dir>/logs/. |
--json-events |
לא | כתוב אירועי התקדמות של תרגום בפורמט לקריאה מכנית כ‑NDJSON. |
-x, --fix |
לא | תרגם מחדש קבצי Markdown בעלי ביטחון נמוך בהתאם לתוצאות ההערכה הקודמות. |
-c, --min-confidence |
לא | סף ביטחון עבור --fix. ברירת המחדל היא 0.7. |
--add-disclaimer, --no-disclaimer |
לא | הוסף או השבת הודעות הבהרה של תרגום ממכונה. ברירת המחדל ב‑CLI היא שהן מאופשרות. |
-f, --fast |
לא | מצב מהיר לתמונות מיושן. |
-y, --yes |
לא | אשר אוטומטית הודעות, מועיל ב‑CI. |
--repo-url |
לא | כתובת המאגר המשמש בעצת sparse-checkout בטבלת השפות ב‑README. |
--migrate-language-folders |
לא | שנה שמות תיקיות כינויים ישנות, כגון cn או tw, לתיקיות תקניות לפי BCP 47. |
--dry-run |
לא | הצג תצוגה מקדימה של הגירת תיקיות שפה והערכות תרגום ללא כתיבת קבצים. |
אם לא נמסר דגל סוג, translate מעבד Markdown, מחברות ותמונות. תרגום תמונות דורש תצורת Azure AI Vision.
evaluate¶
הערכת איכות תרגומי Markdown עבור שפה אחת.
נסיוני
evaluate היא ניסיונית. היא יכולה להשתמש בבדיקות איכות מבוססות חוקים ובבדיקות מבוססות LLM, כותבת תוצאות הערכה למטא-נתוני התרגום, ומודל הניקוד שלה והתנהגות המטא-נתונים עלולים להשתנות.
דוגמאות נפוצות¶
השתמש בסף ביטחון נמוך מחמיר יותר:
הרץ בדיקות מבוססות-כללים בלבד:
הרץ בדיקות מבוססות LLM בלבד:
אפשרויות¶
| אפשרות | נדרש | תיאור |
|---|---|---|
-l, --language-code |
כן | קוד שפה יחיד להערכה. קודי כינוי מנורמלים. |
-r, --root-dir |
לא | ספריית השורש של הפרויקט. ברירת המחדל היא הספרייה הנוכחית. |
-c, --min-confidence |
לא | סף המשמש בעת רישום תרגומים בעלי ביטחון נמוך. ברירת המחדל היא 0.7. |
-d, --debug |
לא | הפעל רישום דיבוג. |
-s, --save-logs |
לא | שמור יומני רישום ברמת DEBUG תחת <root-dir>/logs/. |
-f, --fast |
לא | הערכה מבוססת-כללים בלבד. |
-D, --deep |
לא | הערכה מבוססת LLM בלבד. |
כברירת מחדל, evaluate משתמש הן בהערכה מבוססת-כללים והן בהערכה מבוססת LLM. התוצאות נכתבות למטא-נתוני התרגום ומסוכמות בקונסול.
co-op-review¶
הרץ בדיקות תחזוקה של תרגום דטרמיניסטיות ללא אישורי API.
בטא
co-op-review היא פקודת סקירה דטרמיניסטית בבטא. היא לא קוראת לספקי מודלים או כותבת קבצים, אבל הבדיקות שלה וסכמת פלט הבעיות עשויות להתפתח.
דוגמאות נפוצות¶
סקור תרגומים לקוריאנית ויפנית מהספרייה הנוכחית:
סקור שורש פרויקט מסוים:
סקור רק את ה‑README לאחר תרגום מסוג README בלבד:
--readme-only מתעלם ממסמכים אחרים ו‑READMEים מקוננים. הוא נכשל אם השורש
README.md חסר. בשילוב עם --changed-from, הוא בודק רק את ה‑README
כאשר קובץ המקור הזה השתנה. תרגום מסוג README בלבד משאיר את קובץ ה‑README המקורי
ללא שינוי, כולל כל סימני מקטעים משותפים.
סקור רק קבצי המקור שהשתנו ביחס ל‑ref בסיסי:
הדפס פלט Markdown בסגנון GitHub לסיכומי CI:
אפשרויות¶
| אפשרות | נדרש | תיאור |
|---|---|---|
-l, --language-code |
לא | קוד שפה לסקירה. ניתן להעביר מספר פעמים או כערך מופרד ברווח. ברירת המחדל היא כל שפות התרגום שהתגלו. |
-r, --root-dir |
לא | ספריית השורש של הפרויקט. ברירת המחדל היא הספרייה הנוכחית. |
--changed-from |
לא | Git ref המשמש להגבלת הסקירה לקבצי מקור שהשתנו. |
--readme-only |
לא | סקור רק את תרגום קובץ השורש README.md. |
--format |
לא | פורמט הפלט: text או github. ברירת המחדל היא text. |
co-op-review בודק כעת קבצים מתורגמים חסרים, מטא-נתוני תרגום חסרים או מיושנים, שלמות frontmatter של Markdown וסגירות גדרות הקוד, JSON של מחברות מתורגמות לא תקין, ויעדי קישורים מקומיים ב‑Markdown או בתמונות חסרים. קישורים חסרים הם אזהרות כברירת מחדל; בעיות מבניות ורעננות גורמות לכישלון הפקודה.
co-op-translator-mcp¶
הרץ את שרת ה‑Co-op Translator MCP עבור סוכנים, עורכים ולקוחות תואמי MCP.
אמצעי התקשורת ברירת המחדל הוא stdio. עיין במדריך MCP Server עבור הגדרת הלקוח, כלים, משאבים והערות בטיחות.
אפשרויות¶
| אפשרות | נדרש | תיאור |
|---|---|---|
--transport |
לא | העברת MCP: stdio, streamable-http, או sse. ברירת המחדל היא stdio. |
migrate-links¶
עבד מחדש קבצי Markdown מתורגמים ועדכן קישורים למחברות כך שיצביעו למחברות מתורגמות כשזמינות.
דוגמאות נפוצות¶
תצוגה מקדימה של עדכוני קישורים:
עיבוד כל השפות הנתמכות ללא אישור:
כתוב מחדש קישורים רק כאשר מחברות מתורגמות קיימות:
אפשרויות¶
| אפשרות | נדרש | תיאור |
|---|---|---|
-l, --language-codes |
כן | קודי שפה מופרדים ברווח, או "all". |
-r, --root-dir |
לא | ספריית השורש של הפרויקט. ברירת המחדל היא הספרייה הנוכחית. |
--image-dir |
לא | תיקיית תמונות מתורגמות יחסית לשורש. ברירת המחדל היא translated_images. |
--dry-run |
לא | הצג קבצים שישתנו ללא כתיבת עדכונים. |
--fallback-to-original, --no-fallback-to-original |
לא | השתמש בקישורים המקוריים למחברות כאשר מחברות מתורגמות חסרות. מאופשר כברירת מחדל. |
-d, --debug |
לא | הפעל רישום דיבוג. |
-s, --save-logs |
לא | שמור יומני רישום ברמת DEBUG תחת <root-dir>/logs/. |
-y, --yes |
לא | אשר אוטומטית הודעות בעת עיבוד כל השפות. |
סביבה¶
כאשר פקודה דורשת אישורי ספק, קבעו אחד מערכי הספקים האלה. translate --dry-run ו‑co-op-review אינם דורשים אישורי ספק:
# אז'ור OpenAI
AZURE_OPENAI_API_KEY="..."
AZURE_OPENAI_ENDPOINT="https://<resource>.openai.azure.com/"
AZURE_OPENAI_MODEL_NAME="gpt-4o"
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="<deployment>"
AZURE_OPENAI_API_VERSION="2024-12-01-preview"
# או OpenAI
OPENAI_API_KEY="..."
OPENAI_CHAT_MODEL_ID="gpt-4o"
# או Anthropic
ANTHROPIC_API_KEY="..."
ANTHROPIC_MODEL="claude-..."
תרגום תמונות דורש בנוסף את Azure AI Vision:
AZURE_AI_SERVICE_API_KEY="..."
AZURE_AI_SERVICE_ENDPOINT="https://<resource>.cognitiveservices.azure.com/"
פריסת הפלט¶
תרשומים טקסטיים נכתבים תחת:
פלט תמונות מתורגמות נכתב תחת:
לדוגמה, תרגום של README.md ו־docs/setup.md לקוריאנית מייצר:
דוגמאות להעתקה והדבקה (CLI)¶
תרגם Markdown לשלוש שפות:
תרגם מחברות בלבד:
תרגם תמונות בלבד:
תצוגת תרגום Markdown ללא כתיבת קבצים:
תקן תרגומי Markdown בעלי ביטחון נמוך:
הרץ תרגום Markdown ידידותי ל‑CI:
סקור פלט מתורגם:
תצוגה מקדימה של הגירת קישורים: