Ta strona została przetłumaczona przez Cloud Translation API.

Lokalizacja

Blockly udostępnia system do lokalizacji tekstu w aplikacji, np. etykietek, menu kontekstowych i tekstu na blokach. Używa tego systemu do lokalizacji własnych tekstów. Możesz go używać do lokalizacji tekstu charakterystycznego dla Twojej aplikacji.

Uwaga: lokalizacja to to samo co tłumaczenie, z tym wyjątkiem, że pozwala na różne tłumaczenia w różnych krajach, np. różne tłumaczenia na język portugalski w Portugalii i Brazylii.

Jak działa system lokalizacji

System lokalizacji składa się z tokenów lokalizacji, tabel lokalizacji oraz funkcji, które używają tabel do zastępowania tokenów zlokalizowanymi ciągami znaków.

Tokeny lokalizacji

Znak tożsamości lokalizacji to krótki ciąg znaków reprezentujący tekst, który wymaga zlokalizowania. Na przykład w informacji tekstowej w niestandardowym bloku dat może być użyty element danych MY_DATE_TOOLTIP. Tokeny lokalizacji są używane w kodzie zamiast tekstu. Podczas wykonywania Blockly zastępuje te tokeny lokalizowanymi ciągami znaków.

tabele lokalizacji,

Tabela lokalizacji, zwana też tabelą ciągów znaków lub tabelą wiadomości, to obiekt, który mapuje tokeny lokalizacji na zlokalizowane ciągi znaków. W przypadku każdej lokalizacji musisz utworzyć osobną tabelę. Jeśli na przykład chcesz obsługiwać język angielski i hiszpański, tabela języka angielskiego może zawierać:

enTable.MY_DATE_TOOLTIP = 'Enter a date.';

Tabela hiszpańska może zawierać:

esTable.MY_DATE_TOOLTIP = 'Introduzca una fecha.';

Blockly zawiera tabele lokalizacji dla własnych tekstów. Są one dostępne w rozpowszechnianiu Blockly jako pliki o nazwie blockly/msg/xx.js, gdzie xx to kod języka.

Musisz utworzyć tabele lokalizacji dla własnych tekstów. W czasie wykonywania wczytujesz tabele lokalizacji (własne i Blockly) dla wybranego języka do tabeli Blockly.Msg, która jest tabelą lokalizacji używaną wewnętrznie przez Blockly.

Korzystanie z systemu lokalizacji

Zanim zaczniesz korzystać z systemu lokalizacji, musisz określić, ile języków chcesz obsługiwać i czy w przyszłości planujesz obsługiwać więcej języków.

Jeśli chcesz obsługiwać tylko jeden język, wpisz tekst bezpośrednio w kodzie. Nie musisz używać tokenów lokalizacji.
- Jeśli Twój język to angielski (en), nie musisz nic więcej robić. Domyślnie wczytana jest tabela lokalizacji Blockly dla ustawień regionalnych en.
- Jeśli Twój język nie jest en, wczytaj tabelę lokalizacji Blockly dla tego języka.
Jeśli chcesz obsługiwać wiele lokalizacji teraz lub w przyszłości:
1. Zdefiniuj i używaj tokenów lokalizacji w przypadku tekstu własnego.
2. Określ, jak użytkownicy będą wybierać język.
3. Wczytaj tabelę lokalizacji Blockly dla danego języka.
4. Wczytaj tabelę lokalizacji dla danego języka.

Definiowanie i używanie tokenów lokalizacji

Jeśli obsługujesz wiele lokalizacji, musisz zdefiniować i użyć tokenów lokalizacji dla wszystkich tekstów niestandardowych.

Definiowanie tokenów lokalizacji

Dla każdego ciągu, który wymaga zlokalizowania, zdefiniuj token. Możesz użyć niestandardowego prefiksu w przypadku tokenów, aby uniknąć konfliktów z tokenami, które Blockly doda w przyszłości.

Jeśli np. masz 1 blok niestandardowy i 1 kategorię niestandardową, możesz zdefiniować te znaczniki:

MY_DATE_BLOCK_TEXT
MY_DATE_TOOLTIP
MY_DATE_HELPURL
MY_DATE_CATEGORY

Definiowanie tabel lokalizacji

Dla każdego języka, który chcesz obsługiwać, zdefiniuj tabelę lokalizacji. Na przykład:

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

Używanie tokenów lokalizacji w pliku JSON

Aby używać tokenów lokalizacji w pliku JSON, zastąp ciąg znaków, który ma zostać przetłumaczony, odwołaniem do tokenu. Odwołanie do tokena ma postać %{BKY_TOKEN}. Na przykład:

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

Gdy dane JSON zostaną przetworzone (w tym przypadku gdy blok zostanie zainicjowany), Blockly wyszukuje tokeny w pliku Blockly.Msg i zastępuje je zlokalizowanymi ciągami znaków. Jeśli nie znajdzie tokena, pozostawi odwołanie na miejscu i wyemituje ostrzeżenie.

Pełną listę miejsc, w których można używać odwołań do tokenów, znajdziesz w załączniku.

Interpolacja wiadomości JSON

Klucze message w definicji bloku JSON definiują dane wejściowe i pola (w tym etykiety) w bloku. Użycie w tych kluczach odwołań do tokenów pozwala definicji pojedynczego bloku dostosować się do słownictwa, kolejności słów i kierunku pisania w różnych językach. Oto na przykład blok lists_repeat w Blockly w 4 różnych językach:

Blokada lists_repeat
Blok lists_repeat w języku hiszpańskim
Blok lists_repeat w języku koreańskim
Blok lists_repeat w języku arabskim zapisywanym od prawej do lewej

Wszystkie te bloki mają tę samą definicję bloku, której klucz message0 to:

message0: %{BKY_LISTS_REPEAT_TITLE},

Wartość tego tokena w tabeli lokalizacji angielskiej to:

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

Znaczniki interpolacji (%1 i %2) odpowiadają zdefiniowanym przez blok wejściom i polom, a tekst między tymi znacznikami jest konwertowany na nienazwane pola etykiety. Tekst message0 jest przechowywany w tabelach lokalizacji, a nie w definicji bloku, dlatego definicja pojedynczego bloku w pliku JSON może obsługiwać różne kolejności danych wejściowych i pol:

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

Nie jest to możliwe w przypadku definicji bloków w JavaScript, ponieważ różne kolejności danych wejściowych i pól wymagają różnych sekwencji wywołań funkcji.

W przypadku języków zapisywanych od prawa do lewej zapisz ciąg znaków w porządku wizualnym i nie używaj poleceń kierunku Unicode:

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

Więcej informacji o tym, jak Blockly przekształca klucze message w dane wejściowe i pola, znajdziesz w artykule Definiowanie struktury bloku w JSON.

Używanie tokenów lokalizacji w JavaScript

Aby używać tokenów lokalizacji w JavaScript, zastąp ciąg znaków, który ma zostać przetłumaczony, symbolem Blockly.Msg['TOKEN']. Na przykład:

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

Z wyjątkiem przypadków opisanych w aneksie Blockly nie analizuje odwołań do tokenów w JavaScript:

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

Wybieranie języka

Sposób wyboru lokalizacji zależy od aplikacji i nie jest objęty zakresem Blockly. Aplikacja może na przykład zawsze używać tego samego języka, określać język na podstawie adresu URL lub parametrów adresu URL albo pozwalać użytkownikom na wybór języka z listy.

Zasadniczo przed utworzeniem obszaru roboczego należy wybrać lokalizację i wczytać odpowiednie tabele lokalizacji. Jeśli po utworzeniu obszaru roboczego wybierzesz inny język i załadujesz nowe tabele, musisz ponownie utworzyć obszar roboczy: Blockly nie aktualizuje automatycznie istniejących narzędzi ani bloków, aby używać nowego języka. Aby zachować zmiany wprowadzone przez użytkownika (jeśli takie istnieją), zapisz stan przed ponownym utworzeniem obszaru roboczego i ponownie go wczytaj.

Wczytywanie tabeli lokalizacji w Blockly

Blockly udostępnia tabele lokalizacji dla wszystkich własnych tekstów, takich jak tekst w wbudowanych blokach. Jeśli nie używasz języka en, który jest wczytywany domyślnie, musisz wczytać tabelę lokalizacji Blockly dla swojego języka.

Tabele lokalizacji Blockly są przechowywane w plikach o nazwie blockly/msg/xx.js, gdzie xx to kod języka. Listę obsługiwanych lokalizacji znajdziesz w plikach w folderze blockly/msg/json.

Ładowanie tabeli lokalizacji Blockly za pomocą npm

Gdy zaimportujesz Blockly z import * as Blockly from 'blockly';, otrzymasz moduły domyślne: Blockly Core, wbudowane bloki Blockly, generator JavaScripta i tabelę lokalizacji Blockly dla języka angielskiego (en).

Aby załadować tabelę lokalizacji Blockly dla innego języka za pomocą npm:

Importowanie domyślnych modułów Blockly:

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

Zaimportuj tabelę lokalizacji Blockly dla swojej wersji językowej. Aby na przykład zaimportować tabelę dla języka hiszpańskiego (es):
```
import * as Es from 'blockly/msg/es';
```
Wczytaj tabelę za pomocą Blockly.setLocale. Ta funkcja kopiuje tabelę do obiektu Blockly.Msg.
```
Blockly.setLocale(Es);
```
setLocale jest uwzględniona tylko w wersji npm Blockly.

Ładowanie tabeli lokalizacji Blockly bez npm

Aby załadować tabelę lokalizacji Blockly bez użycia npm, użyj tagu <script>, aby załadować tabelę z katalogu msg. Na przykład:

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

Tabela lokalizacji jest wczytywana automatycznie.

Wczytaj własną tabelę lokalizacji

Jeśli zdefiniujesz własne tabele lokalizacji, musisz załadować tabelę dla wybranego języka.

Jeśli używasz npm, możesz to zrobić za pomocą Blockly.setLocale:
```
import * as Es from 'blockly/msg/es';
import {myEsTable} from '../my_tokens_es';
Blockly.setLocale(Es);
Blockly.setLocale(myEsTable);
```
setLocale kopiuje każdą parę klucz-wartość z obiektu wejściowego do obiektu Blockly.Msg. Możesz wywoływać ją wielokrotnie, podając różne klucze, ale wywołanie jej po raz drugi z duplikatem klucza spowoduje zastąpienie pierwszego.
Jeśli nie używasz npm, musisz ręcznie skopiować tabelę do pliku Blockly.Msg. (setLocale jest uwzględniona tylko w wersji npm Blockly). Najłatwiej jest zdefiniować własną wersję setLocale.
```
function mySetLocale(locale) {
  Object.keys(locale).forEach(function (k) {
    Blockly.Msg[k] = locale[k];
  }
}

mySetLocale(myEsTable);
```

Funkcje rozwiązywania odwołań do tokenów

Blockly udostępnia 2 funkcje rozwiązywania odwołań do tokenów: Blockly.utils.parsing.replaceMessageReferences (często używana) i Blockly.utils.parsing.tokenizeInterpolation (rzadko używana). W większości przypadków nie musisz wywoływać żadnej z tych funkcji. Dzieje się tak, ponieważ Blockly już je wywołuje w miejscach, w których obsługuje odwołania do tokenów. Na przykład Blockly używa tych funkcji do rozwiązywania odwołań do tokenów w kluczach messageN, tooltip i helpUrl w definicji bloku JSON.

Jednym z miejsc, w których możesz potrzebować pola replaceMessageReferences, są pola niestandardowe. Jeśli Twoje pole niestandardowe akceptuje odwołania do tokenów w dowolnej opcji, użyj opcji replaceMessageReferences, aby je rozwiązać. Więcej informacji znajdziesz w artykule JSON i rejestracja.

Powiązane artykuły

Języki z zapisem od prawej do lewej: obejrzyj demo.
Pomagaj w lokalizowaniu tekstu w Blockly: zobacz sekcję Tłumaczenie w sekcji poświęconej przyczynianiu się do rozwoju Blockly.

Załącznik: gdzie odwołania do tokenów są dozwolone

Odwołania do tokenów możesz używać w tych kluczach JSON:

W definicjach sekcji narzędzia kategorii:
- name
- colour
W definicjach bloków:
- messageN
- tooltip
- helpUrl
- colour
W opcjach przekazywanych do wszystkich pól:
- tooltip
W tablicach zagnieżdżonych przekazanych do options w funkcji field_dropdown:
- pierwszy element, gdy jest to ciąg znaków;
- wartość alt, gdy pierwszy element jest obiektem opisującym obraz;
W opcjach przekazywanych do field_variable:
- variable
W opcjach przekazywanych do field_label i field_label_serializable:
- text
W opcjach przekazywanych do field_image:
- height
- width
- src
- alt
W tematach:
- colour w stylach kategorii
- colourPrimary, colourSecondary i colourTertiary w stylu blokowym

oraz jako wartości argumentów w tych metodach:

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

W definicji XML skrzynki narzędzi w tych atrybutach:<category>:

name
colour

Więcej informacji o używaniu odwołań do tokenów jako wartości kolorów znajdziesz w artykule Odwołania do kolorów.

Lokalizacja Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.