Adicionar um novo token de localização ao núcleo do Blockly

Se você adicionar um recurso ao núcleo do Blockly que exija novas strings visíveis ao usuário, adicione essas strings a Blockly.Msg para que possam ser traduzidas pelo Translatewiki. Para saber como adicionar tokens de localização ao seu aplicativo, consulte Localização.

  1. Adicione a nova string com um nome e uma descrição adequados ao arquivo msg/messages.js.
  2. Execute npm run messages para adicionar automaticamente sua tradução aos arquivos msg/json/qqq.json e msg/json/en.js. Essa etapa também pode mudar msg/json/constants.js ou msg/json/synonyms.js em alguns casos.
  3. Inspecione os arquivos gerados automaticamente para verificar se estão corretos. O script pode remover a seção @metadata no início de qqq.json. Se isso acontecer, reverta a mudança com cuidado para que a nova string seja adicionada, mas o @metadata não seja removido.
  4. No código do recurso, faça referência à nova string com Blockly.Msg['MY_NEW_MESSAGE'].
  5. Faça commit de todas as mudanças nos arquivos msg junto com o código do recurso.

Por exemplo, se você adicionar este código a 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!';

Em seguida, execute npm run messages. As seguintes mudanças vão aparecer em msg/en.json:

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

e em msg/qqq.json:

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

Em seguida, você pode fazer referência a essa string no código com Blockly.Msg['MY_NEW_MESSAGE'].

Dicas de tradução

O comentário com três barras em msg/messages.js é mostrado aos usuários do TranslateWiki como informações complementares durante a tradução. Forneça contexto sobre onde a mensagem será mostrada aos usuários. Se a mensagem incluir parâmetros (por exemplo, %1) e explique o que os parâmetros significam.

Confira um exemplo de uma boa dica de tradução que explica os parâmetros e fornece um link para mais informações.

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

Tipos de contexto

Muitas dicas usam um prefixo para explicar o contexto de uma mensagem. Os prefixos comuns incluem:

  • bloquear texto
  • texto do botão
  • Menu de contexto
  • lista suspensa
  • matemática
  • notificação toast
  • dica

Se a mensagem aparecer em um desses contextos, use o prefixo adequado.

Sinônimos

Às vezes, uma chave de mensagem precisa ser alterada, mas as traduções não. Nesse caso, você pode definir a mensagem antiga como sinônimo da nova, assim:

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

Mensagens opcionais

Algumas strings de mensagens provavelmente não precisam de tradução, exceto em determinadas circunstâncias, por exemplo, substantivos próprios ou símbolos. No Blockly, os URLs de ajuda geralmente são marcados como opcionais.

Os idiomas só são enviados ao repositório do Blockly se estiverem pelo menos 25% concluídos. Assim, marcar mensagens que provavelmente não precisam de tradução como opcionais vai ajudar esses idiomas a atingir o limite sem precisar concluir as traduções opcionais.


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

Itens "notranslate"

As cores usadas para as categorias de blocos padrão são marcadas como {{notranslate}}. Elas não foram criadas para serem localizadas, mas estão no sistema de localização para que os desenvolvedores possam mudar as cores dos blocos nas categorias padrão com facilidade. Se você adicionar novas categorias de bloqueio, use a diretiva {{notranslate}}. Se você adicionar um tipo de mensagem diferente que acha que nunca deve ser traduzido, pense se o sistema de localização é o lugar certo para a string.


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