хром.i18n

Описание

Манифест

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

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

Все видимые пользователю строки необходимо поместить в файл с именем 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 , предоставляются системой интернационализации. Полный список предопределенных имен сообщений см. в разделе « Предопределенные сообщения» .

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

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

Система интернационализации предоставляет несколько предопределенных сообщений, которые помогут вам локализовать интерфейс. К ним относятся @@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. Если вашего языка нет в списке, выберите ближайший. Например, если язык по умолчанию для вашего расширения — "de_CH" , выберите "de" в 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 .

На следующем рисунке сообщение с именем "colores" присутствует во всех трех языковых версиях, поддерживаемых расширением, а "extName" — только в двух. Везде, где пользователь Google Chrome на американском английском видит метку "Colors", пользователь на британском английском видит "Colours". И пользователи американского, и пользователи британского английского видят название расширения "Hello World". Поскольку языком по умолчанию является испанский, пользователи Google Chrome на любом другом языке, кроме английского, видят метку "Colores" и название расширения "Hola mundo".

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

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

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

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

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

chrome.i18n.getUILanguage(): string