在 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. 檢查自動產生的檔案是否正確。請注意，指令碼可能會移除 qqq.json 開頭的 @metadata 區段。如果發生這種情況，請謹慎還原變更，確保新增字串，但不會移除 @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 中，說明網址通常會標示為選填。

只有在語言至少完成 25% 時，才會提交至 Blockly 存放區。因此，將不太需要翻譯的訊息標示為選填，有助於這些語言達到門檻，無須完成選填翻譯。


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