browser.i18n

Описание

Используйте инфраструктуру chrome.i18n для внедрения интернационализации во всё ваше приложение или расширение.

Манифест

Если расширение содержит каталог /_locales , в манифесте необходимо определить "default_locale" .

Понятия и применение

Все видимые пользователю строки необходимо поместить в файл с именем messages.json . Каждый раз при добавлении новой локали необходимо создавать файл messages в каталоге с именем /_locales/_localeCode_ , где localeCode — это код, например, en для английского языка.

Вот иерархия файлов для интернационализированного расширения, поддерживающего английский ( en ), испанский ( es ) и корейский ( ko ):

В каталоге расширений: manifest.json, *.html, *.js, каталог /_locales. В каталоге /_locales: каталоги en, es и ko, в каждом из которых находится файл messages.json.

Поддержка нескольких языков

Допустим, у вас есть файл с расширением, показанным на следующем рисунке:

Файл manifest.json и файл с JavaScript. В файле .json содержится 'Hello World'. В файле JavaScript указано title = 'Hello World'.

Для интернационализации этого расширения необходимо присвоить каждой видимой пользователю строке имя и поместить его в файл сообщений. Манифест расширения, файлы CSS и код JavaScript используют имя каждой строки для получения её локализованной версии.

Вот как выглядит расширение после интернационализации (обратите внимание, что оно по-прежнему содержит только английские строки):

В файле manifest.json значение 'Hello World' изменено на '__MSG_extName__', а новый элемент 'default_locale' имеет значение 'en'. В файле JavaScript значение 'Hello World' изменено на browser.i18n.getMessage('extName'). Новый файл с именем /_locales/en/messages.json определяет 'extName'.

Несколько замечаний по поводу интернационализации:

  • Вы можете использовать любой из поддерживаемых языковых стандартов . Если вы используете неподдерживаемый языковой стандарт, Google Chrome его проигнорирует.

  • В файлах manifest.json и CSS укажите строку с именем messagename следующим образом:

    __MSG_messagename__

  • В JavaScript-коде вашего расширения или приложения укажите строку с именем messagename следующим образом:

    browser.i18n.getMessage("messagename")

  • При каждом вызове метода getMessage() вы можете указать до 9 строк, которые будут включены в сообщение. Подробнее см. примеры: getMessage .

  • Некоторые сообщения, такие как @@bidi_dir и @@ui_locale , предоставляются системой интернационализации. Полный список предопределенных имен сообщений см. в разделе « Предопределенные сообщения» .

  • In messages.json , each user-visible string has a name, a "message" item, and an optional "description" item. The name is a key such as "extName" or "search_string" that identifies the string. The "message" specifies the value of the string in this locale. The optional "description" provides help to translators, who might not be able to see how the string is used in your extension. For example:

    {
  "search_string": {
    "message": "hello%20world",
    "description": "The string we search for. Put %20 between words that go together."
  },
  ...
}

Для получения дополнительной информации см. раздел «Форматы: Сообщения, специфичные для локали» .

После интернационализации расширения его перевод осуществляется очень просто. Вы копируете файл messages.json , переводите его и помещаете копию в новую директорию в каталоге /_locales . Например, чтобы добавить поддержку испанского языка, просто поместите переведенную копию messages.json в каталог /_locales/es . На следующем рисунке показано предыдущее расширение с новым испанским переводом.

На этом рисунке все выглядит так же, как и на предыдущем, но с новым файлом по адресу /_locales/es/messages.json, содержащим испанский перевод сообщений.

Предварительно заданные сообщения

Система интернационализации предоставляет несколько предопределенных сообщений, которые помогут вам локализовать интерфейс. К ним относятся @@ui_locale , позволяющее определить текущую локаль пользовательского интерфейса, и несколько сообщений @@bidi_... , позволяющих определить направление текста. Последние сообщения имеют имена, похожие на константы в API BIDI (двунаправленный) гаджетов .

Специальное сообщение @@extension_id можно использовать в файлах CSS и JavaScript независимо от того, локализовано расширение или приложение. Это сообщение не работает в файлах манифеста.

В следующей таблице описано каждое предопределенное сообщение.

Название сообщения Описание
@@extension_id Идентификатор расширения или приложения; вы можете использовать эту строку для построения URL-адресов ресурсов внутри расширения. Даже нелокализованные расширения могут использовать это сообщение.
Примечание: это сообщение нельзя использовать в файле манифеста.
@@ui_locale Текущая языковая версия; вы можете использовать эту строку для создания URL-адресов, специфичных для данной языковой версии.
@@bidi_dir Направление текста для текущей локали: "ltr" для языков с направлением письма слева направо, таких как английский, или "rtl" для языков с направлением письма справа налево, таких как арабский.
@@bidi_reversed_dir Если @@bidi_dir имеет значение "ltr", то это "rtl"; в противном случае — "ltr".
@@bidi_start_edge Если @@bidi_dir имеет значение "ltr", то это "left"; в противном случае — "right".
@@bidi_end_edge Если @@bidi_dir имеет значение "ltr", то это "right"; в противном случае — "left".

Вот пример использования @@extension_id в CSS-файле для построения URL-адреса:

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

Если идентификатор расширения равен abcdefghijklmnopqrstuvwxyzabcdef, то выделенная жирным шрифтом строка в предыдущем фрагменте кода становится следующей:

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

Вот пример использования сообщений @@bidi_* в 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;
}

Для языков с письмом слева направо, таких как английский, жирные строки выглядят следующим образом:

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

Локалы

Вы можете выбрать один из множества языковых пакетов, включая некоторые (например, en ), которые позволяют одному переводу поддерживать несколько вариантов одного языка (например, en_GB и en_US ).

Вы можете локализовать свое расширение под любой язык, поддерживаемый Chrome Web Store. Если вашего языка нет в списке, выберите ближайший. Например, если язык по умолчанию для вашего расширения — "de_CH" , выберите "de" в Chrome Web Store.

Код локали Язык (регион)
ar арабский
am амхарский
bg болгарский
bn бенгальский
ca каталанский
cs чешский
da датский
de немецкий
el греческий
en Английский
en_AU Английский (Австралия)
en_GB Английский (Великобритания)
en_US Английский (США)
es испанский
es_419 Испанский (Латинская Америка и Карибский бассейн)
et эстонский
fa персидский
fi финский
fil филиппинский
fr Французский
gu гуджарати
he иврит
hi хинди
hr хорватский
hu венгерский
id индонезийский
it итальянский
ja японский
kn Каннада
ko корейский
lt литовский
lv латышский
ml Малаялам
mr маратхи
ms малайский
nl Голландский
no норвежский
pl польский
pt_BR Португальский (Бразилия)
pt_PT Португальский (Португалия)
ro румынский
ru Русский
sk словацкий
sl словенский
sr сербский
sv шведский
sw суахили
ta тамильский
te телугу
th Тайский
tr турецкий
uk украинский
vi вьетнамский
zh_CN Китайский (Китай)
zh_TW Китайский (Тайвань)

Поиск сообщений

Вам не нужно определять каждую строку для каждой поддерживаемой локали. Пока в файле messages.json для локали по умолчанию есть значение для каждой строки, ваше расширение или приложение будет работать независимо от того, насколько скудным является перевод. Вот как система расширений ищет сообщение:

  1. Выполните поиск в файле сообщений (если таковой имеется) предпочитаемой пользователем локали. Например, если в Google Chrome установлена ​​британская английская локаль ( en_GB ), система сначала ищет сообщение в файле /_locales/en_GB/messages.json . Если этот файл существует и сообщение там есть, система не продолжает поиск.
  2. Если предпочитаемая пользователем локаль имеет региональный символ (то есть, локаль содержит символ подчеркивания: _), поиск выполняется в локали, не содержащей этот региональный символ. Например, если файл сообщений en_GB не существует или не содержит сообщение, система ищет его в файле сообщений en . Если этот файл существует и сообщение находится там, система не ищет дальше.
  3. Найдите в файле сообщений значение локали по умолчанию. Например, если для расширения параметр "default_locale" установлен на "es", и ни в /_locales/en_GB/messages.json , ни в /_locales/en/messages.json нет нужного сообщения, расширение будет использовать сообщение из файла /_locales/es/messages.json .

In the following figure, the message named "colores" is in all three locales that the extension supports, but "extName" is in only two of the locales. Wherever a user running Google Chrome in US English sees the label "Colors", a user of British English sees "Colours". Both US English and British English users see the extension name "Hello World". Because the default language is Spanish, users running Google Chrome in any non-English language see the label "Colores" and the extension name "Hola mundo".

Четыре файла: manifest.json и три файла messages.json (для es, en и en_GB). Файлы es и en содержат записи для сообщений с именами 'extName' и 'colores'; файл en_GB содержит только одну запись (для 'colores').

Настройте языковые параметры вашего браузера.

Для проверки переводов может потребоваться установить языковые настройки браузера. В этом разделе описано, как установить языковые настройки в Windows , macOS , Linux и ChromeOS .

Windows

Изменить языковые настройки можно либо с помощью специальной комбинации клавиш, либо через пользовательский интерфейс Google Chrome. После настройки использование комбинации клавиш быстрее и позволяет использовать несколько языков одновременно.

Используйте сочетание клавиш, специфичное для вашей локали.

Чтобы создать и использовать ярлык, запускающий Google Chrome с определёнными языковыми настройками:

  1. Создайте копию ярлыка Google Chrome, который уже есть на вашем рабочем столе.
  2. Переименуйте новый ярлык в соответствии с новыми языковыми настройками.

  3. Измените свойства ярлыка так, чтобы в поле «Цель» были указаны флаги --lang и --user-data-dir . Целевой объект должен выглядеть примерно так:

    path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir

  4. Запустите Google Chrome, дважды щелкнув по ярлыку.

Например, чтобы создать ярлык, запускающий Google Chrome на испанском языке ( es ), вы можете создать ярлык с именем chrome-es у которого будет следующая цель:

path_to_chrome.exe --lang=es --user-data-dir=c:\chrome-profile-es

Вы можете создать столько ярлыков, сколько вам нужно, что упрощает тестирование на разных языках. Например: 

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
Используйте пользовательский интерфейс.

Вот как изменить языковые настройки с помощью пользовательского интерфейса Google Chrome для Windows:

  1. Значок приложения > Параметры
  2. Выберите вкладку «Под капотом» .
  3. Прокрутите вниз до веб-контента
  4. Нажмите «Изменить настройки шрифта и языка» .
  5. Выберите вкладку «Языки» .
  6. Используйте выпадающее меню, чтобы установить язык Google Chrome.
  7. Перезапустите Chrome

Mac OS

Чтобы изменить языковые настройки на Mac, используйте системные настройки.

  1. В меню Apple выберите «Системные настройки» .
  2. В разделе «Личные данные » выберите «Международные».
  3. Выберите язык и местоположение.
  4. Перезапустите Chrome

Linux

Чтобы изменить языковые настройки в Linux, сначала закройте Google Chrome. Затем одной строкой установите переменную среды LANGUAGE и запустите Google Chrome. Например: 

LANGUAGE=es ./chrome

ChromeOS

Чтобы изменить языковые настройки в ChromeOS:

  1. В системном трее выберите «Настройки» .
  2. В разделе «Языки и ввод» выберите пункт «Язык» в раскрывающемся списке.
  3. Если вашего языка нет в списке, нажмите «Добавить языки» и добавьте его.
  4. После добавления нажмите на пункт меню «Дополнительные действия» с тремя точками рядом с вашим языком и выберите «Отображать ChromeOS на этом языке» .
  5. Чтобы перезапустить ChromeOS, нажмите кнопку « Перезапустить» , которая появится рядом с выбранным языком.

Примеры

Примеры интернационализации можно найти в каталоге examples/api/i18n . Полный пример см. в examples/extensions/news . Другие примеры и помощь в просмотре исходного кода см. в разделе Samples .

getMessage()

Приведенный ниже код получает локализованное сообщение из браузера и отображает его в виде строки. Он заменяет два заполнителя в сообщении строками "string1" и "string2". 

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

Вот как можно передать и использовать одну строку: 

  // 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."
    }
  }
}

Для получения дополнительной информации о заполнителях см. страницу « Сообщения, специфичные для локали» . Подробности о вызове getMessage() см. в справочнике API .

getAcceptLanguages()

Приведенный ниже код получает список принимаемых языков из браузера и отображает его в виде строки, разделяя каждый принимаемый язык запятой (','). 

function getAcceptLanguages() {
  chrome.i18n.getAcceptLanguages(function(languageList) {
    var languages = languageList.join(",");
    document.getElementById("languageSpan").innerHTML = languages;
  })
}

Подробную информацию о вызове функции getAcceptLanguages() см. в справочнике API .

detectLanguage()

Приведенный ниже код определяет до 3 языков в заданной строке и отображает результат в виде строк, разделенных переносами строк. 

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;
  });
}

Для получения более подробной информации о вызове функции detectLanguage(inputText) см. справочник API .

Типы

LanguageCode

Chrome 47+

Код языка ISO, например, en или fr . Полный список поддерживаемых этим методом языков см. в kLanguageInfoTable . Для неизвестного языка будет возвращено значение und , что означает, что [процент] текста неизвестен для CLD.

Тип

нить

Методы

detectLanguage()

Chrome 47+
chrome.i18n.detectLanguage(
  text: string,
): Promise<object>

Определяет язык предоставленного текста с помощью CLD.

Параметры

  • текст

    нить

    Строка, введенная пользователем, подлежит переводу.

Возвраты

  • Promise<object>

    Chrome 99+

getAcceptLanguages()

chrome.i18n.getAcceptLanguages(): Promise<LanguageCode[]>

Получает список языков, поддерживаемых браузером. Это отличается от локали, используемой браузером; чтобы получить локаль, используйте i18n.getUILanguage .

Возвраты

getMessage()

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

Получает локализованную строку для указанного сообщения. Если сообщение отсутствует, этот метод возвращает пустую строку (''). Если формат вызова getMessage() неверен — например, messageName не является строкой или массив подстановок содержит более 9 элементов — этот метод возвращает undefined .

Параметры

  • messageName

    нить

    Название сообщения, указанное в файле messages.json .

  • замены

    любой необязательный

    До 9 строк подстановки, если это требуется в сообщении.

  • параметры

    объект необязательный

    Chrome 79+
    • escapeLt

      логический необязательный

      Экранирование символа < в переводе до &lt; . Это относится только к самому сообщению, а не к заполнителям. Разработчики могут использовать это, если перевод используется в контексте HTML. Шаблоны замыканий, используемые с Closure Compiler, генерируют это автоматически.

Возвраты

  • нить

    Сообщение локализовано для текущего языкового стандарта.

getUILanguage()

chrome.i18n.getUILanguage(): string

Получает язык пользовательского интерфейса браузера. Это отличается от i18n.getAcceptLanguages , которая возвращает предпочтительный язык пользователя.

Возвраты

  • нить

    Языковой код пользовательского интерфейса браузера, например, en-US или fr-FR.