Localize Blocks

Blockly supports block definitions that can be localized to the user's language. Through the use of string tables, message strings in the JSON block definition can adapt the inputs, fields, and labels to reflect the language's vocabulary, word ordering, and direction.

All of these cases share the same JSON block definition:

// Block for creating a list with one element repeated.
{
  "type": "lists_repeat",
  "message0": "%{BKY_LISTS_REPEAT_TITLE}",
  "args0": [
    {
      "type": "input_value",
      "name": "ITEM"
    },
    {
      "type": "input_value",
      "name": "NUM",
      "check": "Number"
    }
  ],
  "output": "Array",
  "colour": "%{BKY_LISTS_HUE}",
  "tooltip": "%{BKY_LISTS_REPEAT_TOOLTIP}",
  "helpUrl": "%{BKY_LISTS_REPEAT_HELPURL}"
}

String Table

The lists_repeat example includes several "%{BKY_...}" strings. Each of these is a reference to a string in the Blockly.Msg string table. When the block is instantiated, Blockly attempts to replace the string with the value.

For example, %{BKY_LISTS_REPEAT_TITLE} is replaced with the value of Blockly.Msg['LISTS_REPEAT_TITLE'], if it exists. If the value does not exist, the %{BKY_...} notation is left in place, and Blockly emits a warning for the missing translation.

As shown in the example, the notation works in several locations. The messages and tooltips allow user visible strings to be replaced. Similarly, dropdown fields can also use the notation for item text. Help URL can be localized to ensure the user is directed to a similarly localized page. And finally, the colour value can use the notation to help centralize the palette of blocks.

If you're using the JavaScript implementation and do not expect to change the user language at runtime, you may find it easier to use a direct reference. For example, either Blockly.Msg['LISTS_REPEAT_TITLE'] or Blockly.Msg.LISTS_REPEAT_TITLE'.

The string tables are loaded via any one of the language specific .js files in msg/js. Load the appropriate file into your web page to load the correct block translation.

JSON Message Interpolation

The message0 attribute (and message1, message2, etc.) dictate the inputs, fields, and surrounding label text. For LISTS_REPEAT_TITLE in the lists_repeat block, the English value is:

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

Two interpolation markers, %1 and %2, mark the locations of the two inputs. Further details are provided in the args0 array. args1 would correspond to the message1 string. See the Create custom blocks guide for more details about specifying block inputs and fields.

The text between the interpolation markers is converted into unnamed label fields. This creates the word ordering of the block and how it reads:

// In Spanish
Blockly.Msg.LISTS_REPEAT_TITLE = "crear lista con el elemento %1 repetido %2 veces";
// In Korean
Blockly.Msg.LISTS_REPEAT_TITLE = "%1을 %2번 넣어, 리스트 생성";

When translating to right-to-left languages, the message string is written in the visual order, and should not include Unicode direction commands:

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

Rebuilding string tables

Building the string table .js files is part of the build:langfiles script. The script takes the identifier keys and English translations from msg/messages.js to create a new en.json. Then, combined with and any translations found in the other JSON files, it will recreate updated JavaScript string tables for all languages, including a new en.js.

The non-English JSON files come from partners at TranslateWiki. See the notes on translating for details about how you can help.