说明
使用 chrome.i18n
基础架构在您的整个应用或扩展程序中实现国际化。
您需要将其中的所有用户可见的字符串都放在名为 messages.json
的文件中。每次添加新的语言区域时,您都需要在名为 _locales/_localeCode_
的目录下添加消息文件,其中 localeCode 是代码,例如 en
表示英语。localeCode
以下是支持英语 (en
)、西班牙语 (es
) 和韩语 (ko
) 的国际化扩展程序的文件层次结构:
如何支持多种语言
假设您有一个包含下图所示文件的扩展名:
要对此扩展程序进行国际化,您需要为每个用户可见的字符串命名,并将其放入消息文件中。扩展程序的清单、CSS 文件和 JavaScript 代码使用每个字符串的名称来获取其本地化版本。
该扩展程序国际化后将如下所示(请注意,它仍然只包含英语字符串):
<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locales="" a="" alt="在 manifest.json 文件中, " and="" been="" changed="" chrome.i18n.getmessage("extname") 指定="" en="" <静态文件名>{4/}.json="" "1=""1"
关于国际化的一些说明:
- 您可以使用任何受支持的语言区域。如果您使用的语言区域不受支持,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”。“message”用于指定此语言区域中的字符串值。可选的“说明”可为翻译人员提供帮助,他们可能无法看到字符串在扩展程序中的使用方式。例如:{ "search_string": { "message": "hello%20world", "description": "The string we search for. Put %20 between words that go together." }, ... }
有关详情,请参阅格式:语言区域专用消息。
扩展程序或应用一经国际化,翻译过程就非常简单。您需要复制 messages.json
,对其进行翻译,然后将该副本放入 _locales
下的新目录中。例如,如需支持西班牙语,只需在 _locales/es
下添加 messages.json
的翻译副本即可。下图显示了使用新西班牙语翻译的上一条扩展。
预定义的消息
为帮助您进行本地化,国际化系统提供了一些预定义的消息。这些消息包括 @@ui_locale
(便于您检测当前的界面语言区域),以及一些 @@bidi_...
消息(可让您检测文本方向)。后一种消息的名称与小工具 BIDI(双向)API 中的常量名称类似。
特殊消息 @@extension_id
可在 CSS 和 JavaScript 文件中使用,无论扩展程序或应用是否已本地化。此消息在清单文件中不起作用。
下表介绍了每条预定义消息。
消息名称 | 说明 |
---|---|
@@extension_id | 扩展程序或应用 ID;您可以使用此字符串为扩展程序中的资源构建网址。即使是未本地化的扩展程序也可以使用此消息。 注意:您不能在清单文件中使用此消息。 |
@@ui_locale | 当前语言区域;您可以使用此字符串构建特定于语言区域的网址。 |
@@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”。 |
以下示例展示了如何在 CSS 文件中使用 @@extension_id
来构建网址:
body {
background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}
如果扩展程序 ID 为 abcdefghijklmnopqrstuvwxyzabcdef,则上一个代码段中的粗体行变为:
background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png');
下面是一个在 CSS 文件中使用 @@bidi_*
消息的示例:
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
文件中每个字符串都有一个值,无论翻译有多稀疏,您的扩展程序或应用都会运行。扩展程序系统搜索消息的方式如下:
- 在消息文件(如果有)中搜索用户首选的语言区域。例如,当 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 的用户看到“颜色”标签,那么英式英语用户会看到“颜色”。美国英语和英式英语用户都会看到扩展程序名称“Hello World”。由于默认语言为西班牙语,因此以任何非英语语言运行 Google Chrome 的用户会看到“颜色”标签和扩展程序名称“Hola mundo”。
如何设置浏览器的语言区域
如需测试翻译,您可能需要设置浏览器的语言区域。本部分介绍了如何在 Windows、Mac OS X、Linux 和 ChromeOS 中设置语言区域。
Windows
您可以使用语言区域特定的快捷方式或 Google Chrome 界面来更改语言区域。完成设置后,使用快捷方式的方法会更快,并且可让您同时使用多种语言。
使用特定于语言区域的快捷方式
要创建并使用快捷方式以特定的语言区域启动 Google Chrome,请执行以下操作:
- 复制桌面上已有的 Google Chrome 快捷方式。
- 重命名新快捷方式以匹配新的语言区域。
更改快捷方式的属性,以便“Target”字段指定
--lang
和--user-data-dir
标志。目标应如下所示:path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
双击快捷方式启动 Google Chrome。
例如,若要创建用西班牙语 (es
) 启动 Google Chrome 的快捷方式,您可以创建具有以下目标的名为 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 版)上使用用户界面更改语言区域:
- 应用图标 > 选项
- 选择高级选项标签页
- 向下滚动到 Web 内容
- 点击更改字体和语言设置
- 选择语言标签页
- 使用下拉菜单设置 Google Chrome 语言
- 重启 Chrome
Mac OS X
要在 Mac 上更改语言区域,请使用系统偏好设置。
- 在 Apple 菜单中,选择系统偏好设置
- 在个人部分下,选择国际
- 选择语言和位置
- 重启 Chrome
Linux
要在 Linux 上更改语言区域,请先退出 Google Chrome。然后,在同一行中设置 LANGUAGE 环境变量并启动 Google Chrome。例如:
LANGUAGE=es ./chrome
ChromeOS
如需在 ChromeOS 上更改语言区域,请执行以下操作:
- 从系统任务栏中选择设置。
- 在语言和输入法部分下,选择语言下拉菜单。
- 如果您的语言未列出,请点击添加语言并进行添加。
- 添加后,点击您语言旁边的三点状更多操作菜单项,然后选择以这种语言显示 ChromeOS。
- 点击设置的语言旁边显示的重启按钮,以重启 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 参考文档。
示例:getAcceptlanguage
以下代码会从浏览器获取接受语言,并将其显示为字符串,用“,”分隔每种接受语言。
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 无法识别文字的 [percentage]
类型
string
方法
detectLanguage()
chrome.i18n.detectLanguage(
text: string,
callback?: function,
)
使用 CLD 检测所提供的文本的语言。
参数
-
text
string
要翻译的用户输入字符串。
-
callback
函数(可选)
callback
参数如下所示:(result: object) => void
-
结果
对象
包含检测到的语言可靠性和 DetectedLanguage 数组的 LanguageDetectionResult 对象
-
isReliable
boolean
CLD 检测到的语言可靠性
-
languages
对象 []
DetectLanguage 的数组
-
language
string
-
百分数
number
检测到的语言所占的百分比
-
-
-
返回
-
Promise<object>
Chrome 99 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getAcceptLanguages()
chrome.i18n.getAcceptLanguages(
callback?: function,
)
获取浏览器的接受语言。这与浏览器使用的语言区域不同;要获取语言区域,请使用 i18n.getUILanguage
。
参数
-
callback
函数(可选)
callback
参数如下所示:(languages: string[]) => void
-
languages
字符串[]
LanguageCode 数组
-
返回
-
Promise<LanguageCode[]>
Chrome 99 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getMessage()
chrome.i18n.getMessage(
messageName: string,
substitutions?: any,
options?: object,
)
获取指定消息的本地化字符串。如果消息缺失,此方法会返回一个空字符串 (')。如果 getMessage()
调用的格式错误(例如,messageName 不是字符串或 substitutions 数组包含 9 个以上的元素),则此方法会返回 undefined
。
参数
-
messageName
string
消息的名称,在
messages.json
文件中指定。 -
substitutions
任意(可选)
最多 9 个替换字符串(如果消息需要任何替代字符串)。
-
选项
对象(可选)
Chrome 79 及更高版本-
escapeLt
布尔值 选填
转义为
<
时对应的<
转义。这仅适用于消息本身,不适用于占位符。如果在 HTML 上下文中使用译文,开发者可能需要使用此方法。与 Closure 编译器配合使用的 Closure 模板会自动生成此说明。
-
返回
-
string
已针对当前语言区域本地化消息。
返回
-
string
浏览器界面语言代码,例如 en-US 或 fr-FR。