插件 jQuery.i18n 中文 API 文档
插件 jQuery.i18n 中文 API 文档 https://github.com/wikimedia/jquery.i18n
基于 jQuery 的国际化库
jQuery.i18n
jQuery.i18n 是一个基于 jQuery 的 Javascript 国际化库。它可以帮助您轻松地使您的 Web 应用程序国际化。
这是维基媒体基金会语言工程团队的一个项目，并在一些维基媒体基金会项目中使用，如通用语言选择器。
jquery.i18n 库使用基于 json 的本地化文件格式“banana”，它用作 MediaWiki 和其他项目的本地化文件格式。
特征
- 简单的文件格式 - JSON。易于人类和机器阅读。
- 任何地方都不会丢失作者和元数据信息。还有其他文件格式使用注释来存储它。
- 对占位符使用 MediaWiki 约定。易于阅读和验证的惯例。例：There are $1 cars
- 支持多个转换，而不使用所有复数形式的额外消息。使用 CLDR 完成多个规则处理。涵盖多种语言
- 支持性别。通过性别价值，您可以根据性别获得正确的句子。
- 支持语法形式。jquery.i18n 具有基本但可扩展的语法转换支持
- 所有语言的后备链。
- 数据 api 消息密钥。示例：
<li data-i18n="message-key"></li>。 - 无需刷新网页即可动态更改界面语言。
- 稳定的语法，复数，性别支持。这些构造可以嵌套到任意级别，以支持复杂的消息本地化
- 通过特殊语言代码的消息文档 qqq
- 可扩展的消息解析器，用于在消息中添加或自定义魔术字。示例：
{sitename}或 [[link]]
快速开始
git clone https://github.com/wikimedia/jquery.i18n.git
cd jquery.i18n
git submodule update --init
测试
npm install
要在本地运行测试，请运行 npm test，这将运行测试。
消息文件格式
消息文件是 json 格式的。作为惯例，您可以在源代码中包含名为 i18n 的文件夹。对于每种语言或区域设置，请使用名为 languagecode.json 的文件。
例：
App
|--src
|--doc
|--i18n
|--ar.json
|--de.json
|--en.json
|--he.json
|--hi.json
|--fr.json
|--qqq.json
下面给出了一个简单的 en.json 文件示例
{
"@metadata": {
"authors": [
"Alice",
"David",
"Santhosh"
],
"last-updated": "2012-09-21",
"locale": "en",
"message-documentation": "qqq",
"AnotherMetadata": "AnotherMedatadataValue"
},
"appname-title": "Example Application",
"appname-sub-title": "An example application with jquery.i18n",
"appname-header-introduction": "Introduction",
"appname-about": "About this application",
"appname-footer": "Footer text"
}
json 文件应该是有效的 json。在 @metadata 包含所有类型的数据是没有消息。您可以存储作者信息，版权，更新日期或任何内容。
消息是键值对。将 appname 作为消息键的前缀以使消息唯一，这是一个很好的约定。它充当消息键的命名空间。使消息键具有 - 分隔的单词也是一个很好的约定，所有这些都是小写的。
如果您想要从其他项目中看到一些真正的 jquery.i18n 消息文件：
MediaWiki 的消息文件 https://github.com/wikimedia/mediawiki-core/tree/master/languages/i18n 来自 jquery.uls 项目的消息文件 https://github.com/wikimedia/jquery.uls/blob/master/i18n
所有语言的单个消息文件
不同的用例支持一些备用消息文件格式。如果您的应用程序不是很大，并希望在单个文件中进行所有翻译，您可以使用以下示例中所示：
{
"@metadata": {
"authors": [
"Alice",
"David",
"Santhosh"
],
"last-updated": "2012-09-21",
"locale": "en",
"message-documentation": "qqq",
"AnotherMetadata": "AnotherMedatadataValue"
},
"en": {
"appname-title": "Example Application",
"appname-sub-title": "An example application with jquery.i18n",
"appname-header-introduction": "Introduction",
"appname-about": "About this application",
"appname-footer": "Footer text"
},
"ml": {
"appname-title": "അപ്ലിക്കേഷന് ഉദാഹരണം",
"appname-sub-title": "jquery.i18n ഉപയോഗിച്ചുള്ള അപ്ലിക്കേഷന് ഉദാഹരണം",
"appname-header-introduction": "ആമുഖം",
"appname-about": "ഈ അപ്ലിക്കേഷനെപ്പറ്റി",
"appname-footer": "അടിക്കുറിപ്പു്"
}
}
这里 json 文件包含语言代码作为键值，messagekey-message 对作为所有语言对的值。您可以根据用例选择此格式或每种语言的文件格式。每种语言文件更便于协作，版本控制，可扩展性等。
在这种方法中，还可以给出文件名作为语言代码的值。
{
"@metadata": {
"authors": [
"Alice",
"David",
"Santhosh"
],
"last-updated": "2012-09-21",
"locale": "en",
"message-documentation": "qqq",
"AnotherMetadata": "AnotherMedatadataValue"
},
"en": {
"appname-title": "Example Application",
"appname-sub-title": "An example application with jquery.i18n",
"appname-header-introduction": "Introduction",
"appname-about": "About this application",
"appname-footer": "Footer text"
},
"ml": "path/to/ml.json"
}
翻译
要翻译 jquery.i18n 应用程序，根据翻译人员的专业知识，有多种方法。
直接编辑 json 文件 - 适用于具有技术背景的翻译人员。如果您的应用程序很小并且您只想使用少量语言，也适用 提供翻译界面以及您的应用程序：适用于拥有大量翻译人员的专有或私人应用程序 使用 translatewiki.net 等开源翻译平台。之前示例中的 MediaWiki 和 jquery.uls 使用 translatewiki.net 进行众包消息转换。Translatewiki.net 可以定期更新您的代码仓库并使用更新的翻译。如果您的应用程序是开源的，并且希望本地化尽可能多的语言，并且翻译人数最多，则强烈建议使用。
用法
切换区域设置
初始化时 jquery.i18n，可以使用 locale 选项给出页面的区域设置。例如
$.i18n( {
locale: 'he' // Locale is Hebrew
} );
如果未给出 locale 选项，jquery.i18n 插件将使用为 html 标记指定的语言属性。例如
<html lang="he" dir="rtl">
在这种情况下，语言环境将是他（希伯来语）。如果该 lang 属性也缺失，它将尝试使用浏览器指定的语言环境。
初始化插件后，可以切换到另一个语言环境。见下面的例子：
$.i18n({
locale: 'he' // Locale is Hebrew
});
$.i18n( 'message-hello' ); // This will give the Hebrew translation of message key `message-hello`.
$.i18n().locale = 'ml'; // Now onwards locale is 'Malayalam'
$.i18n( 'message-hello' ); // This will give the Malayalam translation of message key `message-hello`.
消息加载
可以使用多种方式将 JSON 格式的消息加载到插件中。
动态加载使用 load 方法。
以下示例显示了加载两个 locales-localex 和 localey 的消息。这里 localex 和 localey 就是例子。它们应该是有效的 IS0 639 语言代码（例如：en，ml，hi，fr，ta 等）
$.i18n().load( {
'localex' : {
'message-key1' : 'message1' // Message for localex.
},
'localey' : {
'message-key1' : 'message1'
}
} );
如果我们要加载特定区域设置的消息，可以这样做：
$.i18n().load({
'message-hello': 'Hello World',
'message-welcome': 'Welcome'
}, 'en');
请注意该 load 方法的第二个参数。它应该是有效的语言代码。
也可以从外部 URL 引用消息。见下面的例子
$.i18n().load( {
en: {
'message-hello': 'Hello World',
'message-welcome': 'Welcome'
},
hi: 'i18n/messages-hi.json', // Messages for Hindi
de: 'i18n/messages-de.json'
} );
区域设置的消息也可以部分加载。例
$.i18n().load( {
en: {
'message-hello': 'Hello World',
'message-welcome': 'Welcome'
}
} );
$.i18n().load( {
// This does not remove the previous messages.
en: {
'message-header' : 'Header',
'message-footer' : 'Footer',
// This will overwrite message-welcome message
'message-welcome' : 'Welcome back'
}
} );
由于需要立即呈现接口消息而不是在从服务器加载消息文件的延迟之后，请确保在使用 jQuery.i18n 之前消息存在于客户端。
库应该公开 API 以加载包含键值对消息的对象。示例：$.i18n.load(data)。这将返回一个 jQuery.Promise。
jquery.i18n 插件
jQuery 插件定义 $.i18n() 和 $.fn.i18n()
$.i18n( 'message-key-sample1' );
$.i18n( 'message-key-sample1' );
$.i18n( 'Found $1 {{plural:$1|result|results}}', 10 ); // Message key itself is message text
$.i18n( 'Showing $1 out of $2 {{plural:$2|result|results}}', 5,100 );
$.i18n( 'User X updated {{gender|his|her}} profile', 'male' );
$( '#foo' ).i18n(); // to translate the element matching jquery selector based on data-i18n key
数据 API
可以在没有任何自定义 JavaScript 的情况下显示本地化消息。对于 HTML 标记，添加带有值的属性 data-i18n 作为消息键。例：
<li data-i18n="message-key"></li>.
也可以使上述 li 节点具有后备文本。
<li data-i18n="message-key">Fallback text</li>
框架将对应于 message-key 的本地化消息作为节点的文本值。类似于 $（‘selector’）。i18n（…）。这不适用于动态创建的元素。
请注意，如果 data-i18n 包含 html 标记，则该 html 将不会用作元素内容，而是使用文本版本。但是如果消息键带有前缀 [ html]，则元素的 html 将被更改。例如<li data-i18n="[html]message-key">Fallback html</li>，如果 message-key 的值包含 HTML 标记，则<li>标记 html 将被该 html 替换。
如果要更改元素的 html，还可以使用： $(selector).html($.i18n(messagekey))
例子
见 https://thottingal.in/projects/js/jquery.i18n/demo/
消息格式
占位符
消息采用参数。它们在消息文本中由 $ 1，$ 2，$ 3，… 表示，并在运行时替换。典型的参数值是数字（例如：“删除 3 个版本？”）或用户名（例如：“最后编辑的页面为 $ 1”），页面名称，链接等，或者有时是其他消息。
var message = "Welcome, $1";
$.i18n(message, 'Alice'); // This gives "Welcome, Alice"
复数
为了使句子的语法正确，需要复数形式。jquery.i18n 使用语法支持消息中的复数形式{{PLURAL:$1|pluralform1|pluralform2|…}}
例如：
var message = "Found $1 {{PLURAL:$1|result|results}}";
$.i18n(message, 1); // This gives "Found 1 result"
$.i18n(message, 4); // This gives "Found 4 results"
请注意{{PLURAL：…}}不区分大小写。它也可以是{{复数：…}}。
在英语的情况下，只有 2 种复数形式，但许多语言使用 2 种以上的复数形式。所有复数形式都可以用上面的语法给出，用竖线（|）分隔。每种语言的复数形式的数量在 CLDR 中定义。您需要提供语言的所有复数形式。
例如，英语有 2 个复数形式，消息格式如下{{PLURAL:$1|one|other}}。阿拉伯语有 6 种复数形式，格式如下{{PLURAL:$1|zero|one|two|few|many|other}}。
您不能从中间或开头跳过复数形式。但是你可以从头到尾跳过。例如，在阿拉伯语中，如果消息类似 {{PLURAL:$1|A|B}}，对于 0，将使用 A，对于属于一个，两个，几个，许多的数字，将使用其他类别 B.
如果为特定数字提供了明确的复数形式，则可以使用以下语法
var message = 'Box has {{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}.';
$.i18n(message, 4 ); // Gives "Box has 4 eggs."
$.i18n(message, 12 ); // Gives "Box has a dozen eggs."
性别
与复数类似，根据占位符的性别（主要是用户名），语法会动态更改。英语中的一个例子是“Alice 改变了她的个人资料图片”和“Bob 改变了她的个人资料图片”。要支持此{{GENDER …}}语法，可以在示例中使用
var message = "$1 changed {{GENDER:$2|his|her}} profile picture";
$.i18n(message, 'Alice', 'female' ); // This gives "Alice changed her profile picture"
$.i18n(message, 'Bob', 'male' ); // This gives "Bob changed his profile picture"
请注意，{{GENDER：…}}不区分大小写。它也可以是{{性别：…}}。
语法
$.i18n( { locale: 'fi' } );
var message = "{{grammar:genitive|$1}}";
$.i18n(message, 'talo' ); // This gives "talon"
$.i18n().locale = 'hy'; // Switch to locale Armenian
$.i18n(message, 'Մաունա'); // This gives "Մաունայի"
方向安全隔离
为了避免 BIDI 损坏，看起来像“（Foo_（Bar”，当字符串插入具有相反方向性的上下文时发生，您可以使用{{bidi:…}}。字符串边缘的方向性中性字符可能被 BIDI 错误地解释）这将允许您将替换的字符串嵌入到新的 BIDI 上下文中，// 例如 //：
"Shalom, {{bidi:$1}}, hi!"
嵌入式上下文的方向性通过查看参数来确定 $1，然后显式插入到 Unicode 文本中，确保正确呈现（因为 bidi 算法“知道”参数文本是一个单独的上下文）。
倒退
该插件采用默认值’en’选项’后备’。该库重用 MediaWiki 中提供的后备数据来计算语言回退。在区域设置中找不到消息密钥时使用回退。示例回退：sa-> hi-> en 或 tt-> tt-cyrl-> ru。
请参阅源代码中的 jquery.i18n.fallbacks.js。
魔术字支持
对于复数，性别和语法支持，将使用 MediaWiki 模板式语法 - {{…}}。 $ .i18n.language [‘default’] 将为所有这些实现默认实现 $.i18n.language[ ‘default’ ] 可以覆盖或扩展复数，性别和语法方法 $.i18n.language[’languageCode’]。 有关性别和语法的特定语言规则可以用 languages / langXYZ.js 文件编写 将使用 CLDR 复数解析器动态计算多个表单。
扩展解析器
以下示例说明了扩展解析器以支持更多魔术词
$.extend( $.i18n.parser.emitter, {
// Handle SITENAME keywords
sitename: function () {
return 'Wikipedia';
},
// Handle LINK keywords
link: function ( nodes ) {
return '<a href="' + nodes[1] + '">' + nodes[0] + '</a>';
}
} );
这将解析消息
$.i18n( '{{link:{{SITENAME}}|https://en.wikipedia.org}}' );
至
<a href="https://en.wikipedia.org">Wikipedia</a>
消息文档
消息键和消息不会提供有关正在转换为转换器的消息的足够上下文。每当开发人员添加新消息时，通常的做法是使用相同的消息密钥将消息记录到名为 qqq.json 的文件中。
示例 qqq.json：
{
"@metadata": {
"authors": [
"Developer Name"
]
},
"appname-title": "Application name. Transliteration is recommended",
"appname-sub-title": "Brief explanation of the application",
"appname-header-introduction": "Text for the introduction header",
"appname-about": "About this application text",
"appname-footer": "Footer text"
}
