جعل كتل Gutenberg المخصصة قابلة للترجمة

تعرّف على كيفية تحديد كتل Gutenberg المخصصة التي طورتها والتي يجب أن تكون قابلة للترجمة. يمكنك القيام بذلك عن طريق تكوين ملف wpml-config.xml بمساعدة إضافة الاختبار Multilingual Tools.

هذا الدليل مخصص للمطورين الذين ينشئون كتلهم المخصصة لـ Gutenberg. إذا لم تكن مطوّر إضافات، فراجع كيفية ترجمة المحتوى المنشأ باستخدام محرر Gutenberg.

البدء

للبدء، ثبّت وفعّل ما يلي:

1. إضافة WPML الأساسية
2. WPML ترجمة النصوص
3. Multilingual Tools

لا ينبغي استخدام إضافة Multilingual Tools على المواقع المباشرة أو مواقع الإنتاج. استخدمها للاختبار فقط.

إنشاء واختبار كود XML لتسجيل كتل Gutenberg للترجمة

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

مرر لأسفل إلى قسم WPML: Gutenberg Blocks وانسخ كود XML المُنشأ.

2. اذهب إلى WPML → إعدادات والصق كود XML المُنشأ ضمن علامة التبويب تكوين XML مخصص.

تأكد من مراجعة الكود المُنشأ تلقائياً بعناية. قد تحتاج إلى إزالة بعض الحقول غير المخصصة للترجمة، مثل حقول التكوين ذات القيم المحددة.

انقر على حفظ عندما تكون مستعداً.

3. ارجع إلى الصفحة التي نشرتها وأجرِ تحديثات صغيرة، مثل تعديل نص زر أو عنوان.

انقر على أيقونة الزائد ضمن قسم اللغة لفتح محرر الترجمة المتقدم. تظهر الحقول من كتل Gutenberg في المحرر وتصبح متاحة للترجمة.

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

أمثلة على تسجيل كتل Gutenberg كقابلة للترجمة

ترجمة الصور

لنفترض أن لديك صورة تُعرض باستخدام الكود التالي:

<!-- wp:image {"id":3} -->
<figure class="wp-block-image"><img src="http://example.com/wp-content/uploads/2018/07/figure-2.png" alt="Image alt text" class="wp-image-3"/><figcaption>Image Caption</figcaption></figure>
<!-- /wp:image -->

أنت تريد ترجمة قيمتي السمتين figcaption وalt لهذه الصورة.

لتحقيق ذلك، تحتاج إلى إدراج الكود التالي في wpml-config.xml:

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="core/image" translate="1">
        <xpath>//figure/figcaption</xpath>
        <xpath>//figure/img/@alt</xpath>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

يُرجى وضع في الاعتبار أن السمة type هي core/image وليست wp:image نظراً لأن هذه هي القيمة التي تُرجعها واجهة برمجة التطبيقات (API) الخاصة بالكتلة.

ترجمة الروابط

يمكنك تحديد حقول كتل Gutenberg التي تمثل روابط. سيقوم WPML بعد ذلك باستبدال أي روابط بترجماتها إذا كانت متاحة.

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="core/some-block" translate="1">
        <xpath type="link">//a/@href</xpath>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

ترجمة سمات الكتلة

إليك مثالاً واحداً على تنسيق تعريف كتلة المحرر:

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
        <xpath label="My Block">//p</xpath>
        <key name="title" />
        <key name="foo">
            <key name="bar1" />
            <key name="bar2" />
        </key>
        <key name="/^[^_]\S+$/" search-method="regex" />
        <key name="something" search-method="wildcards" />
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

يمكنك استخدام العنصر key بنفس الطريقة التي يُستخدم بها مع تكوين نصوص المسؤول / wp_options. هذا يعني أيضاً أنه يمكن أن يكون لديك عناصر رئيسية (key) داخل عناصر رئيسية أصل (parent key).

يمكنك استخدام السمة label لإضافة تسميات مخصصة اختيارية تُعرض في محرر الترجمة المتقدم بجوار عناصر الكتلة. عندما تكون السمة label جزءاً من وسم gutenberg-block، فسيتم استخدامها كتسمية احتياطية لعناصر الكتلة التي لا تحتوي على تسمية محددة معرّفة لها.

<wpml-config>
    <gutenberg-blocks>
        <gutenberg-block type="my-plugin/mybutton" translate="1" label="My fallback block label">
            <xpath>//span</xpath>
            <xpath>//a@href</xpath>
        </gutenberg-block>
    </gutenberg-blocks>
</wpml-config>

يمكن أن تحتوي السمة search-method على إحدى قيمتين:

• wildcards (الافتراضي)
• regex.

يمكنك استخدام أحرف البدل (wildcards) بنفس الطريقة المستخدمة في نصوص المسؤول. هذا يعني أنه يمكن استخدام علامة النجمة (*) في السمة name. إليك مثالاً على كتلة واحدة:

<!-- wp:my-plugin/my-block
    {
        "myp": {
            "mypTitle":"The title",
            "mypContent":"The Content",
            "_mypSystem:"Meta attribute to not translate"
        }
    }
/-->

يمكنك تعيين تعريف الكتلة باستخدام حرف بدل (wildcard):

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
      <key name="myp">
          <key name="myp*" />
      </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

سيسمح لك هذا بترجمة ”The title“ و”The content“ نظراً لأن هذه هي السمات الوحيدة التي تبدأ بـ myp.

تتيح لك regex الحصول على تعبير نمطي (regular expression) في السمة name. يمكن أن يكون هذا مفيداً للغاية للتكوينات المعقدة. إليك مثالاً على كتلة واحدة:

<!-- wp:my-plugin/my-block
    {
        "data": {
            "title":"The title",
            "_title":"e980759463943209f6f1ae09a239e353",
            "content":"The Content",
            "_content":"1502a7b825dfe7b789c63830609f1701"
        }
    }
/-->

يمكنك تعيين تعريف الكتلة باستخدام تعبير نمطي:

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
        <key name="data">
            <key name="/^[^_]\S+$/" search-method="regex" />
        </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

سيسمح لك هذا بترجمة ”The title“ و”The content“ نظراً لأن هذه هي السمات الوحيدة التي لا تبدأ بشرطة سفلية (_).

تحفظ بعض إضافات الكتل البيانات في سلسلة JSON مشفرة بتنسيق URL داخل سمة الكتلة. تتيح لك السمة encoding فك تشفير السلسلة وتسجيل مفاتيحها الفرعية للترجمة.

على سبيل المثال، تخزن إضافة LazyBlocks محتوى حقل المكرر (repeater field) في سلسلة JSON مشفرة:

<!-- wp:lazyblock/testwpml {"name":"%5B%7B%22firstname%22:%22Shekhare%22,%22lastname%22:%22Bhandari%22%7D,%7B%22firstname%22:%22Compatibility%22,%22lastname%22:%22Escalation%22%7D%5D","blockId":"Z169b0O","blockUniqueClass":"lazyblock-testwpml-Z169b0O"} /-->

يمكنك تسجيل المفتاحين الفرعيين firstname وlastname باستخدام تكوين XML التالي:

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="lazyblock/team" translate="1">
      <key name="name" encoding="json">
        <key name="*">
          <key name="firstname" />
          <key name="lastname" />
        </key>
      </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

ترجمة روابط سمات الكتلة

لتمكين WPML من ترجمة عناوين URL تلقائياً، يمكنك التصريح عن سمات كتلة Gutenberg كروابط.

إليك مثالاً على كتلة Gutenberg مخصصة تحتوي على رابط قابل للنقر:

<!-- wp:foo/link {"label":"Click here!","url":"https://example.com/some-page/"} /-->

لجعل السمتين label وurl قابلتين للترجمة، أضف ما يلي إلى ملف wpml-config.xml الخاص بك:

<gutenberg-block type="foo/link" translate="1">
	<key name="label" />
	<key name="url" type="link" />
</gutenberg-block>

في هذا التكوين، يؤدي تحديد type="link" للسمة url إلى تمكين WPML من ترجمة عنوان URL تلقائياً.

مساحة اسم الكتلة (Namespace)

يمكن أن يكون لديك تكوين عام لمساحة اسم الكتلة.

لم يعد اسم الكتلة جزءاً مطلوباً من التعريف.

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

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin" translate="1">
        <key name="data">
            <key name="/^[^_]\S+$/" search-method="regex" />
        </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

تحويل المعرفات (IDs) تلقائياً في الكتل

يتميز تحويل المعرفات (ID) بالمرونة ويحاول التكيف مع معظم التنسيقات الممكنة للمعرفات (معرف واحد، قائمة معرفات، مصفوفة متسلسلة، مصفوفة مشفرة بتنسيق JSON).

تأمل الكتلة التالية:

<!-- wp:foo/form {"ids":[27,28]} -->
<div class="wp-block-foo-form-wrap">
  <form class="foo-form" action="" method="post">
    <input type="hidden" name="foo_form_post_ids" value="27,28" />
    <input type="submit" />
  </form>
</div>
<!-- /wp:foo/form -->

يمكنك التصريح عن معرفات سمة الكتلة وقيمة سمة وسم HTML التي تحمل الاسم foo_form_post_ids كمعرفات مقالات، كما هو موضح أدناه:

<gutenberg-block type="foo/form" translate="0">
  <key name="ids">
      <key name="*" type="post-ids" sub-type="post" />
  </key>
  <xpath type="post-ids" sub-type="post">//*[@name="foo_form_post_ids"]/@value</xpath>
</gutenberg-block>

سيتم تحويل الكتلة بأعلى أولوية على المرشّح render_block_data كما هو موضح أدناه:

<!-- wp:foo/form {"ids":[42,43]} -->
<div class="wp-block-foo-form-wrap">
    <form class="foo-form" action="" method="post">
        <input type="hidden" name="foo_form_post_ids" value="42,43" />
        <input type="submit" />
    </form>
</div>
<!-- /wp:foo/form -→

يمكنك استخدام سمات التكوين التالية:

• type – يمكن أن تكون post-ids أو taxonomy-ids
• sub-type (اختياري): يمكن أن تكون الكيان المحدد للسمة type إذا كان معروفاً بالفعل. على سبيل المثال، product لنوع المنشور المخصص Product. إذا لم يتم تعريفها، فسيتم تخمين الكيان المحدد.

موارد إضافية

لمعرفة المزيد حول ملف wpml-config.xml ، تفضل بزيارة دليل ملفات تكوين اللغة.

لتخصيص عناصر أخرى باستخدام ملف wpml-config.xml، تفضل بزيارة أدلتنا الإضافية:

• ترجمة الأكواد المختصرة المخصصة باستخدام WPML
• تسجيل محتوى أداة بناء الصفحات للترجمة
• تسجيل ودجات أداة بناء الصفحات المخصصة للترجمة
• تعيين خيارات الترجمة للحقول المخصصة باستخدام ملف تكوين WPML
• تسجيل المصطلحات والأنواع والتصنيفات المخصصة كقابلة للترجمة
• ترجمة النصوص التي يحفظها القالب والإضافات في wp_options
• تخصيص مبدل لغة WPML باستخدام ملف تكوين WPML