Dodawanie nowego tokena lokalizacji do podstawowego kodu Blockly

Jeśli dodasz do podstawowej wersji Blockly funkcję, która wymaga nowych ciągów widocznych dla użytkownika, musisz dodać te ciągi do Blockly.Msg, aby można było je przetłumaczyć w Translatewiki. (Więcej informacji o dodawaniu tokenów lokalizacji do własnej aplikacji znajdziesz w sekcji Lokalizacja).

  1. Dodaj nowy ciąg znaków z odpowiednią nazwą i opisem do pliku msg/messages.js.
  2. Uruchom polecenie npm run messages, aby automatycznie dodać tłumaczenie do plików msg/json/qqq.json i msg/json/en.js. W niektórych przypadkach ten krok może też zmienić msg/json/constants.js lub msg/json/synonyms.js.
  3. Sprawdź, czy automatycznie wygenerowane pliki są prawidłowe. Pamiętaj, że skrypt może usunąć sekcję @metadata na początku qqq.json. Jeśli tak się stanie, należy ostrożnie cofnąć tę zmianę, aby dodać nowy ciąg znaków, ale nie usunąć znaku @metadata.
  4. W kodzie funkcji odwołaj się do nowego ciągu za pomocą kodu Blockly.Msg['MY_NEW_MESSAGE'].
  5. Zatwierdź wszystkie zmiany w plikach msg wraz z kodem funkcji.

Jeśli na przykład dodasz ten kod do pliku 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!';

Następnie uruchom npm run messages. W msg/en.json powinny pojawić się te zmiany:

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

oraz w msg/qqq.json:

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

Następnie możesz odwołać się do tego ciągu tekstowego w kodzie za pomocą Blockly.Msg['MY_NEW_MESSAGE'].

Wskazówki dotyczące tłumaczenia

Komentarz z trzema ukośnikami w msg/messages.js jest wyświetlany użytkownikom TranslateWiki jako dodatkowe informacje podczas tłumaczenia. Podaj kontekst dotyczący tego, gdzie komunikat będzie wyświetlany użytkownikom. Jeśli wiadomość zawiera parametry (np. %1), wyjaśnij, co oznaczają parametry.

Oto przykład dobrej wskazówki dotyczącej tłumaczenia, która wyjaśnia parametry i zawiera link do dodatkowych informacji.

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

Typy kontekstu

Wiele wskazówek zawiera prefiks, który wyjaśnia kontekst wiadomości. Typowe prefiksy to:

  • blokować tekst,
  • tekst przycisku,
  • menu kontekstowe
  • menu rozwijane
  • matematyka
  • powiadomienie typu toast
  • etykietka

Jeśli Twój komunikat pojawia się w jednym z tych kontekstów, użyj odpowiedniego prefiksu.

Synonimy

Czasami trzeba zmienić klucz wiadomości, ale nie tłumaczenia. W takim przypadku możesz ustawić starą wiadomość jako synonim nowej wiadomości, np. w ten sposób:

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

Opcjonalne wiadomości

Niektóre ciągi tekstowe w wiadomościach raczej nie wymagają tłumaczenia, z wyjątkiem pewnych okoliczności, np. nazw własnych lub symboli. W Blockly adresy URL pomocy są często oznaczane jako opcjonalne.

Języki są dodawane do repozytorium Blockly tylko wtedy, gdy są przetłumaczone w co najmniej 25%. Dlatego oznaczenie wiadomości, które prawdopodobnie nie wymagają tłumaczenia, jako opcjonalnych pomoże tym językom osiągnąć próg bez konieczności uzupełniania opcjonalnych tłumaczeń.


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

Elementy notranslate

Kolory używane w przypadku domyślnych kategorii bloków są oznaczone {{notranslate}}. Nie są one przeznaczone do lokalizacji, ale znajdują się w systemie lokalizacji, aby programiści mogli łatwo zmieniać kolory bloków w domyślnych kategoriach. Jeśli dodasz nowe kategorie blokowania, użyj dyrektywy {{notranslate}}. Jeśli dodasz inny typ wiadomości, który Twoim zdaniem nigdy nie powinien być tłumaczony, zastanów się, czy system lokalizacji jest odpowiednim miejscem dla tego ciągu znaków.


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