хром.i18n

Описание

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

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

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

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

Как поддерживать несколько языков

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

A manifest.json file and a file with JavaScript. The .json file has

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

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

В файле манифеста.json

Некоторые замечания по поводу интернационализации:

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

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

    __MSG_messagename__

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

    chrome.i18n.getMessage("messagename")

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

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

  • В messages.json каждая строка, видимая пользователю, имеет имя, элемент «сообщение» и необязательный элемент «описание». Имя — это ключ, например «extName» или «search_string», который идентифицирует строку. «Сообщение» указывает значение строки в этом языковом стандарте. Необязательное «описание» помогает переводчикам, которые, возможно, не смогут увидеть, как строка используется в вашем расширении. Например:

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

Специальное сообщение @@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»; в противном случае это «правильно».
@@bidi_end_edge Если @@bidi_dir — «ltr», то это «правильно»; в противном случае это «лево».

Вот пример использования @@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 .

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

Вам не нужно определять каждую строку для каждой поддерживаемой локали. Пока файл 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 .

На следующем рисунке сообщение с именем «colores» присутствует во всех трех локалях, поддерживаемых расширением, но «extName» присутствует только в двух локалях. Если пользователь Google Chrome на английском языке (США) видит метку «Цвета», пользователь британского английского видит «Цвета». Пользователи как американского английского, так и британского английского видят расширение «Hello World». Поскольку языком по умолчанию является испанский, пользователи Google Chrome на любом языке, отличном от английского, увидят метку «Colores» и имя расширения «Hola mundo».

Четыре файла: манифест.json и три файла messages.json (для es, en и en_GB). В файлах es и en показаны записи для сообщений с именем

Как установить локаль вашего браузера

Чтобы протестировать переводы, вам может потребоваться установить локаль вашего браузера. В этом разделе рассказывается, как установить локаль в Windows , Mac OS X , Linux и ChromeOS .

Окна

Вы можете изменить языковой стандарт, используя ярлык для конкретного языка или пользовательский интерфейс 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, вы используете системные настройки.

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

Линукс

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

LANGUAGE=es ./chrome

ChromeOS

Чтобы изменить локаль в ChromeOS:

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

Примеры

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

Примеры: getMessage

Следующий код получает локализованное сообщение из браузера и отображает его в виде строки. Он заменяет два заполнителя в сообщении строками «строка1» и «строка2». 

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 .

Пример: обнаружить язык

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

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

Хром 47+

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

Тип

нить

Методы

detectLanguage()

Обещание Chrome 47+
chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

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

Параметры

  • текст

    нить

    Строка ввода пользователя для перевода.

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    (result: object) => void

    • результат

      объект

      Объект LanguageDetectionResult, который содержит информацию о достоверности обнаруженного языка и массив DetectedLanguage.

      • isReliable

        логическое значение

        CLD обнаружил надежность языка

      • языки

        объект[]

        массив обнаруженных языков

        • язык

          нить

        • процент

          число

          Процент обнаруженного языка

Возврат

  • Обещание<объект>

    Хром 99+

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

getAcceptLanguages()

Обещать
chrome.i18n.getAcceptLanguages(
  callback?: function,
)

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

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    (languages: string[]) => void

    • языки

      нить[]

      Массив языкового кода

Возврат

  • Обещание< Код языка []>

    Хром 99+

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

getMessage()

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

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

Параметры

  • имя_сообщения

    нить

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

  • замены

    любые дополнительные

    До 9 строк замены, если сообщение требует их.

  • параметры

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

    Хром 79+
    • побегLt

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

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

Возврат

  • нить

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

getUILanguage()

chrome.i18n.getUILanguage()

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

Возврат

  • нить

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