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ść:
- 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ć. - 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ściamien
. Jeśli plik istnieje, a komunikat się tam znajduje, system nie będzie szukał dalszych informacji. - 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ć:
- Utwórz kopię skrótu do Google Chrome, który jest już na pulpicie.
- Zmień nazwę nowego skrótu, aby pasował do nowego języka.
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
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
Korzystanie z interfejsu
Poniżej opisano, jak zmienić ustawienia regionalne za pomocą interfejsu użytkownika przeglądarki Google Chrome dla systemu Windows:
- Ikona aplikacji > Opcje
- Wybierz kartę Dla zaawansowanych.
- Przewiń w dół do sekcji Treść internetowa.
- Kliknij Zmień ustawienia czcionki i języka.
- Wybierz kartę Języki.
- Wybierz z menu język Google Chrome.
- Uruchom ponownie Chrome
Mac OS X
Aby zmienić język na Macu, użyj preferencji systemowych.
- Z menu Apple wybierz Preferencje systemowe.
- W sekcji Osobiste wybierz Międzynarodowe.
- Wybierz język i lokalizację
- 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:
- W obszarze powiadomień wybierz Ustawienia.
- W sekcji Języki i metody wprowadzania kliknij menu Język.
- Jeśli Twojego języka nie ma na liście, kliknij Dodaj języki i dodaj go.
- 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.
- 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
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()
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 nowszyObietnice 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()
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 nowszyObietnice 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.