chrome.i18n

描述 使用 chrome.i18n 架构为您的整个应用或应用实现国际化支持。
可用版本 从 Chrome 5 开始支持。
内容脚本 完全支持。 了解更多

您需要把所有用户可见的字符串放在一个名为 messages.json 的文件中。每一次您增加新的语言时,您只要在名为 _locales/localeCode 的目录中添加一个消息文件,其中 localeCode 为语言代码,例如 en代表英语。

如下是具有国际化支持的应用的文件结构,它支持英语(en)、西班牙语(es)和韩语(ko):

In the extension directory: manifest.json, *.html, *.js, _locales directory. In the _locales directory: en, es, and ko directories, each with a messages.json file.

如何支持多种语言

假设您有一个应用,包含下图所示的几个文件:

A manifest.json file and a file with JavaScript. The .json file has "name": "Hello World". The JavaScript file has title = "Hello World";

要想为这一应用添加国际化支持,您需要为每一个用户可见的字符串命名,并将它们放在一个消息文件中。应用的清单文件、CSS 文件和 JavaScript 代码使用每一个字符串的名称来获得本地化的版本。

如下是为应用添加国际化支持后看上去的样子(注意它还仅包括英语的字符串):

In the manifest.json file, "Hello World" has been changed to "__MSG_extName__", and a new "default_locale" item has the value "en". In the JavaScript file, "Hello World" has been changed to chrome.i18n.getMessage("extName"). A new file named _locales/en/messages.json defines "extName".

重要提示: 如果您的应用包含 _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"(消息)指定当前语言中字符串的值,可选的 "description"(描述)向翻译者提供帮助,因为翻译者不一定能看到该字符串是如何在您的应用中使用的。例如:
          {
            "search_string": {
              "message": "您好",
              "description": "我们搜索的字符串"
            },
            ...
          }

    有关更多信息,请参见格式:区域特定的消息

一旦为应用或应用添加国际化支持后,将它翻译成另一种语言是非常简单的。您可以复制 messages.json,翻译它,然后将所得文件放在 _locales 下的新目录中。例如,要支持西班牙语,只要将一份已翻译的 messages.json 的副本放在 _locales/es 中即可。下图展示了具有新的西班牙语翻译的应用。

This looks the same as the previous figure, but with a new file at _locales/es/messages.json that contains a Spanish translation of the messages.

预定义消息

国际化支持系统提供了一些预定义消息,来帮助您本地化。这些消息包括 @@ui_locale,让您检测当前用户界面的语言,还有一些 @@bidi_... 消息,让您检测文字方向,@@bidi_... 消息的名称类似于小工具 BIDI(双向)API 中的常量。

无论应用或应用是否已经本地化,都可以在 CSS 和 JavaScript 文件中使用特殊消息 @@extension_id。 这一消息在清单文件中不起作用。

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

消息名称 描述
@@extension_id 应用或应用标识符,您可能需要这一字符串来构造 URL,用于应用中的资源。即使没有本地化的应用也能使用这一消息。
注意: 您不能在清单文件中使用这一消息。
@@ui_locale 当前语言,您可能需要这一字符串来构造区域特定的 URL。
@@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 构造 URL 的例子:

      body {
        background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
      }
      

如果应用标识符为 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_GBen_US)的语言。

支持的语言

您可以使用 百度浏览器应用中心支持的任何语言

搜索消息

您不需要为支持的每一种语言定义每一个字符串。只要默认语言的 messages.json 文件包含每一个字符串的值,无论一种翻译多么稀少您的应用或应用都能运行。如下是应用系统搜索消息的步骤:

  1. 搜索用户首选语言对应的消息文件(如果有的话)。例如,当百度浏览器的语言设置为英式英语(en_GB)时,系统首先在 _locales/en_GB/messages.json 中查找消息。如果文件存在并且找到相应的消息,则系统不再继续查找。
  2. 如果用户首选语言包含区域(即语言名称含有下划线:_),则继续搜索没有指定区域的语言。例如,如果 en_GB 消息文件不存在或者没有包含相应的消息,则系统在 en 的消息文件中查找。如果文件存在并且找到相应的消息,则系统不再继续查找。
  3. 搜索默认语言的消息文件。例如,如果应用的 "default_locale" 设置为 "es",并且 _locales/en_GB/messages.json_locales/en/messages.json 都没有包含对应消息,则应用使用来自 _locales/es/messages.json 的消息。

在下图中,名为 "colores" 的消息在应用支持的三种语言中都存在,但是 "extName" 仅在其中两种语言中存在。用户以美式英语为首选语言运行百度浏览器时看到 "Colors" 标签,在以英式英语为首选语言运行百度浏览器时看到 "Colours",而美式英语与英式英语的用户都能看到应用名称 "Hello World"。因为默认语言为西班牙语,用户在任何非英语语言中运行百度浏览器都会看到 "Colores" 标签以及扩展名称 "Hola mundo"。

Four files: manifest.json and three messages.json files (for es, en, and en_GB).  The es and en files show entries for messages named "extName" and "colores"; the en_GB file has just one entry (for "colores").

例子:getMessage

以下代码从浏览器获取本地化的消息,并显示为字符串,其中还将消息中的两个占位符分别替换为 "string1" 和 "string2"。

      function getMessage() {
        var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
        document.getElementById("languageSpan").innerHTML = message;
      }
      

如下代码演示如何提供并使用单个字符串:

      // 在 JavaScript 代码中
      status.innerText = chrome.i18n.getMessage("error", errorDetails);
      
      "error": {
        "message": "错误:$details$",
        "description": "通用错误模板,需要传递错误参数。",
        "placeholders": {
          "details": {
            "content": "$1",
            "example": "无法获取 RSS 供稿。"
          }
        }
      }
      

有关占位符的更多信息,请参见区域特定的消息页面。有关调用 getMessage() 的细节,请参见 API 参考

例子:getAcceptLanguages

以下代码从浏览器获取可接受的语言,并且将它们以逗号分开显示出来:

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

有关调用 getAcceptLanguages() 的细节,请参见 API 参考

摘要

方法
getAcceptLanguages chrome.i18n.getAcceptLanguages(function callback)
getMessage string chrome.i18n.getMessage(string messageName, any substitutions)
getUILanguage string chrome.i18n.getUILanguage()

方法

getAcceptLanguages

chrome.i18n.getAcceptLanguages(function callback)

获取浏览器可接受的语言。这和浏览器使用的语言不同,要获取这一语言,请使用 i18n.getUILanguage

参数
function callback

callback 参数应该是一个如下形式的函数:

function(array of string languages) {...};
array of string languages

包含浏览器可接受的所有语言的数组,例如en-US、en、zh-CN。

getMessage

string chrome.i18n.getMessage(string messageName, any substitutions)

获得指定消息的本地化字符串。如果消息不存在,该方法返回空字符串("")。如果 getMessage() 的调用格式不正确,例如,messageName 不是字符串或者 substitutions 数组为空或包含的元素超过 9 个,该方法返回 undefined

参数
string messageName

消息的名称,与 messages.json 文件中指定的一致。

any (可选)
substitutions

如果对应的消息需要的话,则包含最多 9 个替代字符串。

getUILanguage

string chrome.i18n.getUILanguage()

从 Chrome 35 开始支持。

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