Aggiungere un nuovo token di localizzazione a Blockly core

Se aggiungi una funzionalità al core di Blockly che richiede nuove stringhe visibili agli utenti, devi aggiungerle a Blockly.Msg in modo che possano essere tradotte da Translatewiki. Per informazioni sull'aggiunta di token di localizzazione per la tua applicazione, consulta Localizzazione.

  1. Aggiungi la nuova stringa con un nome e una descrizione appropriati al file msg/messages.js.
  2. Esegui npm run messages per aggiungere automaticamente la traduzione ai file msg/json/qqq.json e msg/json/en.js. In alcuni casi, questo passaggio potrebbe anche modificare msg/json/constants.js o msg/json/synonyms.js.
  3. Controlla che i file generati automaticamente siano corretti. Tieni presente che lo script potrebbe rimuovere la sezione @metadata all'inizio di qqq.json. Se ciò accade, devi annullare con attenzione la modifica in modo che la nuova stringa venga aggiunta, ma @metadata non venga rimosso.
  4. Nel codice della funzionalità, fai riferimento alla nuova stringa con Blockly.Msg['MY_NEW_MESSAGE'].
  5. Esegui il commit di tutte le modifiche ai file msg insieme al codice della funzionalità.

Ad esempio, se aggiungi questo codice 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!';

Poi esegui npm run messages, dovresti vedere le seguenti modifiche in msg/en.json:

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

e in msg/qqq.json:

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

Puoi quindi fare riferimento a questa stringa nel codice con Blockly.Msg['MY_NEW_MESSAGE'].

Suggerimenti per la traduzione

Il commento con tre barre in msg/messages.js viene mostrato agli utenti di TranslateWiki come informazioni supplementari durante la traduzione. Fornisci un contesto in cui il messaggio verrà mostrato agli utenti. Se il messaggio include parametri (ad es. %1), spiega il significato dei parametri.

Ecco un esempio di suggerimento di traduzione efficace che spiega i parametri e fornisce un link per ulteriori informazioni.

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

Tipi di contesto

Molti suggerimenti utilizzano un prefisso per spiegare il contesto di un messaggio. I prefissi comuni includono:

  • blocca testo
  • button text
  • menu contestuale
  • elenco a discesa
  • matematica
  • notifica popup
  • Descrizione comando

Se il tuo messaggio viene visualizzato in uno di questi contesti, utilizza il prefisso appropriato.

Sinonimi

A volte è necessario modificare una chiave del messaggio, ma non le traduzioni. In questo caso, puoi impostare il vecchio messaggio come sinonimo del nuovo, in questo modo:

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

Messaggi facoltativi

È improbabile che alcune stringhe di messaggi debbano essere tradotte, tranne in determinate circostanze, ad esempio nomi propri o simboli. In Blockly, gli URL di assistenza sono spesso contrassegnati come facoltativi.

Le lingue vengono aggiunte al repository Blockly solo se sono complete almeno al 25%. Pertanto, contrassegnare come facoltativi i messaggi che probabilmente non necessitano di traduzione aiuterà queste lingue a raggiungere la soglia senza dover completare le traduzioni facoltative.


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

Elementi notranslate

I colori utilizzati per le categorie di blocchi predefinite sono contrassegnati da {{notranslate}}. Questi colori non sono pensati per essere localizzati, ma si trovano nel sistema di localizzazione in modo che gli sviluppatori possano facilmente modificare i colori dei blocchi nelle categorie predefinite. Se aggiungi nuove categorie di blocco, utilizza la direttiva {{notranslate}}. Se aggiungi un tipo diverso di messaggio che ritieni non debba mai essere tradotto, valuta se il sistema di localizzazione è il posto giusto per la stringa.


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