chrome.i18n

Opis

Użyj infrastruktury chrome.i18n, aby wdrożyć internacjonalizację całej aplikacji lub rozszerzenia.

Plik manifestu

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

Pojęcia i wykorzystanie

Wszystkie ciągi znaków 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 w przypadku języka angielskiego.

Oto hierarchia plików rozszerzenia międzynarodowego, 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 przedstawionymi na tym rysunku:

Aby przetłumaczyć to rozszerzenie międzynarodowo, nadaj nazwę poszczególnym ciągom widocznym dla użytkowników i umieść go w pliku wiadomości. Plik manifestu rozszerzenia, pliki CSS i kod JavaScript używają nazwy każdego ciągu znaków w celu uzyskania jego zlokalizowanej wersji.

Tak wygląda rozszerzenie w wersji międzynarodowej (pamiętaj, że nadal zawiera ono tylko ciągi w języku angielskim):

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locates="" a="" alt="" chrome.i18n.getmessage="" changed="" chrome.i18n.getmessage("extname").="" standard messages" en="" file="" plik

Uwagi na temat umiędzynarodawiania:

• Możesz używać dowolnego z obsługiwanych języków. Jeśli używasz nieobsługiwanego języka, Google Chrome go ignoruje.

• W pliku manifest.json i pliku CSS odwołaj się do ciągu o nazwie messagename w następujący sposób:

  __MSG_messagename__
  

• W kodzie JavaScript rozszerzenia lub aplikacji znajdź ciąg o nazwie messagename w ten sposób:

  chrome.i18n.getMessage("messagename")
  

• W każdym wywołaniu funkcji getMessage() możesz podać do 9 ciągów, które zostaną umieszczone 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 komunikaty.

• W messages.json każdy ciąg widoczny dla użytkowników ma nazwę, element „message” i opcjonalny element „opis”. Nazwa to klucz, np. „extName” lub „search_string”, który identyfikuje ciąg. Wartość „message” określa wartość ciągu w tym języku. Opcjonalny „opis” ułatwia tłumaczom, którzy mogą nie zobaczyć, 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 Formaty wiadomości związanych z różnymi językami.

Po umiędzynarodowieniu rozszerzenia tłumaczenie jest proste. Skopiujesz plik messages.json, przetłumaczysz go i umieścisz w nowym katalogu pod adresem /_locates. Na przykład, aby zapewnić wsparcie dla języka hiszpańskiego, wystarczy umieścić przetłumaczoną kopię messages.json w grupie /_locates/es. Na ilustracji poniżej widać poprzednie rozszerzenie z nowym tłumaczeniem na język hiszpański.

Wstępnie zdefiniowane komunikaty

System internacjonalizacji udostępnia kilka wstępnie zdefiniowanych komunikatów, które pomogą Ci zlokalizować treści. Należą do nich @@ui_locale (które pozwalają wykryć bieżący język interfejsu) oraz kilka komunikatów @@bidi_..., które pozwalają wykryć kierunek tekstu. Te ostatnie wiadomości mają podobne nazwy do stałych w interfejsie BIDI (dwukierunkowy) interfejsu API gadżetów.

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

Tabela poniżej zawiera opis wszystkich wstępnie zdefiniowanych komunikatów.

Nazwa wiadomości	Opis
@@extension_id	Identyfikator rozszerzenia lub aplikacji. Tego ciągu możesz użyć do utworzenia adresów URL zasobów w rozszerzeniu. Tej wiadomości mogą używać nawet niezlokalizowane rozszerzenia. Uwaga: tej wiadomości nie można użyć w pliku manifestu.
@@ui_locale	Bieżąca lokalizacja. Możesz użyć tego ciągu do tworzenia adresów URL dla określonych języków.
@@bidi_dir	Kierunek tekstu w bieżącym języku – „ltr” dla języków pisanych od lewej do prawej, np. angielski, lub „rtl” dla języków pisanych od prawej do lewej, takich jak arabski.
@@bidi_reversed_dir	Jeśli @@bidi_dir to „ltr”, oznacza to, że ma wartość „rtl”, a w przeciwnym razie ma wartość „ltr”.
@@bidi_start_edge	Jeśli @@bidi_dir ma wartość „ltr”, oznacza to, że ma wartość „left”, a w przeciwnym razie ma wartość „right”.
@@bidi_end_edge	Jeśli @@bidi_dir ma wartość „ltr”, oznacza to, że wartość jest prawidłowa. W przeciwnym razie ma wartość „left”.

Oto przykład użycia właściwości @@extension_id w pliku CSS do utworzenia adresu URL:

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

Jeżeli 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 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 językach zapisywanych od lewej do prawej, na przykład w języku angielskim, pogrubione linie wyglądają tak:

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

Języki

Masz do wyboru wiele regionów, w tym te (np. en), które pozwalają na pojedyncze tłumaczenie z uwzględnieniem wielu odmian danego języka (np. en_GB czy en_US).

Możesz zlokalizować rozszerzenie w dowolnym języku obsługiwanym w Chrome Web Store. Jeśli Twojego języka nie ma na liście, wybierz najbliższą alternatywę. Jeśli na przykład domyślne język rozszerzenia to "de_CH", wybierz "de" w Chrome Web Store.

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
h	chorwacki
hu	węgierski
id	indonezyjski
włoski	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ć każdego ciągu dla każdego obsługiwanego języka. Dopóki plik messages.json języka domyślnego zawiera wartość dla każdego ciągu, rozszerzenie lub aplikacja będzie działać niezależnie od tego, jak rozproszone jest tłumaczenie. Oto jak system rozszerzeń wyszukuje wiadomość:

1. Wyszukaj plik z wiadomościami (jeśli jest dostępny) pod kątem preferowanego języka użytkownika. Jeśli na przykład język Google Chrome jest ustawiony na angielski (en_GB), system najpierw szuka wiadomości w języku /_locates/en_GB/messages.json. Jeśli plik istnieje, a komunikat się tam znajduje, system nie będzie kontynuować.
2. Jeśli preferowany język użytkownika określa region (czyli ma podkreślenie: _), wyszukaj język bez tego regionu. Jeśli na przykład plik en_GB wiadomości nie istnieje lub nie zawiera tej wiadomości, system szuka pliku z wiadomościami en. Jeśli plik istnieje, a komunikat się tam znajduje, system nie będzie szukał dalszych informacji.
3. Wyszukaj język domyślny w pliku wiadomości. Jeśli np. „default_locale” rozszerzenia ma wartość „es”, a /_locates/en_GB/messages.json ani /_locates/en/messages.json nie zawiera wiadomości, rozszerzenie użyje wiadomości z adresu /_locates/es/messages.json.

Na ilustracji poniżej wiadomość o nazwie „colores” występuje we wszystkich 3 językach obsługiwanych przez rozszerzenie, ale „extName” występuje tylko w 2 językach. Za każdym razem, gdy użytkownik korzystający z Google Chrome w języku angielskim (USA) zobaczy etykietę „Kolory”, użytkownik posługujący się brytyjskim językiem angielskim zobaczy „Kolory”. Użytkownicy języka angielskiego (USA i brytyjski) widzą rozszerzenie „Hello World”. Domyślnym językiem jest hiszpański, dlatego użytkownicy korzystający z Google Chrome w językach innych niż angielski zobaczą etykietę „Colores” i nazwę rozszerzenia „Hola mundo”.

Ustaw język przeglądarki

Aby przetestować tłumaczenia, warto ustawić język przeglądarki. W tej sekcji dowiesz się, jak ustawić język w systemach Windows, Mac OS X, Linux i ChromeOS.

Windows

Możesz zmienić język przy użyciu skrótu lub interfejsu użytkownika Google Chrome. Stosowanie skrótów jest szybsze, gdy już skonfigurujesz usługę i umożliwia korzystanie z kilku języków jednocześnie.

Użyj skrótu specyficznego dla języka

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

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

3. Zmień właściwości skrótu, tak by pole Cel określało 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.

Na przykład, aby 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łatwi 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 jeden katalog danych na język, możesz uruchomić przeglądarkę w kilku językach jednocześnie. Wadą jest to, że dane dla poszczególnych regionów nie są udostępniane, co oznacza, że trzeba instalować rozszerzenie wiele razy – raz dla każdego regionu, co może być kłopotliwe, jeśli nie znasz języka. Więcej informacji znajdziesz w artykule Tworzenie i używanie profili.

Korzystanie z interfejsu

Poniżej opisano, jak zmienić ustawienia regionalne za pomocą interfejsu użytkownika przeglądarki Google Chrome dla systemu Windows:

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

Mac OS X

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

1. Z 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ć język 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 języka kliknij menu Więcej czynności z 3 kropkami obok języka i wybierz Wyświetl ChromeOS w tym języku.
5. Kliknij przycisk Uruchom ponownie obok ustawionego 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 i pomoc w wyświetlaniu kodu źródłowego znajdziesz w przykładach.

getMessage()

Poniższy kod pobiera zlokalizowaną wiadomość z przeglądarki i wyświetla ją w postaci ciągu znaków. Zastępuje ona w wiadomości dwie zmienne ciągami „ciąg1” i „ciąg2”.

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

Aby 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 o określonych regionach. Szczegółowe informacje o wywoływaniu funkcji getMessage() znajdziesz w dokumentacji interfejsu API.

getAcceptLanguages()

Poniższy kod pobiera z przeglądarki języki akceptowane i wyświetla je w postaci ciągu znaków, oddzielając każdy z nich 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()

Ten kod wykrywa maksymalnie 3 języki z danego ciągu i wyświetla wynik w postaci ciągów znaków oddzielonych 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 na stronie kLanguageInfoTable. W przypadku nieznanego języka zostanie zwrócona wartość und, co oznacza, że [percentage] tekstu jest nieznanych w CLD.

Typ

string,

Metody

detectLanguage()

Obiecujemy Chrome 47 lub nowszy

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

Określa język podanego tekstu za pomocą CLD.

Parametry

• plik tekstowy,

  string,

  Dane wejściowe użytkownika do przetłumaczenia.

• wywołanie zwrotne

  funkcja optional

  Parametr callback wygląda tak:

  (result: object) => void

  • wynik

    obiekt

    Obiekt LanguageDetectionResult zawiera wykrytą niezawodność języka i tablicę DetectedLanguage

    • isReliable

      boolean

      Zgodność języka wykryta przez CLD

    • wybranych językach

      obiekt[]

      tablica wykrytychLanguage

      • language,

        string,

      • procent

        Liczba

        Odsetek wykrytego języka

Zwroty

• Promise<object>

  Chrome 99 lub nowszy

  Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getAcceptLanguages()

Obiecujemy

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

Pobiera języki przeglądarki. Jest inny niż język używany w przeglądarce. Aby pobrać język, użyj i18n.getUILanguage.

Parametry

• wywołanie zwrotne

  funkcja optional

  Parametr callback wygląda tak:

  (languages: string[]) => void

  • wybranych językach

    ciąg znaków[]

    Tablica kodu języka

Zwroty

• Promise<LanguageCode[]>

  Chrome 99 lub nowszy

  Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getMessage()

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

Pobiera zlokalizowany ciąg znaków dla określonej wiadomości. Jeśli brakuje komunikatu, 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 ma więcej niż 9 elementów, ta metoda zwraca undefined.

Parametry

• messageName

  string,

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

• zamienniki

  dowolne opcjonalne

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

• Opcje

  obiekt opcjonalny

  Chrome 79 lub nowszy
  • escapeLt

    Wartość logiczna opcjonalna

    Escape < – tłumaczenie na język <. Dotyczy to tylko samej wiadomości, a nie obiektów zastępczych. Może być przydatna, jeśli tłumaczenie jest używane w kontekście HTML. Szablony Closure używane z Closure Compiler generują go automatycznie.

Zwroty

• string,

  Wiadomość zlokalizowana dla bieżącego języka.

getUILanguage()

chrome.i18n.getUILanguage()

Pobiera język interfejsu przeglądarki. Jest inny niż i18n.getAcceptLanguages, który zwraca preferowane języki użytkownika.

Zwroty

• string,

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