ترجمة JSON في ووردبريس: ترجمة جافاسكريبت محرر الكتل

لقد قمت بترجمة إضافتك. تظهر سلاسل PHP بشكل مثالي في إعدادات المسؤول، وقوالب الواجهة الأمامية، وإشعارات البريد الإلكتروني - كلها مترجمة. ثم تفتح محرر الكتل، وتجد أن كل تسمية في كتلة Gutenberg المخصصة الخاصة بك لا تزال باللغة الإنجليزية بعناد وسخرية. زر "Add Item"، وعناوين لوحة الفحص، والنص النائب. ملف .mo الخاص بك مُحمّل. فلماذا لا تُترجم هذه السلاسل؟

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

لماذا تبقى سلاسل محرر الكتل لديك باللغة الإنجليزية

إجابة مختصرة: تستخدم PHP وجافاسكريبت نظامي تسليم ترجمة مختلفين تمامًا في ووردبريس، وملف .mo الخاص بك يغذي نظام PHP فقط.

نظاما ترجمة، إضافة واحدة

عندما يقوم ووردبريس بتشغيل load_plugin_textdomain()، فإنه يقرأ ملف .mo المترجم الخاص بك إلى ذاكرة PHP. تبحث كل استدعاءات __()، و_e()، و_x() في كود PHP الخاص بك عن ترجمتها هناك. يعمل هذا لأن PHP يعرض من جانب الخادم - بيانات .mo موجودة مباشرة في نفس العملية.

جافاسكريبت مختلفة. يعمل كود الكتلة الخاص بك في المتصفح، بعد وقت طويل من انتهاء PHP. لا يمكنه الوصول إلى ملف .mo من جانب الخادم. بدلاً من ذلك، تتوقع حزمة @wordpress/i18n - وهي مكافئ Gettext في JS، وتعرض __()، و_x()، وsprintf() لسكريبتاتك - أن يتم تسليم الترجمات كحمولة JSON مرفقة بالسكربت المحدد الذي يحتاجها.

ماذا يحدث لسلسلة JS غير المترجمة

لذا فإن كتلة تحتوي على سلاسل مثل هذه:

import { __ } from '@wordpress/i18n';

registerBlockType( 'myplugin/feature-box', {
    title: __( 'Feature Box', 'myplugin' ),
    edit: () => {
        return <Button>{ __( 'Add Item', 'myplugin' ) }</Button>;
    },
} );

لن تجد أبدًا "Feature Box" أو "Add Item" في ملف .mo الخاص بك، لأن المتصفح لا يقرأ ملفات .mo أبدًا. يجب أن تصل هذه السلاسل كملف JSON، مرتبطة بمعرف السكربت هذا بالضبط. إذا لم تقم بإعداد ذلك، فإن استدعاءات JS __() ستعيد ببساطة اللغة الإنجليزية الأصلية - بصمت، ودون أي خطأ في وحدة التحكم.

ربط ترجمات JSON باستخدام wp_set_script_translations()

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

تسجيل السكربت ومجلد ترجمته

add_action( 'init', function () {
    wp_register_script(
        'myplugin-editor',
        plugins_url( 'build/index.js', __FILE__ ),
        array( 'wp-blocks', 'wp-i18n', 'wp-element' ),
        '1.0.0'
    );

    // Tell WordPress where this script's JSON translations live
    wp_set_script_translations(
        'myplugin-editor',        // the registered script handle
        'myplugin',               // text domain
        plugin_dir_path( __FILE__ ) . 'languages'
    );
} );

عندما يقوم المحرر بتحميل myplugin-editor، يعرف ووردبريس الآن البحث في مجلد languages/ الخاص بك عن ملف JSON يطابق هذا السكربت واللغة المحلية للمستخدم الحالي. إذا وجد واحدًا، فإنه يحقن الترجمات قبل تشغيل سكربتاتك، ويتم حل استدعاءات JS __() بشكل صحيح. يجب أن يتطابق المعرف الذي تمرره تمامًا مع سكربت مسجل - فالمعرف غير المتطابق أو المفقود هو ثاني أكثر الأسباب شيوعًا لفشل الترجمات بصمت.

اسم الملف المشفر بـ MD5 الذي لا يتوقعه أحد

إليك التفصيل الذي يضلل الجميع تقريبًا. ملف JSON الذي يبحث عنه ووردبريس ليس اسمه مرتبًا مثل myplugin-fr_FR.json. يتم تسميته باستخدام تجزئة MD5 لمسار مصدر السكربت:

فك تشفير نمط اسم الملف

myplugin-fr_FR-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.json

النمط هو {textdomain}-{locale}-{md5}.json، حيث التجزئة هي MD5 للمسار النسبي لملف السكربت (على سبيل المثال build/index.js) كما هو مسجل. يقوم ووردبريس بحساب هذه التجزئة في وقت التشغيل للعثور على ملف JSON الصحيح للسكربت الصحيح. إذا قمت بتسمية ملفك يدويًا، فلن يجده ووردبريس، وسوف تقسم بأن النظام معطل بينما هو يبحث فقط عن اسم ملف مختلف.

لا تحسب التجزئة بنفسك. يقوم أمر WP-CLI i18n بذلك نيابة عنك، وهذا هو بالضبط سبب ضرورة استخدام الأدوات بدلاً من إنشاء هذه الملفات يدويًا. ومع ذلك، فإن فهم وجود التجزئة هو ما يوفر عليك ساعات عندما يكون ملف JSON موجودًا في languages/ ولكنه لا يزال يتجاهل - فغالبًا ما يكون ذلك بسبب عدم تطابق تجزئة اسم الملف بسبب تغيير مسار السكربت.

سير العمل الكامل: من make-pot إلى make-json

الخبر السار هو أنك تحتفظ بترجماتك في نفس ملفات .po التي تستخدمها بالفعل. ملف JSON هو نتاج مشتق يتم إنشاؤه في النهاية. الإجابة على سؤال "هل أحافظ على سلاسل JS بشكل منفصل" هي لا - فهي تعيش في نفس ملف .pot/.po مثل سلاسل PHP الخاصة بك، ويقوم أمر إضافي واحد بفصل سلاسل JS إلى JSON.

مسار الأوامر الأربعة

إليك مسار الأوامر الكامل:

# 1. Extract ALL translatable strings (PHP and JS) into one template
wp i18n make-pot . languages/myplugin.pot

# 2. Translate languages/myplugin-fr_FR.po as usual (Poedit, AI, etc.)

# 3. Compile the .mo for PHP strings (server-side, as always)
wp i18n make-mo languages/

# 4. Generate the MD5-hashed JSON files for JS strings
wp i18n make-json languages/ --no-purge

الخطوة الأولى make-pot ذكية بما يكفي لفحص ملفات .php وملفات مصدر .js/.jsx الخاصة بك، لذا فإن ملف .po واحد لكل لغة محلية يحتوي على كل شيء. الخطوة الرابعة make-json تقرأ كل ملف .po مترجم، وتجد الإدخالات التي جاءت من ملفات جافاسكريبت، وتكتب ملف JSON واحدًا بتجزئة صحيحة لكل سكربت. تحافظ علامة --no-purge على سلاسل JS في ملف .po الخاص بك أيضًا، حتى لا تفقدها عملية make-mo اللاحقة - فبدونها، تزيل make-json إدخالات JS من ملف .po، مما يفاجئ الأشخاص الذين يقومون بتشغيل الأوامر بترتيب خاطئ.

يبدو ملف JSON الذي تم إنشاؤه كحد ترجمة بتنسيق Jed:

{
  "translation-revision-date": "2026-06-12 10:00+0000",
  "generator": "WP-CLI/2.x",
  "domain": "messages",
  "locale_data": {
    "messages": {
      "": { "domain": "messages", "lang": "fr_FR" },
      "Feature Box": [ "Bloc fonctionnalité" ],
      "Add Item": [ "Ajouter un élément" ]
    }
  }
}

يقرأ ووردبريس locale_data ويزوده إلى @wordpress/i18n قبل تشغيل سكربتاتك. الآن __( 'Add Item', 'myplugin' ) في المتصفح يعيد Ajouter un élément، ويصبح محرر الكتل الخاص بك مترجمًا أخيرًا.

كيف يختلف هذا عن i18next JSON

يستخدم كلا النظامين JSON، وكلاهما يستهدف جافاسكريبت، وهذا التشابه السطحي يسبب ارتباكًا حقيقيًا. إنهما ليسا قابلين للتبديل. ملف JSON لمحرر الكتل في ووردبريس هو حمولة مشتقة من Gettext، مجزأة بـ MD5، لكل سكربت، ويتم استهلاكها بواسطة @wordpress/i18n. ملف i18next JSON هو ملف مفتاح-قيمة مسطح أو متداخل يتم استهلاكه بواسطة react-i18next أو next-intl، وله بناء جملة {{interpolation}} الخاص به واتفاقيات المفاتيح الجمعية.

إذا كنت تعمل في React أو Next.js العادي خارج ووردبريس، فأنت تريد نهج i18next، والذي نغطيه في translating i18next JSON in React and Next.js. داخل ووردبريس، أنت تريد سير عمل make-json المذكور أعلاه. خلطهما - على سبيل المثال، كتابة JSON على غرار i18next يدويًا وتوقع أن يقوم wp_set_script_translations() بتحميله - لن يعمل ببساطة، لأن ووردبريس يبحث عن تنسيق Jed المجزأ، وليس أزواج مفتاح-قيمة عشوائية.

مصدر واحد، كل التنسيقات التي تحتاجها

تكمن الهشاشة في كل هذا في خطوة الترجمة في المنتصف. يغذي ملف .po الخاص بك كلاً من .mo (PHP) و JSON (JavaScript)، لذا فإن ترجمة واحدة فاشلة - %s مشوهة، علامة <strong> مكسورة، صيغة جمع معاد تسميتها - تسمم كلا المخرجات في آن واحد. ولأن سلاسل JS يتم تحميلها بشكل غير متزامن في المتصفح، فإن الخطأ الهيكلي هناك غالبًا ما يظهر كتسمية فارغة أو تعطل تام بدلاً من حل احتياطي سلس.

تحميل واحد، يغطي PHP وجافاسكريبت

هنا يثبت مسار الترجمة الذي يفهم بنية Gettext قيمته. يأخذ SimplePoTranslate ملف .po أو .pot مصدريًا واحدًا وينتج مخرجات نظيفة ومترجمة في تنسيقات متعددة من تحميل واحد - .po, .mo, .json, .php, و .xliff - لذلك لا تقوم بتجميع أدوات منفصلة لطبقات PHP وجافاسكريبت لديك. يحافظ قفل بناء الجملة (Syntax Locking) الخاص به على %s, %1$s, {count}, و HTML المضمن في مكانه، وهذا مهم بشكل مضاعف لسلاسل محرر الكتل حيث يمكن أن يؤدي عنصر نائب معطل إلى تعطيل لوحة المحرر بأكملها. نتعمق أكثر في نموذج المصدر الواحد، المخرجات المتعددة في one file in, five formats out.

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

الخلاصة

سبب بقاء محرر الكتل الخاص بك باللغة الإنجليزية هو هيكلي، وليس خطأ برمجيًا: ترجمة JSON في ووردبريس هي نظام تسليم منفصل عن ملف .mo، وقد تم بناؤه خصيصًا لأن المتصفحات لا تستطيع قراءة بيانات Gettext من جانب الخادم. بمجرد أن تفهم أن سلاسل جافاسكريبت تحتاج إلى ملف JSON مجزأ بـ MD5 لكل سكربت، يتم إنشاؤه بواسطة wp i18n make-json وربطه بـ wp_set_script_translations()، يصبح الحل ميكانيكيًا. احتفظ بسلاسلك في ملف .po واحد، وقم بتجميع ملف .mo لـ PHP، وقم بتشغيل make-json لـ JS.

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

هل أنت مستعد لترجمة سلاسل JSON و PHP في ووردبريس من مصدر واحد نظيف؟ جرب SimplePoTranslate مجانًا — لا يلزم وجود بطاقة ائتمان. تقوم الطبقة المجانية بترجمة ملفات .po و .pot حقيقية مع قفل بناء الجملة (Syntax Locking) الآمن للعناصر النائبة، بحيث يتم شحن سلاسل محرر الكتل الخاصة بك بشكل صحيح.