WPML

لا يترجم WPML سمات الكتلة المخصصة إلا بالقدر الذي يحدده ملف إعداد اللغة. يخزّن Blockstudio كل قيمة حقل في تعليق الكتلة ضمن blockstudio.attributes، لذا تحتاج كل كتلة إلى إدخال يوجّه WPML إلى حقولها النصية ومعرّفات المرفقات. ويكتب الأمر wp bs wpml config هذه الإدخالات لكل كتلة مسجّلة.

لماذا تحتاج الكتل إلى إعداد

WPML يقرأ الإعداد من ملف باسم wpml-config.xml في المجلد الجذر للقالب النشط ولكل إضافة نشطة. أما الإضافة الإلزامية التي تتكون من ملف واحد، فيحمل مجلدها اسم الملف من دون .php. راجع ملفات إعداد اللغة وجعل كتل Gutenberg قابلة للترجمة.

تُترك الكتلة التي لا يتوفر لها إدخال إلى آلية الكشف التلقائي عن السلاسل في WPML، التي تتيح ترجمة كل سمة نصية في الكتلة. وهذا يشمل كتلة Blockstudio التي تحتوي على قيم select ومراجع ملفات وعناوين URL وفئات CSS. يرى المترجمون هذه القيم التقنية بجوار النص الفعلي، وقد تؤدي ترجمة قيمة select أو فئة إلى تعطيل الكتلة.

إنشاء الإعداد

اطبع الإعداد واحفظه في المجلد الجذر للقالب أو الإضافة التي تتضمن الكتل:

wp bs wpml config > wp-content/themes/my-theme/wpml-config.xml

أو اترك الأمر يكتب الملف:

wp bs wpml config --file=wp-content/themes/my-theme/wpml-config.xml

كتلة تحتوي على حقل نص وصورة ورابط ومكرر:

{
  "name": "my-theme/cards",
  "title": "Cards",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "id": "gallery", "type": "files", "label": "Gallery", "multiple": true },
      {
        "id": "style",
        "type": "select",
        "label": "Style",
        "options": [
          { "value": "light", "label": "Light" },
          { "value": "dark", "label": "Dark" }
        ]
      },
      {
        "id": "cards",
        "type": "repeater",
        "label": "Cards",
        "attributes": [
          { "id": "title", "type": "text", "label": "Title" },
          { "id": "image", "type": "files", "label": "Image" },
          { "id": "link", "type": "link", "label": "Button" }
        ]
      }
    ]
  }
}

تصبح:

<wpml-config>
	<gutenberg-blocks>
		<!-- blockstudio:start -->
		<!-- Generated by wp bs wpml config. Run it again after changing block fields; edits between the markers are replaced. -->
		<gutenberg-block type="my-theme/cards" translate="1" label="Cards">
			<key name="blockstudio">
				<key name="attributes">
					<key name="heading" label="Heading" />
					<key name="gallery">
						<key name="*" type="post-ids" sub-type="attachment" />
					</key>
					<key name="cards">
						<key name="*">
							<key name="title" label="Cards: Title" />
							<key name="image" type="post-ids" sub-type="attachment" />
							<key name="link">
								<key name="title" label="Cards: Button: Link text" />
								<key name="url" type="link" label="Cards: Button: URL" />
							</key>
						</key>
					</key>
				</key>
			</key>
		</gutenberg-block>
		<!-- blockstudio:end -->
	</gutenberg-blocks>
</wpml-config>

لم تُعرّف القيمة style، لذا ينسخها WPML إلى الترجمة من دون تغيير. كما تُنسخ المعرّفات gallery وimage، ويستبدل WPML كلًّا منها بالمرفق الموافق للغة الصفحة عند عرض الكتلة، ما يتيح للصورة المترجمة استخدام نص بديل خاص بها. راجع «تحويل المعرّفات تلقائيًا في الكتل» ضمن جعل كتل Gutenberg قابلة للترجمة. إذا لم تتوفر ترجمة للمرفق، يحتفظ WPML بالمعرّف الأصلي.

ما الذي يُعرّف

يقرأ الأمر الكتل المسجلة بعد توسيع حقول custom/ وحقول الكتل، وتطبيق التجاوزات ومرشحات السمات. تُضمّن الحقول التي تضيفها الإضافات إلى كتلة Blockstudio. ولا تُضمّن الحقول التي تضيفها الإضافات إلى الكتل الأساسية أو كتل الإضافات الأخرى، لأن تلك الكتل تحصل على إعدادها من WPML أو من إضافتها الخاصة.

تحصل الكتلة التي لا تحتوي على حقل نص معرّف على translate="0". ثم ينسخ WPML كل قيمها ولا يتيح ترجمة أي منها. وتظل حقولها files معرّفة داخل الإدخال، لأن WPML يحوّل معرّفات المرفقات مهما كانت قيمة translate. وتُترجم الكتل الداخلية كالمعتاد.

غير معرّف:

• الحقول التي لها hidden، لأن المحررين لا يكتبون قيمها.
• الحقول التي لها "translate": false، راجع أدناه.
• حقول أنواع الحقول المخصصة غير المسجلة مع ضبط translate على true. يطبع الأمر تحذيرًا لكل منها، لأن نوع الحقل وحده يعرف ما إذا كانت قيمته تحتوي على نص. كما يؤدي تحديد "translate": false صراحةً في الحقل إلى إخفاء هذا التحذير عنه. راجع أدناه.
• السمات التي تعرّفها الكتلة في attributes الأصلي بدلًا من تعريفها كحقول Blockstudio.
• مفاتيح التخزين التي تختلف أنواع حقولها، راجع أدناه.

يُعرّف كل حقل نصي، بما في ذلك الحقل الذي يحتوي على قيمة تقنية مثل فئة CSS، ما لم يضبط "translate": false.

استثناء حقل

قد يحتوي الحقل النصي على قيمة يجب أن تكون واحدة في جميع اللغات، مثل اسم حساب أو عنوان بريد إلكتروني أو مرساة أو فئة CSS. يتيحها WPML للترجمة مثل أي نص آخر، وقد تؤدي ترجمتها إلى تعطيل الكتلة. اضبط translate على false لاستثناء الحقل من الإعداد، كي ينسخ WPML قيمته إلى الترجمة من دون تغيير:

{
  "id": "account",
  "type": "text",
  "label": "Account handle",
  "translate": false
}

في group أو tabs أو repeater، ينطبق "translate": false على كل حقل داخلي، بما في ذلك الحاويات المتداخلة. ولا يمكن لعنصر فرعي تجاوز إعداد استثناء الحاوية باستخدام "translate": true. وفي حقل files، يستثني false معرّفات المرفقات أيضًا، فتحافظ الترجمة على المرفقات الأصلية.

يؤدي حذف translate أو ضبطه على true إلى الحفاظ على السلوك الحالي: يقرر نوع الحقل. وهذا لا يجعل الحقول المخفية أو أنواع القيم مثل select قابلة للترجمة. ينطبق الخيار على حقول الكتل والإضافات، ولا يخفي عناصر التحكم في المحرر أو يعطلها، ولا يغيّر القيم المحفوظة. شغّل wp bs wpml config مجددًا بعد تغيير الإعداد، وحدّث wpml-config.xml باستخدام الإعداد الذي تم إنشاؤه.

قيمة label لكل مفتاح هي تسمية الحقل، وتسبقها تسميات المكررات والمجموعات الحاوية التي لها معرّف. يعرضها WPML كاسم الحقل في محرر الترجمة. يضيف المفتاحان لحقل link الرمزين Link text وURL إلى التسمية. وتُترجم هذه اللواحق إلى لغة الموقع، لذا شغّل الأمر باستخدام اللغة المحلية التي يعمل بها المترجمون.

أنواع الحقول المخصصة

يحدد نوع الحقل الذي يخزن سلسلة نصية عادية ذلك عند تسجيله. اضبط translate على true في التعريف، وهذا يتطلب أن يكون attribute هو string:

bs_register_field_type('acme/headline', [
  'attribute' => 'string',
  'translate' => true,
]);

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

تغيير التسميات

تُكتب تسميات الحقول لمحرر المكوّنات، وقد تتضمن تلميحات مثل “Image (optional)” لا معنى لها في محرر الترجمة. ويتلقى المرشح blockstudio/wpml/config/label كل تسمية قبل كتابتها، مع سياق المفتاح:

• block: اسم المكوّن.
• path: مسار تخزين الحقل أسفل blockstudio.attributes، مع المستوى * لصفوف كل مكرّر، مثل cards/*/link.
• field: تعريف الحقل.
• parents: تسميات المكررات والمجموعات الحاوية التي لها معرّف.
• part: text لحقل نصي، أو title أو url لمفتاحي حقل رابط.

add_filter('blockstudio/wpml/config/label', function ($label, $context) {
  return str_replace(' (optional)', '', $label);
}, 10, 2);

أعِد سلسلة فارغة لاستثناء تسمية المفتاح، وبذلك يعرض WPML تسمية المكوّن بدلاً منها. وتُبقي القيمة المُعادة التي ليست سلسلة التسمية الأصلية. أعد تشغيل الأمر بعد تغيير المرشح.

الحقول ذات مفتاح التخزين نفسه

قد ينتهي الأمر بحقلين إلى مفتاح التخزين نفسه، مثل حقل في مكوّن وحقل امتداد لهما id نفسه، أو الحقل text في مجموعة معرّفها cta وحقل معرّفه cta_text. لا يعلن الأمر هذا المفتاح إلا عندما يكون واضحاً ما يُخزّن فيه:

• ضمن حقول المكوّن وخارج صفوف المكرّر، يسجّل Blockstudio سمة واحدة لكل مفتاح تخزين، ولذلك يحل الحقل اللاحق محل السابق، مهما كان نوعه. وينطبق الأمر نفسه على حقول امتدادات المكوّن: يحل حقل لاحق، أو حقل امتداد مسجّل لاحقاً، محل حقل سابق.
• يظل كل من حقل المكوّن وحقل الامتداد ذوي المفتاح نفسه نافذاً. ويتلقى قالب المكوّن القيمة وفق تعريف حقل المكوّن لها، بينما يُطبّق الامتداد باستخدام حقله الخاص. يُعلن المفتاح مرة واحدة عندما يحتاج الحقلان إلى الإعلان نفسه: إذا كان كلاهما حقلي نص (text أو textarea أو richtext أو wysiwyg)، أو رابطين، أو حقلين من نوع files (مع multiple في أي منهما، فيكون مستوى المفتاح *)، أو لم يكن أي منهما معلناً، مثل select وnumber. وتُقارن حقول المكررين اثنين باثنين في صفوفها. وتُؤخذ التسمية من حقل المكوّن.
• يظل الحقلان اللذان لهما id نفسه في صفوف مكرّر واحد نافذين أيضاً، ويُقارن بينهما بالطريقة نفسها.

عندما يختلف النوعان، مثل حقل text في المكوّن وحقل select في امتداد، تكون القيمة المخزنة نصاً أو خياراً من قائمة، بحسب عنصر التحكم الذي كتبها. لا يعلن الأمر المفتاح ويطبع تحذيراً:

Warning: Not declared, the fields that store this key have different types: my-theme/cards: tone (text in the block, select in an extension)

أعِد تسمية أحد الحقلين، أو اجعل نوعيهما متماثلين، حتى يُعلَن المفتاح.

إبقاء الإعدادات محدّثة

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

باستخدام --file، ينشئ الأمر ملفاً مفقوداً. وفي ملف موجود، يستبدل النص الواقع بين <!-- blockstudio:start --> و<!-- blockstudio:end --> فقط، لذلك تبقى الأقسام الأخرى ومدخلات المكوّنات الأخرى كما هي:

<wpml-config>
	<custom-types>
		<custom-type translate="1">book</custom-type>
	</custom-types>
	<gutenberg-blocks>
		<gutenberg-block type="my-plugin/map" translate="1">
			<key name="caption" />
		</gutenberg-block>
		<!-- blockstudio:start -->
		<!-- blockstudio:end -->
	</gutenberg-blocks>
</wpml-config>

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

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

نصوص الصور في مهام الترجمة

يضيف WPML نصوص الصور التي تستخدمها الصفحة إلى مهمة ترجمة الصفحة: العنوان والنص البديل والتسمية التوضيحية والوصف. وعند اكتمال المهمة، يكتب WPML النصوص المترجمة إلى المرفق باللغة المستهدفة، وينشئ ذلك المرفق إن لم يكن موجوداً. راجع كيفية ترجمة الوسائط. يعثر WPML على الصور في وسوم <img> ضمن المحتوى، وفي المعارض والصورة البارزة والمكوّنات التي يتعرّف إليها. يخزّن مكوّن Blockstudio معرّفات المرفقات في تعليق المكوّن، لذا لا يعثر WPML على أي منها.

عندما يكون WPML مفعّلاً، يضيف Blockstudio المرفقات التي تخزّنها حقوله في مكوّنات الصفحة إلى الصور التي عثر عليها WPML:

• حقول files، بما فيها المخفية، وحقول attributes مع media، وهي الحقول نفسها التي يحمّلها محرر المكوّنات كوسائط.
• الحقول في المجموعات وعلامات التبويب وصفوف المكررات والمكوّنات الداخلية.
• حقول الامتدادات، بما فيها تلك الخاصة بالمكوّنات الأساسية ومكوّنات الإضافات الأخرى، لأن قيمها مخزّنة في سمات المكوّن الموسّع.

تُستثنى القيم التي ليست معرّفات مرفقات. لا يلزم إعداد أي شيء، ولا يشارك wpml-config.xml في ذلك. ومن دون WPML، لا يُفحَص أي شيء بحثاً عن مهام الترجمة، ولا يُحمّل صنف تكامل الوسائط.

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

لا تُدرج النصوص في المهمة إلا عند تفعيل أحد خياري نصوص الصور ضمن WPML > Settings > Media Translation: “Automatically detect best options for translating image texts” أو “Translate Media Library texts when translating content”، كما هو الحال مع الصور في المكوّنات الأساسية.

تعرض Blockstudio الصور عبر المرشح wpml_ids_of_media_used_in_post، الذي WPML يُطبَّق على وسائط المنشور في PostWithMediaFiles. لاستبعاد صورة من المهام، أزِل معرّفها في دالة رد نداء على المرشح نفسه بأولوية أعلى من 10:

add_filter(
	'wpml_ids_of_media_used_in_post',
	function ( $ids ) {
		return array_values( array_diff( $ids, array( 42 ) ) );
	},
	20
);