Localizzazione

Blockly fornisce un sistema per la localizzazione del testo in un'applicazione, ad esempio le descrizioni comando, i menu contestuali e il testo sui blocchi. Utilizza questo sistema per localizzare il proprio testo. Puoi utilizzarlo per localizzare il testo specifico della tua applicazione.

Nota:la localizzazione è la stessa della traduzione, tranne per il fatto che consente di avere traduzioni diverse per paesi diversi, ad esempio traduzioni diverse in portoghese in Portogallo e in Brasile.

Come funziona il sistema di localizzazione

Il sistema di localizzazione è costituito da token di localizzazione, tabelle di localizzazione e funzioni che utilizzano le tabelle per sostituire i token con stringhe localizzate.

Token di localizzazione

Un token di localizzazione è una breve stringa che rappresenta il testo da localizzare. Ad esempio, una descrizione comando in un blocco di date personalizzato potrebbe utilizzare il token MY_DATE_TOOLTIP. I token di localizzazione vengono utilizzati nel codice al posto del testo. In fase di esecuzione, Blockly sostituisce questi token con stringhe localizzate.

Tabelle di localizzazione

Una tabella di localizzazione, nota anche come tabella di stringhe o tabella di messaggi, è un oggetto che mappa i token di localizzazione alle stringhe localizzate. È necessaria una tabella diversa per ogni lingua. Ad esempio, se vuoi supportare l'inglese e lo spagnolo, la tua tabella in inglese potrebbe contenere:

enTable.MY_DATE_TOOLTIP = 'Enter a date.';

e la tabella in spagnolo potrebbe contenere:

esTable.MY_DATE_TOOLTIP = 'Introduzca una fecha.';

Blockly include tabelle di localizzazione per il proprio testo. Sono disponibili nella distribuzione di Blockly come file denominati blockly/msg/xx.js, dove xx è il codice della lingua.

Devi creare tabelle di localizzazione per il tuo testo. In fase di esecuzione, carichi le tabelle di localizzazione, quelle di Blockly e le tue, per le impostazioni internazionali scelte in Blockly.Msg, la tabella di localizzazione utilizzata internamente da Blockly.

Utilizzare il sistema di localizzazione

Prima di utilizzare il sistema di localizzazione, devi decidere quante lingue supportare e se prevedi di supportarne altre in futuro.

Definire e utilizzare i token di localizzazione

Quando supporti più lingue, devi definire e utilizzare i token di localizzazione per tutto il testo personalizzato.

Definire i token di localizzazione

Per ogni stringa che deve essere localizzata, definisci un token. Ti consigliamo di utilizzare un prefisso personalizzato con i token per evitare conflitti con i token aggiunti da Blockly in futuro.

Ad esempio, se hai un singolo blocco personalizzato e una singola categoria personalizzata, potresti definire i seguenti token:

MY_DATE_BLOCK_TEXT
MY_DATE_TOOLTIP
MY_DATE_HELPURL
MY_DATE_CATEGORY

Definire le tabelle di localizzazione

Per ogni lingua che vuoi supportare, definisci una tabella di localizzazione. Ad esempio:

// English localization table: my_tokens_en.js
export const myEnTable = {
  MY_DATE_BLOCK_TEXT: 'Date %1',
  MY_DATE_TOOLTIP: 'Enter a date.',
  MY_DATE_HELPURL: 'https://myownpersonaldomain.com/help/en/dateblock'
  MY_DATE_CATEGORY: 'Dates',
}

// Spanish localization table: my_tokens_es.js
export const myEsTable = {
  MY_DATE_BLOCK_TEXT: 'Fecha %1',
  MY_DATE_TOOLTIP: 'Introduzca una fecha.',
  MY_DATE_HELPURL: 'https://myownpersonaldomain.com/help/es/dateblock'
  MY_DATE_CATEGORY: 'Fechas',
}

Utilizzare i token di localizzazione in JSON

Per utilizzare i token di localizzazione in JSON, sostituisci la stringa da localizzare con un riferimento a token. Un riferimento a token ha il formato %{BKY_TOKEN}. Ad esempio:

Blockly.common.defineBlocksWithJsonArray([{
  type: 'my_date',
  message0: '%{BKY_MY_DATE_BLOCK_TEXT}',
  args0: [
    {
      type: 'field_input',
      name: 'DATE',
    }
  ],
  output: 'Date',
  colour: '%{BKY_MY_DATE_COLOUR}',
  tooltip: '%{BKY_MY_DATE_TOOLTIP}',
  helpUrl: '%{BKY_MY_DATE_HELPURL}',
  extensions: ['validate_date'],
}]);

Quando il JSON viene elaborato, in questo caso quando il blocco viene creato, Blockly cerca i token in Blockly.Msg e li sostituisce con stringhe localizzate. Se non trova un token, lascia il riferimento in posizione ed emette un avviso.

Per un elenco completo dei luoghi in cui è possibile utilizzare i riferimenti ai token, consulta la appendice.

Interpolazione dei messaggi JSON

Le chiavi message in una definizione del blocco JSON definiscono gli input e i campi (incluse le etichette) in un blocco. L'uso di riferimenti ai token in queste chiavi consente di adattare una singola definizione di blocco al vocabolario, all'ordine delle parole e alla direzione di più lingue. Ad esempio, di seguito è riportato il blocco lists_repeat di Blockly in quattro lingue diverse:

Blocco lists_repeat in inglese
Blocco lists_repeat in spagnolo
Blocco lists_repeat in coreano
Blocco lists_repeat in arabo da destra a sinistra

Tutti questi blocchi condividono la stessa definizione di blocco, la cui chiave message0 è:

message0: %{BKY_LISTS_REPEAT_TITLE},

Il valore di questo token nella tabella di localizzazione in inglese è:

Blockly.Msg['LISTS_REPEAT_TITLE'] = 'create list with item %1 repeated %2 times';

Gli indicatori di interpolazione (%1 e %2) corrispondono agli input e ai campi definiti del blocco e il testo tra gli indicatori viene convertito in campi di etichette senza nome. Poiché il testo di message0 è memorizzato nelle tabelle di localizzazione e non nella definizione del blocco, una singola definizione di blocco in JSON può supportare diversi ordini di input e campi:

// In Spanish: label, input, label, input, label
Blockly.Msg['LISTS_REPEAT_TITLE'] = "crear lista con el elemento %1 repetido %2 veces";
// In Korean: input, label, input, label, input (dummy)
Blockly.Msg['LISTS_REPEAT_TITLE'] = "%1을 %2번 넣어, 리스트 생성";

Questo non è possibile per le definizioni di blocchi in JavaScript, dove diversi ordini di input e campi richiedono sequenze diverse di chiamate di funzioni.

Quando utilizzi lingue da destra a sinistra, scrivi la stringa del messaggio in ordine visivo e non includere i comandi di direzione Unicode:

// In Arabic. Note how %2 is left of %1, since it reads right to left.
Blockly.Msg['LISTS_REPEAT_TITLE'] = "إنشئ قائمة مع العنصر  %1 %2 مرات";

Per ulteriori informazioni su come Blockly converte le chiavi message in input e campi, consulta Definire la struttura del blocco in JSON.

Utilizzare i token di localizzazione in JavaScript

Per utilizzare i token di localizzazione in JavaScript, sostituisci la stringa da localizzare con Blockly.Msg['TOKEN']. Ad esempio:

// Return the text for a localized context menu item.
displayText: () => Blockly.Msg['MY_CONTEXT_MENU_ITEM'];

Salvo quanto indicato nell'appendice, Blockly non analizza i riferimenti ai token in JavaScript:

// Doesn't work. Returns '%{BKY_MY_CONTEXT_MENU_ITEM}'.
displayText: () => '%{BKY_MY_CONTEXT_MENU_ITEM}';

Scegli una località

La scelta delle impostazioni internazionali è specifica per l'applicazione e non rientra nell'ambito di Blockly. Ad esempio, l'applicazione potrebbe utilizzare sempre la stessa lingua, determinare la lingua dall'URL o dai parametri URL oppure consentire agli utenti di scegliere una lingua da un elenco.

Come regola generale, devi scegliere una lingua e caricare le tabelle di localizzazione corrispondenti prima di creare uno spazio di lavoro. Se scegli un'altra lingua e carichi nuove tabelle dopo aver creato uno spazio di lavoro, dovrai ricrearlo: Blockly non aggiorna la cassetta degli attrezzi o i blocchi esistenti per utilizzare automaticamente la nuova lingua. Per conservare il lavoro dell'utente (se presente), salva lo stato prima di ricreare l'area di lavoro e ricaricala dopo.

Caricare una tabella di localizzazione di Blockly

Blockly fornisce tabelle di localizzazione per tutto il proprio testo, ad esempio il testo sui blocchi integrati. A meno che tu non stia utilizzando le impostazioni internazionali en, che vengono caricate per impostazione predefinita, devi caricare la tabella di localizzazione di Blockly per le tue impostazioni internazionali.

Le tabelle di localizzazione di Blockly sono memorizzate in file denominati blockly/msg/xx.js, dove xx è il codice della lingua. Per un elenco delle lingue supportate, consulta i file in blockly/msg/json.

Caricare una tabella di localizzazione di Blockly con npm

Quando importi Blockly con import * as Blockly from 'blockly';, ottieni i moduli predefiniti: il nucleo di Blockly, i blocchi integrati di Blockly, il generatore di JavaScript e la tabella di localizzazione di Blockly per la locale inglese (en).

Per caricare la tabella di localizzazione di Blockly per una lingua diversa utilizzando npm:

  1. Importa i moduli predefiniti di Blockly:

    import * as Blockly from 'blockly/core';
import 'blockly/blocks';
import 'blockly/javascript'; // Or the generator of your choice

  2. Importa la tabella di localizzazione di Blockly per la tua lingua. Ad esempio, per importare la tabella per le impostazioni internazionali spagnole (es):

    import * as Es from 'blockly/msg/es';

  3. Carica la tabella con Blockly.setLocale. Questa funzione copia la tabella nell'oggetto Blockly.Msg.

    Blockly.setLocale(Es);

    setLocale è incluso solo nella release npm di Blockly.

Caricare una tabella di localizzazione di Blockly senza npm

Per caricare una tabella di localizzazione di Blockly senza utilizzare npm, utilizza un tag <script> per caricare la tabella dalla directory msg. Ad esempio:

<script src="../../blockly_compressed.js"></script>
<script src="../../blocks_compressed.js"></script>
<script src="../../msg/es.js"></script>

La tabella di localizzazione viene caricata automaticamente.

Carica la tua tabella di localizzazione

Se definisci le tue tabelle di localizzazione, devi caricare la tabella per la lingua selezionata.

  • Se utilizzi npm, puoi farlo con Blockly.setLocale:

    import * as Es from 'blockly/msg/es';
import {myEsTable} from '../my_tokens_es';
Blockly.setLocale(Es);
Blockly.setLocale(myEsTable);

    setLocale copia ogni coppia chiave-valore dall'oggetto di input in Blockly.Msg. Puoi chiamarlo più volte con chiavi distinte, ma se lo chiami una seconda volta con una chiave duplicata, la prima viene sovrascritta.

  • Se non utilizzi npm, devi copiare la tabella in Blockly.Msg manualmente. (setLocale è incluso solo nella release npm di Blockly.) Il modo più semplice per farlo è definire la tua versione di setLocale.

    function mySetLocale(locale) {
  Object.keys(locale).forEach(function (k) {
    Blockly.Msg[k] = locale[k];
  }
}

mySetLocale(myEsTable);

Funzioni per risolvere i riferimenti ai token

Blockly fornisce due funzioni per risolvere i riferimenti ai token: Blockly.utils.parsing.replaceMessageReferences (utilizzato di frequente) e Blockly.utils.parsing.tokenizeInterpolation (utilizzato raramente). Nella maggior parte dei casi, non è necessario chiamare nessuna di queste funzioni. Questo perché Blockly li chiama già nei luoghi in cui supporta i riferimenti ai token. Ad esempio, Blockly utilizza queste funzioni per risolvere i riferimenti ai token nelle chiavi messageN, tooltip e helpUrl in una definizione del blocco JSON.

Un caso in cui potresti dover utilizzare replaceMessageReferences è nei campi personalizzati. Se il campo personalizzato accetta riferimenti ai token in una delle sue opzioni, utilizza replaceMessageReferences per risolverli. Per ulteriori informazioni, consulta JSON e registrazione.

  • Lingue con scrittura da destra a sinistra: consulta la demo RTL.
  • Contribuisci alla localizzazione del testo di Blockly: consulta la sezione Traduzione relativa al contributo a Blockly.

Appendice: dove sono consentiti i riferimenti ai token

Puoi utilizzare i riferimenti ai token nelle seguenti chiavi JSON:

  • Nelle definizioni della cassetta degli attrezzi delle categorie:
    • name
    • colour
  • Nelle definizioni dei blocchi:
    • messageN
    • tooltip
    • helpUrl
    • colour
  • Nelle opzioni passate a tutti i campi:
    • tooltip
  • Negli array nidificati passati a options in field_dropdown:
    • Il primo elemento, se si tratta di una stringa
    • Il valore di alt, quando il primo elemento è un oggetto che descrive un'immagine
  • Nelle opzioni passate a field_variable:
    • variable
  • Nelle opzioni passate a field_label e field_label_serializable:
    • text
  • Nelle opzioni passate a field_image:
    • height
    • width
    • src
    • alt
  • Nei temi:
    • colour negli stili di categoria
    • colourPrimary, colourSecondary e colourTertiary negli stili di blocco

E come valori degli argomenti nei seguenti metodi:

  • Block.setColour
  • Blockly.utils.extensions.buildTooltipForDropDown
  • Blockly.utils.extensions.buildTooltipWithFieldText
  • Blockly.utils.parsing.parseBlockColour

E nella definizione XML di una cassetta degli attrezzi nei seguenti attributi di <category>:

  • name
  • colour

Per saperne di più sull'utilizzo dei riferimenti ai token come valori di colore, consulta Riferimenti ai colori.