تعريب قالب ووردبريس للمطورين: Text Domain وPOT/PO/MO وRTL

هذا الدليل مخصص للمطور الذي يريد تعريب قالب ووردبريس من ناحية الكود، وليس فقط ترجمة عبارات موجودة بالفعل. سنراجع Internationalization (i18n)، الـText Domain، دوال الترجمة، ملفات POT/PO/MO، تحميل الترجمات، دعم Child Theme وRTL، مع أخطاء شائعة تجعل القالب غير قابل للترجمة حتى لو استخدمت Loco Translate أو Poedit.

إذا كان القالب جاهزًا للترجمة وتريد فقط ترجمة الواجهة، استخدم المسار العملي عبر Loco Translate. أما إذا كانت النصوص Hardcoded أو Text Domain غير متسق أو RTL غير مدعوم، فهذا الدليل هو المسار الصحيح.

للمطورين

للمسار بدون تعديل كود راجع تعريب قالب ووردبريس باستخدام Loco Translate وضبط RTL.

الفرق بين Internationalization وLocalization

Internationalization أو i18n تعني كتابة القالب بحيث تصبح النصوص قابلة للترجمة أصلًا. أما Localization أو l10n فهي توفير الترجمة الفعلية للغة مثل العربية. إذا لم تنفذ i18n بصورة صحيحة، لن تستطيع أداة الترجمة الوصول إلى السلاسل Hardcoded بشكل موثوق.

1. اضبط Text Domain بصورة صحيحة

Text Domain هو المعرّف الذي يربط سلاسل القالب بترجماتها. وفق Theme Handbook الرسمي، يجب أن يطابق Text Domain الـslug الخاص بالقالب، وهو شرط للقوالب المنشورة في WordPress Theme Directory، ويُكتب عادة lowercase وبصيغة kebab-case عند وجود أكثر من كلمة.

/*
Theme Name: My Theme
Text Domain: my-theme
Domain Path: /languages
*/

لا تستخدم أكثر من Text Domain عشوائيًا داخل القالب نفسه. عدم الاتساق بين header في style.css ودوال الترجمة وملفات اللغة من أكثر أسباب فشل الترجمة.

2. لا تكتب النصوص القابلة للترجمة Hardcoded

النص التالي سيجبر المترجم على تعديل Template نفسه، لذلك لا يصلح لقالب قابل للترجمة:

<h2>Latest Posts</h2>

الأفضل تمرير النص عبر دالة ترجمة مناسبة:

<h2><?php echo esc_html__( 'Latest Posts', 'my-theme' ); ?></h2>

أهم دوال الترجمة التي تحتاجها

• __() لإرجاع النص المترجم دون طباعته مباشرة.
• _e() لطباعة النص المترجم عندما لا تحتاج معالجة إضافية، مع الانتباه إلى escaping في السياق المناسب.
• esc_html__() وesc_html_e() للنصوص التي ستظهر داخل HTML text context.
• esc_attr__() وesc_attr_e() لقيم attributes.
• _x() عندما تحتاج Context لتمييز نفس الكلمة بمعانٍ مختلفة.
• _n() للتعامل مع Singular/Plural بدل تركيب الجملة يدويًا حسب الرقم.

3. استخدم Placeholder بدون كسر الترجمة

عند إدخال قيمة ديناميكية داخل جملة، لا تجمع أجزاء النص بطريقة تمنع المترجم من تغيير ترتيب الكلمات. استخدم Placeholder واضحًا، وأضف Translator Comment عندما يكون السياق غير واضح.

/* translators: %s: author display name. */
printf(
    esc_html__( 'Written by %s', 'my-theme' ),
    esc_html( $author_name )
);

4. ما هي ملفات POT وPO وMO؟

• POT هو Template يحتوي السلاسل القابلة للترجمة ولا يمثل ترجمة لغة محددة.
• PO ملف قابل للقراءة والتحرير يحتوي النص الأصلي والترجمة للغة محددة.
• MO هو الملف المترجم بصيغة binary الذي يستخدمه gettext/WordPress أثناء التشغيل.
• قد توجد أيضًا ملفات JSON لترجمات JavaScript حسب طريقة تسجيل السكربتات والترجمات.

لا تتعامل مع ملف POT على أنه شرط وحيد لنجاح القالب؛ الأهم أن تكون السلاسل نفسها مكتوبة بدوال i18n وText Domain صحيحًا، ثم تولد Template من المصدر.

5. توليد ملف POT باستخدام WP-CLI

إذا كنت تطور القالب، يمكن استخدام WP-CLI i18n لاستخراج السلاسل من المصدر بدل إنشاء ملف POT يدويًا.

wp i18n make-pot . languages/my-theme.pot --domain=my-theme

نفّذ الأمر داخل بيئة التطوير وليس عشوائيًا على Production، وراجع الناتج بعد كل تغييرات كبيرة في السلاسل.

6. أين تحفظ ملفات الترجمة؟

داخل القالب يمكن استخدام مجلد مثل /languages مع تعريف Domain Path عند الحاجة. WordPress يستطيع أيضًا استخدام حزم اللغة داخل wp-content/languages/themes/. إذا كانت الترجمة مخصصة لموقع عميل فلا تحفظها في مكان سيمسحه تحديث القالب دون خطة واضحة.

7. تحميل Text Domain في القوالب المخصصة

في قالب مخصص يمكن تحميل ملفات اللغة في after_setup_theme. استخدم اسم Text Domain نفسه المستخدم في جميع السلاسل.

function mustafawp_theme_setup() {
    load_theme_textdomain(
        'my-theme',
        get_template_directory() . '/languages'
    );
}
add_action( 'after_setup_theme', 'mustafawp_theme_setup' );

إذا كنت تعمل على Child Theme فهناك load_child_theme_textdomain(). لا تغيّر القالب الأب فقط لتجعل ترجمة موقع واحد تعمل؛ افصل تخصيصاتك بحيث لا تضيع عند التحديث.

8. ترجمة JavaScript في القالب

إذا كان القالب يحتوي واجهة JavaScript بها نصوص للمستخدم، لا تترك السلاسل Hardcoded داخل ملفات JS. استخدم APIs الخاصة بالترجمة في WordPress وسجّل ترجمات السكربت بحسب الـhandle والـText Domain. هذا يمنع وجود واجهة PHP عربية بينما المكونات التفاعلية تبقى بالإنجليزية.

9. دعم RTL بالطريقة الصحيحة

في القوالب الكلاسيكية يستطيع WordPress تحميل rtl.css تلقائيًا عندما تكون لغة الموقع من اليمين إلى اليسار. لكن الملف يجب أن يحتوي تعديلات حقيقية للمكونات التي تحتاجها، وليس مجرد direction: rtl على body.

• راجع Flexbox وGrid وترتيب العناصر.
• استخدم logical properties مثل margin-inline وpadding-inline عندما تناسب البنية.
• راجع left/right في positioning والـtransforms.
• لا تعكس الصور والأيقونات بلا تمييز.
• اختبر Navigation وDropdowns وOff-canvas panels.
• اختبر WooCommerce Gallery وCart وCheckout والنماذج.
• راجع third-party libraries التي قد تحتاج إعداد RTL مستقلًا.

10. ما الذي يتغير في Block Themes؟

القوالب المبنية على Block Theme تقلل الاعتماد على بعض Templates الكلاسيكية، لكن قواعد i18n للنصوص التي يضيفها القالب ما زالت مهمة. راجع كذلك styles وpatterns وJavaScript وأي PHP مساعد، ولا تفترض أن استخدام Site Editor يجعل كل النصوص قابلة للترجمة تلقائيًا.

11. اختبر الترجمة قبل إصدار القالب

• غيّر Site Language إلى العربية وتأكد من تحميل الترجمة.
• ابحث عن أي نصوص إنجليزية Hardcoded في الواجهة.
• اختبر Strings بها placeholders وplural forms.
• اختبر لوحة التحكم إذا كان القالب يضيف صفحات إعدادات.
• شغّل PHPCS وفق WordPress Coding Standards على الكود المعدل.
• اختبر RTL على أحجام شاشة متعددة.
• اختبر تحديث القالب للتأكد أن الترجمة المحلية لا تضيع.
• راجع JavaScript console وPHP logs لأي warnings مرتبطة بالترجمة أو التحميل.

أخطاء شائعة في تعريب القوالب

Text Domain مختلف بين الملفات

استخدام my_theme في مكان وmy-theme في مكان آخر يجعل استخراج وتحميل الترجمة غير موثوق. استخدم معرفًا واحدًا.

ترجمة النص داخل الكود مباشرة

استبدال الإنجليزية بالعربية داخل Template يحل مشكلة موقع واحد لكنه يلغي قابلية القالب للترجمة. اجعل السلسلة قابلة للترجمة ثم أضف العربية كLocalization.

عدم Escape الناتج

الترجمة لا تلغي قواعد الأمان. استخدم دالة Escape المناسبة للسياق الذي سيظهر فيه النص وفق WordPress Coding Standards.

تعديل القالب الأب

إذا كان القالب سيستقبل Updates، تعديلات PHP/CSS المباشرة قد تُفقد. استخدم Child Theme أو آلية Extensibility صحيحة عندما تحتاج تخصيصًا دائمًا.

Checklist للمطور

• Text Domain يطابق slug القالب.
• Domain Path مضبوط إذا كان المسار غير الافتراضي.
• جميع السلاسل القابلة للترجمة تمر عبر i18n functions.
• Escaping مناسب للسياق.
• Placeholders وTranslator Comments واضحة.
• POT محدث من المصدر.
• ملفات اللغة في مسار صحيح.
• JavaScript strings مترجمة عند الحاجة.
• RTL مختبر فعليًا وليس نظريًا.
• لا توجد تعديلات ستضيع مع تحديث القالب.

الخلاصة

تعريب قالب ووردبريس على مستوى التطوير يبدأ من Internationalization سليمة: Text Domain متسق، سلاسل غير Hardcoded، دوال ترجمة صحيحة وملفات لغة منظمة. بعد ذلك تأتي Localization العربية ودعم RTL. هذا الفصل يجعل القالب قابلًا للصيانة والتحديث والترجمة لأي لغة بدل تحويله إلى نسخة عربية ثابتة يصعب تطويرها لاحقًا.