API¶

تصدّر gettext_tstrings كل الأسماء التالية. وما عداها ليس API عاماً. هذه الصفحة مرجع التوقيعات؛ وللاطلاع على أمثلة عملية لكل دالة راجع الدليل.

الترجمة¶

تأخذ كل دالة t-string كوسيط موضعي، وتقبل translations وstrict كوسيطين مسميين (راجع الدليل).

الدالة	التوقيع
`gettext`	`(template, /, *, translations=None, strict=False) -> str`
`ngettext`	`(singular, plural, n, /, *, translations=None, strict=False) -> str`
`pgettext`	`(context, template, /, *, translations=None, strict=False) -> str`
`npgettext`	`(context, singular, plural, n, /, *, translations=None, strict=False) -> str`
`tr`	اسم بديل مطابق لـ`gettext`
`ntr`	اسم بديل مطابق لـ`ngettext`

`Translator`¶

dataclass مجمّدة تربط كائن ترجمة:

Translator(translations, strict=False)

يمكن استدعاؤها (_(t"…")) وتوفر gettext وngettext وpgettext وnpgettext وtr وntr.

ربط السياق¶

الاسم	الدور
`use_translations(translations)`	يربط خلال كتلة `with` ثم يعيد الحالة السابقة.
`set_translations(translations)`	يربط بلا كتلة لدورة حياة يديرها إطار العمل.
`get_translations()`	يقرأ الربط الحالي أو يعيد `None`.

يستخدم الربط ContextVar وهو آمن مع التنفيذ المتزامن.

السلاسل المؤجلة¶

الاسم	الدور
`lazy_gettext(template, /, *, strict=False)`	يؤجل الترجمة إلى كل عملية عرض.
`lazy_pgettext(context, template, /, *, strict=False)`	صيغة مع سياق.
`LazyString`	ما تعيده كلتاهما. تُعرض عبر `str()` و`format()` باللغة المربوطة في تلك اللحظة، وتُقارن بنصها المعروض، وهي غير قابلة للتجزئة عمداً.

وتجد الأمثلة العملية، ومنها سبب انتماء strict إلى موضع التعريف، في الترجمة المؤجلة.

المستوى المنخفض¶

`compile_template(template, /) -> CompiledTemplate`¶

يترجم t-string إلى خطة مع إعادة استخدام الخطة الثابتة المخزنة مؤقتاً.

`CompiledTemplate`¶

العضو	المعنى
`.msgid`	معرّف gettext مستقر.
`.placeholders`	الأسماء بترتيب أول ظهور.
`.render(pattern)`	يتحقق ويعرض، ويثير استثناء دائماً عند عدم التطابق.

الأنواع والأخطاء¶

`Translations`¶

Protocol قابل للفحص وقت التشغيل للطرائق القياسية الأربع:

class Translations(Protocol):
    def gettext(self, message: str, /) -> str: ...
    def ngettext(self, singular: str, plural: str, n: int, /) -> str: ...
    def pgettext(self, context: str, message: str, /) -> str: ...
    def npgettext(self, context: str, singular: str, plural: str, n: int, /) -> str: ...

تطابقه gettext.NullTranslations وgettext.GNUTranslations وTranslations من Babel.

الاستثناءات¶

الصنف	متى
`TStringError`	الصنف الأساسي.
`InvalidTemplateError`	تخالف t-string المصدر الاتفاقية.
`InvalidTranslationError`	تخالف الترجمة الاتفاقية؛ يسجل الوضع المرن الخطأ ويعرض المصدر.

نقاط دخول الاستخراج¶

المجموعة	الاسم	الاستخدام
`babel.extractors`	`gettext_tstrings`	قيمة `method` في `babel.cfg`
`babel.checkers`	`gettext_tstrings`	يستخدمه `pybabel compile` تلقائياً

الأداء¶

الرواية الكاملة — ما يُخزَّن في الذواكر المؤقتة، وما تعتمد عليه مفاتيحها، والأرقام المقيسة — في المسار الساخن. والخلاصة: التحقق يُخزَّن مؤقتاً ولا يُتخطى أبداً، والعرض بأكمله يكلف جزءاً من الميكروثانية. شغّل القياس على هدفك الخاص:

uv run python benchmarks/runtime.py