Thêm mã thông báo bản địa hoá mới vào lõi Blockly

Nếu thêm một tính năng vào lõi Blockly và tính năng đó yêu cầu các chuỗi mới mà người dùng có thể nhìn thấy, thì bạn phải thêm các chuỗi đó vào Blockly.Msg để Translatewiki có thể dịch các chuỗi đó. (Để biết thông tin về cách thêm mã thông báo bản địa hoá cho ứng dụng của riêng bạn, hãy xem phần Bản địa hoá.)

  1. Thêm chuỗi mới có tên và nội dung mô tả phù hợp vào tệp msg/messages.js.
  2. Chạy npm run messages để tự động thêm bản dịch vào các tệp msg/json/qqq.json và msg/json/en.js. Bước này cũng có thể thay đổi msg/json/constants.js hoặc msg/json/synonyms.js trong một số trường hợp.
  3. Kiểm tra tính chính xác của các tệp được tạo tự động. Xin lưu ý rằng tập lệnh có thể xoá phần @metadata ở đầu qqq.json. Nếu điều này xảy ra, bạn nên cẩn thận hoàn nguyên thay đổi đó để chuỗi mới được thêm vào nhưng @metadata không bị xoá.
  4. Trong mã tính năng, hãy tham chiếu đến chuỗi mới bằng Blockly.Msg['MY_NEW_MESSAGE'].
  5. Xác nhận tất cả các thay đổi đối với tệp msg cùng với mã tính năng của bạn.

Ví dụ: nếu bạn thêm mã này vào 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!';

Sau đó, hãy chạy npm run messages, bạn sẽ thấy những thay đổi sau trong msg/en.json:

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

và trong msg/qqq.json:

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

Sau đó, bạn có thể tham chiếu chuỗi này trong mã bằng Blockly.Msg['MY_NEW_MESSAGE'].

Gợi ý về bản dịch

Chú thích có ba dấu gạch chéo trong msg/messages.js được hiển thị cho người dùng TranslateWiki dưới dạng thông tin bổ sung khi dịch. Cung cấp bối cảnh về vị trí thông báo sẽ hiển thị cho người dùng. Nếu thông báo có chứa các tham số (ví dụ: %1), hãy giải thích ý nghĩa của các tham số.

Dưới đây là ví dụ về một gợi ý dịch hay, giải thích các tham số và cung cấp đường liên kết đến thông tin khác.

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

Loại ngữ cảnh

Nhiều gợi ý sử dụng một tiền tố để giải thích ngữ cảnh của một thông báo. Các tiền tố phổ biến bao gồm:

  • chặn văn bản
  • văn bản trên nút
  • trình đơn theo bối cảnh
  • trình đơn thả xuống
  • toán học
  • thông báo dạng thông báo nhanh
  • chú thích

Nếu thông báo của bạn xuất hiện trong một trong những ngữ cảnh này, hãy sử dụng tiền tố thích hợp.

Từ đồng nghĩa

Đôi khi, bạn cần thay đổi khoá thông báo nhưng không cần thay đổi bản dịch. Trong trường hợp đó, bạn có thể đặt thông báo cũ làm từ đồng nghĩa của thông báo mới, như sau:

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

Thông báo không bắt buộc

Một số chuỗi thông báo không cần dịch, trừ một số trường hợp nhất định, chẳng hạn như danh từ riêng hoặc biểu tượng. Trong Blockly, các URL trợ giúp thường được đánh dấu là không bắt buộc.

Các ngôn ngữ chỉ được đưa vào kho lưu trữ Blockly nếu hoàn thành ít nhất 25%. Do đó, việc đánh dấu những thông báo không cần dịch là không bắt buộc sẽ giúp những ngôn ngữ đó đáp ứng ngưỡng mà không cần hoàn tất bản dịch không bắt buộc.


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

Mục không được dịch

Màu sắc được dùng cho các danh mục khối mặc định được đánh dấu là {{notranslate}}. Các màu sắc này không nhằm mục đích bản địa hoá, nhưng nằm trong hệ thống bản địa hoá để nhà phát triển có thể dễ dàng thay đổi màu sắc của các khối trong danh mục mặc định. Nếu bạn thêm danh mục chặn mới, hãy sử dụng chỉ thị {{notranslate}}. Nếu bạn thêm một loại thông báo khác mà bạn cho rằng không bao giờ nên được dịch, hãy cân nhắc xem hệ thống bản địa hoá có phải là nơi phù hợp cho chuỗi này hay không.


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