پیام‌های کامل را با t-string‌های پایتون
ترجمه کنید¶

import gettext

from gettext_tstrings import Translator

_ = Translator(gettext.translation("messages", localedir="locales"))
name = "Ada"
print(_(t"Hello {name}"))  # with a Japanese catalog: こんにちは Ada

آیا این برای شماست؟¶

امروز مناسب است اگر برنامه‌تان روی پایتون 3.14 یا جدیدتر اجرا می‌شود؛ همین حالا از gettext و Babel استفاده می‌کنید یا می‌خواهید چرخهٔ PO/MOشان را بپذیرید؛ و نحو t-string با جای‌نگهدارهای نام‌دار می‌خواهید که پیش از رندر بررسی شوند.

هنوز مناسب نیست اگر به پایتون 3.13 یا قدیمی‌تر نیاز دارید؛ APIِ پایدارِ پایتون می‌خواهید — این یک آلفاست و مشخصات آن بخشی است که ته‌نشین شده؛ یا تقریباً همهٔ متن ترجمه‌پذیرتان به‌جای کد پایتون در یک زبان قالب زندگی می‌کند.

از پیش کاتالوگ دارید؟ همچنان کار می‌کنند. _("Hello {name}").format(name=name) و tr(t"Hello {name}") همان msgid را تولید می‌کنند، پس ترجمه‌های موجود از این جابه‌جایی جان سالم به در می‌برند — مهاجرت کل این حرکت را می‌پیماید.

کاتالوگ چه می‌تواند بگوید¶

یک ترجمه نمی‌تواند ساختار پیامی را که ترجمه می‌کند عوض کند. تمامِ وعده همین است، و باقیِ این وب‌گاه از آن برمی‌آید. ترجمه می‌تواند {name} را جابه‌جا یا تکرار کند و می‌تواند هر واژهٔ دیگری را گرد آن بازنویسی کند. اما نمی‌تواند جای‌نگهدار را حذف کند، جای‌نگهدار تازه‌ای بسازد، از راه آن به شیءهای شما دست‌درازی کند، یا قالب‌بندی از خود به آن بیفزاید.

کتابخانه این را در راهِ ورود بررسی می‌کند — هنگام کامپایل کاتالوگ‌ها — و دوباره در زمان رندر؛ و همین است تفاوتِ میان اشتباهی که در بازبینی پیدا می‌شود و اشتباهی که کاربر پیدایش می‌کند.

مسئله‌ای که حل می‌کند¶

یک f-string پیش از آن‌که هیچ کتابخانه‌ای آن را ببیند درون‌یابی شده است — f"Hello {name}" دیگر به "Hello Ada" تبدیل شده، و ترجمهٔ تکه‌های اطراف یک مقدار، دستور زبانِ بیشتر زبان‌ها را می‌شکند. اما t-string (PEP 750) متن ثابت، مقدارهای ارزیابی‌شده، عبارت‌های مبدأ، تبدیل‌ها و مشخصه‌های قالب‌بندی را جدا از هم نگه می‌دارد — و این دقیقاً همان تفکیکی است که یک کاتالوگ پیام لازم دارد. این چه چیزی را عوض می‌کند، در مقایسه با %(name)s و .format() و رشته‌های $.

با این حال، هیچ‌چیز در gettext یا Babel نمی‌گوید یک t-string چگونه به پیام تبدیل شود. این کتابخانه آن انتخاب را انجام می‌دهد، آن را به شکل مشخصاتی نسخه‌دار مکتوب می‌کند و مجموعهٔ آزمون انطباق را برای راستی‌آزمایی‌اش عرضه می‌کند.

قاعده‌های طراحی¶

• ترجمهٔ پیام‌های کامل، نه هرگز تکه‌های جمله.
• پذیرفتن تنها نام‌های سادهٔ متغیر مانند {name}.
• نگه داشتن !r و :.2f زیر کنترل برنامه و بیرون از کاتالوگ.
• اجازه دادن به ترجمه‌ها برای جابه‌جایی و تکرار جای‌نگهدارهای شناخته‌شده، و در همان حال جلوگیری از دسترسی‌شان به خصیصه‌ها یا افزودن قالب‌بندی.
• استفادهٔ دوباره از فایل‌های معمولی POT و PO و MO، و ابزارهایی که همین حالا آن‌ها را می‌خوانند.

و فهرست متناظرِ آنچه عمداً به آن دست نمی‌زند: عددها، ارزها و تاریخ‌ها را بومی‌سازی نمی‌کند — نخست آن‌ها را قالب‌بندی کنید، با Babel؛ خروجی رندرشده را برای HTML یا پوسته یا پایانه escape نمی‌کند؛ و نمی‌تواند داوری کند که ترجمه‌ای درست است یا نه، تنها این‌که جای‌نگهدارهایش سالم‌اند یا نه.

نصب¶

python -m pip install gettext-tstrings

پایتون 3.14 یا جدیدتر. رندر هیچ وابستگی‌ای ندارد — تنها از gettext کتابخانهٔ استاندارد استفاده می‌کند و بس.

استخراج و اعتبارسنجی کاتالوگ از راه Babel انجام می‌شود؛ پس آن افزونه را هر جا pybabel اجرا می‌شود نصب کنید — که معمولاً محیط توسعه یا CI است، نه ایمیج عملیاتی:

python -m pip install "gettext-tstrings[babel]"

گام بعدی¶

از این‌جا شروع کنید — بدون پیش‌فرضِ هیچ تجربه‌ای با gettext:

به‌کارگیری — مرجع‌های کاری:

درک عمیق‌تر — از تاریخ تا پیاده‌سازی:

مرجع — قراردادها:

وضعیت¶

یک نسخهٔ آلفا. قرارداد عمداً کوچک است و مشخصات بخش پایدار آن است؛ APIِ پایتون هنوز ممکن است تغییر کند. پیش از انتشار پایدار، این پروژه به فیکسچرهای زبانی گسترده‌تر، پایش مداوم کارایی، بازبینی API از سوی کسانی که gettext و Babel را جدی به کار می‌برند، و آزمون سازگاری با همهٔ نسخه‌های پشتیبانی‌شدهٔ پایتون و Babel نیاز دارد.

ایشوها و پول‌ریکوئست‌ها خوش‌آمدند — آلفا درست همان زمانی است که هنوز می‌ارزد بر سر رابط بحث کرد.

به جامعه بپیوندید¶

• برای مشارکتی با دامنهٔ مشخص، یک good first issue انتخاب کنید.
• پرسش‌های کاربردی را در Q&A Discussions بپرسید.
• گردش‌کارهای عملیاتی gettext و ایده‌های API را به Ideas Discussions بیاورید.
• پیش از گشودن پول‌ریکوئست، راهنمای مشارکت را بخوانید.