تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الأقلمة

توفّر Blockly نظامًا لترجمة النص في التطبيق، مثل التلميحات وقوائم السياقات والنص على الكتل. ويستخدم هذا النظام لترجُم النص الخاص به، ويمكنك استخدامه لترجمة نص فريد لتطبيقك.

ملاحظة: عملية التعريب هي نفسها عملية الترجمة، إلا أنّها تسمح باختلاف الترجمات حسب البلدان، مثل الترجمات المختلفة إلى البرتغالية في البرتغال والبرازيل.

آلية عمل نظام الترجمة

يتألّف نظام الترجمة من الرموز المميّزة للترجمة وجداول الترجمة والدوالّ التي تستخدِم الجداول لاستبدال الرموز المميّزة بسلاسل مترجمة.

الرموز المميزة للترجمة

الرمز المميّز للترجمة هو سلسلة قصيرة تمثّل النص الذي يجب ترجمته. على سبيل المثال، قد تستخدم التلميح في قالب تاريخ مخصّص الرمز المميّز MY_DATE_TOOLTIP. تُستخدَم الرموز المميّزة للترجمة في الرمز بدلاً من النص. في وقت التشغيل، تستبدل Blockly هذه الرموز المميزة بسلاسل مترجَمة.

جداول الأقلمة

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

enTable.MY_DATE_TOOLTIP = 'Enter a date.';

وقد يحتوي الجدول باللغة الإسبانية على ما يلي:

esTable.MY_DATE_TOOLTIP = 'Introduzca una fecha.';

تتضمّن Blockly جداول أقلمة لنصوصها. وتتوفّر في ملفّات blockly/msg/xx.js ضمن الإصدار المخصّص من Blockly، حيث يمثّل xx رمز اللغة.

عليك إنشاء جداول ترجمة لنصك. في وقت التشغيل، تحمِّل جدولَي الترجمة والشرح، أحدهما خاص بتطبيق Blockly والآخر خاص بك، للغة المحدّدة في Blockly.Msg، وهو جدول الترجمة والشرح الذي يستخدمه تطبيق Blockly داخليًا.

استخدام نظام الترجمة

قبل استخدام نظام الترجمة، عليك تحديد عدد اللغات التي تريد إتاحتها وما إذا كنت تخطّط لإتاحة المزيد من اللغات في المستقبل.

إذا كنت تريد إتاحة لغة واحدة فقط، أدخِل النص مباشرةً في الرمز. لست بحاجة إلى استخدام الرموز المخصّصة للترجمة.
- إذا كانت لغتك هي الإنجليزية (en)، ليس عليك اتّخاذ أي إجراء آخر. يتم تحميل جدول الترجمة في Blockly للغة en تلقائيًا.
- إذا لم تكن لغتك هي en، حمِّل جدول أقلمة Blockly لتلك اللغة.
إذا أردت إتاحة لغات متعددة الآن أو في المستقبل:
1. حدِّد علامات ترميز الترجمة والتعريب واستخدِمها للنص المخصّص.
2. حدِّد كيفية اختيار المستخدمين للغة.
3. حمِّل جدول الترجمة في Blockly للغة.
4. حمِّل جدول الترجمة للّغة.

تحديد الرموز المميّزة للترجمة واستخدامها

عند توفير لغات متعددة، عليك تحديد واستخدام الرموز المخصّصة للترجمة والتعريب لكل النصوص المخصّصة.

تحديد الرموز المخصّصة للترجمة

حدِّد رمزًا مميزًا لكل سلسلة تحتاج إلى الترجمة. ننصحك باستخدام بادئة مخصّصة مع الرموز المميّزة لتجنّب حدوث تعارض مع أي رموز مميّزة أضافتها أداة Blockly في المستقبل.

على سبيل المثال، إذا كان لديك قالب مخصّص واحد وفئة مخصّصة واحدة، يمكنك تحديد الرموز التالية:

MY_DATE_BLOCK_TEXT
MY_DATE_TOOLTIP
MY_DATE_HELPURL
MY_DATE_CATEGORY

تحديد جداول الترجمة

حدِّد جدولاً للترجمة لكل لغة تريد توفيرها. على سبيل المثال:

// English localization table: my_tokens_en.js
export const myEnTable = {
  MY_DATE_BLOCK_TEXT: 'Date %1',
  MY_DATE_TOOLTIP: 'Enter a date.',
  MY_DATE_HELPURL: 'https://myownpersonaldomain.com/help/en/dateblock'
  MY_DATE_CATEGORY: 'Dates',
}

// Spanish localization table: my_tokens_es.js
export const myEsTable = {
  MY_DATE_BLOCK_TEXT: 'Fecha %1',
  MY_DATE_TOOLTIP: 'Introduzca una fecha.',
  MY_DATE_HELPURL: 'https://myownpersonaldomain.com/help/es/dateblock'
  MY_DATE_CATEGORY: 'Fechas',
}

استخدام الرموز المخصّصة للترجمة في ملف JSON

لاستخدام الرموز المميّزة للترجمة في ملف JSON، استبدِل السلسلة المطلوب ترجمتها بأحد مراجع الرموز المميّزة. يكون مرجع الرمز المميّز على الشكل %{BKY_TOKEN}. على سبيل المثال:

Blockly.common.defineBlocksWithJsonArray([{
  type: 'my_date',
  message0: '%{BKY_MY_DATE_BLOCK_TEXT}',
  args0: [
    {
      type: 'field_input',
      name: 'DATE',
    }
  ],
  output: 'Date',
  colour: '%{BKY_MY_DATE_COLOUR}',
  tooltip: '%{BKY_MY_DATE_TOOLTIP}',
  helpUrl: '%{BKY_MY_DATE_HELPURL}',
  extensions: ['validate_date'],
}]);

عند معالجة ملف JSON، أي عند إنشاء مثيل للوحدة، تبحث برمجة Blockly عن الرموز المميّزة في Blockly.Msg وتستبدِلها بسلاسل مكتوبة بلغة معيّنة. إذا لم يعثر على رمز مميّز، يترك المرجع في مكانه ويُرسِل تحذيرًا.

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

إدراج رسالة JSON

تحدِّد مفاتيح message في تعريف كتلة JSON المدخلات والحقول (بما في ذلك التصنيفات) في الكتلة. يتيح استخدام مراجع الرموز المميّزة في هذه المفاتيح تكييف تعريف عنصر واحد مع المفردات وترتيب الكلمات واتجاهات لغات متعددة. على سبيل المثال، إليك رمز lists_repeat في Blockly بأربع لغات مختلفة:

مقتطف lists_repeat باللغة الإنجليزية
عنصر lists_repeat باللغة الإسبانية
عنصر lists_repeat باللغة الكورية
عنصر lists_repeat باللغة العربية من اليمين إلى اليسار

تتشارك كل هذه الكتل تعريف الكتلة نفسه، الذي يكون مفتاحه message0 هو:

message0: %{BKY_LISTS_REPEAT_TITLE},

قيمة هذا الرمز المميّز في جدول الترجمة إلى الإنجليزية هي:

Blockly.Msg['LISTS_REPEAT_TITLE'] = 'create list with item %1 repeated %2 times';

تتوافق علامات الاستبدال (%1 و%2) مع المدخلات والحقول المحدّدة للكتلة، ويتم تحويل النص بين العلامات إلى حقول تسميات بدون اسم. بما أنّ نص message0 يتم تخزينه في جداول الترجمة بدلاً من تعريف العنصر، يمكن أن يتيح تعريف عنصر واحد في ملف JSON استخدام ترتيبات مختلفة للعناصر والحقول:

// In Spanish: label, input, label, input, label
Blockly.Msg['LISTS_REPEAT_TITLE'] = "crear lista con el elemento %1 repetido %2 veces";
// In Korean: input, label, input, label, input (dummy)
Blockly.Msg['LISTS_REPEAT_TITLE'] = "%1을 %2번 넣어, 리스트 생성";

لا يمكن إجراء ذلك لتعريفات الكتل في JavaScript، حيث تتطلّب الترتيبات المختلفة للمدخلات والحقول تسلسلات مختلفة من طلبات البيانات من الدوالّ.

عند استخدام اللغات المكتوبة من اليمين إلى اليسار، اكتب سلسلة الرسالة بترتيب مرئي، ولا تُدرِج أوامر الاتجاه في Unicode:

// In Arabic. Note how %2 is left of %1, since it reads right to left.
Blockly.Msg['LISTS_REPEAT_TITLE'] = "إنشئ قائمة مع العنصر  %1 %2 مرات";

لمزيد من المعلومات عن كيفية تحويل Blockly لمفاتيح message إلى مدخلات و حقول، اطّلِع على مقالة تحديد بنية الوحدات في JSON.

استخدام الرموز المميّزة للترجمة في JavaScript

لاستخدام الرموز المميّزة للترجمة في JavaScript، استبدِل السلسلة التي سيتم تعريب محتواها بBlockly.Msg['TOKEN']. على سبيل المثال:

// Return the text for a localized context menu item.
displayText: () => Blockly.Msg['MY_CONTEXT_MENU_ITEM'];

باستثناء ما هو موضّح في الملحق، لا تُحلِّل أداة Blockly مراجع رمز العلامة في JavaScript:

// Doesn't work. Returns '%{BKY_MY_CONTEXT_MENU_ITEM}'.
displayText: () => '%{BKY_MY_CONTEXT_MENU_ITEM}';

اختيار لغة

تختلف طريقة اختيار لغة التطبيق عن طريقة اختيارها في Blockly. على سبيل المثال، قد يستخدم تطبيقك اللغة نفسها دائمًا، أو يحدّد اللغة من عنوان URL أو مَعلمات عنوان URL، أو يسمح للمستخدمين باختيار لغة من قائمة.

كقاعدة عامة، عليك اختيار لغة وتحميل جداول الترجمة المقابلة لها قبل إنشاء مساحة عمل. إذا اخترت لغة مختلفة وحمّلت جداول جديدة بعد إنشاء مساحة عمل، عليك إعادة إنشاء مساحة العمل: لا تعدّل أداة Blockly صندوق الأدوات أو الوحدات الحالية لاستخدام اللغة الجديدة تلقائيًا. للحفاظ على عمل المستخدم (إن وُجد)، احفظ الحالة قبل إعادة إنشاء مساحة العمل وإعادة تحميلها بعد ذلك.

تحميل جدول أقلمة Blockly

توفّر Blockly جداول ترجمة لكل نصوصها، مثل النص على الكتل المضمّنة. يجب تحميل جدول الترجمة في Blockly للغة التي تستخدمها، ما لم تكن تستخدم لغة en التي يتم تحميلها تلقائيًا.

يتم تخزين جداول الترجمة في Blockly في ملفات باسم blockly/msg/xx.js، حيث يكون xx هو رمز اللغة. للحصول على قائمة باللغات المتوافقة، اطّلِع على الملفات في ملف blockly/msg/json.

تحميل جدول ترجمة Blockly باستخدام npm

عند استيراد Blockly باستخدام import * as Blockly from 'blockly';، ستحصل على الوحدات التلقائية: نواة Blockly، وكتل Blockly المدمجة، ومولد JavaScript ، وجدول الترجمة في Blockly للغة الإنجليزية (en).

لتحميل جدول الترجمة في Blockly بلغة مختلفة باستخدام npm:

استيراد الوحدات التلقائية في Blockly:

import * as Blockly from 'blockly/core';
import 'blockly/blocks';
import 'blockly/javascript'; // Or the generator of your choice

استورِد جدول الترجمة في Blockly للغة التي تريدها. على سبيل المثال، لتحميل الجدول للغة الإسبانية (es):
```
import * as Es from 'blockly/msg/es';
```
حمِّل الجدول باستخدام Blockly.setLocale. تنسخ هذه الدالة الجدول إلى عنصر Blockly.Msg.
```
Blockly.setLocale(Es);
```
لا يتم تضمين setLocale إلا في إصدار npm من Blockly.

تحميل جدول ترجمة Blockly بدون npm

لتحميل جدول ترجمة Blockly بدون استخدام npm، استخدِم علامة <script> لتحميل الجدول من الدليل msg. على سبيل المثال:

<script src="../../blockly_compressed.js"></script>
<script src="../../blocks_compressed.js"></script>
<script src="../../msg/es.js"></script>

يتم تحميل جدول الترجمة تلقائيًا.

تحميل جدول الأقلمة الخاص بك

إذا حدّدت جداول الترجمة الخاصة بك، عليك تحميل الجدول للغة التي اختَرتها.

إذا كنت تستخدم npm، يمكنك إجراء ذلك باستخدام Blockly.setLocale:
```
import * as Es from 'blockly/msg/es';
import {myEsTable} from '../my_tokens_es';
Blockly.setLocale(Es);
Blockly.setLocale(myEsTable);
```
تنسخ setLocale كل زوج مفتاح/قيمة من عنصر الإدخال إلى Blockly.Msg. يمكنك استدعاؤه عدة مرات باستخدام مفاتيح مختلفة، ولكن يؤدي استدعاؤه مرة ثانية باستخدام مفتاح مكرّر إلى استبدال المفتاح الأول.
إذا كنت لا تستخدم npm، عليك نسخ جدولك إلى Blockly.Msg يدويًا. (لا يتم تضمين setLocale إلا في إصدار npm من Blockly.) وأسهل طريقة لإجراء ذلك هي تحديد نسختك الخاصة من setLocale.
```
function mySetLocale(locale) {
  Object.keys(locale).forEach(function (k) {
    Blockly.Msg[k] = locale[k];
  }
}

mySetLocale(myEsTable);
```

دوال لمعالجة مراجع الرموز المميّزة

توفّر Blockly دالتَين لحلّ مراجع الرموز المميّزة: Blockly.utils.parsing.replaceMessageReferences (تُستخدَم بشكل شائع) و Blockly.utils.parsing.tokenizeInterpolation (تُستخدَم بشكل نادر). في معظم الحالات، لست بحاجة إلى استدعاء أيّ من هاتين الدالتَين. ويعود السبب في ذلك إلى أنّ Blockly تستدعيها في الأماكن التي تتيح فيها مراجع الرموز المميّزة. على سبيل المثال، تستخدِم Blockly هذه الدوالّ لتحديد مراجع الرموز المميّزة في مفاتيح messageN وtooltip وhelpUrl في تعريف كتلة JSON.

من الأماكن التي قد تحتاج فيها إلى استخدام replaceMessageReferences هي الحقول المخصّصة. إذا كان الحقل المخصّص يقبل إشارات الرموز المميّزة في أيّ من خياراته، استخدِم replaceMessageReferences لحلّها. لمزيد من المعلومات، اطّلِع على JSON و التسجيل.

الملحق: الأماكن التي يُسمح فيها بمراجع الرموز المميّزة

يمكنك استخدام مراجع الرموز المميّزة في مفاتيح JSON التالية:

في تعريفات مجموعة أدوات الفئات:
- name
- colour
في تعريفات الكتل:
- messageN
- tooltip
- helpUrl
- colour
في الخيارات التي تم تمريرها إلى جميع الحقول:
- tooltip
في المصفوفات المُدمجة التي تم تمريرها إلى options في field_dropdown:
- العنصر الأول، عندما يكون العنصر الأول سلسلة
- قيمة alt، عندما يكون العنصر الأول عنصرًا يصف صورة
في الخيارات التي تم تمريرها إلى field_variable:
- variable
في الخيارات التي تم تمريرها إلى field_label وfield_label_serializable:
- text
في الخيارات التي تم تمريرها إلى field_image:
- height
- width
- src
- alt
في المواضيع:
- colour في أنماط الفئات
- colourPrimary وcolourSecondary وcolourTertiary في أنماط الأشكال المربّعة

وتكون قيم الوسيطات في الطرق التالية:

Block.setColour
Blockly.utils.extensions.buildTooltipForDropDown
Blockly.utils.extensions.buildTooltipWithFieldText
Blockly.utils.parsing.parseBlockColour

وفي تعريف XML لأداة في السمات التالية <category>:

name
colour

لمزيد من المعلومات عن استخدام مراجع الرموز المميّزة كقيم ألوان، اطّلِع على مراجع الألوان.

الأقلمة تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.