ترجمه، ویرایش و بازبینی یک پروژهٔ کوچک¶

با دو فایل کوتاه Markdown و یک زبان هدف شروع کنید. شما خواهید دید ترجمه‌ها کجا نوشته می‌شوند، وقتی منبع تغییر می‌کند چه اتفاقی می‌افتد، و چگونه نتیجه را بررسی کنید.

نتایج ثبت‌شده¶

این مثال در 19 سپتامبر 2026 با Co-op Translator 0.21.0 و Azure OpenAI (gpt-5-mini) اجرا شد. فرمان‌های CLI بدون تغییر از طریق CliRunner کتابخانه Click با استفاده از wheel ساخته‌شده و وابستگی‌های موجود پایتون فراخوانی شدند.

مرحله	نتیجه
پیش‌نمایش	خروج 0؛ هیچ ترجمه‌ای از مدل درخواست نشد
ترجمهٔ اولیه	خروج 0؛ 27.36 ثانیه
بازبینی اولیه	خروج 0
ویرایش README و بازبینی	خروج 1؛ ترجمهٔ قدیمی شناسایی شد
به‌روزرسانی ترجمه	خروج 0؛ 22.17 ثانیه
بازبینی پس از به‌روزرسانی	خروج 0؛ بدون خطا یا هشدار
راهنمای بدون تغییر	بایت‌های یکسان قبل و بعد از به‌روزرسانی README
اجرای مجدد	خروج 0؛ هش‌ش‌های یکسان برای همهٔ فایل‌های ترجمه

این‌ها اندازه‌گیری‌های اجرای جداگانه هستند، نه تضمین‌های عملکرد. زمان راه‌اندازی مستثنی است؛ صورتحساب ارائه‌دهنده اندازه‌گیری نشد. اجرای بدون تغییر هنوز هم ممکن است بررسی سلامت ارائه‌دهنده را انجام دهد.

بازبینی ترجمهٔ اولیه، ترجمهٔ به‌روز‌شده، تفاضل کامل ترجمه، بازبینی قدیمی، بازبینی نهایی، و جزئیات اجرا را بررسی کنید. ترجمهٔ تمام-فایل ممکن است واژگان دیگر را تغییر دهد، همان‌طور که تفاضل ثبت‌شده نشان می‌دهد. هر دو اثر متنی سلب‌مسئولیت تولید‌شده را حفظ می‌کنند.

بازبینی انسانی همچنان اهمیت دارد: به‌روزرسانی ثبت‌شده از [사용 가이드](guide.md)을 استفاده می‌کند؛ Part کره‌ای باید [사용 가이드](guide.md)를 باشد. متن‌های ضبط‌شده این خروجی را دست‌نخورده نگه می‌دارند به‌جای اینکه یک ترجمهٔ ویرایش‌شده را به‌عنوان خروجی مدل ارائه کنند. بازبینی ساختاری با وجود این مشکل نگارشی قبول می‌شود.

1. یک پوشهٔ کوچک آماده کنید¶

از Python 3.11–3.14 و تنظیم محیط مجازی استفاده کنید. نسخه‌ای را که برای این مثال استفاده شده نصب کنید:

python -m pip install co-op-translator==0.21.0
mkdir translation-demo
cd translation-demo
git init

فایل‌های README.txt و guide.txt را در این پوشه دانلود کنید و آن‌ها را به‌صورت README.md و guide.md ذخیره کنید. آن‌ها اسناد پروژهٔ داستانی کوچکی هستند؛ نیازی به نصب برنامه نیست.

README شامل یک بلوک کد و یک لینک به guide.md است. جملهٔ پایانی آن این است:

Notes are saved locally.

فقط همین دو سند منبع را در این پوشه نگه دارید. همهٔ دستورهای بعدی در داخل translation-demo اجرا می‌شوند و در Bash و PowerShell کار می‌کنند.

2. پیش‌نمایش بدون اعتبارنامه¶

translate -l "ko" -md --dry-run

پیش‌نمایش، حجم کار ترجمه را بدون فراخوانی مدل یا نوشتن ترجمه‌ها برآورد می‌کند. برآورد توکن‌ها یک نقل‌قول صورتحساب نیست. اجرای اول باید هر دو فایل Markdown را به‌عنوان کار جدید شناسایی کند.

3. انتخاب ارائه‌دهنده و ترجمه¶

یک ارائه‌دهنده را با استفاده از راهنمای پیکربندی پیکربندی کنید: Azure OpenAI، OpenAI، یا Anthropic. ترجمهٔ متنی با OpenAI و Anthropic نیاز به حساب Azure ندارد. سرویس‌های تصویر برای این مثال لازم نیستند.

اگر از فایل محلی .env استفاده می‌کنید، .env را به .gitignore این پوشه اضافه کنید. فراخوانی‌های ترجمه از حساب ارائه‌دهندهٔ شما استفاده می‌کنند و ممکن است هزینه داشته باشند.

translate -l "ko" -md
co-op-review -l "ko"

فایل‌های translations/ko/README.md و translations/ko/guide.md را باز کنید. واژگان کره‌ای، بلوک کد، و لینکی که از README ترجمه‌شده به guide ترجمه‌شده می‌رود را بررسی کنید. نگارش خروجی بسته به مدل متفاوت است.

co-op-review تازگی، ساختار، و لینک‌های محلی را بررسی می‌کند. نتیجهٔ قبول‌شده دقت زبانی را تضمین نمی‌کند. قبل از ادامه هر خطای گزارش‌شده را حل کنید.

پایهٔ موفق را با Git ثبت کنید (در صورت نیاز ابتدا هویت Git خود را پیکربندی کنید):

git add README.md guide.md translations
git commit -m "Record initial Korean translation"

4. تغییر منبع¶

در README.md، Notes are saved locally. را باِ عبارت زیر جایگزین کنید:

Notes are saved locally as Markdown files.

فایل guide.md را بدون تغییر بگذارید. سپس اجرا کنید:

co-op-review -l "ko"
translate -l "ko" -md --dry-run

بازبینی باید گزارش دهد که ترجمهٔ README قدیمی است و با خطا خارج شود. این وضعیت میانی مورد انتظار است. پیش‌نمایش باید کار مربوط به README تغییر‌یافته را شناسایی کند.

5. به‌روزرسانی و بررسی اختلاف¶

translate -l "ko" -md
git diff -- README.md translations/ko/README.md
git diff -- translations/ko/guide.md
co-op-review -l "ko"

اختلاف واقعی را بررسی کنید: CLI پیش‌فرض فایل تغییر‌یافته را دوباره ترجمه می‌کند، بنابراین مدل می‌تواند سایر واژگان همان فایل را نیز بازنگری کند. راهنمای بدون تغییر نباید اختلافی داشته باشد. بازبینی دیگر نباید README را به‌عنوان قدیمی گزارش دهد؛ به‌جای نادیده گرفتن هر یافتهٔ دیگر، آن‌ها را بررسی کنید.

حفظ سطح بلوکی ویرایش‌های انسانی Markdown نیازمند یک ارائه‌دهندهٔ وضعیت ترجمهٔ اختیاری در Python API است. این قابلیت توسط این فرمان‌های CLI فعال نشده است.

6. اجرای مجدد بدون تغییر¶

تغییرات منبع و ترجمهٔ به‌روزشده را commit کنید:

git add README.md translations
git commit -m "Update Korean translation after source edit"
translate -l "ko" -md
git diff --exit-code -- translations

با ترجمه‌های فعلی و پیکربندی بدون تغییر، مترجم فایل‌ها را نادیده می‌گیرد. فرمان نهایی Git نباید اختلافی ایجاد کند و باید با موفقیت خارج شود.