diff --git a/README.md b/README.md index 1c0a8aba0..710deaa85 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ -# ترجمه مستندات پایتون به فارسی 🐍💛 +# ترجمهٔ مستندات پایتون به فارسی 🐍💛 [](https://discord.gg/yeqtNeaFYf) [](https://www.youtube.com/watch?v=DH5c5ZutTCo) -## درباره پروژه +## دربارهٔ پروژه -ما توی این پروژه گروهی از علاقهمندان به پایتون هستیم که روی ترجمه مستندات رسمی پایتون به فارسی میکنیم. هدف ما این است که حتی کاربرانی که تسلط کامل به زبان انگلیسی ندارند، بتوانند با استفاده از راهنماییهای دقیق و بهروز، اصول برنامهنویسی پایتون را به راحتی یاد بگیرند. +این پروژه گروهی از علاقهمندان به پایتون است که مستندات رسمی پایتون را به فارسی ترجمه میکنند. هدف این است که کاربرانی که تسلط کاملی به زبان انگلیسی ندارند نیز بتوانند با استفاده از راهنماییهای دقیق و بهروز، اصول برنامهنویسی پایتون را بهراحتی یاد بگیرند. ## مجوز @@ -13,32 +13,35 @@ ## راهنمای مشارکت 🌱 -ترجمهها دیگر روی Transifex انجام نمیشوند و مستقیماً از طریق پولریکوئست در همین ریپازیتوری مدیریت میشوند. فایلهای `.po` هر کدام به بخشی از مستندات پایتون (مثل `tutorial/`، `library/` یا `c-api/`) مربوطاند و میتوانید هرکدام را جداگانه ویرایش و پولریکوئست بزنید. +ترجمهها دیگر روی Transifex انجام نمیشوند و مستقیماً از طریق پولریکوئست در همین مخزن (Repository) مدیریت میشوند. فایلهای `.po` هر کدام به بخشی از مستندات پایتون (مثل `tutorial/`، `library/` یا `c-api/`) مربوطاند و میتوانید هرکدام را جداگانه ویرایش و پولریکوئست بزنید. -خلاصه فرایند مشارکت: +خلاصهٔ فرایند مشارکت: -1. ریپازیتوری را فورک و کلون کنید. -2. فایل `.po` مورد نظر رو با [Poedit](https://poedit.net/) باز کنید (رشتههای ترجمهنشده یا fuzzy را میتوانید از پنل فیلتر پیدا کنید). -3. متن انگلیسی (`msgid`) را ترجمه کنید و در بخش ترجمه (`msgstr`) وارد کنید. -4. نشانهگذاریهای Sphinx مثل `` :class:`int` ``، `` :func:`repr` ``، `` ``code`` ``، و جایگزینهایی مثل `%s` یا `{name}` را دقیقاً بدون تغییر نگه دارید؛ فقط متن اطراف آنها ترجمه میشود. -5. پیش از ارسال پولریکوئست، بررسی کنید فایلها مشکلی ندارند: -```bash +1. مخزن را فورک و کلون کنید. +2. اگر ایشیوی مربوط به فایل مورد نظرتان باز نشده، یک ایشیوی «درخواست ترجمهٔ صفحه» باز کنید تا دیگران بدانند آن فایل در حال انجام است. +3. فایل `.po` مورد نظر را با [Poedit](https://poedit.net/) باز کنید (رشتههای ترجمهنشده یا `fuzzy` را میتوانید از پنل فیلتر پیدا کنید). +4. متن انگلیسی (`msgid`) را ترجمه کنید و در بخش ترجمه (`msgstr`) وارد کنید. ترجمه باید در سطح رسمی و با خطاب «شما» نوشته شود. +5. نشانهگذاریهای Sphinx مثل `` :class:`int` ``، `` :func:`repr` ``، `` ``code`` ``، و جایگزینهایی مثل `%s` یا `{name}` را دقیقاً بدون تغییر نگه دارید؛ فقط متن اطراف آنها ترجمه میشود. +6. پیش از ارسال پولریکوئست، بررسی کنید فایلها مشکلی ندارند: + ```bash msgfmt --check your_file.po python3 scripts/check_markup.py your_file.po -``` -6. پولریکوئست را باز کنید — روی هر پولریکوئست بهصورت خودکار بررسیهای لازم اجرا میشود. + ``` +7. پولریکوئست را باز کنید (حداکثر تا ۴ فایل `.po` در هر پولریکوئست) — روی هر پولریکوئست بهصورت خودکار بررسیهای لازم اجرا میشود و ریدتردکس (Read the Docs) نسخهٔ پیشنمایش مستندات را میسازد. اگر بررسیها رد شدند، از تب Actions در گیتهاب ببینید کدام مورد مشکل داشته و همان اسکریپت را بهصورت محلی اجرا کنید. برای دیدن اینکه کدام فایلها هنوز نیاز به ترجمه دارند و چقدر از هرکدام باقی مانده: ```bash python3 scripts/translation_status.py --only-incomplete ``` +راهنمای کاملتر این مراحل، از جمله نکات نگارشی و تایپوگرافی فارسی، در [CONTRIBUTING.md](CONTRIBUTING.md) آمده است. + ### منابع پیشنهادی -قبل از شروع، حتماً نگاهی به این فایلها بیندازید: +پیش از شروع، حتماً نگاهی به این فایلها بیندازید: -- [CONTRIBUTING.md](CONTRIBUTING.md) — راهنمای کامل مشارکت: فرایند بازبینی و تأیید پولریکوئست، همگامسازی با نسخههای جدید پایتون (`scripts/update_python_version.py`)، پاکسازی رشتههای `fuzzy` و نگهداری اعتبار مترجمان در سربرگ فایلهای `.po`. -- [GLOSSARY.md](GLOSSARY.md) — واژهنامهٔ معادلهای فارسی اصطلاحات تخصصی؛ هنگام ترجمه باید به آن پایبند باشیم. +- [CONTRIBUTING.md](CONTRIBUTING.md) — راهنمای کامل مشارکت: انواع ایشیو، نکات نگارشی و تایپوگرافی فارسی، سطح رسمیت و لحن نوشتار، اندازهٔ پولریکوئست، فرایند بازبینی و تأیید پولریکوئست، همگامسازی با نسخههای جدید پایتون (`scripts/update_python_version.py`)، پاکسازی رشتههای `fuzzy` و نگهداری اعتبار مترجمان در سربرگ فایلهای `.po`. +- [GLOSSARY.md](GLOSSARY.md) — واژهنامهٔ معادلهای فارسی اصطلاحات تخصصی؛ هنگام ترجمه باید به آن پایبند باشید. - [TEAM.md](TEAM.md) — فهرست هماهنگکنندهها، بازبینها و مترجمان بههمراه آمار مشارکت. - [STATUS.md](STATUS.md) — جدول وضعیت ترجمهٔ فایلها که بهصورت خودکار بهروزرسانی میشود. @@ -48,13 +51,15 @@ python3 scripts/translation_status.py --only-incomplete ## ارتباط و هماهنگی -برای بحث، هماهنگی و بهروزرسانیهای مرتبط با ترجمه، میتوانید از کانالهای زیر استفاده کنید: +برای بحث، هماهنگی و بهروزرسانیهای مرتبط با ترجمه، میتوانید از کانالهای زیر استفاده کنید: