كيفية ترجمة إضافة ووردبريس (خطوة بخطوة)

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

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

يوضح لك هذا الدليل كيفية ترجمة إضافة ووردبريس من البداية إلى النهاية: العثور على نطاق النص ومجلد اللغة، الحصول على قالب .pot أو إنشائه، بناء ملفات .po و .mo بأسماء صحيحة، ووضعها حيث سيقوم ووردبريس بتحميلها بشكل موثوق. سنتناول أيضًا نوع واحد من الإضافات لا يمكن لهذا النهج ترجمته بالكامل، حتى لا تضيع ساعات في محاولة مستحيلة.

كيف تجد ملفات ترجمة إضافة؟

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

تحديد موقع مجلد اللغات ونطاق النص

افتح دليل الإضافة في wp-content/plugins/your-plugin/ وابحث عن مجلد فرعي /languages. بداخله، ستجد عادةً ملف .pot، وهو القالب الفارغ الذي يحتوي على كل سلسلة قابلة للترجمة.

لتأكيد نطاق النص، افتح ملف PHP الرئيسي للإضافة وانظر إلى كتلة الرأس الخاصة به:

/**
 * Plugin Name: Awesome Plugin
 * Text Domain: awesome-plugin
 * Domain Path: /languages
 */

هنا نطاق النص هو awesome-plugin. هذه القيمة حاسمة، لأن ملفات الترجمة الخاصة بك يجب أن تتضمنها في أسمائها وإلا فلن يطابقها ووردبريس بالإضافة أبدًا. ستراها أيضًا في كل استدعاء لسلسلة نصية في جميع أنحاء الكود:

echo __( 'Settings saved successfully.', 'awesome-plugin' );

هذه الوسيطة الثانية، awesome-plugin، هي نطاق النص مرة أخرى. كل سلسلة نصية تستخدمها يمكن ترجمتها بواسطة كتالوجك. إذا كانت سلسلة نصية في واجهة الإضافة تفتقر إلى هذا الغلاف، على سبيل المثال مطور قام بتشفير echo 'Save' بدون __()، فإن هذه السلسلة غير قابلة للترجمة على الإطلاق، ولا يمكن لملف .po الوصول إليها. تقوم معظم الإضافات الموثوقة بتغليف كل شيء بشكل صحيح، ولكن إذا لاحظت سلسلة أو سلسلتين عنيدتين ترفضان الترجمة، فمن المحتمل أن يكون السبب هو غياب غلاف Gettext في المصدر.

طريقة سريعة لتقييم ما إذا كانت الإضافة جاهزة للترجمة حقًا هي التحقق من قائمتها في دليل WordPress.org، والذي يعرض نسبة الترجمة وروابط إلى قالب /languages. من المرجح أن تحتوي الإضافة التي تحتوي على مشروع ترجمة نشط على سلاسل نظيفة ومغلفة بالكامل أكثر من تلك المهجورة.

ماذا لو لم تكن الإضافة تحتوي على ملف POT؟

بعض الإضافات تأتي بدون قالب .pot. إذا كان مجلد /languages فارغًا أو مفقودًا، فأنت بحاجة إلى إنشاء القالب بنفسك عن طريق مسح الكود المصدري بحثًا عن سلاسل قابلة للترجمة.

الأداة القياسية لذلك هي WP-CLI، التي تستخرج كل استدعاء Gettext إلى ملف .pot جديد.

wp i18n make-pot wp-content/plugins/awesome-plugin \
  wp-content/plugins/awesome-plugin/languages/awesome-plugin.pot

يقوم هذا الأمر بفحص ملفات PHP و JavaScript الخاصة بالإضافة، ويجد كل استدعاء __() و _e() و _n() والاستدعاءات ذات الصلة، ويكتب قالبًا كاملاً. إذا كنت تفضل طريقة رسومية، فيمكن لـ Poedit Pro مسح الكود المصدري بنفس الطريقة. في كلتا الحالتين، تكون النتيجة ملف .pot يحتوي على جميع السلاسل المصدرية بترجمات فارغة، جاهزة للتحويل إلى ملف لغة حقيقي.

لإنشاء القالب الخاص بك فائدة خفية: فهو يلتقط السلاسل التي ربما نسي المطور الأصلي تضمينها في ملف .pot المرفق. تتطور الإضافات بسرعة، وقد يكون القالب الذي جاء مع الإصدار 2.1 يفتقد سلاسل نصية أضيفت في الإصدار 2.4. إعادة الإنشاء من المصدر الحالي يضمن أن كتالوجك يعكس ما تعرضه الإضافة فعليًا اليوم، وليس ما عرضته قبل إصدارين. إذا كنت تحتفظ بترجمات لإضافة بمرور الوقت، فإن إعادة تشغيل make-pot بعد كل تحديث رئيسي هي عادة موثوقة.

إنشاء ملفات PO و MO بالاسم الصحيح

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

صيغة اسم الملف

لترجمات الإضافات، النمط هو text-domain-locale. لذا بالنسبة لنطاق النص awesome-plugin المترجم إلى الألمانية، يجب أن تكون أسماء الملفات:

awesome-plugin-de_DE.po
awesome-plugin-de_DE.mo

رمز اللغة المحلية هو رمز لغة موقع ووردبريس: de_DE للألمانية، fr_FR للفرنسية، es_ES للإسبانية، pt_BR للبرتغالية البرازيلية. إذا أخطأت في اللغة المحلية، سيتخطى ووردبريس ملفك بصمت. يمكنك إنشاء هذه الملفات من قالب .pot في محرر مثل Poedit، الذي يقوم بتجميع ملف .mo الثنائي تلقائيًا عند الحفظ. إذا كنت جديدًا على هذا المحرر، فإن دليل Poedit الكامل يوضح كيفية إنشاء ترجمة من قالب خطوة بخطوة.

أين تضع الملفات حتى لا تمحوها التحديثات

هناك موقعان محتملان، واختيار الصحيح منهما مهم.

# RISKY: inside the plugin — wiped on every plugin update
wp-content/plugins/awesome-plugin/languages/awesome-plugin-de_DE.mo

# SAFE: the global languages override folder — survives updates
wp-content/languages/plugins/awesome-plugin-de_DE.mo

استخدم دائمًا wp-content/languages/plugins/. يفحص ووردبريس هذا الدليل المتجاوز أولاً، ولأنه يقع خارج مجلد الإضافة، فإن تحديث الإضافة لا يمس ترجماتك أبدًا. يتم الكتابة فوق الملفات الموضوعة داخل مجلد الإضافة الخاص بها لحظة تثبيت إصدار جديد.

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

كيف يحمل ووردبريس ترجمتك

تخبر الإضافة الجاهزة للترجمة ووردبريس بتحميل كتالوجها عن طريق استدعاء load_plugin_textdomain() أثناء التهيئة:

add_action( 'init', function() {
    load_plugin_textdomain(
        'awesome-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

بالنسبة لمعظم الإضافات الحديثة في ووردبريس 4.6 وما بعده، لا تحتاج إلى لمس هذا. يقوم ووردبريس تلقائيًا بتحميل الترجمات من wp-content/languages/plugins/ طالما تطابق اسم ملفك ولغة الموقع المحلية. إذا لم تظهر ترجمتك النهائية بعد، فإن السبب يكون دائمًا تقريبًا عدم تطابق في اسم الملف، أو ملف .mo قديم، أو لغة موقع مضبوطة على لغة محلية خاطئة. يرشدك دليل استكشاف الأخطاء وإصلاحها لعدم ظهور ترجماتك عبر كل نقطة من نقاط الفشل هذه.

الإضافات التي تخزن السلاسل النصية في قاعدة البيانات

إليك هذا القيد المهم. يعمل نهج Gettext على ترجمة السلاسل النصية الموجودة في كود الإضافة فقط. تسمح بعض الإضافات، وخاصة منشئات النماذج، ومنشئات الصفحات، وامتدادات التجارة الإلكترونية، بإنشاء محتوى (تسميات النماذج، سمات المنتجات، الرسائل المخصصة) يتم حفظه في قاعدة بيانات ووردبريس. هذه السلاسل هي بيانات ينشئها المستخدم، وليست جزءًا من ملف .pot، لذا لا يمكن لملف .po الوصول إليها. لمحتوى قاعدة البيانات، تحتاج إلى إضافة متعددة اللغات مثل WPML أو Polylang، أو ميزة ترجمة السلاسل النصية الخاصة بالإضافة. اختبر دائمًا ما إذا كانت السلسلة النصية موجودة في الكود أو في قاعدة البيانات قبل الافتراض أن ملف .po يمكنه إصلاحها.

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

الترجمة على نطاق واسع بدون العمل اليدوي الشاق

ترجمة إضافة واحدة إلى لغة واحدة يدويًا أمر يمكن إدارته. ترجمتها إلى عشر لغات، أو ترجمة مجموعة كاملة من الإضافات لموقع عميل، يتحول إلى أيام من العمل المتكرر، وكل تعديل يدوي يخاطر بخلط عنصر نائب مثل %s أو %1$s وكسر الإخراج.

هنا حيث يغير سير العمل السحابي المعادلة. قم بتحميل ملف .po أو .pot الخاص بالإضافة إلى SimplePoTranslate، اختر لغاتك المستهدفة، وتقوم الذكاء الاصطناعي الواعي بالسياق بترجمة الكتالوج بأكمله بينما تقوم ميزة قفل التركيب بتجميد كل عنصر نائب، وعلامة HTML، ورمز الكود بحيث لا يمكن لأي شيء أن يتعطل. تتعامل المعالجة الذكية للمجموعات مع الكتالوجات الكبيرة في تمريرة واحدة، وتقوم بتنزيل ملف ZIP يحتوي على .po و .mo و .json و .php و .xliff معًا، بتنسيق صحيح وجاهز للإسقاط في wp-content/languages/plugins/. يعمل بالكامل في السحابة، لذا لا يوجد تثبيت على سطح المكتب ولا يوجد انتفاخ على موقعك.

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

استخدم المسار اليدوي عندما يكون لديك إضافة واحدة ولغة واحدة. استخدم السحابة عندما تحتاج إلى العديد من اللغات، بسرعة، دون التضحية بسلامة العناصر النائبة.

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