این راهنما مکمل README.md است و جزئیات فنی و فرایندهای پروژه را توضیح می‌دهد. پیش از شروع، حتماً README.md و واژه‌نامه (GLOSSARY.md) را هم بخوانید.

1. ریپازیتوری را روی GitHub فورک کنید و نسخهٔ خودتان را کلون کنید:

   git clone https://github.com/<username>/python-docs-fa.git
   cd python-docs-fa
   git remote add upstream https://github.com/revisto/python-docs-fa.git

2. یک شاخه برای کارتان بسازید (نام شاخه باید گویا باشد، مثلاً translate-something):

   git checkout -b translate-functions

3. کارتان را روی شاخهٔ 3.14 (شاخهٔ پیش‌فرض) آماده کنید.
4. بعد از ترجمه، تغییرات را روی شاخهٔ خودتان پوش کنید و یک پول‌ریکوئست به شاخهٔ 3.14 باز کنید.

فایل‌های .po ساختار مستندات اصلی پایتون را دنبال می‌کنند؛ یعنی هر فایل مربوط به یک صفحهٔ مستندات است:

• bugs.po — صفحهٔ «گزارش باگ»
• tutorial/*.po — آموزش پایتون
• library/*.po — کتابخانهٔ استاندارد
• c-api/*.po — رابط C
• using/، reference/، howto/، faq/، whatsnew/، extending/، installing/، distributing/، deprecations/ و غیره

هر فایل .po شامل جفت‌های msgid (متن انگلیسی) و msgstr (ترجمهٔ فارسی) است.

1. فایل .po مورد نظر را با Poedit یا هر ویرایشگر متنی باز کنید.
   • در Poedit رشته‌های ترجمه‌نشده یا fuzzy را از پنل فیلتر (Filter) پیدا کنید.
2. متن msgid را ترجمه کنید و در msgstr وارد کنید.
3. نشانه‌گذاری‌های Sphinx مثل :class:`int` ، :func:`repr` ، :ref:`...` ، code و جای‌گذارها مثل %s یا {name} را دقیقاً بدون تغییر نگه دارید؛ فقط متن اطراف آن‌ها ترجمه می‌شود. ترجمهٔ target در :term:`text <target>` ممنوع است چون لینک را خراب می‌کند.
4. داخل کدها (بلوک‌های code-block) نام متغیرها، توابع و کلمات کلیدی را ترجمه نکنید؛ فقط رشته‌ها و کامنت‌ها را می‌توانید ترجمه کنید.
5. از واژه‌نامهٔ پروژه (GLOSSARY.md) برای ثابت نگه‌داشتن اصطلاحات استفاده کنید.

# بررسی اعتبار فایل
msgfmt --check your_file.po

# بررسی حفظ نشانه‌گذاری‌های Sphinx
python3 scripts/check_markup.py your_file.po

روی هر پول‌ریکوئست، به‌صورت خودکار این بررسی‌ها (به‌همراه sphinx-lint و ساخت کامل مستندات) در GitHub Actions اجرا می‌شوند.

رشته‌های fuzzy یعنی ترجمهٔ قبلی وجود دارد اما به دلیل تغییر متن اصلی (یا مداخلهٔ ابزارها) باید دوباره بررسی شود. این رشته‌ها در ساختهٔ نهایی مستندات نمایش داده نمی‌شوند و در جدول STATUS.md نیز در ستون «Fuzzy» شمارش می‌شوند. حتماً آن‌ها را بررسی، بازنویسی و سپس علامت fuzzy را حذف کنید.

هر فایل .po در بخش سربرگ خود دو جایگاه برای ثبت اعتبار دارد:

• کامنت # Translators: — فهرست همهٔ کسانی که در ترجمهٔ آن فایل مشارکت داشته‌اند.
• فیلد Last-Translator: — آخرین کسی که فایل را ویرایش کرده است.

قانون اعتبار: ترجیحاً هر وقت فایلی را ویرایش می‌کنید، فیلد Last-Translator: را به نام خودتان تغییر دهید (به فرمت نام <ایمیل>, سال) و اگر نامتان در فهرست # Translators: نیست، آن را اضافه کنید. این کار اختیاری است: هماهنگ‌کننده/بازبین نهایی و اسکریپت update_po_headers.py (که در ادامه شرح داده شده) این اعتبارها را به‌صورت خودکار از تاریخچهٔ git بازسازی می‌کنند، پس اگر آن را انجام ندهید نگران نباشید.

برای بازسازی خودکار این اعتبارها از تاریخچهٔ git، اسکریپت زیر وجود دارد:

# بازسازی اعتبارهای همهٔ فایل‌ها از git history
python3 scripts/update_po_headers.py

# فقط پیش‌نمایش بدون اعمال تغییر
python3 scripts/update_po_headers.py --dry-run

# فقط اصلاح فیلد Language-Team بدون دست‌زدن به اعتبارها
python3 scripts/update_po_headers.py --no-credits \
    --language-team "Persian (https://github.com/revisto/python-docs-fa/)" \
    bugs.po tutorial/

# ادغام نام‌های جدید با فهرست موجود (نام‌های قبلی حذف نمی‌شوند)
python3 scripts/update_po_headers.py --merge bugs.po tutorial/

اسکریپت فقط سربرگ را تغییر می‌دهد و به متن ترجمه‌ها دست نمی‌زند، اما باگ‌های خودکار (مثل ربات‌های GitHub Actions) را از فهرست مترجمان حذف می‌کند. جزئیات کامل در docstring خود اسکریپت آمده است.

• مترجم: فایل‌ها را ترجمه می‌کند و پول‌ریکوئست می‌زند.
• بازبین (reviewer): ترجمه‌ها را از نظر صحت، یکدستی و رعایت واژه‌نامه بررسی می‌کند.
• هماهنگ‌کننده (coordinator): بر فرایندها نظارت دارد، پول‌ریکوئست‌ها را ادغام می‌کند و اعتبار مترجمان را در سربرگ فایل‌ها ثبت می‌کند.

فهرست اعضای تیم همراه با آمار مشارکت در TEAM.md نگهداری می‌شود.

ستون «Translated Count» در TEAM.md توسط scripts/team_stats.py محاسبه می‌شود: اسکریپت روی همهٔ فایل‌های .po تعداد رشته‌های ترجمه‌شده (به‌جز fuzzy) را می‌شمارد و با git blame هر رشته را به نویسندهٔ کامیتی نسبت می‌دهد که آخرین‌بار آن سطر را تغییر داده است. کامیت‌های مکانیکی (همگام‌سازی با CPython، به‌روزرسانی سربرگ «Update .po files» و کامیت‌های ربات/Transifex) شمرده نمی‌شوند و رشته‌های بدون نویسندهٔ مشخص در ردیف «(unassigned)» می‌افتند. این عدد تقریبی است و بنا به ماهیت git، سهم مترجمان دورهٔ Transifex که کارشان از طریق کامیت ربات وارد شده را نشان نمی‌دهد. این به‌روزرسانی به‌همراه بازسازی اعتبارهای سربرگ (با update_po_headers.py) و جدول STATUS.md، شبانه توسط گردش‌کار .github/workflows/maintenance.yml انجام می‌شود.

وقتی نسخهٔ جدیدی از پایتون منتشر می‌شود، متن انگلیسی مستندات تغییر می‌کند و فایل‌های .po باید با آن همگام شوند. اسکریپت scripts/update_python_version.py این کار را خودکار می‌کند:

# همگام‌سازی با نسخهٔ مشخص
python3 scripts/update_python_version.py v3.14.6

# نگه‌داشتن کپی موقت برای بررسی دستی
python3 scripts/update_python_version.py v3.15.0 --keep-src

این اسکریپت نسخهٔ مشخص‌شدهٔ CPython را کلون می‌کند، قالب‌های gettext (*.pot) را از روی آن می‌سازد، فایل‌های .po موجود را با msgmerge به‌روزرسانی می‌کند، برای صفحات جدید فایل .po تازه می‌سازد و در پایان همهٔ فایل‌ها را با msgfmt --check صحت‌سنجی می‌کند. بعد از اجرای آن، خروجی را بازبینی کنید و اعتبارهای سربرگ را (در صورت نیاز با scripts/update_po_headers.py) به‌روزرسانی کنید.

با python3 scripts/translation_status.py --only-incomplete می‌توانید وضعیت دقیق هر فایل را ببینید.