Skip to content

Update CONTRIBUTING.md #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sepehr-rs merged 1 commit into from
Aug 18, 2026
Merged

Update CONTRIBUTING.md #48

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 49 additions & 10 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

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

تمام مشارکت‌کنندگان موظف‌اند از [آیین‌نامهٔ رفتاری PSF](https://www.python.org/psf/conduct/) پیروی کنند. این تعهد در همهٔ ایشیوها و پول‌ریکوئست‌ها به‌صورت یک چک‌باکس ثبت می‌شود.

## شروع کار

1. ریپازیتوری را روی GitHub **فورک** کنید و نسخهٔ خودتان را کلون کنید:
Expand Down Expand Up @@ -29,14 +31,24 @@

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

## انواع ایشیو

پیش از باز کردن ایشیوی جدید، قالب مناسب را از [صفحهٔ ایشیوهای پروژه](https://github.com/python/python-docs-fa/issues/new/choose) انتخاب کنید. سه قالب موجود است:

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

## فرایند ترجمه

1. فایل `.po` مورد نظر را با [Poedit](https://poedit.net) یا هر ویرایشگر متنی باز کنید.
1. فایلی را انتخاب کنید و بررسی کنید آیا [ایشیوی](https://github.com/python/python-docs-fa/issues) مربوط به آن باز شده است یا نه (قالب «درخواست ترجمهٔ صفحه»). اگر باز شده و ترجمهٔ کامل آن در حال انجام است، فایل دیگری را انتخاب کنید؛ در غیر این صورت یک ایشیو باز کرده و شروع به کار کنید.
2. فایل `.po` مورد نظر را با [Poedit](https://poedit.net) یا هر ویرایشگر متنی باز کنید.
- در 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)](GLOSSARY.md) برای ثابت نگه‌داشتن اصطلاحات استفاده کنید.
3. متن `msgid` را ترجمه کنید و در `msgstr` وارد کنید.
4. **نشانه‌گذاری‌های Sphinx** مثل `` :class:`int` `` ، `` :func:`repr` `` ، `` :ref:`...` `` ، `` ``code`` `` و **جای‌گذارها** مثل `%s` یا `{name}` را دقیقاً بدون تغییر نگه دارید؛ فقط متن اطراف آن‌ها ترجمه می‌شود. ترجمهٔ `target` در `` :term:`text <target>` `` ممنوع است چون لینک را خراب می‌کند.
5. داخل کدها (بلوک‌های `code-block`) نام متغیرها، توابع و کلمات کلیدی را ترجمه نکنید؛ فقط رشته‌ها و کامنت‌ها را می‌توانید ترجمه کنید.
6. از [واژه‌نامهٔ پروژه (GLOSSARY.md)](GLOSSARY.md) برای ثابت نگه‌داشتن اصطلاحات استفاده کنید.
7. اگر به اصطلاحی برخوردید که در واژه‌نامه نبود، ترجمه‌ای برای آن انتخاب کنید و به واژه‌نامه اضافه کنید.

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

Expand All @@ -50,9 +62,28 @@ 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` را حذف کنید.
رشته‌های `fuzzy` یعنی ترجمهٔ قبلی وجود دارد اما به دلیل تغییر متن اصلی (یا مداخلهٔ ابزارها) باید دوباره بررسی شود. این رشته‌ها در نسخهٔ نهایی ساخته‌شدهٔ مستندات نمایش داده نمی‌شوند و در جدول `STATUS.md` نیز در ستون «Fuzzy» شمارش می‌شوند. حتماً آن‌ها را بررسی، بازنویسی و سپس علامت `fuzzy` را حذف کنید.

## سربرگ فایل‌های `.po` و اعتبار مترجمان

Expand Down Expand Up @@ -81,7 +112,15 @@ python3 scripts/update_po_headers.py --no-credits \
python3 scripts/update_po_headers.py --merge bugs.po tutorial/
```

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

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

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

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

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

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

Expand All @@ -91,7 +130,7 @@ python3 scripts/update_po_headers.py --merge bugs.po tutorial/

فهرست اعضای تیم همراه با آمار مشارکت در [TEAM.md](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` انجام می‌شود.
ستون «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` انجام می‌شود.

## همگام‌سازی با نسخه‌های جدید پایتون

Expand All @@ -107,6 +146,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` می‌توانید وضعیت دقیق هر فایل را ببینید.
با `python3 scripts/translation_status.py --only-incomplete` می‌توانید وضعیت دقیق هر فایل را ببینید.
Loading