jquery.i18n.properties中文文档(供参考)

南门欣怡
2023-12-01

版本 : 1.2.2


关于

jQuery.i18n.properties是一个轻量级的jQuery插件,用于从.properties文件中提供javascript的国际化,就像在Java资源包中一样。它根据提供的语言和国家代码(ISO-639和ISO-3166)或浏览器报告的语言加载和解析资源包(.properties)。

资源束是包含区域设置特定键值对的“.properties”文件。在Java和Javascript项目之间共享i18n文件时,使用’.properties’文件进行翻译特别有用。此插件首先加载默认文件(例如Messages.properties),然后加载特定于特定区域的文件(Messages_pt.properties,Messages_pt_BR.properties)(比如中文下的粤语),以便在没有提供翻译时,默认值始终可用。翻译的键将作为javascript变量/函数(如果翻译的值包含替换(例如,{0})或作为 map),开发人员可用。

这个插件的灵感来自Keith Wood的 Localisation assistance for jQuery


特征

  • 使用Java标准的“.properties”文件进行翻译
  • 使用标准ISO-639作为语言代码,使用ISO-3166作为国家代码
  • 将资源包从基本语言顺序加载到用户指定/浏览器指定的位置,因此对于未翻译的字符串始终有一个默认值(例如:Messages.properties,Messages_pt.properties,Messages_pt_BR.properties)
  • 如果未指定语言,请使用浏览器报告的语言
  • 资源束字符串中的占位符替换(例如,msg_hello = Hello {0} !!)
  • 支持键中的命名空间(例如,com.company.msgs.hello = Hello!)
  • 支持多行属性值
  • 可用作JavaScript 变量/函数或作为映射的资源束键(map)
  • 可以指定实现的语言以防止不必要的下载

历史

这个项目最初由Nuno Miguel Correia Serra Fernandes创建, 并发布在Google代码上。在2014年,它已经迁移到Github,现在是官方的存储库。

从那时起,其他伟大的贡献者加入了该项目(见下面的积分部分)。

它已被用于各种项目,包括WebRTC phone JSCommunicator(在演示里可以看到jquery-i18n属性在行动),一些Sak项目工具


以下面的.properties文件

Messages.properties:

#此行被插件忽略
msg_hello = Hello
msg_world = World
msg_complex = Good morning {0}!

Messages_pt.properties:

#我们只提供一个“msg_hello”键 
msg_hello = Bom dia

Messages_pt_BR.properties:

#我们只提供一个“msg_hello”键
msg_hello = Olá

现在,假设这些文件位于bundle/文件夹上。可以像下面调用插件:

// 这将初始化插件 
// 这里会显示两个对话框: 一个里面的文本为 "Olá World"
// 另一个的文本为 "Good morning John!" 
jQuery.i18n.properties({
    name:'Messages', 
    path:'bundle/', 
    mode:'both',
    language:'pt_BR',
    checkAvailableLanguages: true,
    async: true,
    callback: function() {
        // 我们指定的模式: 'both' ,所以翻译的值会将作为JS的变量/方法和一个map

        //通过map访问一个简单的值
        jQuery.i18n.prop('msg_hello');
        // 通过map访问带占位符的值         
        jQuery.i18n.prop('msg_complex', 'John');

        // 通过JS变量访问一个简单的值
        alert(msg_hello +' '+ msg_world);
        // 通过JS函数访问带占位符的值
        alert(msg_complex('John'));
    }
});

这将初始化插件(加载bundle文件并解析它们),并显示一个对话框,文本“OláWorld”和另一个显示“Good morning John!”。因为我们没有提供msg_world键的翻译,所以显示英文单词”World“。还要注意,键可用作映射,还可以作为javascript变量(对于简单字符串)和javascript函数(对于具有替换占位符的字符串)。

有关“checkAvailableLanguages”标志的更多信息,请参阅实现语言控制。


实现语言控制

您可以选择定义已实现的语言,并控制下载哪些属性文件。您可以通过在与语言属性文件相同的目录中创建一个文件languages.json来实现。languages.json包含已实现并可供下载的语言代码的列表。这样做的优点有两个:

1.  更少的HTTP连接。
2.  开发人员控制台中404错误较少。 

这里有一个languages.json文件的例子:

{
    "languages": [
        "en_GB",
        "es_ES",
        "pt_BR",
        "sv_SE"
    ]
}

将这作为languages.json保存在与属性文件相同的目录中将阻止i18n尝试拉取除了列出的语言之外的任何语言。

最后一件事你需要做激活语言控制:你需要在你的调用代码中,设置一个标志,checkAvailableLanguages,在你设置传递给i18n.properties函数的时候。如果不这样做,则应用语言查找的默认下降行为。


异步语言文件加载

同步Ajax现在已被弃用,并且将来在某个时候被删除,因此Web开发人员需要开始考虑将它们的代码编写为回调(https://xhr.spec.whatwg.org/)。

考虑到这一点…

如果您对设置提供了“async”标志并将其设置为true,则所有ajax调用都将异步执行,并且在语言文件已全部下载并解析后调用提供的回调。如果您关闭标志或将其设置为false,行为如前所述:所有文件将同步解析,并在过程结束时调用回调。


用法

使用插件

1.将其包含在您的部分:

<script type="text/javascript" language="JavaScript" src="js/jquery.i18n.properties-min.js"></script>

2.初始化插件(最小使用,将使用浏览器报告的语言),并访问翻译的值(假设存在一个名为“org.somekey”的键,它将被设置为一个变量,您可以直接在Javascript中使用):

 <script>
    jQuery.i18n.properties({
        name: 'Messages', 
        callback: function(){ alert( org.somekey ); }
    });
</script>      

Firefox的附加要求

如果使用Firefox和Tomcat webapp,您可能会在Javascript控制台中得到一个syntax error。解决方案是告诉Tomcat属性文件应该解释为text/plain。为此,请将以下内容添加到web.xml中:

<mime-mapping> <extension>properties</extension> <mime-type>text/plain</mime-type> </mime-mapping>

构建缩小的JavaScript文件

1.安装closure编译工具:

apt-get update && apt-get install closure-compiler

2.运行:

closure-compiler --js jquery.i18n.properties.js \ --js_output_file jquery.i18n.properties.min.js

选项

选项描述说明
名称(name)表示资源束的文件的部分名称(或名称)(例如,’Messags’或[‘Msg1’,’Msg2’])。默认为“Messages”可选,字符串或字符串[]
语言(language)ISO-639语言代码和可选的ISO-3166国家代码(例如,’en’,’en_US’,’pt_BR’)。如果未指定,将使用浏览器报告的语言。可选,字符串
路径(path)包含要加载的“.properties”文件的目录的路径。可选,字符串
模式(mode)选项使资源束键可用作Javascript 变量/方法或作为一个map。如果您的捆绑的键包含Javascript保留字,则’map’选项是必需的。可能的选项:’vars’(默认),’map’或’both’。可选,字符串
缓存(cache)是否应由浏览器缓存bundle,或在每个网页加载时强制重新加载。默认为false(即强制重新加载)可选,boolean值
编码(encoding)请求捆绑的编码。属性文件资源束指定为ISO-8859-1格式。默认为UTF-8以实现向后兼容性。可选 ,字符串
回调函数 (callback)回调函数被称为uppon脚本执行完成。可选,方法名
 类似资料: