CONTRIBUTING.md

راهنمای مشارکت در ترجمه‌ی مستندات پایتون

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

تمام مشارکت‌کنندگان موظف‌اند از آیین‌نامه‌ی رفتاری PSF پیروی کنند. این تعهد در همه‌ی ایشیوها و پول‌ریکوئست‌ها به‌صورت یک چک‌باکس ثبت می‌شود.

شروع کار

1. ریپازیتوری را روی GitHub منشعب کنید و نسخه‌ی خودتان را رونوشت کنید:

   git clone https://github.com/<username>/python-docs-fa.git
   cd python-docs-fa
   git remote add upstream https://github.com/python/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 (ترجمه‌ی فارسی) است.

انواع ایشیو

پیش از باز کردن ایشیوی جدید، قالب مناسب را از صفحه‌ی ایشیوهای پروژه انتخاب کنید. چهار قالب موجود است:

• درخواست ترجمه‌ی صفحه: برای اعلام اینکه می‌خواهید صفحه‌ای را ترجمه کنید، یا برای درخواست اولویت‌دادن به ترجمه‌ی یک صفحه‌ی خاص (مثلاً چون برای فعال‌سازی فارسی در تغییردهنده‌ی زبان لازم است). قبل از شروع ترجمه‌ی هر پرونده، از همین قالب استفاده کنید تا دیگران بدانند آن پرونده در حال انجام است.
• پرسش یا پیشنهاد واژه‌نامه: برای سؤال درباره‌ی قواعد ترجمه، یا پیشنهاد اصطلاح جدید برای افزودن به GLOSSARY.md.
• اشکال در ترجمه: برای گزارش ترجمه‌ی نادرست یا مشکل‌دار در یک صفحه‌ی منتشرشده. msgid، msgstr فعلی، و ترجمه‌ی پیشنهادی خود را در قالب وارد کنید.
• پیشنهاد تغییرات در ترجمه: برای پیشنهاد تغییر در یک واژه یا شیوه‌ی نگارشِ ثابت‌شده (نه یک اشکال ساده). فرایند بررسی این نوع پیشنهاد در بخش «پیشنهاد تغییر در واژه یا شیوه‌ی نگارش» توضیح داده شده است.

فرایند ترجمه

1. پرونده‌ای را انتخاب کنید و بررسی کنید آیا ایشیوی مربوط به آن باز شده است یا نه (قالب «درخواست ترجمه‌ی صفحه»). اگر باز شده و ترجمه‌ی کامل آن در حال انجام است، پرونده‌ی دیگری را انتخاب کنید؛ در غیر این صورت یک ایشیو باز کرده و شروع به کار کنید.

2. پرونده‌ی .po مورد نظر را با Poedit یا هر ویرایشگر متنی باز کنید.

   • در Poedit رشته‌های ترجمه‌نشده یا fuzzy را از پنل فیلتر (Filter) پیدا کنید.

3. متن msgid را ترجمه کنید و در msgstr وارد کنید.

4. نشانه‌گذاری‌های Sphinx مثل :class:`int`، :func:`repr`، :ref:`...`، code و جای‌گذارها مثل %s یا {name} را دقیقاً بدون تغییر نگه دارید؛ فقط متن اطراف آن‌ها ترجمه می‌شود. در :term:`target`، اگر عبارت داخل بک‌تیک با شناسه‌ی واژه‌نامه یکی است، می‌توانید آن را به شکل :term:`ترجمه <target>` بنویسید تا هم متن ترجمه‌شده نمایش داده شود و هم لینک درست کار کند؛ در این حالت فقط بخش نمایشی (پیش از <) ترجمه می‌شود و target داخل <> باید دقیقاً همان شناسه‌ی انگلیسی اصلی (بدون تغییر) باقی بماند، چون تغییر آن لینک را خراب می‌کند.

5. داخل کدها (بلوک‌های code-block) نام متغیرها، توابع، کلمات کلیدی و کامنت‌ها ترجمه نمی‌شوند؛ چون کد از راست به چپ نوشته نمی‌شود و وجود متن فارسی داخل آن، کد را ناخوانا می‌کند. فقط رشته‌های متنی (string) قابل‌ترجمه‌اند.

6. اگر به اصطلاحی برخوردید که در واژه‌نامه نبود، ترجمه‌ای برای آن انتخاب کنید و به واژه‌نامه اضافه کنید.

بررسی‌ها قبل از ارسال پول‌ریکوئست

# بررسی اعتبار پرونده
msgfmt --check your_file.po

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

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

پس از باز کردن پول‌ریکوئست، ری‌دِ‌دراکس (Read the Docs) به‌صورت خودکار نسخه‌ی ساخته‌شده‌ی مستندات را می‌سازد؛ از بخش checks پول‌ریکوئست می‌توانید لینک پیش‌نمایش را باز کنید و ترجمه‌ی خود را به‌صورت رندرشده ببینید.

نکات نگارشی و تایپوگرافی فارسی

برای یکدست ماندن ترجمه‌ها، این نکات نگارشی را رعایت کنید:

• «هٔ» در برابر «ه‌ی»: از ترکیب «هٔ» (ه همزه‌دار/ سریا) استفاده نکنید؛ به‌جای آن از «ه‌ی» (با نیم‌فاصله) استفاده کنید. مثال درست: «برنامه‌ی پایتون». مثال نادرست: «برنامهٔ پایتون».

• نیم‌فاصله (ZWNJ): در جاهایی که نیم‌فاصله لازم است (مثل «می‌شود»، «می‌کنید»، جمع با «ها» نظیر «پرونده‌ها»، یا پیشوندهایی مثل «بی‌» و «نا‌») از کاراکتر نیم‌فاصله‌ی واقعی (U+200C) استفاده کنید، نه فاصله‌ی معمولی یا بدون فاصله. مثال درست: «پرونده‌های ترجمه‌نشده». مثال نادرست: «پرونده های ترجمه نشده» یا «فایلهای ترجمه‌نشده».

• اعداد فارسی در برابر اعداد لاتین: در متن روایی فارسی از ارقام فارسی (۰۱۲۳۴۵۶۷۸۹) استفاده کنید (مثلاً «در نسخه‌ی ۳ پایتون»). اما داخل کد، شماره‌ی نسخه‌ی پایتون، مسیر پرونده‌ها، لینک‌ها و هر جایی که عدد بخشی از یک شناسه‌ی فنی است (مثل v3.14.6)، همیشه از ارقام لاتین استفاده کنید و آن‌ها را تغییر ندهید.

• علائم نگارشی فارسی در برابر انگلیسی: در متن فارسی از علائم فارسی استفاده کنید: «،» به‌جای «,» و «؟» به‌جای «?». علائمی که داخل کد، نشانه‌گذاری‌های Sphinx، یا جای‌گذارها هستند دست‌نخورده باقی می‌مانند (چون بخشی از متن انگلیسی اصلی محسوب نمی‌شوند و نباید تغییر کنند).

سطح رسمیت و لحن نوشتار

مستندات پایتون رسمی هستند، پس ترجمه‌ی فارسی هم باید در سطح رسمی نوشته شود؛ نه محاوره‌ای و نه بیش‌ازحد تشریفاتی. چند نکته‌ی عملی:

• برای اشاره به خواننده همیشه از «شما» استفاده کنید، نه «تو». این مورد باید در کل پرونده و در کل پروژه یکدست بماند.
• افعال را به‌صورت رسمی و کامل بنویسید (مثلاً «می‌توانید» نه «می‌تونید»).
• از واژه‌های محاوره‌ای، اختصارات غیررسمی یا شکسته‌نویسی خودداری کنید.
• لحن باید دوستانه و راهنما باشد، اما رسمیتِ متن باید همان سطحی باشد که در مستندات رسمی سایر زبان‌ها (مثل نسخه‌ی انگلیسی) دیده می‌شود.

رشته‌های fuzzy

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

سرآیند پرونده‌های .po و اعتبار مترجمان

هر پرونده‌ی .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/python/python-docs-fa/)" \
    bugs.po tutorial/

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

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

اندازه‌ی پول‌ریکوئست

هر پول‌ریکوئست را به حداکثر ۴ پرونده‌ی .po محدود کنید. این محدودیت هم از پول‌ریکوئست‌های بزرگ و غیرقابل‌بازبینی جلوگیری می‌کند و هم از سیل پول‌ریکوئست‌های تک‌پرونده‌ای برای پرونده‌های خیلی کوچک. اگر چند پرونده‌ی کوچک و مرتبط دارید (مثلاً چند پرونده زیر یک پوشه)، بسته‌بندی‌شان در یک پول‌ریکوئست مشکلی ندارد، تا سقف ۴ پرونده. برای پرونده‌های بزرگ، یک پول‌ریکوئست جداگانه برای هرکدام بهتر است.

اگر بررسی‌های CI رد شد

اگر بررسی‌های خودکار روی پول‌ریکوئست شما رد شدند، به تب Actions در گیت‌هاب بروید و ببینید کدام بررسی مشکل داشته، سپس اسکریپت متناظر آن را به‌صورت محلی اجرا کنید (مثلاً msgfmt --check، scripts/check_markup.py، یا sphinx-lint) تا خطا را پیدا و برطرف کنید.

فرایند بازبینی و نقش‌ها

• مترجم: پرونده‌ها را ترجمه می‌کند و پول‌ریکوئست می‌زند.
• بازبین (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 می‌توانید وضعیت دقیق هر پرونده را ببینید.

پیشنهاد تغییر در واژه یا شیوه‌ی نگارش

اگر می‌خواهید تغییری در ترجمه‌ی یک واژه‌ی ثابت‌شده یا در یکی از شیوه‌های نگارشی رایج پروژه پیشنهاد دهید، این فرایند را دنبال کنید:

1. یک ایشیو با قالب «پیشنهاد تغییرات در ترجمه» باز کنید.
2. پس از تأیید اولیه‌ی نگهدارندگان پروژه، یک نظرسنجی هم‌زمان در گروه تلگرام و در همان ایشیوی گیت‌هاب (با گزینه‌های پسندیدن/نپسندیدن) آغاز می‌شود.
3. این نظرسنجی به مدت دو هفته باز می‌ماند. در پایان این بازه، مجموع آرای موافق و مخالف تعیین می‌کند که آیا تغییر در مستندات اعمال شود یا نه.
4. اگر تغییر رأی نیاورد، پیشنهاد همان تغییر را می‌توان پس از گذشت چهار هفته دوباره به رأی گذاشت.
5. اگر تغییر رأی بیاورد، به یک ایشیوی اصلی (master issue) که فهرست کارها و تغییرات قابل‌انجام را ردیابی می‌کند اضافه می‌شود، تا هر مشارکت‌کننده‌ای که بخواهد بتواند آن را انجام دهد.