ترجم الرسائل كاملة
بسلاسل t-string في Python¶

import gettext

from gettext_tstrings import Translator

_ = Translator(gettext.translation("messages", localedir="locales"))
name = "Ada"
print(_(t"Hello {name}"))  # with a Japanese catalog: こんにちは Ada

هل هذه المكتبة مناسبة لك؟¶

مناسبة اليوم إذا كان تطبيقك يعمل على Python 3.14 أو أحدث؛ وكنت تستخدم gettext وBabel بالفعل، أو تريد اعتماد سير عمل PO/MO الخاص بهما؛ وكنت تريد صيغة t-string بعناصر نائبة مسمّاة تُفحص قبل عرضها.

ليست مناسبة بعد إذا كنت تحتاج Python 3.13 أو أقدم؛ أو كنت تحتاج Python API مستقراً — فهذه نسخة alpha، والمواصفة هي الجزء الذي استقر منها؛ أو كان جُلّ نصك القابل للترجمة يعيش في لغة قوالب لا في شيفرة Python.

ألديك كتالوجات بالفعل؟ ستظل تعمل. تنتج _("Hello {name}").format(name=name) وtr(t"Hello {name}") قيمة msgid نفسها، فتنجو الترجمات الموجودة من التحوّل — والترحيل يمر بالنقلة كاملة.

ما الذي يُسمح للكتالوج بقوله¶

لا تستطيع الترجمة تغيير بنية الرسالة التي تترجمها. هذا هو الوعد كله، وبقية هذا الموقع تتفرّع عنه. يمكن للترجمة أن تغيّر موضع {name} أو تكرره، وأن تعيد كتابة كل كلمة أخرى حوله. ولا يمكنها حذف العنصر النائب، ولا اختراع عنصر جديد، ولا النفاذ من خلاله إلى كائناتك، ولا إضافة تنسيق من عندها.

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

المشكلة التي يحلها¶

تكون f-string قد أُجري عليها الاستيفاء قبل أن تراها أي مكتبة — فتكون f"Hello {name}" قد صارت "Hello Ada"، وترجمة الأجزاء المحيطة بالقيمة تكسر قواعد معظم اللغات. أما t-string (PEP 750) فتحفظ النص الثابت والقيم المقيّمة وتعبيرات المصدر والتحويلات ومواصفات التنسيق منفصلة، وهذا هو الفصل الذي يحتاجه كتالوج الرسائل. وتوضّح ما الذي يغيّره ذلك بالمقارنة مع %(name)s و.format() وسلاسل $.

لا يحدد gettext أو Babel كيفية تحويل t-string إلى رسالة. تختار هذه المكتبة قاعدة واضحة، وتوثقها في مواصفة ذات إصدارات، وتوفر حزمة اختبارات توافق.

قواعد التصميم¶

• ترجمة الرسائل الكاملة لا أجزاء الجمل.
• قبول أسماء متغيرات بسيطة فقط مثل {name}.
• إبقاء !r و:.2f تحت سيطرة التطبيق وخارج الكتالوج.
• السماح للترجمات بإعادة ترتيب العناصر النائبة المعروفة وتكرارها، مع منعها من الوصول إلى الخصائص أو إضافة تنسيق.
• إعادة استخدام ملفات POT وPO وMO والأدوات الحالية.

وفي المقابل، هذه قائمة بما تتركه المكتبة عمداً: فهي لا توطّن الأعداد ولا العملات ولا التواريخ — نسّق تلك أولاً عبر Babel؛ ولا تهرّب المخرجات المعروضة من أجل HTML أو الصدفة أو الطرفية؛ ولا تستطيع الحكم على صحة الترجمة، بل على سلامة عناصرها النائبة فقط.

التثبيت¶

python -m pip install gettext-tstrings

يتطلب Python 3.14 أو أحدث. العرض بلا تبعيات خارجية ويستخدم gettext من المكتبة القياسية فقط.

يعمل الاستخراج والتحقق من الكتالوج عبر Babel. ثبّت الإضافة التالية حيثما يعمل pybabel، وهو عادةً بيئة تطوير أو CI لا صورة إنتاج:

python -m pip install "gettext-tstrings[babel]"

الخطوة التالية¶

ابدأ من هنا — من دون افتراض أي خبرة في gettext:

استخدمها — المراجع العملية:

افهمها — من التاريخ إلى التنفيذ:

المرجع — العقود:

الحالة¶

المشروع في مرحلة alpha. العقد صغير عن قصد، والمواصفة هي الجزء المستقر منه، أما Python API فقد يتغير بعد. نحتاج قبل إصدار مستقر إلى حالات لغوية أوسع، وقياس أداء مستمر، ومراجعة للـAPI ممن يستخدمون gettext وBabel بجدية، واختبارات توافق عبر كل إصدار مدعوم من Python وBabel.

نرحب بـالمشكلات وطلبات السحب — فمرحلة alpha هي بالضبط الوقت الذي تستحق فيه الواجهة النقاش.

شارك في المجتمع¶

• اختر good first issue واضحة النطاق.
• اطرح أسئلة الاستخدام في Q&A Discussions.
• اعرض سير عمل gettext في الإنتاج وأفكار API في Ideas Discussions.
• اقرأ دليل المساهمة قبل فتح طلب سحب.