browser.i18n

Opis

Użyj infrastruktury chrome.i18n, aby zaimplementować internacjonalizację w całej aplikacji lub rozszerzeniu.

Plik manifestu

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

Pojęcia i użycie

Wszystkie ciągi tekstowe widoczne dla użytkowników musisz umieścić w pliku o nazwie messages.json. Za każdym razem, gdy dodajesz nowe ustawienia regionalne, dodajesz plik wiadomości w katalogu o nazwie /_locales/_localeCode_, gdzie localeCode to kod, np. en dla języka angielskiego.

Oto hierarchia plików w przypadku rozszerzenia zinternacjonalizowanego, które obsługuje język angielski (en), hiszpański (es) i koreański (ko):

Obsługa wielu języków

Załóżmy, że masz rozszerzenie z plikami pokazanymi na ilustracji poniżej:

Aby dostosować to rozszerzenie do różnych języków, nazwij każdy ciąg znaków widoczny dla użytkownika i umieść go w pliku wiadomości. Plik manifestu rozszerzenia, pliki CSS i kod JavaScript używają nazwy każdego ciągu znaków, aby uzyskać jego zlokalizowaną wersję.

Oto jak wygląda rozszerzenie po umiędzynarodowieniu (pamiętaj, że nadal zawiera tylko ciągi znaków w języku angielskim):

Kilka uwag na temat internacjonalizacji:

• Możesz użyć dowolnego z obsługiwanych języków. Jeśli użyjesz nieobsługiwanych ustawień regionalnych, Google Chrome je 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łaj się do ciągu o nazwie messagename w ten sposób:

  browser.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 komunikacie. Szczegółowe informacje znajdziesz w sekcji Przykłady: getMessage.

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

• W pliku messages.json każdy ciąg znaków widoczny dla użytkownika ma nazwę, element „message” i opcjonalny element „description”. Nazwa to klucz, np. „extName” lub „search_string”, który identyfikuje ciąg znaków. „message” określa wartość ciągu znaków w danym języku. Opcjonalny element „description” (opis) pomaga tłumaczom, którzy mogą nie widzieć, jak ciąg znaków jest używany w 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 artykule Formats: Locale-Specific Messages (Formaty: wiadomości zależne od języka).

Po umiędzynarodowieniu rozszerzenia jego tłumaczenie jest proste. Skopiuj plik messages.json, przetłumacz go i umieść kopię w nowym katalogu w /_locales. Na przykład, aby obsługiwać język hiszpański, wystarczy umieścić przetłumaczoną kopię pliku messages.json w katalogu /_locales/es. Na ilustracji poniżej widać poprzednie rozszerzenie z nowym tłumaczeniem na język hiszpański.

Wstępnie zdefiniowane wiadomości

System internacjonalizacji udostępnia kilka wstępnie zdefiniowanych komunikatów, które ułatwiają lokalizację. Obejmują one @@ui_locale, dzięki czemu możesz wykryć bieżące ustawienia regionalne interfejsu, oraz kilka komunikatów @@bidi_..., które pozwalają wykryć kierunek tekstu. Te ostatnie komunikaty mają nazwy podobne do stałych w interfejsie API gadżetów BIDI (dwukierunkowym).

Komunikat specjalny @@extension_id może być używany w plikach CSS i JavaScript niezależnie od tego, czy rozszerzenie lub aplikacja są zlokalizowane. Ten komunikat nie działa w plikach manifestu.

W tabeli poniżej znajdziesz opis każdej wstępnie zdefiniowanej wiadomości.

Nazwa wiadomości	Opis
@@extension_id	Identyfikator rozszerzenia lub aplikacji. Możesz użyć tego ciągu znaków do utworzenia adresów URL zasobów w rozszerzeniu. Nawet niezlokalizowane rozszerzenia mogą używać tego komunikatu. Uwaga: nie możesz używać tego komunikatu w pliku manifestu.
@@ui_locale	Bieżące ustawienia regionalne. Możesz użyć tego ciągu znaków do utworzenia adresów URL przeznaczonych dla określonych lokalizacji.
@@bidi_dir	Kierunek tekstu w bieżących ustawieniach regionalnych: „ltr” w przypadku języków pisanych od lewej do prawej (np. polskiego) lub „rtl” w przypadku języków pisanych od prawej do lewej (np. arabskiego).
@@bidi_reversed_dir	Jeśli @@bidi_dir to „ltr”, to jest „rtl”, w przeciwnym razie jest to „ltr”.
@@bidi_start_edge	Jeśli @@bidi_dir ma wartość „ltr”, to jest to „left”, w przeciwnym razie jest to „right”.
@@bidi_end_edge	Jeśli @@bidi_dir ma wartość „ltr”, to jest to „right”, w przeciwnym razie jest to „left”.

Oto przykład użycia @@extension_id w pliku CSS do utworzenia adresu 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 oznaczają:

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

Języki

Możesz wybrać spośród wielu języków, w tym takich (np. en), które umożliwiają obsługę wielu odmian języka (np. en_GB i en_US) za pomocą jednego tłumaczenia.

Możesz zlokalizować rozszerzenie na dowolny język obsługiwany przez Chrome Web Store. Jeśli Twojego regionu nie ma na liście, wybierz najbliższy. Jeśli na przykład domyślnym językiem rozszerzenia jest "de_CH", w Chrome Web Store wybierz "de".

Kod języka	Język (region)
ar	arabski
am	amharski
bg	bułgarski
bn	bengalski
ca	kataloński
cs	czeski
da	duński
de	niemiecki
el	grecki
en	angielski
en_AU	angielski (Australia)
en_GB	angielski (Wielka Brytania)
en_US	angielski (Stany Zjednoczone)
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
he	hebrajski
hi	hindi
hr	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
no	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ć każdego ciągu znaków dla każdego obsługiwanego języka. Jeśli plik messages.json domyślnego języka zawiera wartość dla każdego ciągu, rozszerzenie lub aplikacja będzie działać niezależnie od tego, jak niekompletne jest tłumaczenie. Oto jak system rozszerzeń wyszukuje komunikat:

1. Wyszukaj w pliku wiadomości (jeśli istnieje) preferowane ustawienia regionalne użytkownika. Jeśli na przykład w Google Chrome ustawiony jest brytyjski angielski (en_GB), system najpierw szuka wiadomości w /_locales/en_GB/messages.json. Jeśli ten plik istnieje i zawiera wiadomość, system nie szuka dalej.
2. Jeśli preferowane ustawienia regionalne użytkownika zawierają region (czyli ustawienia regionalne zawierają podkreślenie: _), wyszukaj ustawienia regionalne bez tego regionu. Jeśli na przykład plik wiadomości en_GB nie istnieje lub nie zawiera wiadomości, system wyszuka ją w pliku wiadomości en. Jeśli ten plik istnieje i zawiera wiadomość, system nie szuka dalej.
3. Wyszukaj plik wiadomości dla domyślnego języka. Jeśli na przykład „default_locale” rozszerzenia jest ustawione na „es”, a wiadomość nie znajduje się ani w /_locales/en_GB/messages.json, ani w /_locales/en/messages.json, rozszerzenie użyje wiadomości z /_locales/es/messages.json.

Na poniższym rysunku komunikat o nazwie „colores” jest we wszystkich 3 językach obsługiwanych przez rozszerzenie, ale „extName” jest tylko w 2 z nich. Wszędzie tam, gdzie użytkownik korzystający z Google Chrome w języku angielskim (USA) widzi etykietę „Colors”, użytkownik korzystający z języka angielskiego (Wielka Brytania) widzi „Colours”. Użytkownicy korzystający z amerykańskiej i brytyjskiej odmiany języka angielskiego zobaczą nazwę rozszerzenia „Hello World”. Ponieważ domyślnym językiem jest hiszpański, użytkownicy korzystający z Google Chrome w języku innym niż angielski widzą etykietę „Colores” i nazwę rozszerzenia „Hola mundo”.

Ustawianie języka przeglądarki

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

Windows

Możesz zmienić ustawienia regionalne, używając skrótu klawiszowego dla danego regionu lub interfejsu Google Chrome. Po skonfigurowaniu skrótów możesz szybciej i wygodniej korzystać z kilku języków jednocześnie.

Używanie skrótu przeznaczonego dla określonej lokalizacji

Aby utworzyć i użyć skrótu, który uruchamia Google Chrome z określonymi ustawieniami regionalnymi:

1. Utwórz kopię skrótu do Google Chrome, który znajduje się już na pulpicie.
2. Zmień nazwę nowego skrótu, aby odpowiadała nowemu językowi.

3. Zmień właściwości skrótu, tak aby pole Cel zawierało flagi --lang i --user-data-dir. Cel 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.

Jeśli na przykład chcesz utworzyć skrót, który uruchamia Google Chrome w języku hiszpańskim (es), możesz utworzyć skrót o nazwie chrome-es z następującym elementem docelowym:

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: określenie --user-data-dir jest opcjonalne, ale przydatne. Jeśli masz 1 katalog danych na język, możesz uruchomić przeglądarkę w kilku językach jednocześnie. Wadą jest to, że dane z różnych regionów nie są udostępniane, więc musisz zainstalować rozszerzenie kilka razy – po jednym dla każdego regionu, co może być trudne, jeśli nie znasz języka. Więcej informacji znajdziesz w artykule Tworzenie i używanie profili.

Korzystanie z interfejsu użytkownika

Aby zmienić ustawienia regionalne za pomocą interfejsu Google Chrome w systemie Windows:

1. Ikona aplikacji > Opcje
2. Wybierz kartę Za kulisami.
3. Przewiń do sekcji Treści z internetu.
4. Kliknij Zmień ustawienia czcionki i języka.
5. Wybierz kartę Języki.
6. Użyj menu, aby ustawić język Google Chrome.
7. Uruchom ponownie Chrome.

System operacyjny macOS

Aby zmienić ustawienia regionalne na Macu, użyj preferencji systemowych.

1. Z menu Apple wybierz Preferencje systemowe.
2. W sekcji Osobiste wybierz Międzynarodowe.
3. Wybieranie języka i lokalizacji
4. Uruchom ponownie Chrome.

Linux

Aby zmienić ustawienia regionalne w systemie Linux, najpierw zamknij Google Chrome. Następnie w jednej linii ustaw zmienną środowiskową LANGUAGE i uruchom Google Chrome. Na przykład:

LANGUAGE=es ./chrome

ChromeOS

Aby zmienić ustawienia regionalne w ChromeOS:

1. W obszarze powiadomień wybierz Ustawienia.
2. W sekcji Języki i wprowadzanie 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 Więcej działań z 3 kropkami obok języka i wybierz Wyświetlaj ChromeOS w tym języku.
5. Kliknij przycisk Uruchom ponownie, który pojawi się obok ustawionego języka, aby ponownie uruchomić ChromeOS.

Przykłady

Przykłady internacjonalizacji znajdziesz w katalogu examples/api/i18n. Pełny przykład znajdziesz w sekcji examples/extensions/news. Inne przykłady i pomoc w wyświetlaniu kodu źródłowego znajdziesz w sekcji Przykłady.

getMessage()

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

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

Oto jak możesz podać i użyć pojedynczego ciągu 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 obiektach zastępczych znajdziesz na stronie Wiadomości zależne od języka. Szczegółowe informacje o wywoływaniu getMessage() znajdziesz w dokumentacji API.

getAcceptLanguages()

Poniższy kod pobiera z przeglądarki akceptowane języki i wyświetla je jako ciąg znaków, oddzielając każdy z nich przecinkiem.

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

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

detectLanguage()

Poniższy kod wykrywa maksymalnie 3 języki w podanym 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 detectLanguage(inputText) znajdziesz w dokumentacji API.

Typy

LanguageCode

Chrome 47 lub nowsza browser.* od Chrome 148

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

Typ

tekst

Metody

detectLanguage()

Chrome 47 lub nowsza browser.* od Chrome 148

browser.i18n.detectLanguage(
  text: string,
): Promise<object>

Wykrywa język podanego tekstu za pomocą CLD.

Parametry

• tekst

  tekst

  Ciąg znaków wprowadzony przez użytkownika, który ma zostać przetłumaczony.

Zwroty

• Promise<object>

  Chrome 99 lub nowsza wersja browser.* od Chrome 148

getAcceptLanguages()

browser.i18n.getAcceptLanguages(): Promise<LanguageCode[]>

Pobiera języki akceptowane przez przeglądarkę. Różni się on od języka używanego przez przeglądarkę. Aby uzyskać język, użyj i18n.getUILanguage.

Zwroty

• Promise<LanguageCode[]>

  Chrome 99 lub nowsza wersja browser.* od Chrome 148

getMessage()

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

Pobiera zlokalizowany ciąg znaków dla określonej wiadomości. Jeśli nie ma wiadomości, ta metoda zwraca pusty ciąg znaków (''). Jeśli format wywołania getMessage() jest nieprawidłowy – na przykład messageName nie jest ciągiem znaków lub tablica substitutions zawiera więcej niż 9 elementów – ta metoda zwraca undefined.

Parametry

• messageName

  tekst

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

• zamienniki

  any optional

  Maksymalnie 9 ciągów zastępczych, jeśli wiadomość ich wymaga.

• Opcje

  object opcjonalny

  Chrome 79 lub nowsza browser.* od Chrome 148
  • escapeLt

    boolean opcjonalne

    Znak < w tłumaczeniu na język <. Dotyczy to tylko samej wiadomości, a nie obiektów zastępczych. Deweloperzy mogą używać tej opcji, jeśli tłumaczenie jest używane w kontekście HTML. Szablony Closure używane z kompilatorem Closure generują to automatycznie.

Zwroty

• tekst

  Wiadomość zlokalizowana dla bieżących ustawień regionalnych.

getUILanguage()

browser.i18n.getUILanguage(): string

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

Zwroty

• tekst

  Kod języka interfejsu przeglądarki, np. en-US lub fr-FR.