স্পেসিফিকেশন¶

এই পৃষ্ঠা না পড়েও আপনি লাইব্রেরিটি ব্যবহার করতে পারেন — টিউটোরিয়াল ও গাইড দৈনন্দিন ব্যবহার ঢেকে দেয়। এই পৃষ্ঠা টুল-লেখকদের জন্য: লাইব্রেরি যে রীতিটি বাস্তবায়ন করে, তা একটি ছোট, স্থিতিশীল চুক্তি হিসেবে লিখে রাখা হয়েছে, যাতে অন্য কোনও বাস্তবায়ন — একটি এক্সট্র্যাক্টর, একটি IDE, একটি টাইপ চেকার, বা ভবিষ্যতের কোনও pygettext — তাকে লক্ষ্য করে আন্তঃক্রিয়া করতে পারে। একই নিয়মগুলি তাদের কারণসহ ব্যাখ্যা করা আছে, আর রেফারেন্স বাস্তবায়ন সেগুলি কীভাবে কার্যকর করে তা জানতে আগে এটি কীভাবে কাজ করে পড়ুন।

spec v1 পড়ুন

নিয়মগুলি এক স্ক্রিনে¶

একটি msgid হল সোর্স ক্রমে আক্ষরিক খণ্ডগুলি আর প্রতি ইন্টারপোলেশনে একটি করে {name} টোকেনের সংযোজন। আক্ষরিক বন্ধনী escape করা হয় ({ হয় {{)। নামকে একটি সরল placeholder নাম হতে হবে — 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} placeholder আছে, প্রতিটি আবশ্যক নাম অন্তত একবার আছে, আর অনুমোদিত সেটের বাইরের কোনও নাম নেই। পুনর্বিন্যাস ও পুনরাবৃত্তি ইচ্ছাকৃতভাবেই অনিয়ন্ত্রিত: লক্ষ্য ভাষায় দুটিই ব্যাকরণগতভাবে প্রয়োজনীয় হতে পারে।

বহুবচনের ক্ষেত্রে অনুমোদিত হল শাখাগুলির নামের union আর আবশ্যক তাদের intersection — তাই t"One file"-এর বিপরীতে t"{n} files" রাখলে n যেকোনও রূপের অনুবাদকের কাছে উপলব্ধ থাকে অথচ কোনওটিতেই আবশ্যক নয়, আর লক্ষ্য ভাষার বহুবচন নিয়ম উৎসের থেকে আলাদা হতে পারে।

একটি খালি msgid কখনও খোঁজা হয় না, কারণ gettext সেটি ক্যাটালগের মেটাডেটা হেডারের জন্য সংরক্ষিত রেখেছে।

কনফরম্যান্স¶

conformance/v1.json হল একই দলিলের মেশিন-পাঠযোগ্য রূপ: এমন কিছু কেস, যা একটি t-string-এর স্থির কাঠামোকে একটি msgid-এ মেলায়, আর একটি msgid ও একটি ক্যাটালগ প্যাটার্নকে একটি রেন্ডার করা স্ট্রিং বা একটি প্রত্যাখ্যানে।

কোনও বাস্তবায়ন প্রতিটি কেস পুনরুৎপাদন করলে তবেই সে spec 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-এর প্রতিটি কেসই spec v1-এর অন্তর্গত। এটি SPEC.md-এর যে অংশটিকে কেসটি পরীক্ষা করে তার নাম বলে, তাই "2.2" পড়তে হয় §2.2 হিসেবে, অর্থাৎ placeholder টোকেন উদ্ভবের নিয়ম।

রেফারেন্স বাস্তবায়ন সুইটটিকে নিজের টেস্ট সুইটের অংশ হিসেবেই চালায়, তাই গদ্য আর কোড নীরবে আলাদা হয়ে যেতে পারে না।

সংস্করণায়ন¶

এটি spec v1। msgid উদ্ভবে বা অনুবাদ যাচাইয়ে পশ্চাৎ-অসঙ্গত কোনও বদল সংস্করণ বাড়ায় আর বিদ্যমানটির পাশে একটি নতুন conformance/vN.json পাঠায়। যেসব যোগমূলক স্পষ্টীকরণ উদ্ভূত msgid বা গৃহীত প্যাটার্ন কোনওটিই বদলায় না, সেগুলি নয়।