chrome.i18n

Opis

Aby wdrożyć międzynarodowość w całej aplikacji lub rozszerzeniu, użyj infrastruktury chrome.i18n.

Plik manifestu

Jeśli rozszerzenie ma katalog /_locales, plik manifestu musi definiować "default_locale".

Pojęcia i zastosowanie

Wszystkie widoczne dla użytkownika ciągi tekstowe należy umieścić w pliku o nazwie messages.json. Za każdym razem, gdy dodajesz nową lokalizację, dodajesz plik messages w katalogu o nazwie /_locales/_localeCode_, gdzie localeCode to kod, np. en w przypadku języka angielskiego.

Oto hierarchia plików rozszerzenia z międzynarodową obsługą języka angielskiego (en), hiszpańskiego (es) i koreańskiego (ko):

Obsługa wielu języków

Załóżmy, że masz rozszerzenie z plikami widocznymi na rysunku poniżej:

Aby zglobalizować to rozszerzenie, nadaj nazwę każdemu ciągowi znaków widocznemu dla użytkownika i umieścić go w pliku messages. Plik manifestu rozszerzenia, pliki CSS i kod JavaScript używają nazwy każdego ciągu znaków, aby uzyskać jego wersję w danym języku.

Tak wygląda rozszerzenie po zlokalizowaniu (zauważ, że nadal zawiera tylko ciągi tekstowe w języku angielskim):

Uwagi na temat międzynarodowości:

• Możesz użyć dowolnej obsługiwanej lokalizacji. Jeśli używasz nieobsługiwanego języka, Google Chrome go zignoruje.

• W plikach manifest.json i CSS odwołuj się do ciągu o nazwie messagename w ten sposób:

  __MSG_messagename__
  

• W kodzie JavaScript rozszerzenia lub aplikacji odwołuj się do ciągu tekstowego o nazwie messagename w ten sposób:

  chrome.i18n.getMessage("messagename")
  

• W każdym wywołaniu funkcji getMessage() możesz podać maksymalnie 9 ciągów znaków, które mają zostać uwzględnione w wiadomości. Więcej informacji znajdziesz w sekcji Przykłady: getMessage.

• Niektóre komunikaty, takie jak @@bidi_dir i @@ui_locale, są dostarczane przez system międzynarodowości. Pełną listę wstępnie zdefiniowanych nazw wiadomości znajdziesz w sekcji Wstępnie zdefiniowane wiadomości.

• W pliku messages.json każdy ciąg znaków widoczny dla użytkownika ma nazwę, element „message” (wiadomość) i opcjonalnie element „description” (opis). Nazwa to klucz, np. „extName” lub „search_string”, który identyfikuje ciąg znaków. Parametr „message” określa wartość ciągu w danym regionie językowym. Opcjonalny parametr „description” ułatwia pracę tłumaczom, którzy mogą nie widzieć, jak ciąg znaków jest używany w Twoim rozszerzeniu. Na przykład:

  {
    "search_string": {
      "message": "hello%20world",
      "description": "The string we search for. Put %20 between words that go together."
    },
    ...
  }
  

Więcej informacji znajdziesz w sekcji Formaty: wiadomości w językach lokalnych.

Po zindywidualizowaniu rozszerzenia tłumaczenie go jest proste. Skopiuj plik messages.json, przetłumacz go i umieść kopię w nowym katalogu pod folderem /_locales. Aby na przykład uwzględnić język hiszpański, umieść przetłumaczoną wersję elementu messages.json w elemencie /_locales/es. Na rysunku poniżej widać poprzednią wersję rozszerzenia z nową hiszpańską wersją językową.

Zdefiniowane wstępnie wiadomości

System międzynarodowy udostępnia kilka wstępnie zdefiniowanych wiadomości, które ułatwiają lokalizację. Te komunikaty to @@ui_locale, dzięki którym możesz wykryć bieżącą lokalizację interfejsu, oraz kilka komunikatów @@bidi_..., które pozwalają wykryć kierunek tekstu. Te ostatnie mają nazwy podobne do stałych w interfejsie gadgets BIDI (dwukierunkowym) API.

Specjalny komunikat @@extension_id można używać w plikach CSS i JavaScript niezależnie od tego, czy rozszerzenie lub aplikacja są zlokalizowane. Ta wiadomość nie działa w plikach manifestu.

W tabeli poniżej opisujemy każdą zdefiniowaną wstępnie wiadomość.

Nazwa wiadomości	Opis
@@extension_id	Identyfikator rozszerzenia lub aplikacji; możesz użyć tego ciągu znaków do tworzenia adresów URL zasobów w rozszerzeniu. Z tego komunikatu mogą korzystać nawet nieprzetłumaczone rozszerzenia. Uwaga: nie możesz używać tego komunikatu w pliku manifestu.
@@ui_locale	bieżąca lokalizacja; możesz użyć tego ciągu znaków do tworzenia adresów URL przeznaczonych dla określonych lokalizacji;
@@bidi_dir	kierunek tekstu dla bieżącego języka, „ltr” dla języków z pisownią od lewej do prawej, takich jak angielski, lub „rtl” dla języków z pisownią od prawej do lewej, takich jak arabski;
@@bidi_reversed_dir	Jeśli @@bidi_dir ma wartość „ltr”, to jest to „rtl”, w przeciwnym razie jest to „ltr”.
@@bidi_start_edge	Jeśli @@bidi_dir ma wartość „ltr”, to jest to „lewo”; w przeciwnym razie jest to „prawo”.
@@bidi_end_edge	Jeśli @@bidi_dir ma wartość „ltr”, to jest to „prawo”; w przeciwnym razie jest to „lewo”.

Oto przykład użycia elementu @@extension_id w pliku CSS do tworzenia adresów URL:

body {
  background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}

Jeśli identyfikator rozszerzenia to abcdefghijklmnopqrstuvwxyzabcdef, pogrubiony wiersz w poprzednim fragmencie kodu będzie wyglądał tak:

  background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png');

Oto przykład użycia komunikatów @@bidi_* w pliku CSS:

body {
  direction: __MSG_@@bidi_dir__;
}

div#header {
  margin-bottom: 1.05em;
  overflow: hidden;
  padding-bottom: 1.5em;
  padding-__MSG_@@bidi_start_edge__: 0;
  padding-__MSG_@@bidi_end_edge__: 1.5em;
  position: relative;
}

W przypadku języków pisanych od lewej do prawej, takich jak polski, pogrubione linie stają się:

  dir: ltr;
  padding-left: 0;
  padding-right: 1.5em;

Języki

Możesz wybrać wiele lokalizacji, w tym niektóre (np. en), które umożliwiają tłumaczenie jednego tekstu na różne wersje języka (np. en_GB i en_US).

Możesz zlokalizować rozszerzenie na potrzeby dowolnego regionu obsługiwanego przez Chrome Web Store. Jeśli Twojego regionu nie ma na liście, wybierz najbliższą alternatywę. Jeśli na przykład domyślny język rozszerzenia to "de_CH", w Chrome Web Store wybierz "de".

Kod języka	Język (region)
ar	arabski
am	amharski
bg	bułgarski
bn	bengalski
urząd certyfikacji	kataloński
cs	czeski
da	duński
de	niemiecki
el	grecki
en	angielski
en_AU	angielski (Australia)
en_GB	angielski (Wielka Brytania)
pl_PL	angielski (USA)
es	hiszpański
es_419	hiszpański (Ameryka Łacińska i Karaiby)
et	estoński
fa	perski
fi	fiński
fil	filipiński
fr	francuski
gu	gudżarati
on	hebrajski
hi	hindi
h	chorwacki
hu	węgierski
id	indonezyjski
it	włoski
ja	japoński
kn	kannada
ko	koreański
lt	litewski
lv	łotewski
ml	malajalam
mr	marathi
ms	malajski
nl	niderlandzki
nie	norweski
pl	polski
pt_BR	portugalski (Brazylia)
pt_PT	portugalski (Portugalia)
ro	rumuński
ru	rosyjski
sk	słowacki
sl	słoweński
sr	serbski
sv	szwedzki
sw	suahili
ta	tamilski
te	telugu
th	tajski
tr	turecki
uk	ukraiński
vi	wietnamski
zh_CN	chiński (Chiny)
zh_TW	chiński (Tajwan)

Wyszukiwanie wiadomości

Nie musisz definiować wszystkich ciągów znaków dla wszystkich obsługiwanych języków. Dopóki plik messages.json domyślnej lokalizacji zawiera wartość dla każdego ciągu znaków, rozszerzenie lub aplikacja będą działać niezależnie od tego, jak skąpa jest treść tłumaczenia. Oto jak system rozszerzeń wyszukuje wiadomość:

1. W pliku wiadomości (jeśli istnieje) wyszukaj preferowany język użytkownika. Jeśli na przykład lokalizacja Google Chrome jest ustawiona na język angielski (en_GB), system najpierw szuka wiadomości w języku /_locales/en_GB/messages.json. Jeśli plik istnieje i zawiera wiadomość, system nie szuka dalej.
2. Jeśli preferowany język użytkownika ma region (czyli zawiera znak podkreślenia: _), wyszukaj język bez regionu. Jeśli na przykład plik wiadomości en_GB nie istnieje lub nie zawiera wiadomości, system sprawdza plik wiadomości en. Jeśli plik istnieje i zawiera wiadomość, system nie szuka dalej.
3. W pliku wiadomości wyszukaj domyślny język. Jeśli na przykład parametr „default_locale” rozszerzenia ma wartość „es”, a żadna z opcji /_locales/en_GB/messages.json ani /_locales/en/messages.json nie zawiera wiadomości, rozszerzenie używa wiadomości z /_locales/es/messages.json.

Na poniższym rysunku wiadomość o nazwie „colores” występuje we wszystkich 3 regionach, które obsługuje rozszerzenie, ale wiadomość o nazwie „extName” występuje tylko w 2 regionach. W przypadku użytkownika korzystającego z Google Chrome w języku angielskim (amerykańskim) etykieta „Colors” (kolory) jest wyświetlana jako „Colours” (kolory). Użytkownicy anglojęzyczni (amerykańska i brytyjska odmiana języka angielskiego) widzą nazwę rozszerzenia „Hello World”. Ponieważ językiem domyślnym jest hiszpański, użytkownicy korzystający z Google Chrome w innym języku niż angielski widzą etykietę „Colores” i nazwę rozszerzenia „Hola mundo”.

Ustawianie języka przeglądarki

Aby przetestować tłumaczenia, możesz ustawić język w przeglądarce. W tej sekcji dowiesz się, jak ustawić język w Windows, Mac OS, Linux i ChromeOS.

Windows

Możesz zmienić język za pomocą skrótu lub interfejsu Google Chrome. Po skonfigurowaniu skrótów możesz używać kilku języków jednocześnie, co jest szybsze niż tworzenie osobnych skrótów dla każdego języka.

Używanie skrótu dostosowanego do lokalizacji

Aby utworzyć skrót, który uruchamia Google Chrome z określonym ustawieniem języka i lokalizacji:

1. Utwórz kopię skrótu Google Chrome, który jest już na pulpicie.
2. Zmień nazwę nowego skrótu, aby pasowała do nowego regionu.

3. Zmień właściwości skrótu, aby pole Docelowy zawierało flagi --lang i --user-data-dir. Docelowy element powinien wyglądać mniej więcej tak:

   path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
   

4. Uruchom Google Chrome, klikając dwukrotnie skrót.

Aby na przykład utworzyć skrót, który uruchamia Google Chrome w języku hiszpańskim (es), możesz utworzyć skrót o nazwie chrome-es z takim celem:

path_to_chrome.exe --lang=es --user-data-dir=c:\chrome-profile-es

Możesz utworzyć dowolną liczbę skrótów, co ułatwia testowanie w wielu językach. Przykład:

path_to_chrome.exe --lang=en --user-data-dir=c:\chrome-profile-en
path_to_chrome.exe --lang=en_GB --user-data-dir=c:\chrome-profile-en_GB
path_to_chrome.exe --lang=ko --user-data-dir=c:\chrome-profile-ko

Uwaga: podanie wartości --user-data-dir jest opcjonalne, ale przydatne. Mając jeden katalog danych na lokalizację, możesz uruchamiać przeglądarkę w kilku językach jednocześnie. Wadą jest to, że dane dotyczące lokalizacji nie są udostępniane, więc musisz zainstalować rozszerzenie kilka razy – raz na lokalizację, co może być trudne, jeśli nie znasz języka. Więcej informacji znajdziesz w artykule Tworzenie profili i korzystanie z nich.

Korzystanie z interfejsu

Aby zmienić język za pomocą interfejsu użytkownika w Google Chrome na Windowsa:

1. Ikona aplikacji > Opcje.
2. Kliknij kartę Podstawy.
3. Przewiń do sekcji Treści internetowe.
4. Kliknij Zmień ustawienia czcionki i języka.
5. Wybierz kartę Języki.
6. W menu wybierz język Google Chrome.
7. Uruchom ponownie Chrome.

System operacyjny macOS

Aby zmienić język na Macu, użyj ustawień systemowych.

1. W menu Apple wybierz Preferencje systemowe.
2. W sekcji Osobiście wybierz Międzynarodowy.
3. Wybierz język i lokalizację
4. Uruchom ponownie Chrome.

Linux

Aby zmienić język w Linuksie, najpierw zamknij Google Chrome. Następnie na jednym wierszu ustaw zmienną środowiskową LANGUAGE i uruchom Google Chrome. Na przykład:

LANGUAGE=es ./chrome

ChromeOS

Aby zmienić lokalizację w ChromeOS:

1. Na pasku systemowym wybierz Ustawienia.
2. W sekcji Języki i metody wprowadzania kliknij menu Język.
3. Jeśli Twojego języka nie ma na liście, kliknij Dodaj języki i dodaj go.
4. Po dodaniu kliknij menu z 3 kropkami Więcej działań obok języka i wybierz Wyświetlaj ChromeOS w tym języku.
5. Aby ponownie uruchomić ChromeOS, kliknij przycisk Restart (Uruchom ponownie) obok wybranego języka.

Przykłady

Przykłady internacjonalizacji znajdziesz w katalogu examples/api/i18n. Pełny przykład znajdziesz w sekcji Przykłady/rozszerzenia/wiadomości. Inne przykłady i informacje o wyświetlaniu kodu źródłowego znajdziesz w sekcji Przykłady.

getMessage()

Poniższy kod pobiera z przeglądarki spersonalizowany komunikat i wyświetla go jako ciąg znaków. Zastępuje 2 obiekty zastępcze w wiadomości ciągami tekstowymi „string1” i „string2”.

function getMessage() {
  var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
  document.getElementById("languageSpan").innerHTML = message;
}

Oto jak podać i wykorzystać pojedynczy ciąg znaków:

  // In JavaScript code
  status.innerText = chrome.i18n.getMessage("error", errorDetails);

"error": {
  "message": "Error: $details$",
  "description": "Generic error template. Expects error parameter to be passed in.",
  "placeholders": {
    "details": {
      "content": "$1",
      "example": "Failed to fetch RSS feed."
    }
  }
}

Więcej informacji o wstawkach znajdziesz na stronie Wiadomości zależne od lokalizacji. Szczegółowe informacje o wywoływaniu funkcji getMessage() znajdziesz w dokumentacji interfejsu API.

getAcceptLanguages()

Poniższy kod pobiera z przeglądarki języki akceptowane przez przeglądarkę i wyświetla je jako ciąg znaków, oddzielając każdy język akceptowany przez przeglądarkę znakiem „,”.

function getAcceptLanguages() {
  chrome.i18n.getAcceptLanguages(function(languageList) {
    var languages = languageList.join(",");
    document.getElementById("languageSpan").innerHTML = languages;
  })
}

Szczegółowe informacje o wywoływaniu funkcji getAcceptLanguages() znajdziesz w dokumentacji interfejsu API.

detectLanguage()

Podany niżej kod wykrywa maksymalnie 3 języki w danym ciągu znaków i wyświetla wynik jako ciągi znaków rozdzielone znakami nowego wiersza.

function detectLanguage(inputText) {
  chrome.i18n.detectLanguage(inputText, function(result) {
    var outputLang = "Detected Language: ";
    var outputPercent = "Language Percentage: ";
    for(i = 0; i < result.languages.length; i++) {
      outputLang += result.languages[i].language + " ";
      outputPercent +=result.languages[i].percentage + " ";
    }
    document.getElementById("languageSpan").innerHTML = outputLang + "\n" + outputPercent + "\nReliable: " + result.isReliable;
  });
}

Więcej informacji o wywoływaniu funkcji detectLanguage(inputText) znajdziesz w dokumentacji interfejsu API.

Typy

LanguageCode

Chrome 47 lub nowszy

Kod języka ISO, np. en lub fr. Pełną listę języków obsługiwanych przez tę metodę znajdziesz w stałym polu kLanguageInfoTable. W przypadku nieznanego języka zwrócona zostanie wartość und, co oznacza, że CLD nie zna [procent] tekstu.

Typ

ciąg znaków

Metody

detectLanguage()

Obietnica Chrome 47 lub nowszy

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

Wykrywanie języka, w jakim napisano podany tekst, za pomocą CLD.

Parametry

• tekst

  ciąg znaków

  Ciąg tekstowy wprowadzony przez użytkownika do przetłumaczenia.

• wywołanie zwrotne

  function opcjonalny

  Parametr callback ma postać:

  (result: object) => void

  • wynik

    Obiekt

    Obiekt LanguageDetectionResult, który zawiera wiarygodność wykrytego języka i tablicę DetectedLanguage

    • isReliable

      wartość logiczna

      Zaufanie do wykrycia języka przez CLD

    • języki

      object[]

      tablica detectedLanguage

      • language

        ciąg znaków

      • procent

        liczba

        odsetek wykrytego języka,

Zwroty

• Obietkw<object>

  Chrome 99+

  Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getAcceptLanguages()

Obietnice

chrome.i18n.getAcceptLanguages(
  callback?: function,
)

Pobiera z przeglądarki języki akceptowane przez przeglądarkę. Wartość ta różni się od ustawień języka w przeglądarce. Aby uzyskać ustawienia języka, użyj parametru i18n.getUILanguage.

Parametry

• wywołanie zwrotne

  function opcjonalny

  Parametr callback ma postać:

  (languages: string[]) => void

  • języki

    string[]

    Tablica LanguageCode

Zwroty

• Promise<LanguageCode[]>

  Chrome 99+

  Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getMessage()

chrome.i18n.getMessage(
  messageName: string,
  substitutions?: any,
  options?: object,
)

Pobiera zlokalizowany ciąg tekstowy dla określonej wiadomości. Jeśli brakuje wiadomości, ta metoda zwraca pusty ciąg znaków („”). Jeśli format wywołania funkcji getMessage() jest nieprawidłowy, np. parametr messageName nie jest ciągiem znaków lub tablica substitutions zawiera więcej niż 9 elementów, ta metoda zwraca undefined.

Parametry

• messageName

  ciąg znaków

  Nazwa wiadomości określona w pliku messages.json.

• zastępowania,

  dowolne opcjonalne

  maksymalnie 9 ciągów znaków do zastąpienia, jeśli wiadomość ich wymaga;

• Opcje

  object opcjonalne

  Chrome 79 lub nowszy
  • escapeLt

    wartość logiczna opcjonalna

    Escape < w tłumaczeniu na język <. Dotyczy to tylko samego komunikatu, a nie placeholderów. Deweloperzy mogą użyć tego atrybutu, jeśli tłumaczenie jest używane w kontekście HTML. Szablony Closure używane z Closure Compiler generują to automatycznie.

Zwroty

• ciąg znaków

  wiadomość przetłumaczona na potrzeby bieżącego języka;

getUILanguage()

chrome.i18n.getUILanguage()

Pobiera język interfejsu przeglądarki. Różni się to od funkcji i18n.getAcceptLanguages, która zwraca preferowane języki użytkownika.

Zwroty

• ciąg znaków

  Kod języka interfejsu przeglądarki, np. pl-PL lub en-US.