国际化规范

简述

词条是一个key-value组合，key就是词条key，格式如下：common.button.ok.label = OK.实际应用中，开发只需要在显示端引用i18n key，系统则会根据语种环境自动显示对应语言。 由于多种原因，i18n词条需要在PC和移动端分别开发。

Key Value 命名

1、使用小写字母的单词，各单词间用 . 进行分隔，做到层次分明，例如 工程或插件名称.模块名称.功能名称.相关名 =xxxxxxx

2、插件国际化key 约定 以插件名称开头作为标识 : 例如 HR插件 hr.sign.mobile.lable = Mobile Sign Query

3、英文Value 值 各单词间用空格分隔，不允许出现两个单词拼接在一起的现象 例如： hr.sign.mobile.lable = MobileSignQuery ， 必须使用空格分隔 Mobile Sign Query

国际化反模式

如果是通用的名称，请勿做国际化，比如CAP3、CAP4、iPad，在各语种值都是一样的，没有必要提取词条。

PC端国际化

插件国际化配置文件位于“cfgHome/plugin/插件id/i18n”目录下，按照JDK国际化文件的配置规则命名，可采用多组文件。注意：词条key必须以插件id开始。 默认插件国际化资源配置只能在Java端使用，前端javascript无法使用，如果要开放给前端，可以在插件的i18n文件夹根下创建名为“export_to_js.xml”注册js可以使用的词条key。

PC端标准国际化文件定义目录

PC端国际化文件编写规范 properties中的资源必须经过编码，不允许出现中文、日文、法文等Unicode字符，而必须是ASCII字符。 注意：词条key必须以插件id开始。

《taskmanage_zh_CN.properties》
taskmanage.create.label    = \u521B\u5EFA
taskmanage.create.label1   = \u521B\u5EFA{0}
taskmanage.create.label2   = {0}\u521B\u5EFA{1}

《taskmanage_zh_TW.properties》
taskmanage.create.label    = \u5275\u5EFA
taskmanage.create.label1   = \u5275\u5EFA{0}
taskmanage.create.label2   = {0}\u5275\u5EFA{1}

《taskmanage_en.properties》
taskmanage.create.label    = Create
taskmanage.create.label1   = Create {0}
taskmanage.create.label2   = {0} Create {1}

Java后端调用方式：

String key = ResourceUtil.getString("taskmanage.create.label");
//一个占位符
String key1 = ResourceUtil.getString("taskmanage.create.label1", "admin");
//两个占位符
String key2 = ResourceUtil.getString("taskmanage.create.label2", "上帝", "人");

JSP前端调用方式：

<%-- 注意务必引入common_header --%>
<%@ include file="/WEB-INF/jsp/common/common_header.jsp"%>
<tr>
    <td>ctp:i18n函数</td>
    <td>${ctp:i18n('common.button.add.label')}</td>
</tr>
<tr>
    <td>ctp:i18n_1函数，一个参数，变量参数</td>
    <td>${ctp:i18n_1('common.charactor.limit.label',path)}</td>
</tr>
<tr>
    <td>ctp:i18n_1函数，一个参数，数值参数</td>
    <td>${ctp:i18n_1('common.charactor.limit.label',10)}</td>
</tr>
<tr>
    <td>ctp:i18n_1函数，一个参数，字符串参数</td>
    <td>${ctp:i18n_1('common.charactor.limit.label','测试')}</td>
</tr>
<tr>
    <td>ctp:i18n_2函数，两个参数</td>
    <td>${ctp:i18n_2('common.charactor.limit.label','测试',3)}</td>
</tr>
<tr>
    <td>ctp:i18n_3函数，三个参数</td>
    <td>${ctp:i18n_3('common.charactor.limit.label','测试',3,3)}</td>
</tr>
<tr>
    <td>ctp:i18n_4函数，四个参数</td>
    <td>${ctp:i18n_4('common.charactor.limit.label','测试',3,3,3)}</td>
</tr>
<tr>
    <td>ctp:i18n_5函数，五个参数</td>
    <td>${ctp:i18n_5('common.charactor.limit.label','测试',3,3,3,3)}</td>
</tr>

Javascript中调用国际化： 如果在*.js文件中，默认情况下无法获取国际化词条。 如果要获取国际化词条则需要在/cfgHome/plugin/插件ID/i18n目录下新增export_to_js.xml文件，然后在文件里注册需要被js引用的国际化key。

编写《export_to_js.xml》文件：
<?xml version="1.0" encoding="utf-8"?>
<export>
    <resKey>taskmanage.create.label</resKey>
    <resKey>taskmanage.create.label1</resKey>
    <resKey>taskmanage.create.label2</resKey>
</export>

前端javascript中：
<%-- 注意在JSP中引入common_footer --%>
<%@ include file="/WEB-INF/jsp/common/common_footer.jsp"%>
<script type="text/javascript">
    alert($.i18n('taskmanage.create.label'));
    alert($.i18n('taskmanage.create.label1','参数1'));
    alert($.i18n('taskmanage.create.label2','参数1','参数2'));
</script>

移动端（微协同、M3）国际化

移动端与PC端的国际化词条是分别开发维护的，主要原因是PC国际化词条太过庞大，移动端词条按需使用，需要本地化存储。

移动端国际化代码结构示例：

移动端国际化文件编写示例：

/**此段固定写法，必须加上start*/
if(typeof fI18nData == "undefined"){
    fI18nData = {}
}
/**此段固定写法，必须加上end*/
//常规的国际化定义，key以模块名称开头
fI18nData["Attendance.label.attendance"] = "考勤";
//带占位符的国际化定义
fI18nData["Attendance.label.authAttendTimes"] = "可容纳{0}人";

前端*.html引用国际化标准方式：

<!-- 默认引入zh_CN的国际化，以加速页面响应效率 -->
<script src="${data:dependencies.attendance}/i18n/attendance_zh_CN.js${data:buildversion}"></script>
<script src="${data:dependencies.commons}/i18n/Commons_zh_CN.js${data:buildversion}"></script>
<script src="${data:dependencies.cmp}/js/cmp-i18n.js${data:buildversion}"></script>
<script>
<!-- 异步调用i18n组件，地址指向本模块的i18n文件夹，这一步组件会自动判断国际化环境加载对应文件 -->
cmp.i18n.init("${data:dependencies.attendance}/i18n/","attendance",function(){
//初始化本页面titile国际化标准写法
document.title = cmp.i18n("Attendance.label.atWork");
});
</script>

>>>前端html标签调用国际化方法，使用<i18n>自定义标签来实现：
<div ><span><i18n key="Attendance.label.records"></i18n></span></div>

>>>前端javascript调用国际化方法：
<script type="text/javascript">
//普通写法
var i18n = cmp.i18n("Attendance.label.attendance");
//带占位符的写法
var i18n1 = cmp.i18n("Attendance.label.authAttendTimes","123");
</script>

国际化时区

时区在跨国应用中非常常见。 标准场景是：服务器在北京，张三于2018-9-7 15:00在北京发起一个协同给peter，发起时间保存到北京服务器数据库里是2018-9-7 15:00，peter在纽约连上北京服务器打开协同，看到的协同发起时间应该是2018-9-7 03:00，因为纽约比北京晚12小时。 未做时区支持的技术实现场景是从数据库取出协同发起时间2018-9-7 15:00，然后将日期直接返回给前端页面，如果这样做，则在美国的peter看到的时间就是北京时间的，没有做时区转换。 从服务器向前端传递日期时间，或者从前端提交日期时间保存到服务器时，两种场景都需要在Java后台调用对应的时区转换工具类。

前端提交日期到后端保存：

前端：
<form>
<input type=”text” name=”startTime” value=”2018-7-8”>
</form>

后端：
String startTimeStr = request.getParameter("startTime");
//字符串转日期对象同步实现了时区的转换
Date startTime = Datetimes.parse(startTimeStr, Datetimes.dateStyle);
XXXManager.save(startTime,xxx,xxx);

不需要时区转换，请调用：Datetimes.parseNoTimeZone(dateStr, pattern)

服务器获取日期到前端：

后端：
Date dateTime = xxxDAO.getData();
//日期对象转换为日期字符串，同步实现了时区转换
String timeStr = Datetimes.formatDate(dateTime , Datetimes.datetimeAllStyle);

不需要时区转换，请调用：Datetimes.formatNoTimeZone(date, pattern)

英文前端显示规范

在前端开发过程中，尽量注意一个原则：让文字显示完整，不要出省略号！外国人普遍不认同省略号，他们需要把单词显示完整，一眼能看明白功能意义！所以在看到UE设计的时候要尽量提出质疑---英文下显示怎么办！

多语言扩展工具

我们的标准产品支持将现有的国际化词条导出修改再导入覆盖更新，也支持手动新增一套多语言。这些功能的前提都是要各模块开发的国际化词条足够完善，尽量做到每个点都要国际化！

附录：PC端公共国际化资源表

以下是通用词条，要求能复用尽量复用！