Localization

该SDK支持本地化字符串出现在:

目前为止还不支持本地化CSS和content scripts。

本地化字符串

翻译后的字符串都保存在你的add-on扩展目录下一个名为 "locale"的目录，每个本地化地域对应一个文件。这些文件：

使用文件.properties 格式
被命名为 "xx-YY.properties", 这里的 "xx-YY" 是 name of the locale（本地化区域的名称）
包含所有你想要本地化的字符串，其中由一个本地化字符串标识ID和对应的本地化翻译字符串以 "标识ID=本地化翻译的字符串" 的格式组成。(contain one entry for each string you want to localize, consisting of an identifier for the string and its translation in that locale, in the format identifier=translation.)
需要使用没有BOM的UTF-8格式来编码(need to use UTF-8 without BOM encoding)

假设你的附加组件包含一个单一的本地化字符串，用英语表示为“Hello！”，你想提供英语和法语的本地化支持。

你需要添加两个文件到"locale"目录：

my-addon/
         data
         lib
         locale/
                en-US.properties
                fr-FR.properties

"en-US.properties" 文件中内容:

hello_id= Hello!

"fr-FR.properties" 文件中内容:

hello_id= Bonjour !

现在，每当你的JavaScript或HTML向本地化系统请求hello_id标识的翻译，它将获得与当前区域语言一致的翻译。

在HTML中使用本地化字符串

本例使用的 action button API需要 Firefox 29 或者更高版本。

要从HTML中引用本地化字符串，需要添加一个 data-l10n-id 的属性，到你想本地化的字符串所属的HTML标签中，然后为该属性指定一个ID值(To reference localized strings from HTML, add a data-l10n-id attribute to the HTML tag where you want the localized string to appear, and assign the identifier to it)：

<html>
  <body>
    <h1 data-l10n-id="hello_id"></h1>
  </body>
</html>

然后你就可以使用这个HTML文件来建立你的界面, 比如插入一个 panel 面板：

var button = require("sdk/ui/button/action").ActionButton({
  id: "localized-hello",
  label: "Localized hello",
  icon: "./icon-16.png",
  onClick: function() {
    hello.show();
  }
});

var hello = require("sdk/panel").Panel({
  height: 75,
  width: 150,
  contentURL: require("sdk/self").data.url("my-panel.html")
});

“en-US”和“fr-FR”提供了翻译标识为hello_id字符串的本地化文件，面板将根据当前区域语言设置，显示“Hello！”或者“Bonjour！”：

翻译文本会插入到具有data-l10n-id属性集的节点中。任何之前存在的内容只是被替换掉了。(The translation is inserted into the node which has the data-l10n-id attribute set. Any previously existing content is just replaced.)

本地化字符串只能作为text文本插入, 所以你不能使用下面的语句插入HTML：

hello_id= <blink>Hello!</blink>

Localizing Element Attributes

这是 Firefox 39 上的新功能

你可以在properties文件中，通过设置 l10n-id.attributeName 的值，本地化某些具有 l10n-id属性的元素的属性值。像这样(You can localize certain attributes of elements with an l10n-id by setting its value with l10n-id.attributeName in the properties file like)：

hello_id.accesskey= H

可以支持以下几个属性：

accesskey
alt
label
title
placeholder

更多的 ARIA 属性aria-label, aria-valuetext 和 aria-moz-hint 的本地化将通过在Firefox OS上同样的别名被支持(Further the localization of the ARIA attributes aria-label, aria-valuetext and aria-moz-hint are supported with the same aliases as on Firefox OS)：

ariaLabel
ariaValueText
ariaMozHint

在JavaScript代码中使用本地化字符串

为了在主附加组件代码中引用本地化字符串，你需要这样做：

var _ = require("sdk/l10n").get;
console.log(_("hello_id!"));

指定的 "_" 并不是必需的，但是作为 gettext 工具的默认约定，这能更好的配合其他默认使用 "_" 来表示本地化字符串的现有工具。

导入 l10n 模块，然后指定 "_" (下划线）为模块的 get 函数。
把所有涉及本地化的字符串放到 _() 函数中包括起来。

如果你运行它，你会看到输出为预期的当前设置的区域语言:

info: Hello!

info: Bonjour !

注意你不能在content scripts中 require() 一个模块，所以目前还不能在content script 中引用本地化字符串。

复数

l10n 模快支持复数形式，不同的语言有不同的复数形态。例如，英语有两种形式：相对于"one"的单数形式，和对于"everything else, including zero"的复数形式：

one tomato
no tomatoes
two tomatoes

但是俄罗斯语对于以 1 结尾(除了11)的数字、以 2-4 结尾(除了12-14)的数字和其他数字，有着不同的复数形态：

один помидор     // one tomato
два помидора     // two tomatoes
пять помидоров   // five tomatoes

SDK使用 Unicode CLDR 数据描述由不同的语言使用的不同复数形式。

Unicode CLDR 复数形式

Unicode CLDR项目定义了用于描述一个特定语言的多个规则的一种方案。在这个方案中一种语言对应最多有六种不同的范围的数字，有以下类别区分：zero(零个)，one(一个)，two(两个)，few(几个)，many(很多)，和other(其他)。(The Unicode CLDR project defines a scheme for describing a particular language's plural rules. In this scheme a language maps each distinct range of numbers on to one of up to six forms, identified by the following categories: zero, one, two, few, many, and other.)

英语有两种复数形式，可以表示为 "1" 映射到 "one" 和 "everything else" 映射到 "other"的形式(English has two forms, which can be described by mapping "1" to "one" and "everything else" to "other")：

one   → n is 1;
other → everything else

俄罗斯语有四种形式，可以使用以下方式表示:

one   → n mod 10 is 1 and n mod 100 is not 11;
few   → n mod 10 in 2..4 and n mod 100 not in 12..14;
many  → n mod 10 is 0 or n mod 10 in 5..9 or n mod 100 in 11..14;
other → everything else

所有语言的多个规则可以在CLDR的语言复数规则页面查到 (即使这个规则表相对于 CLDR XML source 已经过时了).

SDK中的复数形式

代码中，在 _()函数中的本地化ID参数之后提供一个额外的参数，用来表示代表多少个项的本地化字符串(In the code, you supply an extra parameter alongside the identifier, describing how many items there are)：

var _ = require("sdk/l10n").get;
console.log(_("tomato_id"));
console.log(_("tomato_id", 1));
console.log(_("tomato_id", 2));
console.log(_("tomato_id", 5));
console.log(_("tomato_id", .5));

在 .properties 文件中通过使用 CLDR 关键字，对于每种语言可能的复数形式你可以自定义不同的本地化字符串。所以对于英语可以有两种本地化（注意"other" 分类不是 CDLR 关键字）。（In the .properties file for each language you can define a different localization for each plural form possible in that language, using the CLDR keywords. So in English we could have two plural localizations (note that the "other" category does not take the CLDR keyword)）

# en-US translations
tomato_id[one]= %d tomato
tomato_id= %d tomatoes

俄罗斯语中可以定义四种本地化的复数形式：

# ru-RU translations
tomato_id[one]= %d помидор
tomato_id[few]= %d помидора
tomato_id[many]= %d помидоров
tomato_id= %d помидоры

The localization module itself understands the CLDR definitions for each language, enabling it to map between, for example, "2" in the code and "few" in the ru-RU.properties file. Then it retrieves and returns the localization appropriate for the count you supplied.

Placeholders

The l10n module supports placeholders, allowing you to insert a string which should not be localized into one which is. The following "en-US" and "fr-FR" ".properties" files include placeholders:

# en-US translations
hello_id= Hello %s!

# fr-FR translations
hello_id= Bonjour %s !

To use placeholders, supply the placeholder string after the identifier:

var _ = require("sdk/l10n").get;
console.log(_("hello_id", "Bob"));
console.log(_("hello_id", "Alice"));

In the "en-US" locale, this gives us:

info: Hello Bob!
info: Hello Alice!

In "fr-FR" we get:

info: Bonjour Bob !
info: Bonjour Alice !

Ordering Placeholders

When a localizable string can take two or more placeholders, translators can define the order in which placeholders are inserted, without affecting the code.

Primarily, this is important because different languages have different rules for word order. Even within the same language, though, translators should have the freedom to define word order.

For example, suppose we want to include a localized string naming a person's home town. There are two placeholders: the name of the person and the name of the home town:

var _ = require("sdk/l10n").get;
console.log(_("home_town_id", "Bob", "London"));

An English translator might want to choose between the following:

"<town_name> is <person_name>'s home town."

"<person_name>'s home town is <town_name>"

To choose the first option, the .properties file can order the placeholders as follows:

home_town_id= %2s is %1s's home town.

This gives us the following output:

info: London is Bob's home town.

在首选项设置中的本地化字符串

通过加入一个 "preferences" 字段的结构到你的附加组件的 "package.json" 文件中，你可以为你的附加组件定义首选项选项，用户可以在Firefox的 Add-ons Manager 看到和编辑它。

Preferences (首选项)有一个必需的title标题项和一个可选的description描述项这些字符串将出现在 Add-ons Manager中，来帮助向用户解释各个首选项设置的意义。

要对preferences中的title标题部分进行本地化，所有在"properties"文件中，形式为preferences中的name后面接着 _title 的本地化标识ID，其对应的值就是标题的本地化字符串。(To provide the localized form of the preference title, include an entry in your "properties" file whose identifier is the preference name followed by _title, and whose value is the localized title.)
要对preferences中的description描述部分进行本地化，所有在"properties"文件中，形式为preferences中的name后面接着 _description 的本地化标识ID，其对应的值就是描述的本地化字符串。(To provide the localized form of the preference description, include an entry in your "properties" file whose identifier is the preference name followed by _description, and whose value is the localized description.）

例如, 假设你的 "package.json" 中只定义了一个设置选项：

{
    "preferences": [
        {
            "type": "string", 
            "name": "monster_name", 
            "value": "Gerald",
            "title": "Name"
        }
    ], 
    "name": "monster-builder", 
    "license": "MPL 2.0", 
    "author": "me", 
    "version": "0.1", 
    "fullName": "Monster Builder", 
    "id": "[email protected]", 
    "description": "Build your own monster"
}

在你的"en-US.properties"文件中, 应该包括下面两个项：

monster_name_title= Name
monster_name_description= What is the monster's name?

在你的"fr-FR.properties"文件中, 应该包括下面两个法语的翻译项：

monster_name_title= Nom
monster_name_description= Quel est le nom du monstre ?

现在，当浏览器的区域设置为 "en-US", 用户会在 Add-ons Manager看到这样：

当浏览器区域设置为 "fr-FR", 用户会看到:

下拉菜单menulist和单选按钮radio的类型有多个选项，每一个选项的标签属性都会展示给用户。如果本地化文件中有一项是以前缀是"{name} _options" 为键的键值对，其中"{name}"是选项的标签名字，该键值对的值就是一个选项标签的本地化字符串。（The menulist and the radio preference types have options. The label attribute of each option is displayed to the user. If the locale file has a entry with the value of the label attribute prefixed with "{name}_options." as its key, where {name} is the name of the preference, its value is used as a localized label.）

Using Identifiers

If the localization system can't find an entry for a particular identifier using the current locale, then it just returns the identifier itself.

This has the nice property that you can write localizable, fully functional add-ons without having to write any locale files. You can just use the default language strings as your identifier, and subsequently supply .properties files for all the additional locales you want to support.

For example, in the case above you could use "Hello!" as the identifier, and just have one .properties file for the "fr-FR" locale:

Hello!= Bonjour !

Then when the locale is "en-US", the system would fail to find a .properties file, and return "Hello!".

However, this approach makes it difficult to maintain an add-on which has many localizations, because you're using the default language strings both as user interface strings and as keys to look up your translations. This means that if you want to change the wording of a string in the default language, or fix a typo, then you break all your locale files.

Locale Updater

The locale updater add-on makes it easier to update locale files. Once you've installed it, open the Add-on Manager, and you'll see a see a new button labeled "Update l10n" next to each add-on you've installed:

Click the button and you'll be prompted for a new .properties file for that add-on. If you provide a new file, the add-on's locale data will be updated with the new file.

Limitations

The current localization support is a first step towards full support, and contains a number of limitations.

There's no support for content scripts or CSS files: at the moment, you can only localize strings appearing in JavaScript files that can require() SDK modules and in HTML.
The set of locale files is global across an add-on. This means that a module isn't able to override a more general translation: so a module informal.js can't specify that "hello_id" occurring in its code should be localized to "Hi!".
The SDK tools compile the locale files into a JSON format when producing an XPI. This means that translators can't localize an add-on given the XPI alone, but must be given access to the add-on source.
The add-on developer must manually assemble the set of localizable strings that make up the locale files. In a future release we'll add a command to cfx that scans the add-on for localizable strings and builds a template .properties file listing all the strings that need to be translated.