إضافة رمز مميّز جديد للترجمة إلى حزمة Blockly الأساسية

إذا أضفت ميزة إلى حزمة Blockly الأساسية تتطلّب سلاسل جديدة مرئية للمستخدمين، عليك إضافة هذه السلاسل إلى Blockly.Msg حتى يتمكّن Translatewiki من ترجمتها. (للحصول على معلومات حول إضافة رموز مميّزة خاصة بالأقلمة لتطبيقك، راجِع الأقلمة).

1. أضِف السلسلة الجديدة مع اسم ووصف مناسبَين إلى ملف msg/messages.js.
2. نفِّذ الأمر npm run messages لإضافة الترجمة تلقائيًا إلى الملفَين msg/json/qqq.json وmsg/json/en.js. قد تتغير هذه الخطوة أيضًا msg/json/constants.js أو msg/json/synonyms.js في بعض الحالات.
3. تحقَّق من صحة الملفات التي تم إنشاؤها تلقائيًا. يُرجى العِلم أنّ النص البرمجي قد يزيل القسم @metadata في بداية qqq.json. في حال حدوث ذلك، عليك التراجع عن هذا التغيير بعناية حتى تتم إضافة السلسلة الجديدة بدون إزالة @metadata.
4. في رمز الميزة، أشِر إلى السلسلة الجديدة باستخدام Blockly.Msg['MY_NEW_MESSAGE'].
5. نفِّذ جميع التغييرات على ملفات msg إلى جانب رمز الميزة.

على سبيل المثال، إذا أضفت هذا الرمز إلى msg/messages.js:

/** @type {string} */
/// This is a hint to translators about the context for the message.
Blockly.Msg.MY_NEW_MESSAGE = 'This is a string that users will see!';

بعد ذلك، شغِّل npm run messages، وستظهر لك التغييرات التالية في msg/en.json:

// ...
    "MY_NEW_MESSAGE": "This is a message that users will see!",
// ...

وفي msg/qqq.json:

// ...
    "MY_NEW_MESSAGE": "This is a hint to translators about the context for the message.",
// ...

يمكنك بعد ذلك الإشارة إلى هذه السلسلة في الرمز باستخدام Blockly.Msg['MY_NEW_MESSAGE'].

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

يظهر التعليق الذي يتضمّن ثلاثة خطوط مائلة في msg/messages.js لمستخدمي TranslateWiki كمعلومات تكميلية عند الترجمة. قدِّم سياقًا حول المكان الذي ستظهر فيه الرسالة للمستخدمين. إذا كانت الرسالة تتضمّن مَعلمات (مثل %1)، اشرح معنى المَعلمات.

في ما يلي مثال على تلميح ترجمة جيد يشرح المَعلمات ويوفّر رابطًا للحصول على مزيد من المعلومات.

/** @type {string} */
/// block text - Repeatedly counts a variable (%1)
/// starting with a (usually lower) number in a range (%2),
/// ending with a (usually higher) number in a range (%3), and counting the
/// iterations by a number of steps (%4).  As in
/// [https://github.com/google/blockly/wiki/Loops#count-with
/// https://github.com/google/blockly/wiki/Loops#count-with].
Blockly.Msg.CONTROLS_FOR_TITLE = 'count with %1 from %2 to %3 by %4';

أنواع السياق

تستخدم العديد من التلميحات بادئة لشرح سياق الرسالة. تشمل البادئات الشائعة ما يلي:

• نص محظور
• نص الزر
• قائمة السياقات
• قائمة منسدلة
• الرياضيات
• إشعار منبثق
• تلميح

إذا ظهرت رسالتك في أحد هذه السياقات، استخدِم البادئة المناسبة.

المرادفات

في بعض الأحيان، يجب تغيير مفتاح الرسالة، ولكن لا يجب تغيير الترجمات. في هذه الحالة، يمكنك ضبط الرسالة القديمة كمرادف للرسالة الجديدة، كما يلي:

/** @type {string} */
Blockly.Msg.CONTROLS_FOR_INPUT_DO = Blockly.Msg.CONTROLS_REPEAT_INPUT_DO;

الرسائل الاختيارية

من غير المحتمل أن تحتاج بعض سلاسل الرسائل إلى ترجمة إلا في ظروف معيّنة، مثل الأسماء الصحيحة أو الرموز. في Blockly، غالبًا ما يتم وضع علامة "اختياري" على عناوين URL الخاصة بالمساعدة.

لا يتم إدراج اللغات في مستودع Blockly إلا إذا كانت مكتملة بنسبة %25 على الأقل. وبالتالي، سيساعد تصنيف الرسائل التي من غير المحتمل أن تحتاج إلى ترجمة على أنّها اختيارية في استيفاء هذه اللغات للحد الأدنى بدون الحاجة إلى إكمال الترجمات الاختيارية.

/** @type {string} */
/// {{Optional}} math - The symbol for the binary operation addition.
Blockly.Msg.MATH_ADDITION_SYMBOL = '+';

العناصر التي لا يمكن ترجمتها

يتم وضع علامة {{notranslate}} على الألوان المستخدَمة لفئات الحظر التلقائية. ولا يُفترض أن يتم تعريب هذه الألوان، ولكنها مضمّنة في نظام التعريب ليتمكّن المطوّرون من تغيير ألوان الحظر في الفئات التلقائية بسهولة. في حال إضافة فئات حظر جديدة، استخدِم التوجيه {{notranslate}}. إذا أضفت نوعًا مختلفًا من الرسائل التي تعتقد أنّه يجب عدم ترجمتها مطلقًا، فكِّر مليًا ما إذا كان نظام الترجمة هو المكان المناسب للسلسلة.

/** @type {string} */
/// {{Notranslate}} Hue value for all logic blocks.
Blockly.Msg.LOGIC_HUE = '210';