Cette page a été traduite par l'API Cloud Translation.

Localisation

Blockly fournit un système permettant de localiser le texte dans une application, comme les info-bulles, les menus contextuels et le texte sur les blocs. Il utilise ce système pour localiser son propre texte. Vous pouvez l'utiliser pour localiser le texte propre à votre application.

Remarque:La localisation est identique à la traduction, sauf qu'elle permet de proposer des traductions différentes pour différents pays, comme des traductions différentes en portugais au Portugal et au Brésil.

Fonctionnement du système de localisation

Le système de localisation se compose de jetons de localisation, de tables de localisation et de fonctions qui utilisent les tables pour remplacer les jetons par des chaînes localisées.

Jetons de localisation

Un jeton de localisation est une courte chaîne qui représente du texte à localiser. Par exemple, une info-bulle dans un bloc de date personnalisé peut utiliser le jeton MY_DATE_TOOLTIP. Les jetons de localisation sont utilisés dans le code à la place du texte. Au moment de l'exécution, Blockly remplace ces jetons par des chaînes localisées.

Tables de localisation

Une table de localisation, également appelée table de chaînes ou table de messages, est un objet qui met en correspondance des jetons de localisation avec des chaînes localisées. Vous avez besoin d'une table différente pour chaque paramètre régional. Par exemple, si vous souhaitez prendre en charge l'anglais et l'espagnol, votre table en anglais peut contenir les éléments suivants:

enTable.MY_DATE_TOOLTIP = 'Enter a date.';

Votre table en espagnol peut contenir les éléments suivants:

esTable.MY_DATE_TOOLTIP = 'Introduzca una fecha.';

Blockly inclut des tables de localisation pour son propre texte. Ils sont disponibles dans la distribution Blockly sous la forme de fichiers nommés blockly/msg/xx.js, où xx est le code de langue.

Vous devez créer des tables de localisation pour votre propre texte. Au moment de l'exécution, vous chargez les tables de localisation (celles de Blockly et la vôtre) pour les paramètres régionaux choisis dans Blockly.Msg, qui est la table de localisation utilisée en interne par Blockly.

Utiliser le système de localisation

Avant d'utiliser le système de localisation, vous devez décider du nombre de paramètres régionaux que vous souhaitez prendre en charge et si vous prévoyez d'en ajouter à l'avenir.

Si vous ne souhaitez prendre en charge qu'une seule langue, saisissez votre texte directement dans votre code. Vous n'avez pas besoin d'utiliser de jetons de localisation.
- Si vos paramètres régionaux sont définis sur l'anglais (en), vous n'avez rien d'autre à faire. Le tableau de localisation Blockly pour les paramètres régionaux en est chargé par défaut.
- Si votre langue n'est pas en, chargez le tableau de localisation de Blockly pour cette langue.
Si vous souhaitez prendre en charge plusieurs paramètres régionaux maintenant ou à l'avenir:
1. Définissez et utilisez des jetons de localisation pour votre texte personnalisé.
2. Déterminez comment les utilisateurs choisissent une langue.
3. Chargez le tableau de localisation de Blockly pour la langue.
4. Chargez votre table de localisation pour la langue.

Définir et utiliser des jetons de localisation

Lorsque vous prenez en charge plusieurs paramètres régionaux, vous devez définir et utiliser des jetons de localisation pour l'ensemble de votre texte personnalisé.

Définir des jetons de localisation

Pour chaque chaîne à localiser, définissez un jeton. Vous pouvez utiliser un préfixe personnalisé avec vos jetons pour éviter les conflits avec les jetons que Blockly ajoutera à l'avenir.

Par exemple, si vous disposez d'un seul bloc personnalisé et d'une seule catégorie personnalisée, vous pouvez définir les jetons suivants:

MY_DATE_BLOCK_TEXT
MY_DATE_TOOLTIP
MY_DATE_HELPURL
MY_DATE_CATEGORY

Définir des tables de localisation

Pour chaque groupe de paramètres régionaux que vous souhaitez prendre en charge, définissez une table de localisation. Exemple :

// 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',
}

Utiliser des jetons de localisation dans le format JSON

Pour utiliser des jetons de localisation en JSON, remplacez la chaîne à localiser par une référence de jeton. Une référence de jeton se présente sous la forme %{BKY_TOKEN}. Exemple :

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'],
}]);

Lorsque le fichier JSON est traité (dans ce cas, lorsque le bloc est instancié), Blockly recherche les jetons dans Blockly.Msg et les remplace par des chaînes localisées. Si aucun jeton n'est trouvé, la référence reste en place et un avertissement est émis.

Pour obtenir la liste complète des endroits où les références de jeton peuvent être utilisées, consultez l'annexe.

Interpolation de messages JSON

Les clés message d'une définition de bloc JSON définissent les entrées et les champs (y compris les libellés) d'un bloc. L'utilisation de références de jetons dans ces clés permet à une seule définition de bloc de s'adapter au vocabulaire, à l'ordre des mots et à la direction de plusieurs paramètres régionaux. Par exemple, voici le bloc lists_repeat de Blockly dans quatre langues différentes:

Bloc lists_repeat en anglais
Bloc lists_repeat en espagnol
Bloc lists_repeat en coréen
Bloc lists_repeat en arabe de droite à gauche

Tous ces blocs partagent la même définition de bloc, dont la clé message0 est la suivante:

message0: %{BKY_LISTS_REPEAT_TITLE},

La valeur de ce jeton dans le tableau de localisation en anglais est la suivante:

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

Les repères d'interpolation (%1 et %2) correspondent aux entrées et aux champs définis du bloc, et le texte situé entre les repères est converti en champs de libellé sans nom. Étant donné que le texte de message0 est stocké dans des tables de localisation et non dans la définition du bloc, une seule définition de bloc au format JSON peut prendre en charge différents ordres d'entrées et de champs:

// 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번 넣어, 리스트 생성";

Cela n'est pas possible pour les définitions de blocs en JavaScript, où différents ordres d'entrées et de champs nécessitent différentes séquences d'appels de fonction.

Lorsque vous utilisez des langues de l'écriture de droite à gauche, écrivez la chaîne de message dans l'ordre visuel et n'incluez pas de commandes de direction Unicode:

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

Pour en savoir plus sur la façon dont Blockly convertit les clés message en entrées et en champs, consultez la section Définir la structure de bloc en JSON.

Utiliser des jetons de localisation en JavaScript

Pour utiliser des jetons de localisation en JavaScript, remplacez la chaîne à localiser par Blockly.Msg['TOKEN']. Exemple :

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

Sauf indication contraire dans l'annexe, Blockly n'analyse pas les références de jeton en JavaScript:

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

Choisir un paramètre régional

Le choix d'une langue dépend de l'application et n'entre pas dans le champ d'application de Blockly. Par exemple, votre application peut toujours utiliser les mêmes paramètres régionaux, les déterminer à partir de l'URL ou des paramètres d'URL, ou laisser les utilisateurs choisir des paramètres régionaux dans une liste.

En règle générale, vous devez choisir une langue et charger les tables de localisation correspondantes avant de créer un espace de travail. Si vous choisissez une autre langue et que vous chargez de nouvelles tables après avoir créé un espace de travail, vous devrez le recréer: Blockly ne met pas à jour la boîte à outils ou les blocs existants pour utiliser automatiquement la nouvelle langue. Pour préserver le travail de l'utilisateur (le cas échéant), enregistrez l'état avant de recréer l'espace de travail et de le recharger par la suite.

Charger un tableau de localisation Blockly

Blockly fournit des tables de localisation pour l'ensemble de son propre texte, comme le texte des blocs intégrés. Sauf si vous utilisez les paramètres régionaux en, qui sont chargés par défaut, vous devez charger le tableau de localisation Blockly pour vos paramètres régionaux.

Les tables de localisation de Blockly sont stockées dans des fichiers nommés blockly/msg/xx.js, où xx est le code de langue. Pour obtenir la liste des paramètres régionaux compatibles, consultez les fichiers de blockly/msg/json.

Charger une table de localisation Blockly avec npm

Lorsque vous importez Blockly avec import * as Blockly from 'blockly';, vous obtenez les modules par défaut: le noyau Blockly, les blocs intégrés Blockly, le générateur JavaScript et la table de localisation Blockly pour la langue anglaise (en).

Pour charger la table de localisation de Blockly pour une autre langue à l'aide de npm:

Importez les modules par défaut de Blockly:

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

Importez la table de localisation Blockly pour votre langue. Par exemple, pour importer le tableau pour les paramètres régionaux espagnols (es) :
```
import * as Es from 'blockly/msg/es';
```
Chargez la table avec Blockly.setLocale. Cette fonction copie la table dans l'objet Blockly.Msg.
```
Blockly.setLocale(Es);
```
setLocale n'est inclus que dans la version npm de Blockly.

Charger une table de localisation Blockly sans npm

Pour charger une table de localisation Blockly sans utiliser npm, utilisez une balise <script> pour charger la table à partir du répertoire msg. Exemple :

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

La table de localisation est chargée automatiquement.

Charger votre propre table de localisation

Si vous définissez vos propres tables de localisation, vous devez charger la table pour la langue de votre choix.

Si vous utilisez npm, vous pouvez le faire avec Blockly.setLocale:
```
import * as Es from 'blockly/msg/es';
import {myEsTable} from '../my_tokens_es';
Blockly.setLocale(Es);
Blockly.setLocale(myEsTable);
```
setLocale copie chaque paire clé-valeur de l'objet d'entrée dans Blockly.Msg. Vous pouvez l'appeler plusieurs fois avec des clés distinctes, mais l'appeler une deuxième fois avec une clé en double écrase la première.
Si vous n'utilisez pas npm, vous devez copier votre table dans Blockly.Msg manuellement. (setLocale n'est inclus que dans la version npm de Blockly.) Le moyen le plus simple de procéder consiste à définir votre propre version de setLocale.
```
function mySetLocale(locale) {
  Object.keys(locale).forEach(function (k) {
    Blockly.Msg[k] = locale[k];
  }
}

mySetLocale(myEsTable);
```

Fonctions permettant de résoudre les références de jetons

Blockly fournit deux fonctions pour résoudre les références de jetons : Blockly.utils.parsing.replaceMessageReferences (couramment utilisé) et Blockly.utils.parsing.tokenizeInterpolation (rarement utilisé). Dans la plupart des cas, vous n'avez pas besoin d'appeler aucune de ces fonctions. En effet, Blockly les appelle déjà dans les endroits où il prend en charge les références de jeton. Par exemple, Blockly utilise ces fonctions pour résoudre les références de jeton dans les clés messageN, tooltip et helpUrl d'une définition de bloc JSON.

Vous pouvez avoir besoin d'utiliser replaceMessageReferences dans les champs personnalisés. Si votre champ personnalisé accepte des références de jeton dans l'une de ses options, utilisez replaceMessageReferences pour les résoudre. Pour en savoir plus, consultez la section JSON et enregistrement.

Articles associés

Langues de droite à gauche: consultez la démo de la langue de droite à gauche.
Aidez à localiser le texte de Blockly: consultez la section Traduire sur la contribution à Blockly.

Annexe: Cas où les références de jeton sont autorisées

Vous pouvez utiliser des références de jeton dans les clés JSON suivantes:

Dans les définitions de la boîte à outils des catégories :
- name
- colour
Dans les définitions de bloc :
- messageN
- tooltip
- helpUrl
- colour
Dans les options transmises à tous les champs :
- tooltip
Dans les tableaux imbriqués transmis à options dans field_dropdown :
- Premier élément, lorsqu'il s'agit d'une chaîne
- Valeur alt, lorsque le premier élément est un objet décrivant une image
Dans les options transmises à field_variable :
- variable
Dans les options transmises à field_label et field_label_serializable :
- text
Dans les options transmises à field_image :
- height
- width
- src
- alt
Dans les thèmes :
- colour dans les styles de catégorie
- colourPrimary, colourSecondary et colourTertiary dans les styles de bloc

Et comme valeurs d'argument dans les méthodes suivantes:

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

Et dans la définition XML d'une boîte à outils, dans les attributs suivants de <category>:

name
colour

Pour en savoir plus sur l'utilisation de références de jetons comme valeurs de couleur, consultez la section Références de couleur.

Localisation Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.