منتديات رحيل لكل العرب - عرض مشاركة واحدة - دليل المطور لتهيئة إضافات ووردبريس للترجمة

مهرة النجدية · 24-02-2019, 10:43 PM

دليل المطور لتهيئة إضافات ووردبريس للترجمة

دليل المطور لتهيئة إضافات ووردبريس للترجمة

توجد الكثير من المقالات التّتي تتحدّث عن ترجمة إضافات Plugins ووردبريس، إلّا أنّ القليل منها يتطرّق لتفاصيل عمليّة التّرجمة عندما تكون مهمَّة يوميّة.

wp-plugins-i18n.thumb.png.5c4cf6d923ef6f

مالّذي يحدُث عند تغيير جزء من الشّفرة البرمجيّة Code؟ مالّذي يحدُث عند إضافة سلاسل محارف Strings جديدة؟ مالّذي يحدُث عند تحديث إضافة إلى إصدار جديد؟

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

يتوفّر ووردبريس بلغات عدّة: تُضَمَّن في نظام ووردبريس لإدارة المحتوى قابليّة الاستخدام بأيّ لغة، على الرّغم من أنّ لغة الواجهة الافتراضيّة هي الإنجليزية الأميركية (التّرميز en_US).

يتوفّر ووردبريس بلغات عدّة: تُضَمَّن في نظام ووردبريس لإدارة المحتوى قابليّةُ الاستخدام بأيّ لغة، على الرّغم من أنّ لغة الواجهة الافتراضيّة هي الإنجليزية الأميركية (التّرميز en_US).

إنشاء إضافة
أوّل ما يجب تنفيذه هو إنشاء إضافة. سننشئ إضافةً للتّطبيق عليها. يُمكنك متابعة درس مُقدّمة إلى برمجة إضافات Wordpress للمزيد حول برمجة إضافات ووردبريس.

ستعمل الإضافة على كتابة نصّ تحفيزي في التّرويسة Header.

أولًا أنشئ مجلَّدًا جديدًا ضمن مجلَّد الإضافات وسمِّه wp-admin-motivation. ثمّ أنشئ ملفًّا ضمن هذا المجلّد وسمِّه wp-admin-motivation.php. في ما يلي الشّفرة الّتي يجب وضعها في الملفّ:

<?php
/*
Plugin Name: Admin Motivation
Description: Shows motivational messages in the admoin bar
Author: Daniel Pataki
Version: 1.0
Text Domain: wp-admin-motivation
*/
function get_motivation_text() {
$motivation = array(
'You are awesome',
'This website is boss',
'You look great today',
'Your earlobes are well rounded, good job!'
);
shuffle( $motivation );
return $motivation[0];
}
add_action( 'admin_notices', 'show_motivation_text' );
function show_motivation_text() {
$text = get_motivation_text();
echo "<p id='wp-admin-motivation'>$text</p>";
}
add_action( 'admin_enqueue_scripts', 'motivation_assets' );
function motivation_assets($hook) {
wp_enqueue_style( 'motivation-styles', plugin_dir_url( __FILE__ ) . 'styles.css' );
}
تخلِط الدّالّة الأولى ()get_motivation_text مصفوفة Array من العبارات التّحفيزيّة باستخدام دالّة shuffle الموجودة في PHP، ثمّ بعد الخلط تختار العبارة الأولى من المصفوفة. يُمكن عدّ دالّة ()get_motivation_text وسيلةً لتوزيع العبارات التّحفيزيّة عشوائيًّا.

نربُط في الخطوة التّاليّة بين دالّة ()show_motivation_text والخطّاف Hook المسمَّى admin_notices. تحصُل دالّة ()show_motivation_text على عبارة تحفيزيّة عشوائيّة عن طريق ()get_motivation_text ثمّ تطبع العبارة داخل فقرة ذات معرّف wp-admin-motivation.

تكون العبارة التّحفيزيّة، بالوصول إلى هذه النّقطة، مرئيّة؛ ولكنّنا سنغيّر موضعها لتكون إلى جانب تبويب خيّارات/مساعدة (Options/help). نستخدم CSS لهذا الغرض.

تكتفي بعض الإضافات بوضع بضعة أسطر CSS في التّرويسة، إلّا أنّ الطّريقة الصّحيحة للتّعامل مع CSS هيّ إدراج الأسطُر ضمن الطّابور Queue؛ وذلك عن طريق ربط دالّة ()motivation_assets بالخطّاف admin_enqueue_scripts وإدراج CSS في الطّابور هناك.

يحدّد النّمط مواضع النّصّ مع أخذ اتّجاه الكتابة من اليمين إلى اليسار Right-to-left, RTL في الحسبان.

#wp-admin-motivation {
float: right;
padding-right: 15px;
padding-top: 7px;
margin: 0;
font-size: 11px;
}

.rtl #wp-admin-motivation {
float: left;
padding-left: 15px;
}
الإضافة جاهزة الآن للعمل. المشكل الوحيد هو أنّ العبارات التّحفيزيّة تستخدم الإنجليزيّة فقط. إن أردت استخدام لغة أخرى فسيتطلّب الأمر إنشاء إضافة مماثلة وإبدال العبارات الإنجليزيّة بعبارات اللّغة المستهدفة. تخيّل أنّك تُريد استهداف عشرين لغةً، يعني هذا أنّك ستحتاج لعشرين إضافة لا يوجد فرق بينها سوى في العبارات المعروضة. الكثير من الجهد المهدور، لا بدّ من وجود وسيلة أخرى.

تدويل Internationalizing إضافة
يهدف تدويل الإضافات في الأساس إلى جعلها جاهزةً لتُترجَم. يتطلّب التّدويل تغليفَ سلاسل المحارف Strings في دوالّ خاصّة تُسخدَم لتحميل التّرجمات الصّحيحة.

توجد العديد من دوالّ التّدويل إلّا أنّنا سنأخذ فقط واحدةً منها، وهي دالّة ()__، ونترك البقيّة إلى أن نفهم المثال.

تأخذ الدّالّة ()__ معطييْن: النّص الّذي نُريد ترجمته ونطاق النّصّ Text domain. في ما يلي الصّيغة العامّة لاستخدام هذه الدّالّة:

<?php $greeting = __( 'Hello There!', 'text-domain' ); ?>
نحصُل بعد استخدام دالّة ()__ على ترجمة النّصّ إن كانت موجودة، وإلّا فإنّ الدّالّة تُعيد النّصّ الأصليّ. تستخدم الدّالّةُ اللّغةَ الحاليّة لتحديد التّرجمة المطلوبة. يُمكنك الانتقال بين لغات ووردبريس في الإعدادات. تُطبَّق اللّغة المُختارة في الإعدادات على جميع التّرجمات.

نأتي الآن لنطاق النّصّ، حتّى تكتمل عندنا الصّورة. نطاق النّصّ هو طريقة لتجميع التّرجمات مع بعض. لدى القالب Theme الّذي تستخدمه نطاق نصّ خاصّ به، نفس الشّيء بالنّسبة لجميع الإضافات. تجعل نطاقات النّصوص من التّفريق بين التّرجمات عمليّةً أيسر.

يجب أن يكون نطاق النّصّ، بالنّسبة للإضافات، مطابقًا لاسم مجلّد الإضافة. يعني هذا، في مثالنا، أنّ نطاق النّصّ يجب أن يكون wp-admin-motivation. كلّ ما ياوجّب علينا فعله، من أجل تدويل الإضافة، هو تغليف سلاسل المحارف بالدّالّة ()__.

$motivation = array(
__( 'You are awesome', 'wp-admin-motivation'),
__( 'This website is boss', 'wp-admin-motivation'),
__( 'You look great today', 'wp-admin-motivation'),
__( 'Your earlobes are well rounded, good job!, 'wp-admin-motivation')'
);
تنفيذ التّرجمات
جعلنا في الخطوة السّابقة سلاسل المحارف جاهزةً للتّرجمة، لكن لحدّ الآن لا توجد أيّ ترجمات على الموقع. يجب أن نخبر ووردبريس أين توجد ترجمات الإضافة. الطّريقة المعياريّة لذلك هي إنشاء مجلّد فرعيّ باسم lang ضمن مجلَّد الإضافة. أنشئ مجلّد lang الآن وأضف الشّفرة التّاليّة في الملفّ الرّئيس للإضافة حتى يعرف ووردبريس أين توجد التّرجمات:

add_action('plugins_loaded', 'wan_load_textdomain');
function wan_load_textdomain() {
load_plugin_textdomain( 'wp-admin-motivation', false, dirname( plugin_basename(__FILE__) ) . '/lang/' );
تعدّ دالة ()load_plugin_textdomain أساسيّةً هنا ويجب أن تُستدعى من دالّة مربوطة بالخطّاف plugins_loaded. أوّل معطى لدالّة ()load_plugin_textdomain هو اسم نطاق النّصّ الّذي تحدّثنا عنه سابقًا، الثّاني مهجور Deprecated، والثّالث هو مجلّّد اللّغة.

ستكون أسماء ملفّات التّرجمات على صيغة plugin_name-locale.mo. حيثُ plugin_name اسم الإضافة وlocale المحلّيّة. سنرى في ما بعد كيفيّة إنشاء هذه التّرجمات. تذكّر، في الوقت الحاليّ، أنّك يجب أن تضع ملفّات التّرجمات هنا.

ملحوظة: المحليّة Locale هي مجموعة من المُعطيات تحدّد لغة المستخدم، دولته، وأيّ تفضيلات خاصّة قد يودّ المستخدم رؤيتها في لغة الواجهة. سنختار ترجمة العبارات التّحفيزيّة الموجودة في الإضافة إلى اللّغة العربيّة؛ لذا سيكون المفّ باسم wp-admin-motivation-ar.mo.

بالوصول إلى هذه النّقطة سيعمل كلّ شيء بالطريقة المرجوَّة، ينقُصُنا فقط إنشاء التّرجمات.

إنشاء التّرجمات
توجد طُرُق متعدّدة لإنشاء ترجمات إلّا أنّ النّتيجة في النّهاية متطابقة. ستحصُل على ملفّين، أحدهما بامتداد po. والآخر بامتداد mo. الأوّل يُمكن للأشخاص قراءته، ويُمكنك فتحه بأيّ محرّر نصوص والتّعديل عليه. أمّا الملفّ ذو الامتداد mo. فهو نتاج تحويل ملفّ po. إلى صيغة مقروءة بالنّسبة للآلة، ذات حجم أصغر بكثير إلّا أنّه لا يمكن للإنسان قراءتها.

في ما يلي مثال على ملفّ PO غير مُترجَم. توجد في أعلى الملفّ معلومات أساسيّة عن التّرجمة، المترجِم والمشروع؛ تليها سلاسل محارف تُمكن ترجمتها متبوعة بأماكن التّرجمات المنتظَرة.

msgid ""
msgstr ""
"Project-Id-Version: WP Admin Motivation 1.0.0\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2015-04-27 13:09+0100\n"
"PO-Revision-Date: 2015-04-27 13:09+0100\n"
"Last-Translator: Daniel Pataki <contact@tastique.org>\n"
"Language-Team: Daniel Pataki <hello@danielpataki.com>\n"
"Language: Hungarian\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Poedit-KeywordsList: __;_e\n"
"X-Poedit-Basepath: .\n"
"X-Poedit-SearchPath-0: ..\n"

#: ../wp-admin-motivation.php:20
msgid "You are awesome"
msgstr ""

#: ../wp-admin-motivation.php:21
msgid "This website is boss"
msgstr ""

#: ../wp-admin-motivation.php:22
msgid "You look great today"
msgstr ""

#: ../wp-admin-motivation.php:23
msgid "Your earlobes are well rounded, good job!"
msgstr ""
الصّيغة العامّة للأسطُر في ملفّ التّرجمة هي التّاليّة:

#: مسار الملفّ الّذي توجد به السّلسلة:رقم السّطر حيثُ توجد السّلسلة
msgid "السّلسة المطلوبة ترجمتها"
msgstr "التّرجمة"
قد تظنّ أنّ كون أماكن تواجد السّلاسل مذكورة مباشرةً بعد ذكر رقم السّطر الّذي تتواجد به يجعل من إنشاء وصيّانة ملفّات التّرجمة أمرًا شاقًّا. لهذا السّبب توجد أدوات مخصًّصة للمساعدة. تُساعد أدوات المدير Admin tools في توليد ملفّات po. للإضافات الموجودة في مستودع ووردبريس. كما يُمكن أيضًا إنشاء ملفّات po. عبر البرنامج الرّائع Poedit.

نزّل Poedi وشغّله؛ انقُر على File (ملفّ) ثمّ New catalog (مسرَد جديد). أدخل المعلومات المطلوبة في النّافذة المنبثقة. لا تهتّم بطقم المحارف (Charset) وصيّغ الجمع (Plural forms)؛ سنكتفي الآن بالمعلومات الأساسيّة.

02_Poedit_Catalog_properties.thumb.png.2

انتقل إلى تبويب Sources paths (مسارات المصادر). يُخبر مربَّع Paths (المسارات) Poedit أين يجب عليه البحث عن السّلاسل القابلة للتّرجمة ذات العلاقة بالمسار القاعديّ (Base path).

03_Poedit__Sources_paths.thumb.png.396ab

سنضع التّرجمات ضمن مجلَّد فرعيّ في الإضافة؛ يعني هذا أنّ لدينا خيّارين لإعداد المسارات في Poedit:

ضبط المسار القاعديّ Base path على القيمة /.. (المجلَّد الأب) وإعطاء القيمة . (المجلَّد الحاليّ) لمربَّع المسارات Paths.
ضبط قيمة المسار القاعديّ Base path على قيمة المجلَّد الحاليّ . وقيمة مربَّع المسارات Paths على المجلَّد الأب /...
يُخبر الخيّار الأوّل Poedit أنّ الشّفرة البرمجيّة للإضافة موجودة في المجلَّد الأب لمجلَّد اللّغة lang؛ أي أنّ البرنامج سيذهب للمجلَّد الأب ويبحث في ذلك المجلَّد. أمّا الخيّار الثّاني فيقول إنّ المجلَّد الّذي يوجد به الملفّ الحاليّ هو مجلَّد اللّغة؛ وأنّ الملفّات الّتي يجب التّحقّق منها توجد في المجلَّد الأعلى، لذلك استخدمنا /.. في مربَّع المسارات Paths. سنعتمد في هذا الدّرس الخيّار الثّانيّ.

الخطوة التّاليّة هي ضبط الكلمات المفتاحيّة في تبويب Sources keywords (الكلمات المفتاحيّة للمصادر). نحدّد في هذا التّبويب أسماء دوالّ التّرجمة المستخدَمة. في المثال هنا نحتاج فقط لإضافة دالّة __. في أغلب الحالات ستحتاج لإدراج دالتّيْن إلى ثلاث؛ راجع التّرجمة المتقدّمة أدناه.

لم يبق إلّا الموافقة على البيانات المُدخَلة. سيطلُب منك البرنامج مكان حفظ الملفّ؛ اختر مسار المجلَّد lang إن كنت اعتمدت الخيّار الثّاني في إعداد المسارات أعلاه. سيبحث Poedit في ملفّات الإضافة ويعثُر على السّلاسل الجاهزة للتّرجمة.

04_Poedit_-_Strings_detected.thumb.png.3

يُمكنك بعدها ترجمة هذه السّلاسل إلى اللّغة الّتي تُريد.

05_Poedit_Strings_translated.thumb.png.4

احفَظ الملفّ بعد الانتهاء من التّرجمة وسيولّد Poedit ملفّ MO في مجلَّد lang. تجب إعادة تسميّة ملفّ MO (اسم الملفّ في الإعداد الافتراضيّ هو default.mo) ليوافق الصّيغة الّتي ناقشناها سابقًا؛ أي أن اسم الملفّ، في المثال لدينا، هو wp-admin-motivation-ar.mo. بالنّسبة لملفّ PO فلايهمّ اسمه كثيرًا، إلّا أنّ من الأفضل تسميّته بنفس الطّريقة لكي تعرف بسهولة أيّ ملفّ PO يوافق ملفّ MO إذا كانت توجد الكثير من الملفّات في مجلَّد اللّغات.

ستظهر العبارات التّحفيزيّة باللّغة العربيّة؛ بعد وضع ملفّ اللّغة في مجلَّد اللّغات ضمن الإضافة وتفعيل اللّغة العربيّة في إعدادات ووردبريس.

صيّانة التّرجمات
يبدو تحديث التّرجمات صعبًا للوهلة الأولى، إلّا أنّه ليس كذلك. صحيحٌ أنّ ملفّ PO يحوي رقم السّطر الّذي توجد به السّلسلة المُترجمَة، لكن ووردبريس لا يعتمد على أرقام الأسطُر عند استخدام ملفّ PO. الهدف من استخدام الملفّ والسّكر الّذيْن توجد بهما سلسلة المحارف المُترجَمة هو مساعدة المترجِم بحيث يُمكن النّظر إلى مكان وجود العبارة ومن ثمّ ترجمتها حسب السّيّاق الّذي وردت فيه.

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

تُشبه ملفّات POT ملفّات PO؛ إلّا أنّها لا تحتوي على أيّ ترجمات، فكلّ ما تحتويه هو الجمل والعبارات الجاهزة للتّرجمة؛ أيّ أنّها قوالب فقط. تكون التّرجمات سهلة ما دام ملفّ القالب محدَّثًا ويحوي رقم السّطر الصّحيح لكلّ سلسلة محارف.

إذا احتجت إلى تحديث ملفّ لغة فكلّ ما عليك فعله هو فتحه عن طريق Poedit ثمّ النّقر على أيقونة التّحديث Update وسيُشعرك البرنامج بالسّلاسل الجديدة والمُعدَّلة ويمكنك بعدها التّعديل عليها.

قبول التّرجمات
من الأمور الّتي يحدُث فيها الارتباك كثيرًا، على الأقلّ هذا ما حدث لي أولَ وهلة، هو كيفيّة إنشاء ترجمات جديدة لإضافة. كيف يُمكنني إضافة ترجماتي الخاصّة؟ كنتُ أظنّ أنّ هذه العمليّة تحدُث آليًّا، لكنّها ليست كذلك.

عندما يُعجَب أحدهم بإضافة فإنّه يترجمها إلى لغته باستخدام ملفّ POT المضمَّن في الإضافة ثمّ يُرسل التّرجمة (ملفّات MO وPO) إلى مطوّر الإضافة الّذي يضعها في ملفّ lang، يُنشئ إصدارًا جديدًا ويدفعها إلى مستودع ووردبريس. عندما يتلقّى مستخدم الإضافة التّحديث تظهر الإضافة بلغة واجهة ووردبريس لديه، إن كانت ضمن اللّغات الموجوة في ملفّ lang.

أستضيف كلّ مستودعاتي على Github وهو ما يسهّل على المترجمين إرسال ملفّات التّرجمة لي باستخدام طلبات السّحب Pull requests. كلّ ما عليّ فعله بعدها هو الضّغط على زرّ وإنشاء إصدار جديد من مستودع ووردبريس.

التّرجمات المتقدّمة
تعرّفنا في ما سبق على طريقة ترجمة سلاسل محارف قاعديّة عن طريق دالّة ()__. توجد 14 دالة ترجمة في ووردبريس يُمكن استخدامها لتدقيق ضبط ترجماتك. على الأرجح لن تحتاج إلّا إلى 3 أو 4 منها. نبدأ بالأشهر من بينها.

1- ()__
هذه هي الدّالّة الأساسيّة للتّرجمة. تأخذ سلسلة محارف وتُعيد التّرجمة إن كانت موجودة.

2- ()e_
نفس عمل الدّالّة السّابقة تقريبًا، إلّا أنّها بدلًا من إرجاع التّرجمة تعرضها مباشرةً.

3- ()n_
تتيح هذه الدّالة وسيلة أنيقة للتّعامل مع الجموع. تأخذ الدّالّة أربعة معطيات: صيغة المفرد، صيغة الجمع، العدد الّذي على أساسه ستعرض الصّيغة (صيغة المفرد أو الجمع) ونطاق النّصّ. في ما يلي مثال سريع:

<?php
$messages = get_message_count();
// الاستعمال المبَسَّط: لا تُظهر الدّالة العدد الفعليّ
$text = _n( 'You have one message', 'You have lots of messages', $messages, 'my-message-app' );
// في طريقة الاستعمال هذه نُظهر العدد الفعليّ للرّسائل
$text = sprintf( _n( 'You have one message', 'You have %s messages', $messages, 'my-message-app' ), $messages )
?>
في هذا المثال نحصُل على عدد الرّسائل ضمن متغيّر messages ثمّ نستخدم هذا المتغيّر في دالّة ()n_ الّتي تعتمد على قيمة المتغيّر لاختيّار سلسلة المحارف الّتي تعرضها (بصيغة المفرد أو الجمع). في طريقة الاستعمال المبسَّط للدّالة لا يظهر عدد الرّسائل ضمن سلسلة المحارف المعروضة حيثُ توجد عبارتان، الأولى للعرض إذا كانت قيمة messages مفردة وتُعرَض الثّانيّة في حالة الجمع. إذا أردنا عرض العدد نستخدم عبارة s% في المكان الّذي نُريد أن يُعرض فيه العدد.

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

في اللّغة العربيّة يتغيّر المعدود حسب العدد في ما مجموعه خمس صيّغ (مفرَد، مثنَّى وثلاث حالات بالنّسبة للجمع)، إضافةً للصّيغة الّتي يكون العدد فيها يُساوي صفرا (أيّ أنّ المجموع يُساوي ستة). لمن يُريد التّفصيل في المسألة فليراجع فصل العدد والمعدود في النّحو :).

لأخذ هذه التّغييرات في الحسبان عند إنشاء ملفّ التّرجمة نُخبر Poedit بعدد صيّغ الجمع الموجودة لدينا، بالنّسبة للعربيّة:

nplurals=6; plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 && n%100<=10 ? 3 : n%100>=11 ? 4 : 5;
06_Poedit_plural_forms.thumb.png.4b49678

قبل البدء في البحث عن سلاسل المحارف نُضيف الدّالة n_ في تبويب Sources keywords (الكلمات المفتاحيّة للمصادر) حتى يتعرّف عليها البرنامج؛ إضافةً للدّالّة __ السّابقة.

07_Poedit_keywords.thumb.png.5c9b56aa782

ملحوظة: من المهمّ جدًّا كتابة الدّالّة بالصّيغة n:1,2_ الّتي تعني أنّ المُعطى الأوّل (الرّقم 1) يعبّر عن صيغة المفرد وأنّ المعطى الثّاني لصيغة الجمع.

يمكننا الآن إنشاء ملفّ اللّغة وترجمة العبارات الواردة فيه مع أخذ الجمع بالحسبان.

08_Poedit_plural_forms.thumb.png.deaf1e6

ملحوظة: أبقِ عبارة %s في التّرجمات الّتي تحتاج ذلك، أي الّتي يكون العدد فيها اثنان فما فوق. ستُبدَل هذه العبارة بالعدد الفعليّ أثناء تنفيذ البرنامج. مثلًا إذا كان العدد بين 3 و 10 (التّبويب الرّابع في الصّورة، الّذي يحمل العنوان Form 3) فيمكن أن تكون التّرجمة “توجد لديك 3 رسائل” أو “توجد لديك 8 رسائل”. القيمة (3 و 8) ستُعرف أثناء عمل الإضافة الّتي ستضعها مكان %s.

4- ()x_
تهدف هذه الدّالّة إلى الوقاية من الخلط بين الكلمات مختلفة المعنى الّتي تُكتَب بنفس الطّريقة. مثلًا إذا كنت تستخدم كلمة pair بمعنى “زوج أشخاص” وبمعنى “ربط بجهاز بلوتوث” فيُمكن أن يشتبه المعنى. لمنع الاشتباه ولمساعدة المترجم على اختيّار العبارة المناسبة في لغته استخدم دالّة ()x_.

_x( 'Pair', 'A pair of people', 'my-plugin-textomaind' );
_x( 'Pair', 'As in: pairing devices', 'my-plugin-textomaind' );
5- ()ex و ()nx
يُشبه عمل هاتيْن الدّالتيْن عمل دالّة ()x_ أعلاه. الفرق هو أنّ ()ex_ تعرض النّتيجة مباشرةً في حين أنّ nx_ تُضيف إمكانيّة تحديد صيغة للجمع.

تخليص Escaping التّرجمات
تتيح الدّوال السّتّ التّاليّة إمكانيّة تخليص التّرجمة من أجل الاستخدام الآمن في نصوص HTML (الثّلاث الأخيرة) أو خاصيّاته attributes (الثّلاث الأولى).

()esc_attr__
()esc_attr_e
()esc_attr_x
()esc_html__
()esc_html_e
()esc_html_x
ترجمات Noop
تسجّل دوالّ Noop سلاسل المحارف بصيغة الجمع في ملفّ POT دون أن تترجمها. يعود السّبب في ذلك إلى أنّ العدد غير معروف سلفًا، وهو ما يعني أنّنا سنحتاج لدالّة أخرى للحصول على العدد وبالتّالي اختيّار صيغة المعدود (الجمع). لهذا السّبب نستخدم دالّة Noop ثمّ نترجم القيمة الحقيقيّة لاحقًا بعد الحصول على العدد. راجع المقال التّالي للمزيد.

تستخدم الدّوال التّاليّة لهذا الغرض:

()n_noop_
()nx_noop_
()translate_nooped_plural
ترجمة Javascript
ربّما ننساءل ماذا عن سلاسل المحارف الموجودة ضمن شفرة Javascript؟ يقدّم ووردبريس الحلّ عبر دالّة ()wp_localize_script. تأخذ هذه الدّالّة ثلاثة معطيات: مِقبض Handle (معرّف) السّكريبت الّذي نُريد ترجمته، اسم كائن Object للاستخدام داخل السّكريبت ومصفوفة التّرجمة. في ما يلي مثال على ترجمة سلاسل محارف ضمن Javascript:

add_action( 'admin_enqueue_scripts', 'motivation_assets' );
function motivation_assets($hook) {
wp_enqueue_script( 'motivation-scripts', plugin_dir_url( __FILE__ ) . 'scripts' );
wp_localize_script( 'motivation-scripts', 'wma', array(
'section_title' => __( 'Today's motivation', 'wp-admin-motivation' )
));
}
بعد إضافة التّرجمات يُمكنك استخدامها في ملفّ Javascript المُسجَّل. يجب عليك استخدام اسم الكائن ومفاتيح مصفوفة التّرجمة:

jQuery.html( "<h2>" + wma.section_title + "</h2>" );

المصدر: منتديات رحيل لكل العرب - من قسم: قسم تطوير المواقع ومحركات البحث والسيو Seo والووردبريس WordPress

24-02-2019, 10:43 PM	#1
مهرة النجدية تاريخ التسجيل: Feb 2019 الدولة: قلب ابي العمر: 31 المشاركات: 1,006 التقييم: 10	مهرة النجدية تاريخ التسجيل: Feb 2019 الدولة: قلب ابي العمر: 31 المشاركات: 1,006 التقييم: 10 دليل المطور لتهيئة إضافات ووردبريس للترجمة دليل المطور لتهيئة إضافات ووردبريس للترجمة دليل المطور لتهيئة إضافات ووردبريس للترجمة توجد الكثير من المقالات التّتي تتحدّث عن ترجمة إضافات Plugins ووردبريس، إلّا أنّ القليل منها يتطرّق لتفاصيل عمليّة التّرجمة عندما تكون مهمَّة يوميّة. wp-plugins-i18n.thumb.png.5c4cf6d923ef6f مالّذي يحدُث عند تغيير جزء من الشّفرة البرمجيّة Code؟ مالّذي يحدُث عند إضافة سلاسل محارف Strings جديدة؟ مالّذي يحدُث عند تحديث إضافة إلى إصدار جديد؟ هذه هي نوعيّة الأسئلة الّتي سيُجيب عليها هذا المقال. سنتطرَّق، خطوة بخطوة، كيف نعمل من أجل أن تكون الإضافات الجديدة أو المُحدَّثة جاهزةً للتّرجمة إلى أيّ لغة. يتوفّر ووردبريس بلغات عدّة: تُضَمَّن في نظام ووردبريس لإدارة المحتوى قابليّة الاستخدام بأيّ لغة، على الرّغم من أنّ لغة الواجهة الافتراضيّة هي الإنجليزية الأميركية (التّرميز en_US). يتوفّر ووردبريس بلغات عدّة: تُضَمَّن في نظام ووردبريس لإدارة المحتوى قابليّةُ الاستخدام بأيّ لغة، على الرّغم من أنّ لغة الواجهة الافتراضيّة هي الإنجليزية الأميركية (التّرميز en_US). إنشاء إضافة أوّل ما يجب تنفيذه هو إنشاء إضافة. سننشئ إضافةً للتّطبيق عليها. يُمكنك متابعة درس مُقدّمة إلى برمجة إضافات Wordpress للمزيد حول برمجة إضافات ووردبريس. ستعمل الإضافة على كتابة نصّ تحفيزي في التّرويسة Header. أولًا أنشئ مجلَّدًا جديدًا ضمن مجلَّد الإضافات وسمِّه wp-admin-motivation. ثمّ أنشئ ملفًّا ضمن هذا المجلّد وسمِّه wp-admin-motivation.php. في ما يلي الشّفرة الّتي يجب وضعها في الملفّ: <?php /* Plugin Name: Admin Motivation Description: Shows motivational messages in the admoin bar Author: Daniel Pataki Version: 1.0 Text Domain: wp-admin-motivation */ function get_motivation_text() { $motivation = array( 'You are awesome', 'This website is boss', 'You look great today', 'Your earlobes are well rounded, good job!' ); shuffle( $motivation ); return $motivation[0]; } add_action( 'admin_notices', 'show_motivation_text' ); function show_motivation_text() { $text = get_motivation_text(); echo "<p id='wp-admin-motivation'>$text</p>"; } add_action( 'admin_enqueue_scripts', 'motivation_assets' ); function motivation_assets($hook) { wp_enqueue_style( 'motivation-styles', plugin_dir_url( __FILE__ ) . 'styles.css' ); } تخلِط الدّالّة الأولى ()get_motivation_text مصفوفة Array من العبارات التّحفيزيّة باستخدام دالّة shuffle الموجودة في PHP، ثمّ بعد الخلط تختار العبارة الأولى من المصفوفة. يُمكن عدّ دالّة ()get_motivation_text وسيلةً لتوزيع العبارات التّحفيزيّة عشوائيًّا. نربُط في الخطوة التّاليّة بين دالّة ()show_motivation_text والخطّاف Hook المسمَّى admin_notices. تحصُل دالّة ()show_motivation_text على عبارة تحفيزيّة عشوائيّة عن طريق ()get_motivation_text ثمّ تطبع العبارة داخل فقرة ذات معرّف wp-admin-motivation. تكون العبارة التّحفيزيّة، بالوصول إلى هذه النّقطة، مرئيّة؛ ولكنّنا سنغيّر موضعها لتكون إلى جانب تبويب خيّارات/مساعدة (Options/help). نستخدم CSS لهذا الغرض. تكتفي بعض الإضافات بوضع بضعة أسطر CSS في التّرويسة، إلّا أنّ الطّريقة الصّحيحة للتّعامل مع CSS هيّ إدراج الأسطُر ضمن الطّابور Queue؛ وذلك عن طريق ربط دالّة ()motivation_assets بالخطّاف admin_enqueue_scripts وإدراج CSS في الطّابور هناك. يحدّد النّمط مواضع النّصّ مع أخذ اتّجاه الكتابة من اليمين إلى اليسار Right-to-left, RTL في الحسبان. #wp-admin-motivation { float: right; padding-right: 15px; padding-top: 7px; margin: 0; font-size: 11px; } .rtl #wp-admin-motivation { float: left; padding-left: 15px; } الإضافة جاهزة الآن للعمل. المشكل الوحيد هو أنّ العبارات التّحفيزيّة تستخدم الإنجليزيّة فقط. إن أردت استخدام لغة أخرى فسيتطلّب الأمر إنشاء إضافة مماثلة وإبدال العبارات الإنجليزيّة بعبارات اللّغة المستهدفة. تخيّل أنّك تُريد استهداف عشرين لغةً، يعني هذا أنّك ستحتاج لعشرين إضافة لا يوجد فرق بينها سوى في العبارات المعروضة. الكثير من الجهد المهدور، لا بدّ من وجود وسيلة أخرى. تدويل Internationalizing إضافة يهدف تدويل الإضافات في الأساس إلى جعلها جاهزةً لتُترجَم. يتطلّب التّدويل تغليفَ سلاسل المحارف Strings في دوالّ خاصّة تُسخدَم لتحميل التّرجمات الصّحيحة. توجد العديد من دوالّ التّدويل إلّا أنّنا سنأخذ فقط واحدةً منها، وهي دالّة ()__، ونترك البقيّة إلى أن نفهم المثال. تأخذ الدّالّة ()__ معطييْن: النّص الّذي نُريد ترجمته ونطاق النّصّ Text domain. في ما يلي الصّيغة العامّة لاستخدام هذه الدّالّة: <?php $greeting = __( 'Hello There!', 'text-domain' ); ?> نحصُل بعد استخدام دالّة ()__ على ترجمة النّصّ إن كانت موجودة، وإلّا فإنّ الدّالّة تُعيد النّصّ الأصليّ. تستخدم الدّالّةُ اللّغةَ الحاليّة لتحديد التّرجمة المطلوبة. يُمكنك الانتقال بين لغات ووردبريس في الإعدادات. تُطبَّق اللّغة المُختارة في الإعدادات على جميع التّرجمات. نأتي الآن لنطاق النّصّ، حتّى تكتمل عندنا الصّورة. نطاق النّصّ هو طريقة لتجميع التّرجمات مع بعض. لدى القالب Theme الّذي تستخدمه نطاق نصّ خاصّ به، نفس الشّيء بالنّسبة لجميع الإضافات. تجعل نطاقات النّصوص من التّفريق بين التّرجمات عمليّةً أيسر. يجب أن يكون نطاق النّصّ، بالنّسبة للإضافات، مطابقًا لاسم مجلّد الإضافة. يعني هذا، في مثالنا، أنّ نطاق النّصّ يجب أن يكون wp-admin-motivation. كلّ ما ياوجّب علينا فعله، من أجل تدويل الإضافة، هو تغليف سلاسل المحارف بالدّالّة ()__. $motivation = array( __( 'You are awesome', 'wp-admin-motivation'), __( 'This website is boss', 'wp-admin-motivation'), __( 'You look great today', 'wp-admin-motivation'), __( 'Your earlobes are well rounded, good job!, 'wp-admin-motivation')' ); تنفيذ التّرجمات جعلنا في الخطوة السّابقة سلاسل المحارف جاهزةً للتّرجمة، لكن لحدّ الآن لا توجد أيّ ترجمات على الموقع. يجب أن نخبر ووردبريس أين توجد ترجمات الإضافة. الطّريقة المعياريّة لذلك هي إنشاء مجلّد فرعيّ باسم lang ضمن مجلَّد الإضافة. أنشئ مجلّد lang الآن وأضف الشّفرة التّاليّة في الملفّ الرّئيس للإضافة حتى يعرف ووردبريس أين توجد التّرجمات: add_action('plugins_loaded', 'wan_load_textdomain'); function wan_load_textdomain() { load_plugin_textdomain( 'wp-admin-motivation', false, dirname( plugin_basename(__FILE__) ) . '/lang/' ); تعدّ دالة ()load_plugin_textdomain أساسيّةً هنا ويجب أن تُستدعى من دالّة مربوطة بالخطّاف plugins_loaded. أوّل معطى لدالّة ()load_plugin_textdomain هو اسم نطاق النّصّ الّذي تحدّثنا عنه سابقًا، الثّاني مهجور Deprecated، والثّالث هو مجلّّد اللّغة. ستكون أسماء ملفّات التّرجمات على صيغة plugin_name-locale.mo. حيثُ plugin_name اسم الإضافة وlocale المحلّيّة. سنرى في ما بعد كيفيّة إنشاء هذه التّرجمات. تذكّر، في الوقت الحاليّ، أنّك يجب أن تضع ملفّات التّرجمات هنا. ملحوظة: المحليّة Locale هي مجموعة من المُعطيات تحدّد لغة المستخدم، دولته، وأيّ تفضيلات خاصّة قد يودّ المستخدم رؤيتها في لغة الواجهة. سنختار ترجمة العبارات التّحفيزيّة الموجودة في الإضافة إلى اللّغة العربيّة؛ لذا سيكون المفّ باسم wp-admin-motivation-ar.mo. بالوصول إلى هذه النّقطة سيعمل كلّ شيء بالطريقة المرجوَّة، ينقُصُنا فقط إنشاء التّرجمات. إنشاء التّرجمات توجد طُرُق متعدّدة لإنشاء ترجمات إلّا أنّ النّتيجة في النّهاية متطابقة. ستحصُل على ملفّين، أحدهما بامتداد po. والآخر بامتداد mo. الأوّل يُمكن للأشخاص قراءته، ويُمكنك فتحه بأيّ محرّر نصوص والتّعديل عليه. أمّا الملفّ ذو الامتداد mo. فهو نتاج تحويل ملفّ po. إلى صيغة مقروءة بالنّسبة للآلة، ذات حجم أصغر بكثير إلّا أنّه لا يمكن للإنسان قراءتها. في ما يلي مثال على ملفّ PO غير مُترجَم. توجد في أعلى الملفّ معلومات أساسيّة عن التّرجمة، المترجِم والمشروع؛ تليها سلاسل محارف تُمكن ترجمتها متبوعة بأماكن التّرجمات المنتظَرة. msgid "" msgstr "" "Project-Id-Version: WP Admin Motivation 1.0.0\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2015-04-27 13:09+0100\n" "PO-Revision-Date: 2015-04-27 13:09+0100\n" "Last-Translator: Daniel Pataki <contact@tastique.org>\n" "Language-Team: Daniel Pataki <hello@danielpataki.com>\n" "Language: Hungarian\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "X-Poedit-KeywordsList: __;_e\n" "X-Poedit-Basepath: .\n" "X-Poedit-SearchPath-0: ..\n" #: ../wp-admin-motivation.php:20 msgid "You are awesome" msgstr "" #: ../wp-admin-motivation.php:21 msgid "This website is boss" msgstr "" #: ../wp-admin-motivation.php:22 msgid "You look great today" msgstr "" #: ../wp-admin-motivation.php:23 msgid "Your earlobes are well rounded, good job!" msgstr "" الصّيغة العامّة للأسطُر في ملفّ التّرجمة هي التّاليّة: #: مسار الملفّ الّذي توجد به السّلسلة:رقم السّطر حيثُ توجد السّلسلة msgid "السّلسة المطلوبة ترجمتها" msgstr "التّرجمة" قد تظنّ أنّ كون أماكن تواجد السّلاسل مذكورة مباشرةً بعد ذكر رقم السّطر الّذي تتواجد به يجعل من إنشاء وصيّانة ملفّات التّرجمة أمرًا شاقًّا. لهذا السّبب توجد أدوات مخصًّصة للمساعدة. تُساعد أدوات المدير Admin tools في توليد ملفّات po. للإضافات الموجودة في مستودع ووردبريس. كما يُمكن أيضًا إنشاء ملفّات po. عبر البرنامج الرّائع Poedit. نزّل Poedi وشغّله؛ انقُر على File (ملفّ) ثمّ New catalog (مسرَد جديد). أدخل المعلومات المطلوبة في النّافذة المنبثقة. لا تهتّم بطقم المحارف (Charset) وصيّغ الجمع (Plural forms)؛ سنكتفي الآن بالمعلومات الأساسيّة. 02_Poedit_Catalog_properties.thumb.png.2 انتقل إلى تبويب Sources paths (مسارات المصادر). يُخبر مربَّع Paths (المسارات) Poedit أين يجب عليه البحث عن السّلاسل القابلة للتّرجمة ذات العلاقة بالمسار القاعديّ (Base path). 03_Poedit__Sources_paths.thumb.png.396ab سنضع التّرجمات ضمن مجلَّد فرعيّ في الإضافة؛ يعني هذا أنّ لدينا خيّارين لإعداد المسارات في Poedit: ضبط المسار القاعديّ Base path على القيمة /.. (المجلَّد الأب) وإعطاء القيمة . (المجلَّد الحاليّ) لمربَّع المسارات Paths. ضبط قيمة المسار القاعديّ Base path على قيمة المجلَّد الحاليّ . وقيمة مربَّع المسارات Paths على المجلَّد الأب /... يُخبر الخيّار الأوّل Poedit أنّ الشّفرة البرمجيّة للإضافة موجودة في المجلَّد الأب لمجلَّد اللّغة lang؛ أي أنّ البرنامج سيذهب للمجلَّد الأب ويبحث في ذلك المجلَّد. أمّا الخيّار الثّاني فيقول إنّ المجلَّد الّذي يوجد به الملفّ الحاليّ هو مجلَّد اللّغة؛ وأنّ الملفّات الّتي يجب التّحقّق منها توجد في المجلَّد الأعلى، لذلك استخدمنا /.. في مربَّع المسارات Paths. سنعتمد في هذا الدّرس الخيّار الثّانيّ. الخطوة التّاليّة هي ضبط الكلمات المفتاحيّة في تبويب Sources keywords (الكلمات المفتاحيّة للمصادر). نحدّد في هذا التّبويب أسماء دوالّ التّرجمة المستخدَمة. في المثال هنا نحتاج فقط لإضافة دالّة __. في أغلب الحالات ستحتاج لإدراج دالتّيْن إلى ثلاث؛ راجع التّرجمة المتقدّمة أدناه. لم يبق إلّا الموافقة على البيانات المُدخَلة. سيطلُب منك البرنامج مكان حفظ الملفّ؛ اختر مسار المجلَّد lang إن كنت اعتمدت الخيّار الثّاني في إعداد المسارات أعلاه. سيبحث Poedit في ملفّات الإضافة ويعثُر على السّلاسل الجاهزة للتّرجمة. 04_Poedit_-_Strings_detected.thumb.png.3 يُمكنك بعدها ترجمة هذه السّلاسل إلى اللّغة الّتي تُريد. 05_Poedit_Strings_translated.thumb.png.4 احفَظ الملفّ بعد الانتهاء من التّرجمة وسيولّد Poedit ملفّ MO في مجلَّد lang. تجب إعادة تسميّة ملفّ MO (اسم الملفّ في الإعداد الافتراضيّ هو default.mo) ليوافق الصّيغة الّتي ناقشناها سابقًا؛ أي أن اسم الملفّ، في المثال لدينا، هو wp-admin-motivation-ar.mo. بالنّسبة لملفّ PO فلايهمّ اسمه كثيرًا، إلّا أنّ من الأفضل تسميّته بنفس الطّريقة لكي تعرف بسهولة أيّ ملفّ PO يوافق ملفّ MO إذا كانت توجد الكثير من الملفّات في مجلَّد اللّغات. ستظهر العبارات التّحفيزيّة باللّغة العربيّة؛ بعد وضع ملفّ اللّغة في مجلَّد اللّغات ضمن الإضافة وتفعيل اللّغة العربيّة في إعدادات ووردبريس. صيّانة التّرجمات يبدو تحديث التّرجمات صعبًا للوهلة الأولى، إلّا أنّه ليس كذلك. صحيحٌ أنّ ملفّ PO يحوي رقم السّطر الّذي توجد به السّلسلة المُترجمَة، لكن ووردبريس لا يعتمد على أرقام الأسطُر عند استخدام ملفّ PO. الهدف من استخدام الملفّ والسّكر الّذيْن توجد بهما سلسلة المحارف المُترجَمة هو مساعدة المترجِم بحيث يُمكن النّظر إلى مكان وجود العبارة ومن ثمّ ترجمتها حسب السّيّاق الّذي وردت فيه. لن تحتاج إلى ملفّات التّرجمة إن كانت التّعديلات الّتي تُجريها تقتصر على الشّفرة البرمجيّة الّتي توجد بها سلاسل المحارف الجاهزة للتّرجمة دون أن تعدّل على هذه الأخيرة. ما أفعله عادةً هو إنشاء ملفّ POT ثمّ أحدّثه في كلّ مرة أحدّث فيها الإضافة، حتى ولو لم تتغيَّر سلاسل المحارف. تُشبه ملفّات POT ملفّات PO؛ إلّا أنّها لا تحتوي على أيّ ترجمات، فكلّ ما تحتويه هو الجمل والعبارات الجاهزة للتّرجمة؛ أيّ أنّها قوالب فقط. تكون التّرجمات سهلة ما دام ملفّ القالب محدَّثًا ويحوي رقم السّطر الصّحيح لكلّ سلسلة محارف. إذا احتجت إلى تحديث ملفّ لغة فكلّ ما عليك فعله هو فتحه عن طريق Poedit ثمّ النّقر على أيقونة التّحديث Update وسيُشعرك البرنامج بالسّلاسل الجديدة والمُعدَّلة ويمكنك بعدها التّعديل عليها. قبول التّرجمات من الأمور الّتي يحدُث فيها الارتباك كثيرًا، على الأقلّ هذا ما حدث لي أولَ وهلة، هو كيفيّة إنشاء ترجمات جديدة لإضافة. كيف يُمكنني إضافة ترجماتي الخاصّة؟ كنتُ أظنّ أنّ هذه العمليّة تحدُث آليًّا، لكنّها ليست كذلك. عندما يُعجَب أحدهم بإضافة فإنّه يترجمها إلى لغته باستخدام ملفّ POT المضمَّن في الإضافة ثمّ يُرسل التّرجمة (ملفّات MO وPO) إلى مطوّر الإضافة الّذي يضعها في ملفّ lang، يُنشئ إصدارًا جديدًا ويدفعها إلى مستودع ووردبريس. عندما يتلقّى مستخدم الإضافة التّحديث تظهر الإضافة بلغة واجهة ووردبريس لديه، إن كانت ضمن اللّغات الموجوة في ملفّ lang. أستضيف كلّ مستودعاتي على Github وهو ما يسهّل على المترجمين إرسال ملفّات التّرجمة لي باستخدام طلبات السّحب Pull requests. كلّ ما عليّ فعله بعدها هو الضّغط على زرّ وإنشاء إصدار جديد من مستودع ووردبريس. التّرجمات المتقدّمة تعرّفنا في ما سبق على طريقة ترجمة سلاسل محارف قاعديّة عن طريق دالّة ()__. توجد 14 دالة ترجمة في ووردبريس يُمكن استخدامها لتدقيق ضبط ترجماتك. على الأرجح لن تحتاج إلّا إلى 3 أو 4 منها. نبدأ بالأشهر من بينها. 1- ()__ هذه هي الدّالّة الأساسيّة للتّرجمة. تأخذ سلسلة محارف وتُعيد التّرجمة إن كانت موجودة. 2- ()e_ نفس عمل الدّالّة السّابقة تقريبًا، إلّا أنّها بدلًا من إرجاع التّرجمة تعرضها مباشرةً. 3- ()n_ تتيح هذه الدّالة وسيلة أنيقة للتّعامل مع الجموع. تأخذ الدّالّة أربعة معطيات: صيغة المفرد، صيغة الجمع، العدد الّذي على أساسه ستعرض الصّيغة (صيغة المفرد أو الجمع) ونطاق النّصّ. في ما يلي مثال سريع: <?php $messages = get_message_count(); // الاستعمال المبَسَّط: لا تُظهر الدّالة العدد الفعليّ $text = _n( 'You have one message', 'You have lots of messages', $messages, 'my-message-app' ); // في طريقة الاستعمال هذه نُظهر العدد الفعليّ للرّسائل $text = sprintf( _n( 'You have one message', 'You have %s messages', $messages, 'my-message-app' ), $messages ) ?> في هذا المثال نحصُل على عدد الرّسائل ضمن متغيّر messages ثمّ نستخدم هذا المتغيّر في دالّة ()n_ الّتي تعتمد على قيمة المتغيّر لاختيّار سلسلة المحارف الّتي تعرضها (بصيغة المفرد أو الجمع). في طريقة الاستعمال المبسَّط للدّالة لا يظهر عدد الرّسائل ضمن سلسلة المحارف المعروضة حيثُ توجد عبارتان، الأولى للعرض إذا كانت قيمة messages مفردة وتُعرَض الثّانيّة في حالة الجمع. إذا أردنا عرض العدد نستخدم عبارة s% في المكان الّذي نُريد أن يُعرض فيه العدد. بالنّسبة لملفّ PO فينبغي أخذ اللّغة الّتي نريد التّرجمة إليها في الحسبان. في أغلب اللّغات الأوروبيّة لا توجد سوى صيغة واحدة للجمع: إذا كان المعدود أكبر من أو يُساوي اثنين يُعدّ جمعا، أي أنّ هناك حالتين فقط (واحدة للمفرَد والأخرى للجمع). في اللّغة العربيّة يتغيّر المعدود حسب العدد في ما مجموعه خمس صيّغ (مفرَد، مثنَّى وثلاث حالات بالنّسبة للجمع)، إضافةً للصّيغة الّتي يكون العدد فيها يُساوي صفرا (أيّ أنّ المجموع يُساوي ستة). لمن يُريد التّفصيل في المسألة فليراجع فصل العدد والمعدود في النّحو :). لأخذ هذه التّغييرات في الحسبان عند إنشاء ملفّ التّرجمة نُخبر Poedit بعدد صيّغ الجمع الموجودة لدينا، بالنّسبة للعربيّة: nplurals=6; plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 && n%100<=10 ? 3 : n%100>=11 ? 4 : 5; 06_Poedit_plural_forms.thumb.png.4b49678 قبل البدء في البحث عن سلاسل المحارف نُضيف الدّالة n_ في تبويب Sources keywords (الكلمات المفتاحيّة للمصادر) حتى يتعرّف عليها البرنامج؛ إضافةً للدّالّة __ السّابقة. 07_Poedit_keywords.thumb.png.5c9b56aa782 ملحوظة: من المهمّ جدًّا كتابة الدّالّة بالصّيغة n:1,2_ الّتي تعني أنّ المُعطى الأوّل (الرّقم 1) يعبّر عن صيغة المفرد وأنّ المعطى الثّاني لصيغة الجمع. يمكننا الآن إنشاء ملفّ اللّغة وترجمة العبارات الواردة فيه مع أخذ الجمع بالحسبان. 08_Poedit_plural_forms.thumb.png.deaf1e6 ملحوظة: أبقِ عبارة %s في التّرجمات الّتي تحتاج ذلك، أي الّتي يكون العدد فيها اثنان فما فوق. ستُبدَل هذه العبارة بالعدد الفعليّ أثناء تنفيذ البرنامج. مثلًا إذا كان العدد بين 3 و 10 (التّبويب الرّابع في الصّورة، الّذي يحمل العنوان Form 3) فيمكن أن تكون التّرجمة “توجد لديك 3 رسائل” أو “توجد لديك 8 رسائل”. القيمة (3 و 8) ستُعرف أثناء عمل الإضافة الّتي ستضعها مكان %s. 4- ()x_ تهدف هذه الدّالّة إلى الوقاية من الخلط بين الكلمات مختلفة المعنى الّتي تُكتَب بنفس الطّريقة. مثلًا إذا كنت تستخدم كلمة pair بمعنى “زوج أشخاص” وبمعنى “ربط بجهاز بلوتوث” فيُمكن أن يشتبه المعنى. لمنع الاشتباه ولمساعدة المترجم على اختيّار العبارة المناسبة في لغته استخدم دالّة ()x_. _x( 'Pair', 'A pair of people', 'my-plugin-textomaind' ); _x( 'Pair', 'As in: pairing devices', 'my-plugin-textomaind' ); 5- ()ex و ()nx يُشبه عمل هاتيْن الدّالتيْن عمل دالّة ()x_ أعلاه. الفرق هو أنّ ()ex_ تعرض النّتيجة مباشرةً في حين أنّ nx_ تُضيف إمكانيّة تحديد صيغة للجمع. تخليص Escaping التّرجمات تتيح الدّوال السّتّ التّاليّة إمكانيّة تخليص التّرجمة من أجل الاستخدام الآمن في نصوص HTML (الثّلاث الأخيرة) أو خاصيّاته attributes (الثّلاث الأولى). ()esc_attr__ ()esc_attr_e ()esc_attr_x ()esc_html__ ()esc_html_e ()esc_html_x ترجمات Noop تسجّل دوالّ Noop سلاسل المحارف بصيغة الجمع في ملفّ POT دون أن تترجمها. يعود السّبب في ذلك إلى أنّ العدد غير معروف سلفًا، وهو ما يعني أنّنا سنحتاج لدالّة أخرى للحصول على العدد وبالتّالي اختيّار صيغة المعدود (الجمع). لهذا السّبب نستخدم دالّة Noop ثمّ نترجم القيمة الحقيقيّة لاحقًا بعد الحصول على العدد. راجع المقال التّالي للمزيد. تستخدم الدّوال التّاليّة لهذا الغرض: ()n_noop_ ()nx_noop_ ()translate_nooped_plural ترجمة Javascript ربّما ننساءل ماذا عن سلاسل المحارف الموجودة ضمن شفرة Javascript؟ يقدّم ووردبريس الحلّ عبر دالّة ()wp_localize_script. تأخذ هذه الدّالّة ثلاثة معطيات: مِقبض Handle (معرّف) السّكريبت الّذي نُريد ترجمته، اسم كائن Object للاستخدام داخل السّكريبت ومصفوفة التّرجمة. في ما يلي مثال على ترجمة سلاسل محارف ضمن Javascript: add_action( 'admin_enqueue_scripts', 'motivation_assets' ); function motivation_assets($hook) { wp_enqueue_script( 'motivation-scripts', plugin_dir_url( __FILE__ ) . 'scripts' ); wp_localize_script( 'motivation-scripts', 'wma', array( 'section_title' => __( 'Today's motivation', 'wp-admin-motivation' ) )); } بعد إضافة التّرجمات يُمكنك استخدامها في ملفّ Javascript المُسجَّل. يجب عليك استخدام اسم الكائن ومفاتيح مصفوفة التّرجمة: jQuery.html( "<h2>" + wma.section_title + "</h2>" ); المصدر: منتديات رحيل لكل العرب - من قسم: قسم تطوير المواقع ومحركات البحث والسيو Seo والووردبريس WordPress
	اقتباس