Ajouter un nouveau jeton de localisation au cœur de Blockly

Si vous ajoutez une fonctionnalité au cœur de Blockly qui nécessite de nouvelles chaînes visibles par l'utilisateur, vous devez ajouter ces chaînes à Blockly.Msg afin qu'elles puissent être traduites par Translatewiki. (Pour savoir comment ajouter des jetons de localisation pour votre propre application, consultez Localisation.)

  1. Ajoutez votre nouvelle chaîne avec un nom et une description appropriés au fichier msg/messages.js.
  2. Exécutez npm run messages pour ajouter automatiquement votre traduction aux fichiers msg/json/qqq.json et msg/json/en.js. Cette étape peut également modifier msg/json/constants.js ou msg/json/synonyms.js dans certains cas.
  3. Vérifiez que les fichiers générés automatiquement sont corrects. Notez que le script peut supprimer la section @metadata au début de qqq.json. Dans ce cas, vous devez annuler soigneusement cette modification afin que votre nouvelle chaîne soit ajoutée, mais que @metadata ne soit pas supprimé.
  4. Dans le code de votre fonctionnalité, référencez la nouvelle chaîne avec Blockly.Msg['MY_NEW_MESSAGE'].
  5. Validez toutes les modifications apportées aux fichiers msg en même temps que votre code de fonctionnalité.

Par exemple, si vous ajoutez ce code à 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!';

Exécutez ensuite npm run messages. Les modifications suivantes devraient s'afficher dans msg/en.json :

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

et dans msg/qqq.json :

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

Vous pouvez ensuite référencer cette chaîne dans le code avec Blockly.Msg['MY_NEW_MESSAGE'].

Indications pour la traduction

Le commentaire à triple barre oblique dans msg/messages.js est affiché aux utilisateurs de TranslateWiki comme information supplémentaire lors de la traduction. Indiquez le contexte dans lequel le message sera affiché aux utilisateurs. Si le message inclut des paramètres (par exemple, %1), expliquez ce que signifient les paramètres.

Voici un exemple de bon conseil de traduction qui explique les paramètres et fournit un lien vers plus d'informations.

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

Types de contexte

De nombreux conseils utilisent un préfixe pour expliquer le contexte d'un message. Voici les préfixes courants :

  • bloquer les annonces textuelles ;
  • texte du bouton
  • menu contextuel
  • liste déroulante
  • maths
  • notification toast
  • Info-bulle

Si votre message s'affiche dans l'un de ces contextes, utilisez le préfixe approprié.

Synonymes

Il arrive parfois qu'une clé de message doive être modifiée, mais pas les traductions. Dans ce cas, vous pouvez définir l'ancien message comme synonyme du nouveau message, comme suit :

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

Messages facultatifs

Il est peu probable que certaines chaînes de message aient besoin d'être traduites, sauf dans certaines circonstances (par exemple, les noms propres ou les symboles). Dans Blockly, les URL d'aide sont souvent marquées comme facultatives.

Les langues ne sont ajoutées au dépôt Blockly que si elles sont complètes à au moins 25 %. Par conséquent, marquer comme facultatifs les messages qui n'ont probablement pas besoin d'être traduits aidera ces langues à atteindre le seuil sans avoir à effectuer les traductions facultatives.


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

Éléments notranslate

Les couleurs utilisées pour les catégories de blocs par défaut sont indiquées par {{notranslate}}. Ces couleurs ne sont pas destinées à être localisées, mais elles se trouvent dans le système de localisation afin que les développeurs puissent facilement modifier les couleurs des blocs dans les catégories par défaut. Si vous ajoutez des catégories de blocage, utilisez la directive {{notranslate}}. Si vous ajoutez un autre type de message qui, selon vous, ne devrait jamais être traduit, demandez-vous si le système de localisation est le bon endroit pour la chaîne.


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