# الترجمات

يتضمن Blockstudio ترجماته في المجلد `languages`. ويستخدمها WordPress عندما تطابق لغة الموقع أو اللغة المحددة في ملف المستخدم الشخصي إحدى هذه اللغات. وينطبق الأمر نفسه عندما يعمل Blockstudio كإضافة أو كإضافة إلزامية أو كحزمة Composer.

## اللغات المتاحة

يتضمن Blockstudio ترجمات للغات WordPress المسجلة في ملف `languages/locales.json` المضمّن معه، بما في ذلك المتغيرات الإقليمية والرسمية وغير الرسمية. الإنجليزية (`en_US`) هي اللغة المصدر ولا تحتاج إلى ملف ترجمة. تجمع القائمة اللغات التي يدعمها WordPress في GlotPress، إلى جانب المتغيرات المتاحة من WordPress ملف ترجمة نواة API.

حُوفظ على ترجمتي الألمانية (`de_DE`) والألمانية الرسمية (`de_DE_formal`). أُنشئت الترجمات الإضافية باستخدام GPT-6 Luna، ووُسِمت في ترويسات `.po` الخاصة بها بأنها مولّدة آليًا. اجتازت فحوص الاكتمال والتنسيق الآلية، لكن لم يراجعها كلها متحدثون أصليون. نرحب بالتصحيحات.

تغطي الترجمات عناصر التحكم في الحقول داخل محرر الكتل، وصفحة الإدارة، ولوحة التحرير، وطبقة أدوات المطور، ورسائل نقاط نهاية REST. أما التسميات ونصوص المساعدة في ملفات `block.json` الخاصة بكم، فهي تابعة لقالبكم أو إضافتكم وتستخدم نطاق النص الخاص بها.

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

## تجاوز ترجمة

تكون لملفات الترجمة في `wp-content/languages/plugins` الأولوية على الملفات المضمّنة، سواء لسلاسل PHP (`blockstudio-de_DE.mo` أو `blockstudio-de_DE.l10n.php`) أو للنصوص البرمجية (ملف واحد لكل معرّف نص برمجي، مثل `blockstudio-de_DE-blockstudio-blocks.json`).

## المساهمة بترجمة

كل لغة عبارة عن ملف `.po` يمكنكم تحريره بأي محرر نصوص أو بأداة ترجمة مثل Poedit. نرحب بالتصحيحات واللغات الجديدة عبر طلبات السحب.

1. لإضافة لغة، انسخوا `languages/blockstudio.pot` إلى `languages/blockstudio-<locale>.po`، مثل `blockstudio-fr_FR.po`، واضبطوا ترويسات `Language` و`Plural-Forms`. ولتحسين لغة، حرروا ملف `.po` الموجود لها.
2. ترجموا السلاسل. أبقوا العناصر النائبة مثل `%1$s` كما هي في الترجمة.
3. شغّلوا `npm run i18n`. فهو ينشئ ملفات `.mo` و`.l10n.php` و`.json` التي يحمّلها WordPress.
4. أضيفوا ملف `.po` إلى الالتزام مع الملفات المُنشأة، ثم افتحوا طلب سحب.

إذا تعذر عليكم تشغيل `npm`، فيكفي فتح طلب سحب يتضمن ملف `.po` وحده. ويمكن إضافة الملفات المُنشأة قبل الدمج.

## إنشاء الترجمات المفقودة

يمكن للمشرفين إنشاء المدخلات المفقودة باستخدام Codex CLI موثّق. هذا أمر تطوير اختياري، وليس شيئًا يشغّله WordPress:

```bash
npm run i18n:translate -- --dry-run
npm run i18n:translate
```

النموذج الافتراضي هو `gpt-6-luna`. للعمل على لغة واحدة، استخدموا `npm run i18n:translate -- --locale fr_FR`. يستخرج الأمر أحدث السلاسل المصدرية، ويملأ الترجمات المفقودة، ثم يجمّع ملفات `.mo` و`.l10n.php` وملفات `.json` الخاصة بكل نص برمجي. لا تُرسل إلى Codex سوى سلاسل الواجهة العامة وسياقها وصيغها الحالية، ولا يُرسل محتوى الموقع أو بيانات المستخدمين.

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

يحدّث `npm run i18n:locales` قائمة اللغات وقواعد الجمع صراحةً من WordPress/GlotPress. ويتحقق `npm run i18n:coverage` من اكتمال كل لغة في القائمة المُعتمدة داخل المستودع. لا تستدعي فحوص التغطية ولا التكامل المستمر المعتاد الذكاء الاصطناعي، ولا تجلب بيانات اللغات. راجعوا README في المستودع للاطلاع على خيارات تقسيم العمل والعمليات المتزامنة والاستعادة.

## السلاسل القابلة للترجمة في الكود

- PHP: استخدم الدوال WordPress مع نطاق النص `blockstudio`، على سبيل المثال `__( 'Invalid block.', 'blockstudio' )`.
- JavaScript: استورد `__` من `@/utils/__` ومرّر سلسلة نصية حرفية، على سبيل المثال `__( 'Add row' )`. لا يمكن ترجمة السلسلة التي تُنشأ أثناء التشغيل، لذا استخدم سلسلة حرفية واحدة لكل صيغة.
- يحتاج كل حزمة نصوص برمجية جديدة تحتوي على سلاسل قابلة للترجمة إلى إدخال في `scripts/i18n.ts` واستدعاء `wp_set_script_translations()` بالمُعرّف نفسه و`Translations::script_path()`.

بعد تغيير السلاسل، شغّل `npm run i18n`. فهو يحدّث `languages/blockstudio.pot` وكل ملف `.po`. تظل السلاسل الجديدة بالإنجليزية إلى أن يترجمها مترجم أو يملأها `npm run i18n:translate`. يشغّل CI كلاً من `npm run i18n:check` و`npm run i18n:coverage`، ويرفضان الملفات المترجمة المجمّعة القديمة أو مشكلات الاستخراج أو عدم اكتمال تغطية اللغات. يظل إنشاء الملفات إجراءً صريحًا يتخذه المشرف على الصيانة.