הוספת טוקן לוקליזציה חדש לליבת 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. מבצעים Commit לכל השינויים בקובצי 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), explain what the parameters mean.

זוהי דוגמה להערה טובה לתרגום שמסבירה את הפרמטרים ומספקת קישור למידע נוסף.

/** @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';