ข้อกำหนด¶

คุณใช้ไลบรารีนี้ได้โดยไม่ต้องอ่านหน้านี้ — บทแนะนำ และ คู่มือ ครอบคลุมการใช้งานในชีวิตประจำวันแล้ว หน้านี้มีไว้สำหรับผู้เขียนเครื่องมือ: ธรรมเนียมปฏิบัติที่ไลบรารีนี้อิมพลีเมนต์ถูกเขียนบันทึกไว้เป็นสัญญาเล็ก ๆ ที่เสถียร เพื่อให้อีกการอิมพลีเมนต์หนึ่ง — ตัวสกัดข้อความ IDE ตัวตรวจสอบชนิด หรือ pygettext ในอนาคต — สามารถยึดมันเป็นเป้าหมายและทำงานร่วมกันได้ สำหรับกฎชุดเดียวกันที่อธิบายพร้อมเหตุผล และวิธีที่การอิมพลีเมนต์อ้างอิงนำกฎเหล่านั้นไปปฏิบัติ โปรดอ่าน หลักการทำงาน ก่อน

อ่าน spec 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 บวกแพตเทิร์นแคตตาล็อกไปยังสตริงที่เรนเดอร์แล้ว หรือการปฏิเสธ

การอิมพลีเมนต์หนึ่ง สอดคล้องกับ 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 อยู่ในข้อกำหนด v1 ทั้งหมด มันระบุหัวข้อของ SPEC.md ที่กรณีนั้นทดสอบ ดังนั้น "2.2" จึงอ่านว่า §2.2 ซึ่งเป็นกฎการอนุมานโทเคนตัวยึดตำแหน่ง

การอิมพลีเมนต์อ้างอิงรันชุดทดสอบนี้เป็นส่วนหนึ่งของชุดทดสอบของตัวเอง เนื้อความและโค้ดจึงไม่มีทางแยกห่างจากกันอย่างเงียบ ๆ

การกำหนดเวอร์ชัน¶

นี่คือ spec v1 การเปลี่ยนแปลงที่เข้ากันย้อนหลังไม่ได้ต่อการอนุมาน msgid หรือต่อการตรวจสอบคำแปลจะเพิ่มเลขเวอร์ชันและออก conformance/vN.json ตัวใหม่เคียงข้างตัวที่มีอยู่ ส่วนการชี้แจงเชิงเพิ่มเติมที่ไม่เปลี่ยนทั้ง msgid ที่อนุมานได้และแพตเทิร์นที่ยอมรับจะไม่เพิ่มเลขเวอร์ชัน