جعل إضافات وقوالب ووردبريس جاهزة للترجمة

كل يوم ينمو ووردبريس ويتطور أكثر فأكثر وفي جميع الدول العالم الناطقة باللغة الإنجليزية وغيرها، وأغلب البرمجة في ووردبريس تتم باللغة الإنجليزية بالإضافة إلى أغلب الإضافات والقوالب تكتب بسلاسل نصية باللغة الإنجليزية على الرغم من أن أكثر من نصف مستخدميه لغتهم الأصلية ليست الإنجليزية.

هذا المقال، تعزيز للمقال الموجود مسبقا على أكاديمية حسوب، حول دليل المطور لتهيئة إضافات ووردبريس للترجمة.

وهذا هو السبب الذي جعلنا نشهد على المدى العقد الماضي المزيد من المناقشات لدعم التدويل التي ستجعل ووردبريس يدعم جميع اللغات الأخرى، وهذا سيكون ضروريا لو كنت تعمل على إضافات أو قوالب عالمية الانتشار.

يجب علينا القيام بثلاثة خطوات حتى نتمكن من ترجمة السلاسل النصية لعناصر الواجهة:

1. اختر، صرّح، و استخدم "مجال النص".
2. استخدم وظائف مناسبة لسلاسلك النصية ومجال النص المختار.
3. سيسمح لك هذا بإنشاء ملفات الترجمة.

بفضل ملفات الترجمة هذه، ستسمح للناس بترجمة قوالبك و إضافاتك.

ما هو "مجال النص" ؟

مجال النص هو "ترجمة مساحة الأسماء"  (translation namespace) لإضافاتك أو ثيماتك وهي طريقة لوردبريس لفصل قائمة من "السلاسل النصية لترجمتها" من بقية السلاسل النصية.
وتكمن أهمية مجال النص في أن بعض السلاسل النصية قد تعني معاني كثيرة في الإضافات والقوالب، فمثلا كلمة "!Let’s go" قد تعني "Create a membership account" في سياق وقد تعني "Start the survey" في سياق آخر.

لذلك بعد تعريف مجال النص، واستخدامه مع "gettext" أو مع دوال الترجمة التي سوف نقوم بشرحها فيما بعد. (إن مشروع gettext جزء أساسي من طريقة عمل نظام الترجمة في الووردبريس)
إذا أردت أن تضع مجال النص في إضافتك أو في قالبك في الجزء العلوي للتعليقات الموجود في ملف style.css للقوالب أو في ملف PHP الرئيسي لإضافتك. فسيكون مشابهًا لهذا بالنسبة للقوالب:

<?php
/*
Plugin Name: Pretend Plugin
[Other comment-block information goes here]
Text Domain: wpshout
*/

أما للقوالب فسيكون مشابهًا لهذا:

/*
Theme Name: Pretend Theme
[Other comment-block information goes here]
Text Domain: wpshout
*/

دوال Gettext: أبقِ ()__ و ()e_ و ()x_ و ()n_ صحيحة

لجعل النصوص الخاصة بك قابلة للترجمة، تحتاج إلى تمرير دالة سوف تقوم باستبدال "!Let’s go" مع ترجمتها باللغة الإسبانية أو العربية أو الفرنسية أو غيرها، ولتسهيل هذا الأمر، يقوم ووردبريس بإعطاء أسماء قصيرة جدا للدوال التي تقوم بهذه الوظيفة.

الدالة ()__

أعتقد أن هذه الدالة هي الدالة الأهم، فلقد حصلت على أكثر اسم مبهم وغريب. لكن هدفها الرئيسي هو السماح لجميع السلاسل النصية بأن تترجم إلى لغة أخرى إذا كان يجب ذلك. وتُستخدم هذه الدالة مع معاملين الأول للسلسلة النصية والثاني لمجال النص، على سبيل المثال:

echo __(
    'WPShout is a great WordPress site!',
    'wpshout'
);

الطباعة الذاتية بواسطة () e_

الدالة الأولى ستقوم بإرجاع نص فقط ويجب عليك طباعة (عرض) النص بنفسك، فإذا كان هذا يزعجك فيمكنك استخدام ()e_ فهي مثل ()__ echo . ستقوم هذه الدالة باختصار كتابة بعض الأحرف، لكنها لن تقوم بأي شيئ آخر، وهذا مثال تطبيقي على استخدام هذه الدالة:

_e(
    'WPShout is a great WordPress site!',
    'wpshout'
);

والآن سنبدأ بالتعامل مع الجوانب الدقيقة للترجمة.

توفير نص للشرح بواسطة ()x_

في بعض الأحيان كلمة أو جملة تكون مبهمة وصعبة الترجمة فقد تعني العديد من المعاني، فمثلا كلمة "post" قد تعني اسما مثل "مشاركة" أو "تدوينة" وقد تعني فعلا مثل "نشر" (to post - to publish).
على عكس الدالتين السابقتين، يمكنك بواسطة ()x_ وضع نص لشرح الكلمة أو الجملة مثل المثال التالي:

_x(
   'Post',
   'verb, as in "to publish"',
   'wpshout'
);

النص الأوسط لن يظهر للمستخدم، لكنه سيظهر للمترجم حتى يفهم النص. (يذكر أنه توجد دالة ()ex_ و التي تجمع ما بين e_ و x_).

الجمع بواسطة ()n_

من المشاكل التي قد تواجهها في الترجمة هو الجمع. ففي اللغة الإنجليزية، "I have 1 Comment" (أنا أملك 1 تعليق) أو "I have 3 Comments" (أنا أملك 3 تعليقات)، لأجل معالجة مشكلة جمع كلمة تعليق، ووردبريس يوفر لك دالة ()n_ التي ستقوم بمعالجة الفرق بين الإثنين.
في العادة، عندما تستخدم دالة ()n_ سوف تحتاج إلى استدعاء دالة الكتابة ()printf. (أو sprintf التي تقوم بإرجاع سلسلة نصية على عكس printf التي تقوم بطباعة النص).
وهذه الدوال ستقوم باستبدال قيمة في سلسلة نصية مع قيمة تم تمريرها لهم. لتفهم أكثر أنظر للكود أدناه:

printf(
    _n(
        'One comment',
        '%s comments',
        $comments,
        'wpshout'
    ),
    $comments
);

ستلاحظ أننا استخدمنا قيمة عددية مسندة إلى متغير comments$ مرتين. نفترض أن comments$ تمتلك قيمة "3". في المرة الأولى استخدمنا comments$ مع n__ لتحديد هل سنستخدم الجمع أو لا، وبما أن 3 أكبر من 1 سوف يختار " s% comments" بدلا من "One comment".
أما في المرة الثانية فاستخدمناها مع printf لوضع الرقم في السلسلة النصية، عن طريق استبدال s% بـ 3 والتي هي قيمة المتغير comments$، لتكون الجملة الكاملة المطبوعة هي "3 comments".

دوال Gettext أخرى

سوف نقوم بشرح جميع الدوال المهمة والأساسية، وهذا لا يعني أنه لا توجد دوال أخرى جديرة بالاهتمام:

• ()__esc_attr: هذه الدالة تقوم بنفس وظيفة ()__ لكنها سوف تراعي ()esc_attr (سمة الخروج للـ HTML) لدواعي السلامة. (يوجد أيضا دالة ()esc_attr_e و دالة ()esc_attr_x).
• ()__esc_html: نفس الشيء مع هذه الدالة، ففي سبيل السلامة يمكنك الجمع بين سمة الخروج للـ HTML وبين ترجمتك. (و بالطبع توجد دالة ()esc_html_e و دالة ()esc_html_x).
•  ()n_noop_ : هذه الدالة تقوم بنفس وظيفة دالة ()n_ لكن بدون عمليات.

تسليم الترجمة إلى جافا سكريبت عن طريق دالة ()wp_localize_script

بسبب أن الترجمات في الووردبريس يتم التعامل معها عن طريق PHP، سوف تحتاج إلى تمرير السلاسل النصية لاستخدمها مع الجافا سكريبت، ويمكنك فعل هذا عن طريق دالة ()wp_localize_script. هذه الدالة مفيدة للغاية وتستخدم كثيرا خارج الترجمة، لأنها تمكنك من تمرير أية قيمة أو متغير من PHP إلى جافا سكريبت. لكن الاستخدام الأساسي لها للترجمة ولذلك سميت باسمها.
وهذا هو مثال لطريقة استخدام هذه الدالة:

wp_localize_script(
    'wpshout-js',
    'strings',
    array(
        'hello' => __( 'Hello!', 'wpshout' );
    )
);

وللوصول إلى هذه القيم عن طريق ووردبريس، فستقوم بشيء مثل:

alert(strings.hello);

تمتلك دالة ()wp_localize_script ثلاثة معاملات:

1. المعرّف (handle) الذي استخدمناه في ()wp_enqueue_script (أو ()wp_register_script) للجافا سكريبت التي نقوم بترجمتها.
2. اسم كائن جافا سكريبت الذي نريد أن ترتبط به ترجمتنا.
3. مصفوفة (array) مترابطة للترجمات، مع مؤشر index أو اسم خاص كمفتاح و قيمة كسلسلة نصية ابتدائية لاستخدمها.

يتم التعامل مع الترجمة نفسها عن طريق نفس دوال PHP التي شرحناها في الجزء السابق من الدرس.

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

حتى الأن كنا نتحدث عن البرمجة باستخدام PHP، لكن هنالك جزء ثاني لا يعتمد على الـ PHP، وهذا الجزء هو الذي يقوم بإنشاء ملفات الترجمة.

يعتبر هذا الجزء صعبا بالنسبة لي، فببطء يقوم نظام ووردبريس ببناء حلول أكثر قوة و أكثر إفادة للتعامل مع العمل الحالي للترجمة (أنظر إلى GlotPress ،translate.wordpress.org و the Polyglot Make blog) لكن يبقى هذا الجزء صعبا للمستخدم ذا الخبرة المتوسطة، على الرغم من أننا سنقوم بشرح أساسياته لكننا لن نخوض في التفاصيل، بالنسبة لي اعتدت على استخدام Poedit كمحرر للترجمة.

مهما كانت الطريقة الذي اعتدت بها أن تقوم بإنشاء وتعديل و قراءة ملفات الترجمة، يوجد ثلاثة أنواع أساسية من ملفات الترجمة:

• ملفات pot.: الملفات الرئيسية للإضافات والقوالب، والتي قامت بجمع جميع السلاسل النصية من الدوال ()s__ وغيرها.
• ملفات po.: هذه الملفات عبارة عن نص ترجمة السلاسل النصية الإنجليزية إلى اللغة المستهدفة، نادرا ما سوف تقوم بتعديل واحدة مباشرة (لأن الصيغة بها الكثير من الكلمات والرموز المبهمة والغريبة) لكن يمكنك فتحها باستخدام محرر نصوص والقيام بتعديلات سريعة للترجمة.
• ملفات mo.: الترجمة النهائية من اللغة الإنجليزية إلى اللغة المستهدفة، وهذه الملفات عبارة عن ملفات ثنائية (binary files) تستخدم وتقرأ عن طريق ووردبريس، لذلك عندما تقوم بفتحها مع محرر النصوص لن تستطيع معالجتها، لذا إذا أردت القيام بذلك يجب عليك العودة إلى ملفات PO و التعديل عليها و إعادة إنشاء ملفات MO.

كما أخبرتك سابقا، هذا هو الجزء الأصعب بالنسبة لي، لكن إذا كان إضافتك أو قالبك في مستودعات WordPress.org، سوف تجد ملفات pot. جاهزة بالنسبة لك وسيفهم مترجميك كيف يهتمون بالباقي.
إذا أردت المزيد من التفاصيل أو الأدوات، قم بزيارة صفحة Translating WordPress.

ماذا تعلمنا حول تدويل كود ووردبريس

لقد قمنا في هذا الدرس بتغطية الأجزاء الثلاثة الرئيسية لجعل كود ووردبريس الخاص بك جاهزا للترجمة: اختر مجال النص، استخدم دوال gettext ومن ثم أحصل على ملف POT لصنع ملفات الترجمة PO و MO. الخطوات سهلة و قابلة للتنفيذ، ولها تأثير كبير للناطقين بغير اللغة الإنجليزية، أو أولئك الذين يحسون براحة أكبر عند استخدامهم لغة أخرى تعلموها مؤخرا.

ترجمة -وبتصرف- للمقال Making plugins and themes translation ready لصاحبه: David Hayes.