chrome.i18n

Opis

Plik manifestu

Jeśli rozszerzenie ma katalog /_locales, w pliku manifestu musi być zdefiniowany element "default_locale".

Pojęcia i zastosowanie

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

Oto hierarchia plików w przypadku rozszerzenia z wersjami w języku angielskim (en), hiszpańskim (es) i koreańskim (ko):

Obsługa wielu języków

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

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

Tak wygląda rozszerzenie po dostosowaniu do różnych języków (zauważ, ż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 ustawień regionalnych. Jeśli używasz nieobsługiwanego ustawienia regionalnego, Google Chrome je zignoruje.

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

  __MSG_messagename__
  

• W kodzie JavaScript rozszerzenia lub aplikacji odwołaj 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. 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 wiadomości znajdziesz w sekcji Wstępnie zdefiniowane wiadomości.

• W 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 w tym języku. Opcjonalny „opis” pomaga tłumaczom, którzy mogą nie widzieć, jak ciąg tekstowy 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 artykule Formaty: wiadomości dostosowane do ustawień regionalnych.

Po zinternacjonalizowaniu rozszerzenia jego przetłumaczenie jest proste. Kopiujesz plik messages.json, tłumaczysz go i umieszczasz kopię w nowym katalogu w folderze /_locales. Aby na przykład obsługiwać język hiszpański, wystarczy umieścić przetłumaczoną kopię pliku messages.json w folderze /_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 predefiniowanych komunikatów, które pomogą Ci dostosować aplikację do lokalnego rynku. Obejmują one @@ui_locale, dzięki czemu możesz wykryć bieżący język interfejsu, oraz kilka komunikatów @@bidi_..., które umożliwiają wykrycie kierunku tekstu. Te ostatnie wiadomości mają nazwy podobne do stałych w interfejsie API gadżetów BIDI (dwukierunkowym).

Specjalny komunikat @@extension_id można stosować w plikach CSS i JavaScript niezależnie od tego, czy rozszerzenie lub aplikacja są dostosowane do konkretnego języka. Ta wiadomość nie działa w plikach manifestu.

W tabeli poniżej znajdziesz opis każdej predefiniowanej wiadomości.

Oto przykład użycia znaku @@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 zmieni się na:

  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 angielski, pogrubione wiersze będą wyglądać tak:

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

Języki

Możesz wybierać spośród wielu ustawień regionalnych, 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 przetłumaczyć rozszerzenie na dowolny język obsługiwany przez Chrome Web Store. Jeśli Twojego regionu nie ma na liście, wybierz najbliższą alternatywę. Jeśli np. domyślny język rozszerzenia to "de_CH", w Chrome Web Store wybierz "de".

Wyszukiwanie wiadomości

Nie musisz definiować każdego ciągu znaków dla każdego obsługiwanego języka. Jeśli plik messages.jsondomyślnych ustawień regionalnych zawiera wartość dla każdego ciągu znaków, rozszerzenie lub aplikacja będzie działać niezależnie od tego, jak rzadkie jest tłumaczenie. Oto jak system rozszerzeń wyszukuje wiadomość:

1. Wyszukaj w pliku wiadomości (jeśli taki istnieje) preferowany język użytkownika. Jeśli na przykład w Google Chrome ustawiony jest język angielski (Wielka Brytania) (en_GB), system najpierw szuka komunikatu w /_locales/en_GB/messages.json. Jeśli ten plik istnieje i zawiera wiadomość, system nie szuka dalej.
2. Jeśli preferowany język użytkownika ma region (czyli zawiera podkreślenie: _), wyszukaj język bez tego regionu. Jeśli na przykład plik en_GB nie istnieje lub nie zawiera wiadomości, system wyszuka ją w pliku en. Jeśli ten plik istnieje i zawiera wiadomość, system nie szuka dalej.
3. Wyszukaj w pliku wiadomości domyślne ustawienia regionalne. Jeśli na przykład w przypadku rozszerzenia parametr „default_locale” ma wartość „es”, a ani /_locales/en_GB/messages.json, ani /_locales/en/messages.json nie zawiera wiadomości, rozszerzenie użyje wiadomości z pliku /_locales/es/messages.json.

Na ilustracji poniżej wiadomość o nazwie „colores” jest dostępna we wszystkich 3 językach, które obsługuje rozszerzenie, ale „extName” tylko w 2 z nich. W każdym miejscu, w którym użytkownik korzystający z Google Chrome w języku angielskim (Stany Zjednoczone) widzi etykietę „Colors”, użytkownik korzystający z języka angielskiego (Wielka Brytania) widzi etykietę „Colours”. Użytkownicy w Stanach Zjednoczonych i Wielkiej Brytanii zobaczą nazwę rozszerzenia „Hello World”. Ponieważ domyślnym językiem jest hiszpański, użytkownicy korzystający z Google Chrome w dowolnym języku innym niż angielski zobaczą etykietę „Colores” i nazwę rozszerzenia „Hola mundo”.

Ustawianie ustawień regionalnych przeglądarki

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

Windows

Możesz zmienić ustawienia regionalne za pomocą skrótu klawiszowego lub interfejsu Google Chrome. Po skonfigurowaniu skrótu jest on szybszy i umożliwia korzystanie z kilku języków jednocześnie.

Używanie skrótu dostosowanego do lokalizacji

Aby utworzyć i używać skrótu, który uruchamia Google Chrome w określonym języku:

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

3. Zmień właściwości skrótu, tak aby w polu Element docelowy były określone 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.

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 tym miejscem 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

Korzystanie z interfejsu

Aby zmienić ustawienia regionalne w interfejsie Google Chrome w systemie Windows:

1. Ikona aplikacji > Opcje
2. Wybierz kartę Pod maską.
3. Przewiń do sekcji Treści internetowe.
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 komputerze Mac, użyj preferencji systemowych.

1. W menu Apple wybierz Preferencje systemowe.
2. W sekcji Osobiste wybierz Międzynarodowe.
3. Wybierz język i lokalizację
4. Uruchom ponownie Chrome.

Linux

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

LANGUAGE=es ./chrome

ChromeOS

Aby zmienić ustawienia regionalne w ChromeOS:

1. Z obszaru powiadomień 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 języka kliknij ikonę z 3 kropkami Więcej działań 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 examples/extensions/news. Więcej przykładów i pomoc w wyświetlaniu kodu źródłowego znajdziesz w sekcji Przykłady.

getMessage()

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

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

Oto jak 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 symbolach zastępczych znajdziesz na stronie Wiadomości w określonym języku. Więcej informacji 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 poszczególne akceptowane języki 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 API.

detectLanguage()

Poniższy 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 API.

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

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

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

chrome.i18n.getUILanguage(): string