хром.i18n

дата обновления: 2026-09-25 robots: noindex

Описание

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

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

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

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

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

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

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

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

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

  __MSG_messagename__
  

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

  chrome.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 . На следующем рисунке показано предыдущее расширение с новым испанским переводом.

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

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

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

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

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

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

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

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

Для проверки переводов может потребоваться установить языковые настройки браузера. В этом разделе описано, как установить языковые настройки в Windows , Mac OS X , 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 X

Чтобы изменить языковые настройки на 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 .

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