المواصفة¶

يمكنك استخدام هذه المكتبة من دون قراءة هذه الصفحة — يغطي الدرس التعليمي والدليل الاستخدام اليومي. هذه الصفحة موجهة لمؤلفي الأدوات: العقد صغير ومستقر عمداً كي تستطيع أدوات الاستخراج وIDE ومدققات الأنواع وإصدار مستقبلي من pygettext تنفيذه والتوافق معه. وللاطلاع على القواعد نفسها مشروحةً بأسبابها، وكيف ينفذها التنفيذ المرجعي، اقرأ كيف تعمل أولاً.

اقرأ المواصفة v1

القواعد في شاشة واحدة¶

يجمع msgid المقاطع الحرفية بترتيب المصدر ورمز {name} لكل استيفاء. تُهرب الأقواس الحرفية ({ تصبح {{). يجب أن يحقق الاسم str.isidentifier() وألا يكون كلمة محجوزة في Python. تبقى التحويلات ومواصفات التنسيق في التطبيق.

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 القواعد نفسها على شكل حالات قابلة للقراءة آلياً. يكون التنفيذ متوافقاً مع spec v1 إذا أعاد نتائج كل الحالات؛ نصوص الأخطاء وأنواع الاستثناءات ليست جزءاً من الحكم.

{
  "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، أي قاعدة اشتقاق رمز العنصر النائب.

يشغّل التنفيذ المرجعي هذه الحزمة ضمن اختباراته.

الإصدارات¶

أي تغيير غير متوافق في اشتقاق msgid أو التحقق ينشئ إصداراً جديداً وملف conformance/vN.json جديداً. أما التوضيح الإضافي الذي لا يغير النتائج فلا يغير الإصدار.