@beisen/i18n-tools

1.2.0 • Public • Published

说明

本组件基于 i18next 二次封装而来,根据 beisen 的业务进行了一些内部处理。如需使用原版请参阅:https://www.i18next.com。

使用方法

1.安装 npm i @beisen/i18n-tools
2.引入资源
可以使用 import 或者直接放入 html 中,直接放入的情况下需要使用 window.I18NTools 来进行调用。
3.初始化站点
注意:由于多语言资源的获取需要在应用初次渲染前完成,所以引入时需要将应用渲染的方法放入回调中。
在初始化方法中做了语言是 zh-CN 时的默认处理,此时不会做初始化,直接调用回调,以提升性能。此时某些 api 可能会有不正常的情况,实践中遇到时再做处理。

cloud 或者其他非模板页应用

I18NTools.appInit({
    lng: 'zh_CN', // 当前语言
    versions: {'en_US': 'v1.0', 'zh_CN': 'v1.0'}, // 涉及语言的版本
    application: 'BeisenCloudDemo', // 当前应用
    i18nSite: 'i18n.italent-inc.cn', // 多语言站点地址,用以区分开发测试线上环境
    namespaces: ['test1'], // 选填,获取当前应用下指定类型下的数据,不填时会取出所有类型
    platform: 'BeisenCloud-PC', // 平台基础应用需传递该属性,用以取出系统级资源,取值如下:BeisenCloud-PC/BeisenCloud-Mobile/Ocean-PC/Ocean-Mobile/iTalent-H5/isSysRes
    ajaxMethod: function (){}, // 选填,在移动端外壳中时,需要调用原生的 ajax 方法,此时需要传递该参数并实现一些功能,具体请参照 ajax.js 来编写
    callback: function (err){
        ReactDOM.render(<App />, document.getElementById('root'));
    } // 初始化回调
});

组件级别初始化

I18NTools.moduleInit({
    lng: 'en_US', // 当前语言
    i18nSite: 'i18n.italent-inc.cn', // 多语言站点地址,用以区分开发测试线上环境
    application: 'BeisenCloudDemo', // 当前应用
    namespaces: ['module1'], // 当前组件的命名空间
    callback: function (err, t){
        console.info('初始化成功');
    }
});

4.调用对应的翻译方法
I18NTools 上有对应对象的挂载,翻译时提供两种方法,单个获取 getTrans ,批量获取 getTransList。
推荐使用批量获取,好处是可以直接使用默认值进行简单合并,单个获取时如果对应的 key 不存在,会返回 undefined,在应用中需要做默认值处理
单复数的区分使用的是 key 后增加 _plural 的形式,当count数字为复数时会直接调用带后缀的 key。
注意:单复数区分依赖于后方传递参数中的 count 且和语言绑定,目前应该只有英文涉及该问题,其他语言暂时不变
注意:默认情况下可以不填类别,遇到需要传递时,系统级 key 的顶层是 System,应用级 key 的顶层是 Application,传递时以:隔开,例如 System:form.age 这样

// "form": {
//     "age": "年龄",
//     "name": "姓名",
//     "message": "卡片 {{name}} 无效",
//     "keyWithCount": "{{count}} item",
//     "keyWithCount_plural": "{{count}} items"
// }

// 常规调用
window.I18NTools.getTrans('form.age') => '年龄'
// 带参数翻译
window.I18NTools.getTrans('form.message', {name: '身份证'}) => '卡片 身份证 无效'
// 单复数区分
window.I18NTools.getTrans('keyWithCount', {count: 0}); // -> "0 items"
window.I18NTools.getTrans('keyWithCount', {count: 1}); // -> "1 item"
window.I18NTools.getTrans('keyWithCount', {count: 5}); // -> "5 items"
window.I18NTools.getTrans('keyWithCount', {count: 100}); // -> "100 items"
// 批量获取
window.I18NTools.getTransList(['form.age', ['form.message', {name: '身份证'}]]) => {form.age:'年龄', form.message:'卡片 身份证 无效'}
// 直接获取本地存储的分组信息,该 api 仅会获取本地存储中的对象,不支持其他功能
window.I18nTools.getDataByGroup(namespace, group); => {key1: value1, key2: value2}

isExist方法用于获取某个 key 是否在定义中存在。

window.I18NTools.isExist('form.message') => true
window.I18NTools.isExist('form.alert') => false

key 可以在翻译中嵌套使用

//     {
//         "nesting1": "1 $t(nesting2)",
//         "nesting2": "2 $t(nesting3)",
//         "nesting3": "3",
//     }

window.I18NTools.getTrans('nesting1'); // -> "1 2 3"  

设计说明

主要流程如下:
翻译控制台配置翻译内容 -> 发布版本 -> sdk 通过站点获取资源 -> 应用中使用 sdk 方法获取翻译后的文字 -> 展示到页面上

设计上分割如下:
组件: 不关注语言信息,如果有语言相关的固定文字,提取为 props 用于传递,为了方便统一规则建议采用 props.i18n 对象传递翻译字典。
这里会遇到一个问题,例如“选中了 X 条数据”,这里 X 是组件运行时才会有的数字,这里有三种解决方案:
1.通过状态提升,将 X 暴露到组件外部,可以通过组件的指定方法拿到当前的 X,这样可以在组件外部翻译完成,组件中不必再进行处理。
2.在不同语境下 X 的前后内容是固定的,可以拆分为两个 key,写入对应的 value 即可,例如上文中的例子,可以使用“selected”,“items”来包裹 X,语义上也没有问题。
3.使用其他占位符替换 X,在组件中获取翻译后的文本,然后替换为真实的 X。
在能够满足需求的前提下,优先使用第2种方案,这样侵入性最小。其他两种视情况选用。

应用/模板: 首先调用 sdk 的初始化方法,之后统一调用 sdk 中的翻译方法进行翻译,翻译后的内容按照 props.i18n 传入组件中,实现最终的翻译效果。

翻译控制台: 负责管理所有应用的翻译资源,支持分组。

Readme

Keywords

none

Package Sidebar

Install

npm i @beisen/i18n-tools

Weekly Downloads

44

Version

1.2.0

License

none

Unpacked Size

223 kB

Total Files

4

Last publish

Collaborators

  • albert-zhang
  • liugenpeng
  • beisencorp
  • lgm
  • neozw