此页面由 Cloud Translation API 翻译。

chrome.i18n

说明

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

清单

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

概念和用法

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

以下是支持英语 (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="" have been="" changed="" chrome.i18n.getmessage("extname")，="" en="" file="" <文件名=""1=""1="" <strong>.<文件>"<文件名>/<文件名>。

关于国际化的一些说明：

您可以使用任何受支持的语言区域。如果您使用的语言区域不受支持，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，对其进行翻译，然后将该副本放入 /_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”；否则为“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	马拉地语
ms	马来语
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 的用户看到“颜色”标签，那么英式英语用户会看到“颜色”。美国英语和英式英语用户都会看到扩展程序名称“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。

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

注意：指定 --user-data-dir 不是强制要求，但很方便。为每个语言区域设置一个数据目录可让您同时以多种语言运行浏览器。其缺点是，由于系统不会共享语言区域的数据，因此您必须多次安装扩展程序（每个语言区域一次），当您不说相应语言时，这可能具有挑战性。如需了解详情，请参阅创建和使用配置文件。

使用界面

以下将介绍如何在 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 参考文档。

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
    
    对象 []
    
    DetectLanguage 的数组
    
    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。