Opis
Skorzystaj z infrastruktury chrome.i18n
, aby wdrożyć internacjonalizację całej aplikacji lub rozszerzenia.
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
):
Jak obsługiwać wiele 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="" _locales="" a="" alt="W pliku manifest.json " and="" been="" changed="" chrome.i18n.getmessage("extname").="" hasdefined="" en javascript="" file="" filetym
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 lub aplikacji można łatwo go przetłumaczyć. Kopiujesz plik messages.json
, tłumaczysz go i umieszczasz w nowym katalogu w lokalizacji _locales
. Na przykład: aby obsługiwać język hiszpański, umieść przetłumaczoną kopię messages.json
w polu _locales/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.
Nazwa wiadomości | Opis |
---|---|
@@extension_id | Rozszerzenie lub identyfikator aplikacji; możesz użyć tego ciągu do utworzenia adresów URL zasobów w rozszerzeniu. Tej wiadomości mogą użyć nawet rozszerzenia, które nie są zlokalizowane. Uwaga: nie można jej użyć w pliku manifestu. |
@@ui_locale | Bieżące ustawienie języka. Możesz użyć tego ciągu do utworzenia adresów URL dla konkretnych języków. |
@@bidi_dir | Kierunek tekstu dla bieżącego języka („ltr”) w przypadku języków pisanych od lewej do prawej (np. angielski) lub „rtl” (języki pisane od prawej do lewej), takich jak japoński. |
@@bidi_reversed_dir | Jeśli @@bidi_dir to „ltr”, oznacza to „rtl”. W przeciwnym razie jest to „ltr”. |
@@bidi_start_edge | Jeśli @@bidi_dir ma wartość „ltr”, wartość to „left”. W przeciwnym razie ma wartość „right”. |
@@bidi_end_edge | Jeśli @@bidi_dir ma wartość „ltr”, wartość to „right”. W przeciwnym razie ma wartość „left”. |
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ć spośród wielu języków, w tym niektórych (np. en
), dzięki czemu jedno tłumaczenie będzie obsługiwać wiele wersji językowych (np. en_GB
i en_US
).
Obsługiwane ustawienia regionalne
Możesz używać dowolnego z ustawień regionalnych obsługiwanych przez Chrome Web Store.
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ść:
- 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_locales/en_GB/messages.json
. Jeśli plik istnieje, a konkretnie pojawi się w nim wiadomość, system nie szuka dalej. - 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ścien
. Jeśli plik istnieje, a konkretna wiadomość już tam jest, system nie szuka dalej. - 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
_locales/en_GB/messages.json
ani_locales/en/messages.json
, rozszerzenie używa wiadomości ze strony_locales/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”.
Jak ustawić język 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żywanie skrótu określonego dla regionu
Aby utworzyć skrót powodujący uruchomienie Google Chrome w określonym języku i użyć go:
- Utwórz kopię skrótu do przeglądarki Google Chrome, który jest już na pulpicie.
- Zmień nazwę nowego skrótu, aby pasowała do nowego języka.
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
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 użytkownika
Aby zmienić ustawienia regionalne przy użyciu interfejsu użytkownika Google Chrome dla Windows:
- Ikona aplikacji > Opcje
- Wybierz kartę Dla zaawansowanych.
- Przewiń w dół do sekcji Treści internetowe.
- Kliknij Zmień ustawienia czcionki i języka.
- Wybierz kartę Języki.
- Korzystając z menu, wybierz Język Google Chrome.
- Uruchom ponownie Chrome
Mac OS X
Aby zmienić ustawienia regionalne na Macu, skorzystaj z preferencji systemowych.
- W menu Apple wybierz Preferencje systemowe.
- W sekcji Osobiste wybierz Międzynarodowe.
- Wybierz język i lokalizację
- 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:
- 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 kliknij menu Więcej działań z 3 kropkami obok języka i wybierz Wyświetlaj ChromeOS w tym języku.
- 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.
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.
Przykład: getAcceptLanguage
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.
Przykład: wykrywaj język
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.
Typy
LanguageCode
Kod języka w formacie ISO, np. en
lub fr
. Pełną listę języków obsługiwanych przez tę metodę znajdziesz w sekcji kLanguageInfoTable. W przypadku nieznanego języka zwracana jest wartość und
, co oznacza, że [percentage] tekstu jest nieznanym CLD.
Typ
string,
Metody
detectLanguage()
chrome.i18n.detectLanguage(
text: string,
callback?: function,
)
Wykrywa język podanego tekstu za pomocą listy CLD.
Parametry
-
plik tekstowy,
string,
Ciąg wejściowy użytkownika do przetłumaczenia.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(result: object) => void
-
wynik
obiekt
Obiekt LanguageDetectionResult, który przechowuje wykrytą niezawodność języka i tablicę DetectedLanguage
-
isReliable
boolean
Usługa CLD wykryła niezawodność języka
-
języki
obiekt[]
tablica wykrytego języka
-
language,
string,
-
procent
Liczba
Procent wykrytego języka
-
-
-
Akcje powrotne
-
Promise<object>
Chrome 99 i nowszeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getAcceptLanguages()
chrome.i18n.getAcceptLanguages(
callback?: function,
)
Pobiera języki akceptowane przez przeglądarkę. Różni się on od regionu używanego w przeglądarce. Aby go uzyskać, użyj i18n.getUILanguage
.
Parametry
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(languages: string[]) => void
-
języki
string[]
Tablica kodu języka
-
Akcje powrotne
-
Promise<LanguageCode[]>
Chrome 99 i nowszeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getMessage()
chrome.i18n.getMessage(
messageName: string,
substitutions?: any,
options?: object,
)
Pobiera zlokalizowany ciąg znaków dla określonej wiadomości. Jeśli komunikatu nie ma, ta metoda zwraca pusty ciąg znaków („'”). Jeśli format wywołania getMessage()
jest nieprawidłowy – np. messageName nie jest ciągiem znaków lub tablica substitutions ma więcej niż 9 elementów – ta metoda zwraca wartość undefined
.
Parametry
-
messageName
string,
Nazwa wiadomości określona w pliku
messages.json
. -
zamienniki
dowolne opcjonalne
Maksymalnie 9 ciągów zastępczych, jeśli są wymagane w wiadomości.
-
Opcje
obiekt opcjonalnie
Chrome 79 i nowsze-
escapeLt
wartość logiczna opcjonalna
Naciśnij klawisz
<
w tłumaczeniu na język<
. Dotyczy to tylko samej wiadomości, a nie obiektów zastępczych. Programiści mogą użyć tej opcji, jeśli tłumaczenie jest używane w kontekście HTML. Szablony Closure Compiler używane w aplikacji Closure Compiler generują to automatycznie.
-
Akcje powrotne
-
string,
Wiadomość zlokalizowana na bieżący język.
getUILanguage()
chrome.i18n.getUILanguage()
Pobiera język interfejsu przeglądarki. Różni się ona od funkcji i18n.getAcceptLanguages
, która zwraca preferowane języki użytkownika.
Akcje powrotne
-
string,
Kod języka interfejsu przeglądarki, np. en-US lub fr-FR.