התאמה לשוק המקומי

ב-Blockly יש מערכת ללוקליזציה של הטקסט באפליקציה, כמו תוויות עזר, תפריטי הקשר והטקסט בבלוקסים. המערכת הזו משמשת אותו לצורך לוקליזציה של הטקסט שלו, ואתם יכולים להשתמש בה כדי ללוקליזציה של טקסט ייחודי לאפליקציה שלכם.

הערה: תהליך הלוקליזציה זהה לתהליך התרגום, אלא שהוא מאפשר ליצור תרגומים שונים למדינות שונות. לדוגמה, תרגומים שונים לפורטוגזית בפורטוגל ובברזיל.

איך פועלת מערכת הלוקליזציה

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

טוקנים של התאמה לשוק המקומי

אסימון לוקליזציה הוא מחרוזת קצרה שמייצגת טקסט שצריך לבצע לו לוקליזציה. לדוגמה, תיאור קצר בבלוק תאריכים בהתאמה אישית עשוי להשתמש באסימון MY_DATE_TOOLTIP. אסימוני לוקליזציה משמשים בקוד במקום בטקסט. בזמן הריצה, Blockly מחליף את האסימונים האלה במחרוזות מותאמות לשוק המקומי.

טבלאות של התאמה לשוק המקומי

טבלת לוקליזציה, שנקראת גם טבלת מחרוזות או טבלת הודעות, היא אובייקט שממפה אסימוני לוקליזציה למחרוזות מותאמות לשוק המקומי. צריך טבלה נפרדת לכל אזור גיאוגרפי. לדוגמה, אם רוצים לתמוך באנגלית ובספרדית, הטבלה באנגלית עשויה להכיל:

enTable.MY_DATE_TOOLTIP = 'Enter a date.';

והטבלה בספרדית עשויה להכיל:

esTable.MY_DATE_TOOLTIP = 'Introduzca una fecha.';

Blockly כולל טבלאות לוקליזציה לטקסט שלו. הם זמינים בהפצה של Blockly כקבצים בשם blockly/msg/xx.js, כאשר xx הוא קוד ה-locale.

צריך ליצור טבלאות של לוקליזציה לטקסט שלכם. בזמן הריצה, טוענים את טבלאות התרגום – של Blockly ושלכם – לשפה ולאזור שנבחרו לטבלה Blockly.Msg, שהיא טבלת התרגום שבה Blockly משתמש באופן פנימי.

שימוש במערכת הלוקליזציה

לפני שמשתמשים במערכת הלוקליזציה, צריך להחליט כמה אזורים גיאוגרפיים רוצים לתמוך בהם, ואם מתכננים לתמוך באזורים גיאוגרפיים נוספים בעתיד.

הגדרה של אסימוני לוקליזציה ושימוש בהם

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

הגדרת אסימונים של התאמה לשוק המקומי

מגדירים אסימון לכל מחרוזת שצריך לבצע לה לוקליזציה. מומלץ להשתמש בתחילית בהתאמה אישית עם האסימונים כדי למנוע התנגשויות עם אסימונים ש-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 יש טבלאות של תרגום לשפות שונות לכל הטקסטים שלו, כמו הטקסט בבלוקים המובנים. אלא אם אתם משתמשים בלוקאל en, שנטען כברירת מחדל, צריך לטעון את טבלת הלוקליזציה של Blockly ללוקאל שלכם.

טבלאות הלוקליזציה של Blockly נשמרות בקבצים בשם blockly/msg/xx.js, כאשר xx הוא קוד השפה והאזור. רשימת המיקומים הנתמכים מופיעה בקבצים שבספרייה blockly/msg/json.

טעינת טבלת לוקליזציה של Blockly באמצעות npm

כשמייבאים את Blockly באמצעות import * as Blockly from 'blockly';, מקבלים את המודולים שמוגדרים כברירת מחדל: הליבה של Blockly, בלוקים מובנים של Blockly, הגנרטור של JavaScript וטבלת הלוקליזציה של Blockly לאזור הגיאוגרפי 'אנגלית (en)'.

כדי לטעון את טבלת הלוקליזציה של Blockly לאזור אחר באמצעות npm:

  1. מייבאים את מודולי ברירת המחדל של Blockly:

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

  2. מייבאים את טבלת הלוקליזציה של Blockly עבור האזור הגיאוגרפי שלכם. לדוגמה, כדי לייבא את הטבלה של הלקוח המקומי בספרדית (es):

    import * as Es from 'blockly/msg/es';

  3. טוענים את הטבלה באמצעות 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 ורישום.

  • שפות שכתוב בהן מימין לשמאל: הדגמה של RTL
  • לעזור בהתאמה של הטקסט של Blockly לשוק המקומי: בקטע תרגום בקטע 'הוספת תוכן ל-Blockly'.

נספח: איפה מותר להשתמש בהפניות לטוקנים

אפשר להשתמש בהפניות לאסימונים במפתחות ה-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

למידע נוסף על שימוש בהפניות לאסימונים כערכים של צבעים, ראו הפניות לצבעים.