|
| 1 | +# راهنمای مشارکت در ترجمهٔ مستندات پایتون |
| 2 | + |
| 3 | +این راهنما مکمل [README.md](README.md) است و جزئیات فنی و فرایندهای پروژه را توضیح میدهد. پیش از شروع، حتماً [README.md](README.md) و [واژهنامه (GLOSSARY.md)](GLOSSARY.md) را هم بخوانید. |
| 4 | + |
| 5 | +## شروع کار |
| 6 | + |
| 7 | +1. ریپازیتوری را روی GitHub **فورک** کنید و نسخهٔ خودتان را کلون کنید: |
| 8 | + ```bash |
| 9 | + git clone https://github.com/<username>/python-docs-fa.git |
| 10 | + cd python-docs-fa |
| 11 | + git remote add upstream https://github.com/revisto/python-docs-fa.git |
| 12 | + ``` |
| 13 | +2. یک شاخه برای کارتان بسازید (نام شاخه باید گویا باشد، مثلاً `translate-something`): |
| 14 | + ```bash |
| 15 | + git checkout -b translate-functions |
| 16 | + ``` |
| 17 | +3. کارتان را روی شاخهٔ `3.14` (شاخهٔ پیشفرض) آماده کنید. |
| 18 | +4. بعد از ترجمه، تغییرات را روی شاخهٔ خودتان پوش کنید و یک **پولریکوئست** به شاخهٔ `3.14` باز کنید. |
| 19 | + |
| 20 | +## ساختار فایلها |
| 21 | + |
| 22 | +فایلهای `.po` ساختار مستندات اصلی پایتون را دنبال میکنند؛ یعنی هر فایل مربوط به یک صفحهٔ مستندات است: |
| 23 | + |
| 24 | +- `bugs.po` — صفحهٔ «گزارش باگ» |
| 25 | +- `tutorial/*.po` — آموزش پایتون |
| 26 | +- `library/*.po` — کتابخانهٔ استاندارد |
| 27 | +- `c-api/*.po` — رابط C |
| 28 | +- `using/`، `reference/`، `howto/`، `faq/`، `whatsnew/`، `extending/`، `installing/`، `distributing/`، `deprecations/` و غیره |
| 29 | + |
| 30 | +هر فایل `.po` شامل جفتهای `msgid` (متن انگلیسی) و `msgstr` (ترجمهٔ فارسی) است. |
| 31 | + |
| 32 | +## فرایند ترجمه |
| 33 | + |
| 34 | +1. فایل `.po` مورد نظر را با [Poedit](https://poedit.net) یا هر ویرایشگر متنی باز کنید. |
| 35 | + - در Poedit رشتههای ترجمهنشده یا `fuzzy` را از پنل فیلتر (Filter) پیدا کنید. |
| 36 | +2. متن `msgid` را ترجمه کنید و در `msgstr` وارد کنید. |
| 37 | +3. **نشانهگذاریهای Sphinx** مثل `` :class:`int` `` ، `` :func:`repr` `` ، `` :ref:`...` `` ، `` ``code`` `` و **جایگذارها** مثل `%s` یا `{name}` را دقیقاً بدون تغییر نگه دارید؛ فقط متن اطراف آنها ترجمه میشود. ترجمهٔ `target` در `` :term:`text <target>` `` ممنوع است چون لینک را خراب میکند. |
| 38 | +4. داخل کدها (بلوکهای `code-block`) نام متغیرها، توابع و کلمات کلیدی را ترجمه نکنید؛ فقط رشتهها و کامنتها را میتوانید ترجمه کنید. |
| 39 | +5. از [واژهنامهٔ پروژه (GLOSSARY.md)](GLOSSARY.md) برای ثابت نگهداشتن اصطلاحات استفاده کنید. |
| 40 | + |
| 41 | +### بررسیها قبل از ارسال پولریکوئست |
| 42 | + |
| 43 | +```bash |
| 44 | +# بررسی اعتبار فایل |
| 45 | +msgfmt --check your_file.po |
| 46 | + |
| 47 | +# بررسی حفظ نشانهگذاریهای Sphinx |
| 48 | +python3 scripts/check_markup.py your_file.po |
| 49 | +``` |
| 50 | + |
| 51 | +روی هر پولریکوئست، بهصورت خودکار این بررسیها (بههمراه `sphinx-lint` و ساخت کامل مستندات) در GitHub Actions اجرا میشوند. |
| 52 | + |
| 53 | +## رشتههای fuzzy |
| 54 | + |
| 55 | +رشتههای `fuzzy` یعنی ترجمهٔ قبلی وجود دارد اما به دلیل تغییر متن اصلی (یا مداخلهٔ ابزارها) باید دوباره بررسی شود. این رشتهها در ساختهٔ نهایی مستندات نمایش داده نمیشوند و در جدول `STATUS.md` نیز در ستون «Fuzzy» شمارش میشوند. حتماً آنها را بررسی، بازنویسی و سپس علامت `fuzzy` را حذف کنید. |
| 56 | + |
| 57 | +## سربرگ فایلهای `.po` و اعتبار مترجمان |
| 58 | + |
| 59 | +هر فایل `.po` در بخش سربرگ خود دو جایگاه برای ثبت اعتبار دارد: |
| 60 | + |
| 61 | +- کامنت `# Translators:` — فهرست همهٔ کسانی که در ترجمهٔ آن فایل مشارکت داشتهاند. |
| 62 | +- فیلد `Last-Translator:` — آخرین کسی که فایل را ویرایش کرده است. |
| 63 | + |
| 64 | +**قانون اعتبار:** هر وقت فایلی را ویرایش میکنید، فیلد `Last-Translator:` را به نام خودتان تغییر دهید (به فرمت `نام <ایمیل>, سال`) و اگر نامتان در فهرست `# Translators:` نیست، آن را اضافه کنید. این کار معمولاً در پولریکوئستها بهصورت خودکار توسط هماهنگکننده/بازبین نهایی میشود. |
| 65 | + |
| 66 | +برای بازسازی خودکار این اعتبارها از تاریخچهٔ git، اسکریپت زیر وجود دارد: |
| 67 | + |
| 68 | +```bash |
| 69 | +# بازسازی اعتبارهای همهٔ فایلها از git history |
| 70 | +python3 scripts/update_po_headers.py |
| 71 | + |
| 72 | +# فقط پیشنمایش بدون اعمال تغییر |
| 73 | +python3 scripts/update_po_headers.py --dry-run |
| 74 | + |
| 75 | +# فقط اصلاح فیلد Language-Team بدون دستزدن به اعتبارها |
| 76 | +python3 scripts/update_po_headers.py --no-credits \ |
| 77 | + --language-team "Persian (https://github.com/revisto/python-docs-fa/)" \ |
| 78 | + bugs.po tutorial/ |
| 79 | + |
| 80 | +# ادغام نامهای جدید با فهرست موجود (نامهای قبلی حذف نمیشوند) |
| 81 | +python3 scripts/update_po_headers.py --merge bugs.po tutorial/ |
| 82 | +``` |
| 83 | + |
| 84 | +> اسکریپت فقط سربرگ را تغییر میدهد و به متن ترجمهها دست نمیزند، اما باگهای خودکار (مثل رباتهای GitHub Actions) را از فهرست مترجمان حذف میکند. جزئیات کامل در docstring خود اسکریپت آمده است. |
| 85 | +
|
| 86 | +## فرایند بازبینی و نقشها |
| 87 | + |
| 88 | +- **مترجم:** فایلها را ترجمه میکند و پولریکوئست میزند. |
| 89 | +- **بازبین (reviewer):** ترجمهها را از نظر صحت، یکدستی و رعایت واژهنامه بررسی میکند. |
| 90 | +- **هماهنگکننده (coordinator):** بر فرایندها نظارت دارد، پولریکوئستها را ادغام میکند و اعتبار مترجمان را در سربرگ فایلها ثبت میکند. |
| 91 | + |
| 92 | +فهرست اعضای تیم همراه با آمار مشارکت در [TEAM.md](TEAM.md) نگهداری میشود. |
| 93 | + |
| 94 | +## همگامسازی با نسخههای جدید پایتون |
| 95 | + |
| 96 | +وقتی نسخهٔ جدیدی از پایتون منتشر میشود، متن انگلیسی مستندات تغییر میکند و فایلهای `.po` باید با آن همگام شوند. اسکریپت `scripts/update_python_version.py` این کار را خودکار میکند: |
| 97 | + |
| 98 | +```bash |
| 99 | +# همگامسازی با نسخهٔ مشخص |
| 100 | +python3 scripts/update_python_version.py v3.14.6 |
| 101 | + |
| 102 | +# نگهداشتن کپی موقت برای بررسی دستی |
| 103 | +python3 scripts/update_python_version.py v3.15.0 --keep-src |
| 104 | +``` |
| 105 | + |
| 106 | +این اسکریپت نسخهٔ مشخصشدهٔ CPython را کلون میکند، قالبهای gettext (`*.pot`) را از روی آن میسازد، فایلهای `.po` موجود را با `msgmerge` بهروزرسانی میکند، برای صفحات جدید فایل `.po` تازه میسازد و در پایان همهٔ فایلها را با `msgfmt --check` صحتسنجی میکند. بعد از اجرای آن، خروجی را بازبینی کنید و اعتبارهای سربرگ را (در صورت نیاز با `scripts/update_po_headers.py`) بهروزرسانی کنید. |
| 107 | + |
| 108 | +## اولویتها |
| 109 | + |
| 110 | +اگر تازهکار هستید، اول روی فایلهایی تمرکز کنید که برای قرار گرفتن فارسی در «تغییردهندهٔ زبان» (language switcher) مستندات پایتون لازماند: |
| 111 | + |
| 112 | +- `bugs.po` |
| 113 | +- همهٔ فایلهای `tutorial/` |
| 114 | +- `library/functions.po` |
| 115 | + |
| 116 | +با `python3 scripts/translation_status.py --only-incomplete` میتوانید وضعیت دقیق هر فایل را ببینید. |
0 commit comments