此页面由 Cloud Translation API 翻译。

chrome.i18n

说明

使用 chrome.i18n 基础架构在您的整个应用或扩展程序中实现国际化。

清单

如果扩展程序具有 /_locales 目录，则清单必须定义 "default_locale"。

概念和用法

您需要将其所有的用户可见字符串都放入名为 messages.json 的文件中。每次添加新的语言区域时，请在名为 /_locales/_localeCode_ 的目录下添加消息文件，其中 localeCode 是一个代码，例如表示英语的 en。

以下是支持英语 (en)、西班牙语的国际化扩展程序的文件层次结构 (es) 和韩语 (ko)：

在扩展程序目录中：manifest.json、*.html、*.js、/_locates 目录。在 /_locates 目录中：en、es 和 ko 目录，每个目录包含 messages.json 文件。

支持多种语言

假设您的扩展程序包含如下图所示的文件：

一个 manifest.json 文件和一个包含 JavaScript 的文件。该 .json 文件包含

如需对此扩展程序进行国际化，请为每个用户可见的字符串命名，并将其放入消息中文件。扩展程序的清单、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 中，每个用户可见的字符串都有一个名称，即“消息”以及可选的 "description"内容。名称是一个键，例如“extName”或“搜索字符串”用于标识字符串。“消息”指定此语言区域中的字符串值。“说明”字段（可选）为翻译人员提供了帮助，因为他们可能无法了解该字符串在。例如：
```
{
  "search_string": {
    "message": "hello%20world",
    "description": "The string we search for. Put %20 between words that go together."
  },
  ...
}
```

如需了解详情，请参阅格式：语言区域专用消息。

扩展程序国际化后，翻译工作非常简单。您复制 messages.json、翻译该文件，然后将副本放入 /_locates 下的新目录中。例如，为了支持西班牙语，只需在/_locates/es下方附上messages.json的翻译副本即可。下图会显示带有新西班牙语翻译的上一个扩展程序。

这与上一个图一样，但带有一个新文件 /_locates/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”；否则就是“正确”。
`@@bidi_end_edge`	如果 `@@bidi_dir` 为“ltr”，就表示“right”；否则为“左侧”。

以下示例展示了如何在 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 应用商店支持的任何语言区域对扩展程序进行本地化。如果此处未列出您的语言区域，请选择最接近的备选语言区域。例如，如果扩展程序的默认语言区域是"de_CH"，请在 Chrome 应用商店中选择 "de"。

语言区域代码	语言（区域）
ar	阿拉伯语
am	阿姆哈拉语
bg	保加利亚语
bn	孟加拉语
ca	加泰罗尼亚语
cs	捷克语
da	丹麦语
de	德语
el	希腊语
en	英语
en_AU	英语（澳大利亚）
en_GB	英语（英国）
zh_CN	英语（美国）
es	西班牙语
es_419	西班牙语（拉丁美洲和加勒比地区）
et	爱沙尼亚语
fa	波斯语
fi	芬兰语
fil	菲律宾语
fr	法语
gu	古吉拉特语
他	希伯来语
hi	印地语
小时	克罗地亚语
hu	匈牙利语
id	印度尼西亚语
it	意大利语
ja	日语
kn	卡纳达语
ko	韩语
lt	立陶宛语
lv	拉脱维亚语
ml	马拉雅拉姆语
mr	马拉地语
毫秒	马来语
nl	荷兰语
否	挪威语
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)，系统会先用以下语言查找消息： /_locates/en_GB/messages.json。如果该文件存在并且存在消息，系统会查找不需要再执行后续操作了
如果用户偏好的区域设置包含区域（即区域设置中有下划线“_”），搜索不包含该区域的语言区域例如，如果 en_GB 消息文件不存在，或者消息，则系统会在 en 消息文件中查找。如果该文件存在，并且消息就在那里，系统不再继续查看。
在消息文件中搜索默认语言区域。例如，如果扩展程序的 “default_locale”已设置为“es”，且 /_locates/en_GB/messages.json 和 /_locates/en/messages.json 包含消息，该扩展程序使用来自 /_locates/es/messages.json。

在下图中，名为“colores”的消息扩展程序的三个语言区域但支持“extName”只有 2 个语言区域。美国境内使用 Google Chrome 浏览器的用户英语用户看到“Colors”标签，而英国英语用户看到“Colours”标签。美式英语和英国英语用户会看到扩展程序名称“Hello World”。由于默认语言是西班牙语以任何非英语语言运行 Google Chrome 浏览器的用户都会看到“颜色”标签和扩展程序名字“Hola mundo”。

四个文件：manifest.json 和三个 messages.json 文件（用于 es、en 和 en_GB）。es 和 en 文件会显示名为

设置浏览器的语言区域

如需测试翻译，您可能需要设置浏览器的语言区域。本部分介绍了如何设置 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。

例如，要创建用西班牙语启动 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

注意：虽然指定 --user-data-dir 是可选操作，但会非常方便。每个语言区域有一个数据目录可让您同时使用多种语言运行浏览器。其缺点在于语言区域的您必须多次安装扩展程序 - 每个语言区域一次，如果您不懂当地语言，这可能会是一个挑战。如需了解详情，请参阅创建和使用配置文件。

使用界面

下面介绍了如何使用适用于 Windows 的 Google Chrome 浏览器的界面更改语言区域：

应用图标 >选项
选择高级选项标签页
向下滚动到网页内容
点击更改字体和语言设置
选择语言标签页
使用下拉菜单设置 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 参考文档。

getAcceptLanguages()

以下代码从浏览器获取 Accept-languages，并将它们显示为字符串，用“,”分隔各个接受语言。

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

Chrome 47 及更高版本

ISO 语言代码，例如 en 或 fr。如需查看此方法支持的语言的完整列表，请参阅 kLanguageInfoTable。对于未知语言，系统将返回 und，这意味着 CLD 无法识别文本的 [percentage]

类型

字符串

方法

detectLanguage()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 47 及更高版本

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

使用 CLD 检测所提供文本的语言。

参数

text

字符串

要翻译的用户输入字符串。
callback

函数（可选）

callback 参数如下所示：
```
(result: object) => void
```
- 结果
  
  对象
  
  包含检测到的语言可靠性和 DetectedLanguage 数组的 LanguageDetectionResult 对象
  - isReliable
    
    布尔值
    
    CLD 检测到的语言可靠性
  - 语言
    
    object[]
    
    由 detectedLanguage 组成的数组
    
    language
    
    字符串
    
    百分比
    
    number
    
    检测到的语言所占的百分比

Promise<object>

Chrome 99 及更高版本

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getAcceptLanguages()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.i18n.getAcceptLanguages(
  callback?: function,
)

获取浏览器的接受语言。它不同于浏览器使用的语言区域；如需获取语言区域，请使用 i18n.getUILanguage。

参数

callback

函数（可选）

callback 参数如下所示：
```
(languages: string[]) => void
```
- 语言
  
  字符串[]
  
  LanguageCode 数组

Promise<LanguageCode[]>

Chrome 99 及更高版本

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getMessage()

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

获取指定消息的本地化字符串。如果消息丢失，此方法将返回空字符串 ('')。如果 getMessage() 调用的格式不正确（例如，messageName 不是字符串或者 substitutions 数组包含超过 9 个元素），则此方法会返回 undefined。

参数

messageName

字符串

messages.json 文件中指定的消息名称。
substitutions

任何选填字段

最多 9 个替换字符串（如果需要）。
选项

对象（可选）

Chrome 79 及更高版本
- escapeLt
  
  布尔值（可选）
  
  在翻译成<时转义“<”。这仅适用于消息本身，而不适用于占位符。如果是在 HTML 上下文中使用翻译，开发者可能需要使用此属性。与 Closure 编译器一起使用的 Closure 模板会自动生成此框。

字符串

消息已针对当前语言区域进行了本地化。

getUILanguage()

chrome.i18n.getUILanguage()

获取浏览器的浏览器界面语言。它与返回首选用户语言的 i18n.getAcceptLanguages 不同。

字符串

浏览器界面语言代码，例如 en-US 或 fr-FR。