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 указано название "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() можно указать до девяти строк, которые будут включены в сообщение. Подробные сведения приведены в разделе Примеры: getMessage.

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

  • В файле messages.json у каждой видимой пользователю строки есть название, элемент message и необязательный элемент description. Название – это ключ, например extName или search_string, который идентифицирует строку. В поле message указывается значение строки в этой локали. Необязательное поле description содержит пояснения для переводчиков, которые могут не знать, как строка используется в расширении. Пример:

    {
  "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_..., позволяющих определить направление текста. Последние сообщения имеют названия, похожие на константы в gadgets BIDI (bi-directional) API.

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

В таблице ниже описаны все стандартные сообщения.

Название сообщенияОписание
@@extension_idИдентификатор расширения или приложения. Эту строку можно использовать для создания URL ресурсов в расширении. Это сообщение можно использовать даже в нелокализованных расширениях.
Примечание. Это сообщение нельзя использовать в файле манифеста.
@@ui_localeТекущие региональные настройки. Эту строку можно использовать для создания URL, зависящих от региона.
@@bidi_dirНаправление текста для текущего региона: ltr (слева направо) для таких языков, как русский, или rtl (справа налево) для таких языков, как арабский.
@@bidi_reversed_dirЕсли для @@bidi_dir задано значение ltr, то для этого атрибута будет установлено значение rtl, и наоборот.
@@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. Если вашего региона нет в списке, выберите наиболее подходящий вариант. Например, если в расширении по умолчанию используется язык "de_CH", выберите "de" в интернет-магазине Chrome.

Код региональных настроек Язык (регион)
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. Поиск в файле messages (если он есть) по предпочитаемому языку пользователя. Например, если в Google Chrome выбран британский английский (en_GB), система сначала ищет сообщение в /_locales/en_GB/messages.json. Если файл существует и в нем есть сообщение, система не ищет дальше.
  2. Если в предпочитаемой локали пользователя указан регион (то есть в локали есть символ подчеркивания: _), выполните поиск локали без этого региона. Например, если файл сообщений en_GB не существует или не содержит сообщения, система ищет в файле сообщений en. Если файл существует и в нем есть сообщение, система не ищет дальше.
  3. Найдите файл messages для региональных настроек по умолчанию. Например, если в качестве значения default_locale указано es, а в папках /_locales/en_GB/messages.json и /_locales/en/messages.json нет нужного сообщения, расширение использует сообщение из папки /_locales/es/messages.json.

На рисунке ниже сообщение colores есть во всех трех региональных настройках, поддерживаемых расширением, а extName – только в двух. Например, если пользователь, использующий Google Chrome на американском английском, видит надпись "Colors", то пользователь, использующий британский английский, видит "Colours". Пользователи, говорящие на американском и британском английском, увидят название Hello World. Поскольку языком по умолчанию является испанский, пользователи, у которых в Google Chrome выбран любой язык, кроме английского, увидят ярлык Colores и название расширения 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. Другие примеры и инструкции по просмотру исходного кода можно найти в разделе Примеры.

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()

Следующий код определяет до трех языков в заданной строке и выводит результат в виде строк, разделенных новыми строками.

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 и более поздние версии browser.* начиная с Chrome 148

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

Тип

string

Методы

detectLanguage()

Chrome 47 и более поздние версии browser.* начиная с Chrome 148 
browser.i18n.detectLanguage(
  text: string,
): Promise<object>

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

Параметры

  • Текст

    string

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

Возвраты

  • Promise<object>

    Chrome 99 и более поздние версии browser.* начиная с Chrome 148

getAcceptLanguages()

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

Получает список языков, поддерживаемых браузером. Она отличается от региональных настроек браузера, которые можно получить с помощью метода i18n.getUILanguage.

Возвраты

  • Promise<LanguageCode[]>

    Chrome 99 и более поздние версии browser.* начиная с Chrome 148

getMessage()

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

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

Параметры

  • messageName

    string

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

  • замены

    any optional

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

  • Параметры

    Объект (необязательно)

    Chrome 79+ browser.* начиная с Chrome 148
    • escapeLt

      Логическое значение (необязательно)

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

Возвраты

  • string

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

getUILanguage()

browser.i18n.getUILanguage(): string

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

Возвраты

  • string

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