此页面由 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 代码使用每个字符串的名称来获取其本地化版本。

以下是扩展程序国际化后的内容（请注意，扩展程序仍仅包含英语字符串）：

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locates="" a="" alt="在 manifest.json 文件中，" and="" been="" changed="" chrome.i18n.getmessage("extname") " file" " " " "

关于国际化的一些注意事项：

您可以使用任何受支持的语言区域。如果您使用不受支持的语言区域，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”用于指定此语言区域中的字符串值。可选的“description”为翻译人员提供了帮助，因为翻译人员可能无法了解该字符串在扩展程序中的使用方式。例如：
```
{
  "search_string": {
    "message": "hello%20world",
    "description": "The string we search for. Put %20 between words that go together."
  },
  ...
}
```

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

扩展程序国际化后，翻译工作非常简单。您复制 messages.json 并对其进行翻译，然后将副本放入 /_locates 下的新目录中。例如，如需支持西班牙语，只需将 messages.json 的翻译副本放在 /_locates/es 下即可。下图显示了包含新西班牙语翻译的上一个扩展程序。

这与上一个图相同，但带有一个新文件 /_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”；否则，此值为“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 应用商店支持的任何语言区域对扩展程序进行本地化。如果此处未列出您的语言区域，请选择最接近的备选语言区域。例如，如果扩展程序的默认语言区域是"de_CH"，请在 Chrome 应用商店中选择 "de"。

语言区域代码	语言（区域）
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	印地语
小时	克罗地亚语
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”仅包含其中两个语言区域。当使用美式英语的 Google Chrome 用户看到“Colors”标签时，英国英语用户看到“Colors”。美国英语和英国英语用户都会看到扩展程序名称“Hello World”。由于默认语言是西班牙语，因此以任何非英语运行 Google Chrome 的用户都会看到标签“Colores”和扩展程序名称“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()

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

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]

类型

string

方法

detectLanguage()

Promise Chrome 47 及更高版本

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

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

参数

text

string

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

函数（可选）

callback 参数的格式为：
```
(result: object) => void
```
- 结果
  
  对象
  
  包含检测到的语言可靠性和 DetectedLanguage 数组的 LanguageDetectionResult 对象
  - isReliable
    
    boolean
    
    CLD 检测到的语言可靠性
  - languages
    
    对象 []
    
    由 detectedLanguage 组成的数组
    
    language
    
    string
    
    百分数
    
    number
    
    检测到的语言所占的百分比

Promise<object>

Chrome 99 及更高版本

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

getAcceptLanguages()

Promise

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

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

参数

callback

函数（可选）

callback 参数的格式为：
```
(languages: string[]) => void
```
- languages
  
  字符串[]
  
  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

string

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

任何选填字段

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

对象（可选）

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

string

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

getUILanguage()

chrome.i18n.getUILanguage()

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

string

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