براہِ راست مواد پر جائیں

تصریح

آپ اس صفحے کو پڑھے بغیر بھی یہ لائبریری استعمال کر سکتے ہیں — روزمرہ کا استعمال ٹیوٹوریل اور رہنما میں آ چکا ہے۔ یہ صفحہ اوزار بنانے والوں کے لیے ہے: جس اصول پر یہ لائبریری عمل کرتی ہے، اسے ایک چھوٹے اور مستحکم معاہدے کی صورت میں لکھ دیا گیا ہے تاکہ کوئی دوسرا نفاذ — کوئی استخراج کار، کوئی IDE، کوئی ٹائپ چیکر، یا مستقبل کا pygettext — اسے ہدف بنا سکے اور اس کے ساتھ چل سکے۔ انہی اصولوں کو ان کی وجوہات سمیت، اور یہ کہ حوالہ جاتی نفاذ انہیں کیسے برتتا ہے، پہلے یہ کیسے کام کرتی ہے میں پڑھیے۔

تصریح v1 پڑھیے

اصول ایک ہی سکرین میں

msgid ماخذ کی ترتیب میں ثابت ٹکڑوں اور ہر انٹرپولیشن کے لیے ایک {name} ٹوکن کو جوڑ کر بنتا ہے۔ ثابت بریسز کو ایسکیپ کیا جاتا ہے ({ {{ بن جاتا ہے)۔ نام لازماً ایک سادہ پلیس ہولڈر نام ہو — str.isidentifier() اس پر صادق آئے اور وہ Python کا کلیدی لفظ نہ ہو۔ کنورژن اور فارمیٹ اسپیک 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 مع کیٹلاگ پیٹرن کو ایک رینڈر شدہ سٹرنگ یا ایک مستردگی سے جوڑتے ہیں۔

کوئی نفاذ تصریح v1 کے مطابق اُس وقت ہے جب وہ ہر کیس کا نتیجہ دہرا دے۔ یہ کیس صرف وہی کچھ نام لیتے ہیں جو تصریح متعین کرتی ہے — اخذ شدہ msgid، قبول اور مسترد ہونے والے پیٹرن، رینڈر شدہ آؤٹ پٹ — اور کبھی کوئی غلطی کا پیغام یا استثنا کی قسم نہیں، لہٰذا کسی دوسری زبان کا نفاذ انہیں جوں کا توں چلا سکتا ہے۔

انٹرپولیشنز کو ساختی طور پر بیان کیا جاتا ہے، کبھی Python کے ماخذ کوڈ کی شکل میں نہیں:

{
  "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 کا ہر کیس تصریح v1 سے تعلق رکھتا ہے۔ یہ SPEC.md کے اُس حصے کا نام ہے جسے وہ کیس آزماتا ہے، چنانچہ "2.2" کو §2.2 پڑھیے، یعنی پلیس ہولڈر ٹوکن اخذ کرنے کا قاعدہ۔

حوالہ جاتی نفاذ اس سویٹ کو اپنے ٹیسٹ سویٹ کے حصے کے طور پر چلاتا ہے، چنانچہ متن اور کوڈ خاموشی سے ایک دوسرے سے دور نہیں ہو سکتے۔

ورژن بندی

یہ تصریح v1 ہے۔ msgid کے اخذ یا ترجمے کی توثیق میں کوئی پچھلی مطابقت توڑنے والی تبدیلی ورژن بڑھا دیتی ہے اور موجودہ فائل کے ساتھ ایک نئی conformance/vN.json بھیجتی ہے۔ وہ اضافی وضاحتیں جو نہ اخذ شدہ msgid بدلتی ہیں اور نہ قبول شدہ پیٹرن، ایسا نہیں کرتیں۔