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 (ترجمه‌ی فارسی) است.

انواع ایشو

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

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

فرایند ترجمه

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

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

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

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

4. برای پیدا کردن ترجمه‌ی مناسب برای کلمات و عبارات تخصصی، از این پیوند به واژه‌یاب پایتون رفته و واژه/عبارت موردنظر خود را جست‌جو کنید.

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

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

7. اگر به اصطلاحی برخوردید که در واژه‌نامه نبود و فکر میکنید که باید در واژه‌نامه باشد، به بخش «افزودن واژه یا اصطلاح جدید به واژه‌نامه» همین پرونده بروید.

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

# بررسی اعتبار پرونده
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 می‌توانید وضعیت دقیق هر پرونده را ببینید.

گزارش اشکال در ترجمه

اگر اشکالی در ترجمه‌ی یکی از صفحه‌ها پیدا کرده‌اید، لطفاً یک ایشو با قالب «اشکال در ترجمه» ایجاد کنید.

در ایشو، لطفاً موارد زیر را ذکر کنید:

• محل دقیق ترجمه‌ی مشکل‌دار (مسیر پرونده یا لینک صفحه)
• در صورت نیاز، تصویری از ترجمه
• در صورت دسترسی، متن msgid و msgstr مربوطه

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

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

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

افزودن واژه یا اصطلاح جدید به واژه‌نامه

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

پیشنهادهای افزودن واژه‌ی جدید نیز پس از بررسی اولیه‌ی نگهدارندگان، در صورت نیاز از همان فرایند نظرسنجی توضیح داده شده در بالا استفاده خواهند کرد تا درباره‌ی پذیرش یا رد آن تصمیم‌گیری شود.

مشارکت‌ها به واژه‌نامه باید به پرونده‌ی glossary.tsv انجام شوند.