مرجع CLI¶

Co-op Translator این نقاط ورود خط فرمان را نصب می‌کند:

translate
evaluate
migrate-links
co-op-review
co-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 را تنظیم کنید، یا برای اجبار خروجی Rich CO_OP_TRANSLATOR_OUTPUT_STYLE=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	به‌جای اجرای مستقیم دستورات CLI، سرور MCP را پیکربندی کنید.

translate¶

فایل‌های Markdown، نوت‌بوک‌ها، و متن تصاویر را به یک یا چند زبان مقصد ترجمه کنید.

translate -l "ko ja fr"

مثال‌های رایج¶

فقط فایل‌های Markdown را ترجمه کنید:

translate -l "de" -md

فقط نوت‌بوک‌ها را ترجمه کنید:

translate -l "zh-CN" -nb

Markdown و تصاویر را ترجمه کنید:

translate -l "pt-BR" -md -img

به‌روزرسانی ترجمه‌های موجود با حذف و بازایجاد آن‌ها:

translate -l "ko" -u

بدون پرسش‌های تعاملی اجرا کنید:

translate -l "ko ja" -md -y

ذخیره لاگ‌ها:

translate -l "ko" -s

نوشتن رویدادهای پیشرفت ساختاریافته:

translate -l "ko ja" -md --json-events progress.ndjson

گزینه‌ها¶

گزینه	ضروری	توضیحات
`-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`	خیر	URL مخزن که در توصیه sparse-checkout جدول زبان‌های README استفاده می‌شود.
`--migrate-language-folders`	خیر	تغییر نام پوشه‌های جایگزین قدیمی، مانند `cn` یا `tw`, به پوشه‌های استاندارد BCP 47.
`--dry-run`	خیر	پیش‌نمایش مهاجرت پوشه‌های زبان و برآوردهای ترجمه بدون نوشتن فایل‌ها.

اگر هیچ فلگ نوعی ارائه نشود، translate فایل‌های Markdown، نوت‌بوک‌ها، و تصاویر را پردازش می‌کند. ترجمه تصویر نیاز به پیکربندی Azure AI Vision دارد.

evaluate¶

کیفیت ترجمه‌های Markdown را برای یک زبان ارزیابی کنید.

آزمایشی

evaluate آزمایشی است. می‌تواند از بررسی‌های کیفی مبتنی بر قوانین و مبتنی بر LLM استفاده کند، نتایج ارزیابی را در فراداده ترجمه می‌نویسد، و مدل امتیازدهی و رفتار فراداده ممکن است تغییر کند.

evaluate -l "ko"

مثال‌های رایج¶

استفاده از آستانه سخت‌گیرانه‌تر برای اطمینان پایین:

evaluate -l "es" -c 0.8

فقط بررسی‌های مبتنی بر قانون را اجرا کنید:

evaluate -l "fr" -f

فقط بررسی‌های مبتنی بر LLM را اجرا کنید:

evaluate -l "ja" -D

گزینه‌ها¶

گزینه	ضروری	توضیحات
`-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 یک دستور بازبینی بتا و قطعی است. این دستور ارائه‌دهندگان مدل را فراخوانی نمی‌کند و فایل‌ها را نمی‌نویسد، اما بررسی‌ها و طرح خروجی مسائل آن ممکن است تکامل یابد.

co-op-review -l "ko"

مثال‌های رایج¶

بازبینی ترجمه‌های کره‌ای و ژاپنی از دایرکتوری فعلی:

co-op-review -l "ko ja"

بازبینی یک ریشه پروژه مشخص:

co-op-review -l "fr" -r ./my-course

فقط README را پس از ترجمه‌ای که فقط README را دربرمی‌گیرد بازبینی کنید:

translate -l "ko" --readme-only -y
co-op-review -l "ko" --readme-only --format github

--readme-only سایر اسناد و READMEهای تو در تو را نادیده می‌گیرد. این گزینه در صورتی که ریشه README.md در ریشه موجود نباشد، ناموفق می‌شود. در ترکیب با --changed-from، تنها README را بازبینی می‌کند وقتی آن فایل منبع تغییر کرده باشد. ترجمه فقط-README، README منبع را تغییر‌نخورده باقی می‌گذارد، از جمله هر نشانگر بخش مشترک.

فقط فایل‌های منبعی را که نسبت به یک مرجع پایه تغییر کرده‌اند بازبینی کنید:

co-op-review -l "ko" --changed-from origin/main

خروجی Markdown با فرمت GitHub را برای خلاصه‌های CI چاپ کنید:

co-op-review -l "ko ja" --changed-from origin/main --format github

گزینه‌ها¶

گزینه	ضروری	توضیحات
`-l`, `--language-code`	خیر	کد زبان برای بازبینی. می‌تواند چند بار پاس‌دهی شود یا به‌صورت یک مقدار جداشده با فاصله باشد. پیش‌فرض تمام زبان‌های ترجمه‌شده کشف‌شده.
`-r`, `--root-dir`	خیر	ریشه پروژه. پیش‌فرض دایرکتوری جاری است.
`--changed-from`	خیر	مرجع Git که برای محدود کردن بازبینی به فایل‌های منبع تغییر‌یافته استفاده می‌شود.
`--readme-only`	خیر	فقط ترجمه `README.md` ریشه را بازبینی کند.
`--format`	خیر	فرمت خروجی: `text` یا `github`. پیش‌فرض `text`.

co-op-review در حال حاضر بررسی وجود فایل‌های ترجمه‌شده مفقود، فراداده ترجمه مفقود یا قدیمی، انسجام frontmatter و code fence در Markdown، JSON نوت‌بوک ترجمه‌شده نامعتبر، و هدف‌های لینک محلی Markdown یا تصویر مفقود را انجام می‌دهد. لینک‌های مفقود به‌صورت پیش‌فرض هشدار هستند؛ مشکلات ساختاری و تازگی باعث شکست دستور می‌شوند.

co-op-translator-mcp¶

سرور MCP Co-op Translator را برای عامل‌ها، ویرایشگرها و کلاینت‌های سازگار با MCP اجرا کنید.

co-op-translator-mcp

انتقال پیش‌فرض stdio است. برای پیکربندی کلاینت، ابزارها، منابع و نکات ایمنی به راهنمای سرور MCP مراجعه کنید.

گزینه‌ها¶

گزینه	ضروری	توضیحات
`--transport`	خیر	انتقال MCP: `stdio`، `streamable-http`، یا `sse`. پیش‌فرض `stdio`.

migrate-links¶

فایل‌های Markdown ترجمه‌شده را دوباره پردازش کرده و لینک‌های نوت‌بوک را به‌روز کنید تا هرگاه موجود باشند به نوت‌بوک‌های ترجمه‌شده اشاره کنند.

migrate-links -l "ko ja"

مثال‌های رایج¶

پیش‌نمایش به‌روزرسانی لینک‌ها:

migrate-links -l "ko" --dry-run

پردازش تمام زبان‌های پشتیبانی‌شده بدون تأیید:

migrate-links -l "all" -y

فقط زمانی لینک‌ها را بازنویسی کنید که نوت‌بوک‌های ترجمه‌شده وجود داشته باشند:

migrate-links -l "ko" --no-fallback-to-original

گزینه‌ها¶

گزینه	ضروری	توضیحات
`-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 به اعتبارنامه ارائه‌دهنده نیاز ندارند:

# آزور اوپن‌ای‌آی
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_API_KEY="..."
OPENAI_CHAT_MODEL_ID="gpt-4o"

# یا آنتروپیک
ANTHROPIC_API_KEY="..."
ANTHROPIC_MODEL="claude-..."

ترجمه تصویر علاوه بر این نیاز به Azure AI Vision دارد:

AZURE_AI_SERVICE_API_KEY="..."
AZURE_AI_SERVICE_ENDPOINT="https://<resource>.cognitiveservices.azure.com/"

چیدمان خروجی¶

ترجمه‌های متنی در زیر نوشته می‌شوند:

translations/<language-code>/<original-path>

خروجی تصاویر ترجمه‌شده در زیر نوشته می‌شود:

translated_images/<language-code>/<original-path>

برای مثال، ترجمهٔ README.md و docs/setup.md به زبان کره‌ای خروجی زیر را تولید می‌کند:

translations/ko/README.md
translations/ko/docs/setup.md

مثال‌های قابل کپی/چسباندن CLI¶

Markdown را به سه زبان ترجمه کنید:

translate -l "ko ja fr" -md

فقط نوت‌بوک‌ها را ترجمه کنید:

translate -l "zh-CN" -nb

فقط تصاویر را ترجمه کنید:

translate -l "pt-BR" -img

پیش‌نمایش ترجمه Markdown بدون نوشتن فایل‌ها:

translate -l "de es" -md --dry-run

اصلاح ترجمه‌های Markdown با اطمینان پایین:

evaluate -l "ko" -c 0.8
translate -l "ko" --fix -c 0.8 -md

اجرای ترجمه Markdown سازگار با CI:

translate -l "ko ja" -md -y -s

بازبینی خروجی ترجمه‌شده:

co-op-review -l "ko ja"

پیش‌نمایش مهاجرت لینک‌ها:

migrate-links -l "ko" --dry-run