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"="""zh".="""extname"."="""hello=""_locates=&quot;&quot;a=&quot;&quot;alt="在 manifest.json 文件中,"and=&quot;&quot;已经=""changed=&quot;&quot;chrome.i18n.getmessage("extname")=""defines=&quot;&quot;en=&quot;&quot;file=&quot;&quot;file,=&quot;&quot;has=&quot;&quot;hello=&quot;&quot;in=&quot;&quot;item=&quot;&quot;javascript=&quot;&quot;messages.json=&quot;&quot;named=&quot;&quot;new=""src=&quot;/static/docs/extensions/mv2/reference/i18n/images/i18n-after-1.gif&quot;the=&quot;&quot;to=&quot;&quot;value=""world"=""/>

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

  • 您可以使用任何受支持的语言区域。如果您使用的语言区域不受支持,Google Chrome 并忽略它。
  • manifest.json 和 CSS 文件中,引用名为 messagename 的字符串,如下所示:

    __MSG_messagename__
    
  • 在扩展程序或应用的 JavaScript 代码中,引用名为 messagename 的字符串,如下所示:

    chrome.i18n.getMessage("messagename")
    
  • 每次调用 getMessage() 时,您最多可以提供 9 个要在消息中包含的字符串。请参阅 示例:getMessage

  • 某些消息(例如 @@bidi_dir@@ui_locale)由国际化流程提供, 系统。如需查看预定义消息名称的完整列表,请参阅预定义消息部分。

  • messages.json 中,每个用户可见的字符串都有一个名称,即“消息”以及可选的 &quot;description&quot;内容。名称是一个键,例如“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_GBen_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 文件的每个字符串都有一个值,那么无论采用何种方式运行您的扩展程序或应用 翻译表现如何。扩展程序系统搜索消息的方法如下:

  1. 在消息文件(如果有)中搜索用户的首选语言区域。例如,当 Google Chrome 的语言区域设为英式英语 (en_GB),系统会先用以下语言查找消息: /_locates/en_GB/messages.json。如果该文件存在并且存在消息,系统会查找 不需要再执行后续操作了
  2. 如果用户偏好的区域设置包含区域(即区域设置中有下划线“_”),搜索 不包含该区域的语言区域例如,如果 en_GB 消息文件不存在,或者 消息,则系统会在 en 消息文件中查找。如果该文件存在,并且 消息就在那里,系统不再继续查看。
  3. 在消息文件中搜索默认语言区域。例如,如果扩展程序的 “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 文件会显示名为

设置浏览器的语言区域

如需测试翻译,您可能需要设置浏览器的语言区域。本部分介绍了如何设置 WindowsMac OS XLinuxChromeOS 中的语言区域。

Windows

您可以使用特定于语言区域的快捷方式或 Google Chrome 界面更改语言区域。通过 快捷方法更快捷,只要完成设置,即可同时使用多种语言。

使用特定于语言区域的快捷键

要创建和使用快捷方式,以在特定语言区域启动 Google Chrome,请执行以下操作:

  1. 复制桌面上已有的 Google Chrome 快捷方式。
  2. 重命名新的快捷方式,使其与新的语言区域相匹配。
  3. 更改快捷方式的属性,以便“Target”字段指定 --lang--user-data-dir 标志。目标应如下所示:

    path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
    
  4. 双击快捷方式以启动 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
使用界面

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

  1. 应用图标 >选项
  2. 选择高级选项标签页
  3. 向下滚动到网页内容
  4. 点击更改字体和语言设置
  5. 选择语言标签页
  6. 使用下拉菜单设置 Google Chrome 语言
  7. 重启 Chrome

Mac OS X

如要更改 Mac 上的语言区域,请使用系统偏好设置。

  1. 在 Apple 菜单中,选择系统偏好设置
  2. 个人部分下,选择国际
  3. 选择您的语言和位置
  4. 重启 Chrome

Linux

要在 Linux 上更改语言区域,请先退出 Google Chrome。然后在一行中,将 LANGUAGE 环境变量并启动 Google Chrome。例如:

LANGUAGE=es ./chrome

ChromeOS

如需更改 ChromeOS 的语言区域,请执行以下操作:

  1. 从系统任务栏中选择设置
  2. 语言和输入法部分下,选择语言下拉菜单。
  3. 如果您的语言未列出,请点击添加语言并进行添加。
  4. 添加语言后,点击相应语言旁边的三点状更多操作菜单项,然后选择 以这种语言显示 ChromeOS
  5. 点击已设置语言旁边显示的重启按钮,以重启 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 语言代码,例如 enfr。如需查看此方法支持的语言的完整列表,请参阅 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&lt;object&gt;

    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&lt;LanguageCode[]&gt;

    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

      布尔值(可选)

      在翻译成&lt;时转义“<”。这仅适用于消息本身,而不适用于占位符。如果是在 HTML 上下文中使用翻译,开发者可能需要使用此属性。与 Closure 编译器一起使用的 Closure 模板会自动生成此框。

返回

  • 字符串

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

getUILanguage()

chrome.i18n.getUILanguage()

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

返回

  • 字符串

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