विनिर्देश¶

इस लाइब्रेरी का उपयोग यह पेज पढ़े बिना किया जा सकता है — रोज़मर्रा का उपयोग ट्यूटोरियल और गाइड कवर करते हैं। यह पेज टूल लेखकों के लिए है: लाइब्रेरी जिस परिपाटी को लागू करती है, वह एक छोटे, स्थिर अनुबंध के रूप में लिखी गई है ताकि कोई दूसरा क्रियान्वयन — कोई एक्सट्रैक्टर, कोई IDE, कोई type checker, या भविष्य का pygettext — उसे लक्ष्य बनाकर अंतरसंचालित हो सके। वही नियम कारणों समेत, और संदर्भ क्रियान्वयन उन्हें कैसे निभाता है, इसके लिए पहले यह कैसे काम करता है पढ़ें।

spec v1 पढ़ें

नियम एक स्क्रीन में¶

msgid स्रोत क्रम में शाब्दिक खंडों और प्रति इंटरपोलेशन एक {name} token का सम्मिलन है। शाब्दिक braces escape होते हैं ({ बनता है {{)। नाम को सरल placeholder नाम होना चाहिए — str.isidentifier() सत्य हो और वह Python keyword न हो। conversion और format spec 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} placeholders हों, हर आवश्यक नाम कम से कम एक बार आए, और अनुमत समुच्चय से बाहर का कोई नाम न आए। पुनर्क्रमण और दोहराव जान-बूझकर अनियंत्रित हैं: दोनों लक्ष्य भाषा में व्याकरण की दृष्टि से आवश्यक हो सकते हैं।

बहुवचन के लिए अनुमत शाखाओं के नामों का union है और आवश्यक उनका intersection — तो t"One file" बनाम t"{n} files" किसी भी रूप के अनुवादक को n उपलब्ध छोड़ता है पर किसी से माँगता नहीं, और लक्ष्य भाषा के बहुवचन नियम स्रोत से भिन्न हो सकते हैं।

खाली msgid कभी नहीं खोजा जाता, क्योंकि gettext उसे कैटलॉग के metadata header के लिए आरक्षित रखता है।

कन्फ़ॉर्मन्स¶

conformance/v1.json वही दस्तावेज़ मशीन-पठनीय रूप में है: ऐसे मामले जो t-string की स्थिर संरचना को msgid से जोड़ते हैं, और msgid + कैटलॉग pattern को रेंडर की गई स्ट्रिंग या अस्वीकृति से।

कोई क्रियान्वयन spec v1 के अनुरूप है जब वह हर मामले को पुन: उत्पन्न करता है। मामले केवल वही नाम लेते हैं जो विनिर्देश परिभाषित करता है — व्युत्पन्न msgid, स्वीकृत और अस्वीकृत patterns, रेंडर किया गया आउटपुट — और कभी कोई त्रुटि संदेश या exception type नहीं, ताकि किसी और भाषा का क्रियान्वयन उन्हें अपरिवर्तित चला सके।

इंटरपोलेशन संरचनात्मक रूप से वर्णित होते हैं, कभी 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" फ़ील्ड spec का संस्करण नहीं है — v1.json का हर केस spec v1 का ही है। यह SPEC.md के उस अनुभाग का नाम देता है जिसे केस परखता है, इसलिए "2.2" का अर्थ §2.2 है, यानी placeholder token निकालने का नियम।

संदर्भ क्रियान्वयन इस सुइट को अपने ही टेस्ट सुइट के हिस्से के रूप में चलाता है, इसलिए गद्य और कोड चुपचाप अलग-अलग नहीं बहक सकते।

संस्करणन¶

यह spec v1 है। msgid की व्युत्पत्ति या अनुवाद सत्यापन में पीछे-असंगत बदलाव संस्करण बढ़ाता है और मौजूदा के बग़ल में नई conformance/vN.json शिप करता है। जो योगात्मक स्पष्टीकरण न व्युत्पन्न msgid बदलते हैं न स्वीकृत patterns, वे नहीं बढ़ाते।