chrome.i18n

Description

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

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

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

# 如何支持多种语言

假设您有一个包含下图所示文件的扩展名：

为了国际化这个扩展，你命名每个用户可见的字符串并将其放入一个消息文件中。扩展的清单、CSS 文件和 JavaScript 代码使用每个字符串的名称来获取其本地化版本。

这是扩展国际化后的样子（请注意，它仍然只有英文字符串）：

重要提示：如果扩展具有 _locales 目录，则清单必须定义“default_locale”。

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

您可以使用任何受支持的语言环境。如果您使用不受支持的语言环境，谷歌浏览器会忽略它。
在 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)”指定此语言环境中字符串的值。可选的“描述”为翻译人员提供帮助，他们可能无法看到字符串在您的扩展中的使用方式。例如：
```
{
  "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，因此您可以检测当前的 UI 区域设置，以及一些可让您检测文本方向的 @@bidi_...消息。后一种消息与小工具 BIDI（双向）API 中的常量具有相似的名称。

特殊消息@@extension_id 可用于 CSS 和 JavaScript 文件，无论扩展程序或应用程序是否已本地化。此消息在清单文件中不起作用。

下表描述了每个预定义的消息。

消息名称	Description
`@@extension_id`	扩展程序或应用程序 ID；您可以使用此字符串为扩展程序中的资源构建 URL。即使未本地化的扩展程序也可以使用此消息。注意：您不能在清单文件中使用此消息。
`@@ui_locale`	当前语言环境；您可以使用此字符串来构建特定于语言环境的 URL。
`@@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”，那么这是“对的”；否则，它是“左”。

下面是在 CSS 文件中使用 @@extension_id 构造 URL 的示例：

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;

# Locales(语言环境)

您可以从许多区域设置中进行选择，包括一些（例如 en）让单个翻译支持一种语言的多种变体（例如 en_GB 和 en_US）。

# Supported locales(支持的语言环境)

您不必为每个受支持的语言环境定义每个字符串。只要默认语言环境的 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 的用户都会看到标签“Colores”和扩展名“Hola mundo”。

# 如何设置浏览器的区域设置

要测试翻译，您可能需要设置浏览器的区域设置。本节介绍如何在 Windows、Mac OS X、Linux 和 Chrome OS 中设置区域设置。

# Windows

您可以使用特定于区域设置的快捷方式或 Google Chrome UI 更改区域设置。设置后，快捷方式会更快，并且可以让您同时使用多种语言。

# Using a locale-specific shortcut(使用特定于语言环境的快捷方式)

要创建和使用使用特定语言环境启动 Google Chrome 的快捷方式：

复制桌面上已有的 Google Chrome 快捷方式。
重命名新的快捷方式以匹配新的语言环境。
更改快捷方式的属性，以便 Target 字段指定 --lang 和 --user-data-dir 标志。目标应如下所示：
```
path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
```
1. 双击快捷方式启动谷歌浏览器。

例如，要创建一个以西班牙语 (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 是可选的，但很方便。每个区域设置一个数据目录可让您同时以多种语言运行浏览器。一个缺点是，由于区域设置的数据未共享，因此您必须多次安装扩展程序 — 每个区域设置一次，当您不会说该语言时，这可能具有挑战性。有关更多信息，请参阅创建和使用配置文件。

# Using the UI（使用用户界面）

以下是在 Windows 版 Google Chrome 上使用 UI 更改区域设置的方法：

App icon > Options （应用程序图标 > 选项）
Choose the Under the Hood tab （选择引擎盖下选项卡）
Scroll down to Web Content （向下滚动到 Web 内容）
Click Change font and language settings （单击更改字体和语言设置）
Choose the Languages tab （选择语言选项卡）
Use the drop down to set the Google Chrome language （使用下拉菜单设置 Google Chrome 语言）
Restart Chrome（重启 Chrome）

# Mac OS X

要更改 Mac 上的区域设置，请使用系统首选项。

From the Apple menu, choose System Preferences（从 Apple 菜单中，选择系统偏好设置）
Under the Personal section, choose International（在个人部分下，选择国际）
Choose your language and location（选择您的语言和位置）
Restart Chrome（重启 Chrome）

# Linux

要在 Linux 上更改语言环境，请先退出 Google Chrome。然后，在一行中设置 LANGUAGE 环境变量并启动Google Chrome。例如：

LANGUAGE=es ./chrome

# Chrome OS

要更改 Chrome 操作系统上的语言环境：

From the system tray, choose Settings.（从系统托盘中，选择设置。）
Under the Languages and input section, choose the Language dropdown.（在语言和输入部分下，选择语言下拉菜单。）
If your language is not listed, click Add languages and add it.（如果未列出您的语言，请单击添加语言并添加它。）
Once added, click the the 3-dot More actions menu item next to your language and choose Display Chrome OS in this language.（添加后，单击您的语言旁边的三点更多操作菜单项，然后选择以该语言显示 Chrome 操作系统。）
Click the Restart button that appears next to the set language to restart Chrome OS.（单击显示在设置语言旁边的重新启动按钮以重新启动 Chrome 操作系统。）

# Examples(例子)

您可以在 examples/api/i18n 目录中找到简单的国际化示例。有关完整示例，请参阅examples/extensions/news。有关其他示例和查看源代码的帮助，请参阅示例。

# Examples: 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 参考。

# Example: getAcceptLanguages

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

function getAcceptLanguages() {
  chrome.i18n.getAcceptLanguages(function(languageList) {
    var languages = languageList.join(",");
    document.getElementById("languageSpan").innerHTML = languages;
  })
}

有关调用 getAcceptLanguages() 的详细信息，请参阅 API 参考。

# Example: 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 参考。

Summary

Types

LanguageCode

Methods

detectLanguage
getAcceptLanguages
getMessage
getUILanguage

Types

# LanguageCode

Chrome 47+

ISO 语言代码，例如 en 或 fr。有关此方法支持的语言的完整列表，请参阅 kLanguageInfoTable。对于未知语言， und 将被返回，这意味着 [percentage] 文本是 CLD 未知的

TYPE

string

Methods

# detectLanguage

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

Chrome 47+

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

PARAMETERS

text

string

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

callback

function

callback参数如下所示：

(result: object) => void

result

object

LanguageDetectionResult 对象，包含检测到的语言可靠性和 DetectedLanguage 数组

isReliable
boolean
CLD 检测到的语言可靠性
languages
object[]
检测到的语言数组
- language
  string
- percentage
  number
  检测到的语言的百分比

# getAcceptLanguages

chrome.i18n.getAcceptLanguages( callback: function, )

获取浏览器的接受语言。这与浏览器使用的语言环境不同；要获取语言环境，请使用 i18n.getUILanguage。

PARAMETERS

callback

function

callback参数如下所示：

(languages: string[]) => void

languages
string[]
语言代码数组

# getMessage

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

Foreground only

获取指定消息的本地化字符串。如果消息丢失，则此方法返回一个空字符串 ('')。如果 getMessage() 调用的格式错误——例如，messageName 不是字符串或替换数组有超过 9 个元素——此方法返回 undefined。

PARAMETERS

messageName

string

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

substitutions

any optional

最多 9 个替换字符串（如果消息需要的话）。

options

object optional

Chrome 79+

escapeLt
boolean optional
将 < 转义为 <。这仅适用于消息本身，不适用于占位符。如果翻译用于 HTML 上下文，开发人员可能希望使用它。与 Closure Compiler 一起使用的 Closure Templates 会自动生成它。

RETURNS

string

针对当前区域设置本地化的消息。

# getUILanguage

chrome.i18n.getUILanguage()

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

RETURNS

string

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

By.一粒技术服务

chrome.i18n

chrome.i18n

Description

# 如何支持多种语言

# 预定义消息

# Locales(语言环境)

# Supported locales(支持的语言环境)

# 如何设置浏览器的区域设置

# Windows

# Using a locale-specific shortcut(使用特定于语言环境的快捷方式)

# Using the UI（使用用户界面）

# Mac OS X

# Linux

# Chrome OS

# Examples(例子)

# Examples: getMessage

# Example: getAcceptLanguages

# Example: detectLanguage

Summary

Types

Methods

Types

# LanguageCode

Methods

# detectLanguage

# getAcceptLanguages

# getMessage

# getUILanguage

results matching ""

No results matching ""