پرش به محتویات

مشخصات

می‌توانید بی‌آنکه این صفحه را بخوانید از این کتابخانه استفاده کنید — آموزش و راهنما کاربرد روزمره را پوشش می‌دهند. این صفحه برای نویسندگان ابزار است: قراردادی که این کتابخانه پیاده می‌کند به شکل پیمانی کوچک و پایدار مکتوب شده است تا پیاده‌سازی دیگری — یک استخراج‌کننده، یک IDE، یک بررسی‌کنندهٔ نوع، یا pygettextی در آینده — بتواند آن را هدف بگیرد و با آن سازگار بماند. برای همان قواعد، شرح‌شده با دلیل‌هایشان و همراه با شیوه‌ای که پیاده‌سازی مرجع آن‌ها را به انجام می‌رساند، نخست چگونه کار می‌کند را بخوانید.

نسخهٔ ۱ مشخصات را بخوانید

قواعد در یک صفحه

msgid به‌هم‌پیوستنِ قطعه‌های تحت‌اللفظی و یک نشانهٔ {name} به‌ازای هر درون‌یابی است، به ترتیب مبدأ. آکولادهای تحت‌اللفظی escape می‌شوند ({ به {{ بدل می‌شود). نام باید نامی سادهٔ جای‌نگهدار باشد — str.isidentifier() بر آن صادق است و کلیدواژهٔ پایتون نیست. تبدیل‌ها و مشخصه‌های قالب‌بندی جزء msgid نیستند؛ آن‌ها زیر کنترل برنامه می‌مانند.

t-string msgid
t"Hello {name}" Hello {name}
t"Total: {amount:,.2f}" Total: {amount}
t"Config {{raw}} is {value}" Config {{raw}} is {value}
t"Hello {user.name}" رد می‌شود — نامی ساده نیست

ترجمه آن‌گاه معتبر است که تنها جای‌نگهدارهای خالیِ {name} را در خود داشته باشد، هر نام لازم دست‌کم یک بار در آن بیاید، و هیچ نامی بیرون از مجموعهٔ مجاز در آن نیاید. جابه‌جایی و تکرار عمداً بی‌قید مانده‌اند: هر دو می‌توانند در زبان مقصد از نظر دستوری ضروری باشند.

برای صورت‌های جمع، مجاز اجتماع نام‌های دو شاخه است و لازم اشتراک آن‌ها — پس t"One file" در برابر t"{n} files" نام n را برای مترجمِ هر یک از دو صورت در دسترس می‌گذارد بی‌آنکه در هیچ‌کدام الزامی باشد، و قواعد جمعِ زبان مقصد می‌تواند با قواعد مبدأ فرق داشته باشد.

msgid تهی هرگز جست‌وجو نمی‌شود، چون gettext آن را برای سرآیند فرادادهٔ کاتالوگ نگه داشته است.

انطباق

conformance/v1.json همان سند است در صورت ماشین‌خوان: حالت‌هایی که ساختار ایستای یک t-string را به یک msgid نگاشت می‌دهند، و یک msgid به‌علاوهٔ یک الگوی کاتالوگ را به یک رشتهٔ رندرشده یا به یک ردشدن.

یک پیاده‌سازی آن‌گاه با نسخهٔ ۱ مشخصات منطبق است که هر حالت را بازتولید کند. حالت‌ها تنها چیزی را نام می‌برند که مشخصات تعریف می‌کند — msgidهای مشتق‌شده، الگوهای پذیرفته و ردشده، خروجی رندرشده — و هرگز پیام خطا یا نوع استثنایی را؛ پس پیاده‌سازی‌ای به زبانی دیگر می‌تواند آن‌ها را بی‌هیچ تغییری اجرا کند.

درون‌یابی‌ها ساختاری توصیف می‌شوند، هرگز به‌صورت کد مبدأ پایتون:

{
  "spec": "2.2",
  "name": "format spec stays out of the msgid",
  "source": [
    "Total: ",
    {"expression": "amount", "value": 1234.5, "format_spec": ",.2f"}
  ],
  "msgid": "Total: {amount}"
}

میدانِ "spec" نسخهٔ مشخصات نیست — هر مورد در v1.json به مشخصات نسخهٔ ۱ تعلق دارد. این میدان بخشی از SPEC.md را نام می‌برد که آن مورد می‌آزماید؛ پس "2.2" یعنی §۲.۲، همان قاعدهٔ اشتقاق نشانهٔ جای‌نگهدار.

پیاده‌سازی مرجع این مجموعه را همچون بخشی از مجموعه‌آزمون خودش اجرا می‌کند؛ پس متن و کد نمی‌توانند بی‌سروصدا از هم دور شوند.

نسخه‌گذاری

این نسخهٔ ۱ مشخصات است. تغییری ناسازگار با گذشته در اشتقاق msgid یا در اعتبارسنجی ترجمه، شمارهٔ نسخه را بالا می‌برد و یک conformance/vN.jsonِ تازه را در کنار موجود روانه می‌کند. اما روشن‌سازی‌های افزایشی که نه msgidهای مشتق‌شده را عوض می‌کنند و نه الگوهای پذیرفته‌شده را، چنین نمی‌کنند.