chrome.i18n

Opis

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ść.

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".

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

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.

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

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

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

chrome.i18n.getUILanguage()