Agrega un token de localización nuevo al núcleo de Blockly

Si agregas una función al núcleo de Blockly que requiere nuevas cadenas visibles para el usuario, debes agregar esas cadenas a Blockly.Msg para que Translatewiki las pueda traducir. (Para obtener información sobre cómo agregar tokens de localización para tu propia aplicación, consulta Localización).

  1. Agrega tu cadena nueva con un nombre y una descripción adecuados al archivo msg/messages.js.
  2. Ejecuta npm run messages para agregar automáticamente tu traducción a los archivos msg/json/qqq.json y msg/json/en.js. En algunos casos, este paso también puede cambiar msg/json/constants.js o msg/json/synonyms.js.
  3. Inspecciona los archivos generados automáticamente para verificar que sean correctos. Ten en cuenta que el script puede quitar la sección @metadata al comienzo de qqq.json. Si esto sucede, debes revertir cuidadosamente ese cambio para que se agregue la cadena nueva, pero no se quite @metadata.
  4. En el código de tu función, haz referencia a la nueva cadena con Blockly.Msg['MY_NEW_MESSAGE'].
  5. Confirma todos los cambios en los archivos msg junto con el código de tu función.

Por ejemplo, si agregas 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!';

Luego, ejecuta npm run messages. Deberías ver los siguientes cambios en msg/en.json:

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

y en msg/qqq.json:

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

Luego, puedes hacer referencia a esta cadena en el código con Blockly.Msg['MY_NEW_MESSAGE'].

Sugerencias de traducción

El comentario con tres barras diagonales en msg/messages.js se muestra a los usuarios de TranslateWiki como información complementaria durante la traducción. Proporciona contexto sobre dónde se mostrará el mensaje a los usuarios. Si el mensaje incluye parámetros (p.ej., %1), explica qué significan los parámetros.

Este es un ejemplo de una buena sugerencia de traducción que explica los parámetros y proporciona un vínculo a más información.

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

Muchas de las sugerencias usan un prefijo para explicar el contexto de un mensaje. Los prefijos comunes incluyen los siguientes:

  • Bloquear texto
  • Texto del botón
  • Menú contextual
  • menú desplegable
  • matemáticas
  • Notificación emergente
  • cuadro de información

Si tu mensaje aparece en uno de estos contextos, usa el prefijo adecuado.

Sinónimos

A veces, es necesario cambiar la clave de un mensaje, pero no las traducciones. En ese caso, puedes establecer el mensaje anterior como sinónimo del mensaje nuevo, de la siguiente manera:

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

Mensajes opcionales

Es poco probable que algunas cadenas de mensajes necesiten traducción, excepto en ciertas circunstancias, por ejemplo, nombres propios o símbolos. En Blockly, las URLs de ayuda suelen marcarse como opcionales.

Los idiomas solo se confirman en el repositorio de Blockly si están completos en al menos un 25%. Por lo tanto, marcar como opcionales los mensajes que probablemente no necesiten traducción ayudará a que esos idiomas cumplan con el umbral sin necesidad de completar las traducciones opcionales.


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

Elementos que no se traducen

Los colores que se usan para las categorías de bloques predeterminadas están marcados como {{notranslate}}. Estos colores no están diseñados para localizarse, pero se encuentran en el sistema de localización para que los desarrolladores puedan cambiar los colores de los bloques en las categorías predeterminadas con facilidad. Si agregas nuevas categorías de bloqueo, usa la directiva {{notranslate}}. Si agregas un tipo de mensaje diferente que crees que nunca se debería traducir, considera si el sistema de localización es el lugar adecuado para la cadena.


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