chrome.i18n

Opis

Plik manifestu

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

Pojęcia i zastosowanie

Wszystkie ciągi widoczne dla użytkowników musisz umieścić w pliku o nazwie messages.json. Za każdym razem, gdy dodajesz nowy język, dodajesz plik wiadomości w katalogu o nazwie /_locales/_localeCode_, gdzie localeCode jest kodem, np. en w języku angielskim.

Oto hierarchia plików międzynarodowego rozszerzenia obsługującego angielski (en), hiszpański (es) i koreański (ko):

Obsługa wielu języków

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

Aby internacjonalizować to rozszerzenie, nadaj nazwę każdemu ciągowi widocznemu dla użytkownika i umieść go w pliku wiadomości. W pliku manifestu rozszerzenia, plikach CSS i kodzie JavaScript jest używana nazwa każdego ciągu znaków, aby uzyskać jego zlokalizowaną wersję.

Tak wygląda rozszerzenie po wersji międzynarodowej (pamiętaj, że nadal zawiera tylko ciągi angielskie):

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locates="" a="" alt="W pliku manifest.json " and="" been="" changed="" chrome.i18n.getmessage("extname"="" hasvworld="" enmessage("extname").="" hasvworld="" enjavascript="" file="" file="" file"

Kilka uwag na temat internacjonalizacji:

• Możesz użyć dowolnego z obsługiwanych języków. Jeśli używasz nieobsługiwanego ustawienia lokalnego, Google Chrome je ignoruje.

• W plikach manifest.json i CSS znajdź ciąg znaków o nazwie messagename w ten sposób:

  __MSG_messagename__
  

• W kodzie JavaScript rozszerzenia lub aplikacji odnieś się do ciągu znaków o nazwie messagename w ten sposób:

  chrome.i18n.getMessage("messagename")
  

• W każdym wywołaniu funkcji getMessage() możesz umieścić maksymalnie 9 ciągów znaków, które będą zawarte w wiadomości. Szczegółowe informacje znajdziesz w sekcji Przykłady: getMessage.

• Niektóre wiadomości, na przykład @@bidi_dir i @@ui_locale, są dostarczane przez system internacjonalizacji. Pełną listę wstępnie zdefiniowanych nazw wiadomości znajdziesz w sekcji Wstępnie zdefiniowane wiadomości.

• W metodzie messages.json każdy ciąg widoczny dla użytkownika ma nazwę, element „wiadomość” i opcjonalny element „opis”. Nazwa jest kluczem, takim jak „extName” czy „ciąg_wyszukiwania”, który identyfikuje ciąg znaków. Pole „message” określa wartość ciągu znaków w danym języku. Opcjonalny opis to ułatwienie tłumaczom, którzy mogą nie być w stanie zobaczyć sposobu użycia ciągu znaków 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 Formaty: wiadomości specyficzne dla języka.

Po umiędzynarodowieniu rozszerzenia można łatwo go przetłumaczyć. Kopiujesz plik messages.json, tłumaczysz go i umieszczasz w nowym katalogu w lokalizacji /_locates. Na przykład: aby obsługiwać język hiszpański, umieść przetłumaczoną kopię messages.json w polu /_locates/es. Poniższy rysunek przedstawia poprzednie rozszerzenie w nowym tłumaczeniu na język hiszpański.

Wstępnie zdefiniowane wiadomości

System internacjonalizacji udostępnia kilka wstępnie zdefiniowanych wiadomości ułatwiających lokalizację. Obejmują one @@ui_locale, który pozwala wykryć bieżący język interfejsu, oraz kilka komunikatów @@bidi_..., które pozwalają określić kierunek tekstu. Te ostatnie wiadomości mają nazwy podobne do stałych w interfejsie API bidI (dwukierunkowy) gadżetów.

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

Tabela poniżej zawiera opis poszczególnych wstępnie zdefiniowanych wiadomości.

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 zmieni się w:

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

Oto przykład użycia wiadomości @@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, np. angielskiego, pogrubione wiersze wyglądają tak:

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

Języki

Możesz wybrać wiele języków, w tym niektóre (np. en), dzięki czemu jedno tłumaczenie obsługuje wiele wersji językowych (np. en_GB i en_US).

Rozszerzenie możesz zlokalizować na dowolny język obsługiwany w Chrome Web Store. Jeśli Twojej lokalizacji nie ma na liście, wybierz najbliższą alternatywę. Jeśli na przykład domyślnym językiem rozszerzenia jest "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.json w domyślnej wersji językowej zawiera wartość każdego ciągu znaków, rozszerzenie lub aplikacja będzie działać niezależnie od tego, jak proste jest tłumaczenie. Oto jak system rozszerzeń wyszukuje wiadomość:

1. Wyszukaj w pliku wiadomości (jeśli istnieje) preferowany język użytkownika. Jeśli na przykład w języku Google Chrome ustawiony jest brytyjski angielski (en_GB), system najpierw wyszukuje wiadomość w języku /_locates/en_GB/messages.json. Jeśli plik istnieje, a konkretnie pojawi się w nim wiadomość, system nie szuka dalej.
2. Jeśli preferowany język użytkownika obejmuje region (czyli jest on z podkreśleniem: _), przeszukaj język bez tego regionu. Jeśli na przykład plik wiadomości en_GB nie istnieje lub nie zawiera wiadomości, system przeszukuje plik wiadomości en. Jeśli plik istnieje, a konkretna wiadomość już tam jest, system nie szuka dalej.
3. Wyszukaj domyślny język w pliku wiadomości. Jeśli np. ustawienie rozszerzenia „default_locale” na „es” to „es”, a wiadomość nie jest podana w polu /_locates/en_GB/messages.json ani /_locates/en/messages.json, rozszerzenie używa wiadomości ze strony /_locates/es/messages.json.

Na ilustracji poniżej komunikat o nazwie „colores” występuje we wszystkich 3 językach obsługiwanych przez rozszerzenie, ale „extName” występuje tylko w dwóch z nich. Za każdym razem, gdy użytkownik korzystający z Google Chrome w języku angielskim (USA) widzi etykietę „Kolory”, użytkownik posługujący się brytyjskim językiem angielskim widzi „Kolory”. Nazwa rozszerzenia „Hello World” widzą użytkownicy obu języków (USA i Wielka Brytania). Ponieważ językiem domyślnym jest hiszpański, użytkownicy korzystający z Google Chrome w języku innym niż angielski widzą etykietę „Kolory” i nazwę rozszerzenia „Hola mundo”.

Ustawianie regionu przeglądarki

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

Windows

Te ustawienia możesz zmienić przy użyciu skrótu lokalnego lub interfejsu Google Chrome. Skrót klawiaturowy jest szybszy, gdy go skonfigurujesz, i umożliwia korzystanie z kilku języków jednocześnie.

Użyj skrótu specyficznego dla określonego języka

Aby utworzyć skrót powodujący uruchomienie Google Chrome w określonym języku i użyć go:

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

3. Zmień właściwości skrótu, tak aby w polu Cel określono flagi --lang i --user-data-dir. Wartość docelowa powinna 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 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

Korzystanie z interfejsu

Aby zmienić ustawienia regionalne przy użyciu interfejsu użytkownika Google Chrome dla Windows:

1. Ikona aplikacji > Opcje
2. Wybierz kartę Dla zaawansowanych.
3. Przewiń w dół do sekcji Treści internetowe.
4. Kliknij Zmień ustawienia czcionki i języka.
5. Wybierz kartę Języki.
6. Korzystając z menu, wybierz Język Google Chrome.
7. Uruchom ponownie Chrome

Mac OS X

Aby zmienić ustawienia regionalne na Macu, skorzystaj z 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 lokalne 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. W obszarze 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 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 obok ustawienia języka, aby ponownie uruchomić ChromeOS.

Przykłady

Proste przykłady internacjonalizacji znajdziesz w katalogu examples/api/i18n. Pełny przykład znajdziesz tutaj: przykłady/rozszerzenia/wiadomości. Więcej przykładów oraz pomoc dotyczącą wyświetlania kodu źródłowego znajdziesz w sekcji Przykłady.

getMessage()

Ten kod pobiera zlokalizowaną wiadomość z przeglądarki i wyświetla ją jako ciąg znaków. Zastępuje ona w wiadomości dwa symbole zastępcze ciągami „ciąg1” i „ciąg2”.

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

Oto jak należy 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 specyficzne dla języka. Szczegółowe informacje o wywoływaniu getMessage() znajdziesz w dokumentacji interfejsu API.

getAcceptLanguages()

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

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 interfejsu API.

detectLanguage()

Poniższy kod wykrywa w danym ciągu maksymalnie 3 języki i wyświetla wynik w postaci ciągów znaków rozdzielonych znakiem 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 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()