# WPML

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

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

WPML يقرأ الإعداد من ملف باسم `wpml-config.xml` في المجلد الجذر للقالب النشط ولكل إضافة نشطة. أما الإضافة الإلزامية التي تتكون من ملف واحد، فيحمل مجلدها اسم الملف من دون `.php`. راجع [ملفات إعداد اللغة](https://wpml.org/documentation/support/language-configuration-files/) و[جعل كتل Gutenberg قابلة للترجمة](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/).

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

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

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

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

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

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

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

```json title="block.json"
{
  "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" }
        ]
      }
    ]
  }
}
```

تصبح:

```xml title="wpml-config.xml"
<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 قابلة للترجمة](https://wpml.org/documentation/support/language-configuration-files/make-custom-gutenberg-blocks-translatable/). إذا لم تتوفر ترجمة للمرفق، يحتفظ WPML بالمعرّف الأصلي.

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

يقرأ الأمر الكتل المسجلة بعد توسيع حقول `custom/` وحقول الكتل، وتطبيق التجاوزات ومرشحات السمات. تُضمّن الحقول التي تضيفها [الإضافات](https://blockstudio.dev/ar/docs/extensions/) إلى كتلة Blockstudio. ولا تُضمّن الحقول التي تضيفها الإضافات إلى الكتل الأساسية أو كتل الإضافات الأخرى، لأن تلك الكتل تحصل على إعدادها من WPML أو من إضافتها الخاصة.

| الحقل | التعريف |
| --- | --- |
| `text`، `textarea`، `richtext`، `wysiwyg` | نص قابل للترجمة. |
| `link` | `title` كنص و`url` مع `type="link"`، بحيث يستبدل WPML الرابط بترجمته عند توفرها. |
| `files` | معرّف المرفق المحفوظ مع `type="post-ids"` و`sub-type="attachment"`. مع `multiple`، مستوى باسم `*` للقائمة، وهو يطابق أيضًا المعرّف المفرد الذي يحفظه الحقل عند اختيار ملف واحد. |
| `repeater` | مستوى باسم `*` يطابق كل صف، مع تعريفات حقول الصف. تعمل المكررات المتداخلة بالطريقة نفسها. |
| `group` مع `id` | حقول المجموعة، مع معرّف المجموعة كبادئة للمفتاح (`cta_text` للحقل `text` في المجموعة `cta`). |
| `group` من دون `id`، `tabs` | الحقول من دون مستوى خاص بها. |
| نوع حقل مخصص مسجل مع ضبط `translate` على `true` | نص قابل للترجمة، مثل حقل `text`. |
| كل نوع مضمّن آخر | غير معرّف. ينسخ WPML القيمة من دون تغيير. |

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

غير معرّف:

- الحقول التي لها `hidden`، لأن المحررين لا يكتبون قيمها.
- الحقول التي لها `"translate": false`، راجع أدناه.
- حقول [أنواع الحقول المخصصة](https://blockstudio.dev/ar/docs/blocks/attributes/custom-field-types/) غير المسجلة مع ضبط `translate` على `true`. يطبع الأمر تحذيرًا لكل منها، لأن نوع الحقل وحده يعرف ما إذا كانت قيمته تحتوي على نص. كما يؤدي تحديد `"translate": false` صراحةً في الحقل إلى إخفاء هذا التحذير عنه. راجع أدناه.
- السمات التي تعرّفها الكتلة في `attributes` الأصلي بدلًا من تعريفها كحقول Blockstudio.
- مفاتيح التخزين التي تختلف أنواع حقولها، راجع أدناه.

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

### استثناء حقل

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

```json title="block.json"
{
  "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`:

```php title="functions.php"
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` لمفتاحي حقل رابط.

```php title="functions.php"
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` في امتداد، تكون القيمة المخزنة نصاً أو خياراً من قائمة، بحسب عنصر التحكم الذي كتبها. لا يعلن الأمر المفتاح ويطبع تحذيراً:

```bash
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 -->` فقط، لذلك تبقى الأقسام الأخرى ومدخلات المكوّنات الأخرى كما هي:

```xml title="wpml-config.xml"
<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 النصوص المترجمة إلى المرفق باللغة المستهدفة، وينشئ ذلك المرفق إن لم يكن موجوداً. راجع [كيفية ترجمة الوسائط](https://wpml.org/documentation/translating-your-contents/media/).
يعثر WPML على الصور في وسوم `<img>` ضمن المحتوى، وفي المعارض والصورة البارزة والمكوّنات التي يتعرّف إليها. يخزّن مكوّن Blockstudio معرّفات المرفقات في تعليق المكوّن، لذا لا يعثر WPML على أي منها.

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

- حقول `files`، بما فيها المخفية، وحقول `attributes` مع `media`، وهي الحقول نفسها التي يحمّلها محرر المكوّنات كوسائط.
- الحقول في المجموعات وعلامات التبويب وصفوف المكررات والمكوّنات الداخلية.
- حقول [الامتدادات](https://blockstudio.dev/ar/docs/extensions/)، بما فيها تلك الخاصة بالمكوّنات الأساسية ومكوّنات الإضافات الأخرى، لأن قيمها مخزّنة في سمات المكوّن الموسّع.

تُستثنى القيم التي ليست معرّفات مرفقات. لا يلزم إعداد أي شيء، ولا يشارك `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:

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