chrome.i18n

refresh date: 2026-09-25 robots: noindex

Opis

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

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

Jak obsługiwać wiele języków

Załóżmy, że masz rozszerzenie z plikami pokazanymi 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 (pamiętaj, że nadal zawiera tylko ciągi znaków w języku angielskim):

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locales="" a="" alt="W pliku manifest.json " and="" been="" changed="" chrome.i18n.getmessage("extname").="" defines="" en="" file="" file,="" has="" hello="" in="" item="" javascript="" messages.json="" named="" new="" src="/static/images/i18n-after-1.gif" the="" to="" value="" world"="" />

Kilka uwag na temat internacjonalizacji:

• Możesz użyć dowolnego z obsługiwanych ustawień regionalnych. Jeśli używasz nieobsługiwanego języka, Google Chrome go 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 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. Więcej informacji 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 sekcji Formaty: wiadomości w określonym języku.

Po zinternacjonalizowaniu rozszerzenia lub aplikacji ich 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 wiadomości, 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 komunikaty mają nazwy podobne do stałych w interfejsie API gadżetów BIDI (dwukierunkowym).

Specjalna wiadomość @@extension_id może być używana w plikach CSS i JavaScript niezależnie od tego, czy rozszerzenie lub aplikacja są dostosowane do innego 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 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ś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.

Obsługiwane ustawienia regionalne

Możesz używać dowolnych języków 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 domyślnego języka 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 z wiadomościami (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 wyszuka komunikat w pliku _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 np. plik en_GB messages nie istnieje lub nie zawiera wiadomości, system wyszuka ją w pliku en messages. Jeśli ten plik istnieje i wiadomość się w nim znajduje, system nie szuka dalej.
3. Wyszukaj w pliku wiadomości domyślny język. 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 wersjach językowych obsługiwanych przez rozszerzenie, a wiadomość „extName” tylko w 2 z nich. Wszędzie tam, gdzie 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 języka angielskiego w Stanach Zjednoczonych i Wielkiej Brytanii widzą 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, Mac OS X, Linux i ChromeOS.

Windows

Możesz zmienić ustawienia regionalne za pomocą skrótu specyficznego dla danego regionu lub interfejsu Google Chrome. Skrót jest szybszy po skonfigurowaniu i umożliwia używanie kilku języków jednocześnie.

Używanie skrótu przeznaczonego dla określonej lokalizacji

Aby utworzyć i użyć 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, aby w polu Element docelowy były podane 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.

Jeśli na przykład chcesz 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. Kliknij kartę Pod maską.
3. Przewiń w dół 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

Mac OS X

Aby zmienić ustawienia regionalne na komputerze Mac, użyj preferencji systemowych.

1. W menu Apple wybierz Ustawienia systemowe.
2. W sekcji Osobiste wybierz Międzynarodowe.
3. Wybór języka i lokalizacji
4. Uruchom ponownie Chrome

Linux

Aby zmienić ustawienia regionalne w Linuksie, 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 kliknij element menu 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

Proste 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.

Przykłady: getMessage

Podany niżej kod pobiera z przeglądarki zlokalizowany komunikat i wyświetla go jako ciąg znaków. Zastępuje 2 obiekty zastępcze w wiadomości ciągami „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ślonych językach. Szczegółowe informacje o wywoływaniu funkcji getMessage() znajdziesz w dokumentacji API.

Przykład: getAcceptLanguages

Poniższy kod pobiera z przeglądarki akceptowane języki i wyświetla je jako ciąg 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.

Przykład: detectLanguage

Poniższy kod wykrywa maksymalnie 3 języki w podanym 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,
  callback?: function,
): Promise<object>

chrome.i18n.getAcceptLanguages(
  callback?: function,
): Promise<LanguageCode[]>

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

chrome.i18n.getUILanguage(): string