Описание
Используйте инфраструктуру chrome.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 | Идентификатор расширения или приложения; вы можете использовать эту строку для построения 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 для локали по умолчанию есть значение для каждой строки, ваше расширение или приложение будет работать независимо от того, насколько скудным является перевод. Вот как система расширений ищет сообщение:
- Выполните поиск в файле сообщений (если таковой имеется) предпочитаемой пользователем локали. Например, если в Google Chrome установлена британская английская локаль (
en_GB), система сначала ищет сообщение в файле/_locales/en_GB/messages.json. Если этот файл существует и сообщение там есть, система не продолжает поиск. - Если предпочитаемая пользователем локаль имеет региональный символ (то есть, локаль содержит символ подчеркивания: _), поиск выполняется в локали, не содержащей этот региональный символ. Например, если файл сообщений
en_GBне существует или не содержит сообщение, система ищет его в файле сообщенийen. Если этот файл существует и сообщение находится там, система не ищет дальше. - Найдите в файле сообщений значение локали по умолчанию. Например, если для расширения параметр "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 с определёнными языковыми настройками:
- Создайте копию ярлыка Google Chrome, который уже есть на вашем рабочем столе.
- Переименуйте новый ярлык в соответствии с новыми языковыми настройками.
Измените свойства ярлыка так, чтобы в поле «Цель» были указаны флаги
--langи--user-data-dir. Целевой объект должен выглядеть примерно так:path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dirЗапустите 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:
- Значок приложения > Параметры
- Выберите вкладку «Под капотом» .
- Прокрутите вниз до веб-контента
- Нажмите «Изменить настройки шрифта и языка» .
- Выберите вкладку «Языки» .
- Используйте выпадающее меню, чтобы установить язык Google Chrome.
- Перезапустите Chrome
Mac OS
Чтобы изменить языковые настройки на Mac, используйте системные настройки.
- В меню Apple выберите «Системные настройки» .
- В разделе «Личные данные » выберите «Международные».
- Выберите язык и местоположение.
- Перезапустите Chrome
Linux
Чтобы изменить языковые настройки в Linux, сначала закройте Google Chrome. Затем одной строкой установите переменную среды LANGUAGE и запустите Google Chrome. Например:
LANGUAGE=es ./chrome
ChromeOS
Чтобы изменить языковые настройки в ChromeOS:
- В системном трее выберите «Настройки» .
- В разделе «Языки и ввод» выберите пункт «Язык» в раскрывающемся списке.
- Если вашего языка нет в списке, нажмите «Добавить языки» и добавьте его.
- После добавления нажмите на пункт меню «Дополнительные действия» с тремя точками рядом с вашим языком и выберите «Отображать ChromeOS на этом языке» .
- Чтобы перезапустить 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
Код языка ISO, например, en или fr . Полный список поддерживаемых этим методом языков см. в kLanguageInfoTable . Для неизвестного языка будет возвращено значение und , что означает, что [процент] текста неизвестен для CLD.
Тип
нить
Методы
detectLanguage()
chrome.i18n.detectLanguage(
text: string,
): Promise<object>
Определяет язык предоставленного текста с помощью CLD.
Параметры
- текст
нить
Строка, введенная пользователем, подлежит переводу.
Возвраты
Promise<object>
Chrome 99+
getAcceptLanguages()
chrome.i18n.getAcceptLanguages(): Promise<LanguageCode[]>
Получает список языков, поддерживаемых браузером. Это отличается от локали, используемой браузером; чтобы получить локаль, используйте i18n.getUILanguage .
Возвраты
Promise< LanguageCode []>
Chrome 99+
getMessage()
chrome.i18n.getMessage(
messageName: string,
substitutions?: any,
options?: object,
): string
Получает локализованную строку для указанного сообщения. Если сообщение отсутствует, этот метод возвращает пустую строку (''). Если формат вызова getMessage() неверен — например, messageName не является строкой или массив подстановок содержит более 9 элементов — этот метод возвращает undefined .
Параметры
- messageName
нить
Название сообщения, указанное в файле
messages.json. - замены
любой необязательный
До 9 строк подстановки, если это требуется в сообщении.
- параметры
объект необязательный
Chrome 79+- escapeLt
логический необязательный
Экранирование символа
<в переводе до<. Это относится только к самому сообщению, а не к заполнителям. Разработчики могут использовать это, если перевод используется в контексте HTML. Шаблоны замыканий, используемые с Closure Compiler, генерируют это автоматически.
Возвраты
нить
Сообщение локализовано для текущего языкового стандарта.
getUILanguage()
chrome.i18n.getUILanguage(): string
Получает язык пользовательского интерфейса браузера. Это отличается от i18n.getAcceptLanguages , которая возвращает предпочтительный язык пользователя.
Возвраты
нить
Языковой код пользовательского интерфейса браузера, например, en-US или fr-FR.