@whalecloud/portal-plugin-i18n
基于umi-plugin-locale-paik的一款国际化插件
是umi
多语言国际化插件,官方umi-plugin-locale的改进版本
- 支持json格式数据
- 支持命令行进行国际化数据提取
- 支持动态加载国际化数据
- 支持远程获取国际化数据
v0.0.6
- 支持国际化数据热更新
v0.1.0
- 支持加载动态json格式的国际化数据
v0.1.3
@whalecloud/portal-plugin-i18n
基于umi-plugin-locale-paik
做了以下改进:
-
dev
与build
之前首先会对资源重新编译 - 全局与局部的国际化调用统一用
umi/locale
,局部的国际化资源也可从props.intl
内获取 - 修复
locales/
目录不存在时直接编译报错的问题 - 修复编译之前读取本地语言包失败的问题
- 支持远程加载子系统内的国际化
-
shell
脚本兼容windows
环境
demo
请务必查看实例仓库代码
portal-plugin-il8n-demo
注意
-
umi intl
命令会根据配置提取国际化到public
- **国际化资源统一放在名为
messages/
的目录下 - 动态资源必须以
d-
或者D-
开头命名,才能编译到public
- 增加了webpack配置,build模式下,public/lang下面的文件不进行编译,减少体积
使用
yarn
或者 npm
$ yarn add @whalecloud/portal-plugin-i18n
配置说明
本插件需要禁用官方插件umi-locale-plugin
的locale
功能
config/config.js
或者 .umirc.js
配置如下
export default [
[
'@whalecloud/portal-plugin-i18n',
{
...
locale:false, // 禁用官方locale, 默认关闭
...
},
],
['@whalecloud/portal-plugin-i18n', options],
];
options 默认值
{
locale: {
default: 'en', // 默认为英文
},
translate: {
support: { // 默认支持中文和英文
enUS: 'en-US',
zhCN: 'zh-CN',
},
},
}
目录说明
由于官方插件的国际化是放在locales(locale)
文件夹下面, 本插件也继承了官方的设定, 保留了官方@whalecloud/portal-plugin-i18n
插件locale
的全部功能(增加了json的支持
), 所以禁用掉了官方功能,如果是在locales
下面写国际化文件,请保持原样,仅仅是增加了json的支持。
messages/
下面放本插件规定的国际化文件
public/lang
下面放以语言为目录动态加载的国际化文件(json格式)
├── public/lang // 动态国际化数据,不参与打包, js数据
├── zh-CN/
├ ├── Demo.js
└── en-US/
├── Demo.js
├── dist/
├── mock/
└── src/
├── layouts/index.js
|—— locales // 此目录下的数据保持与官方规定一致,仅增加json支持
|__ global.js
|__ global.json
└── pages/
└── messages // 本地国际化数据存放目录,支持js|ts(export default 形式),json
├── global.js
└── global.json
├── .env
└── package.json
插件会将
messages/
目录下的全局资源和locales/**.js
的资源一起整合到locales/**.json
内,所以为使内容工整,查看方便,建议不要在locales/
目录里写国际化,而是写在messages/
目录下。 如果.umirc.js(config/config.js)
里配置了singular: true
,messages
要改成message
,locales
要改成locale
。
messages
messages目录下放置国际化数据,格式规定如下
- 对象形式
- 必须包含
id
,defaultMessage
两个key, 其余根据项目情况添加
test.json
{
"test":{
"id":"title-test",
"defaultMessage":"title-test {title}",
"zhCN":"全局标题{title}"
...
}
}
test.js
export default {
test:{
id:'title-test',
defaultMessage:'title-test {title}',
zhCN:'全局标题{title}',
zhTW:'全域性標題{title}',
zhHK:'全局標題{title}',
},
}
options 所有配置
{
locale: {
baseNavigator: true,
momentLocaleMap: { en: 'en-nz', zh: 'zh-cn' }, // moment插件国际化
fdxMap: { en: 'en_US', zh: 'zh_CN' }, // fdx组件国际化
localeMap: { zh: 'zh-CN', en: 'en-US' }, // 本地国际化文件
default: 'en', // 默认语言
}
translate: { // 默认翻译的类型
support: { // 默认支持中文和英文
enUS: 'en-US',
zhCN: 'zh-CN',
},
},
dynamicIntl: true // 是否支持动态加载,默认为true,开启后才可使用withIntl函数
autoIntl: true // 是否支持热更新,默认为true
}
options[baseNavigator|default]
与官方配置相同,开启该功能后如果不能识别传入的语言,则会默认启用浏览器语言
options.momentLocaleMap options.fdxMap
由于moment
,fdx
国际化文件名称并不是严格和浏览器等到的语言名称一致的的,可以根据配置指定加载的文件
如上面配置所示,则是指定浏览器语言为en
时,使用 moment
下的moment/locale/en-nz
国际化文件,antd
下的antd/lib/locale-provider/en-US
文件
options.localeMap
当 options.default
不是标准的文件命名, 或者浏览器语言不是预期的lang-country
形式时(如zh
,en
),此配置可以指定加载locales
下的哪种国际化文件,如 zh: 'zh-CN'
, 则会合并所有locales
文件夹下面zh-CN.json
或者zh-CN.js
文件作为国际化资源
options.translate
这个是messages
下面国际化数据的map信息,用于表示目录与key的转换关系
用上面的test.json
举例说明,如下配置
{
support:{
enUS:'en-US',
zhCN:'zh-CN',
zhTW:'zh-TW',
zhHK:'zh-HK',
}
}
enUS:'en-US'
表示 enUS
的value值会被提取到en-US
文件里,
即最终生成的 src/locales/en-US.json
包含
{
...
"title-test":"title-test {title}"
...
}
options.translate
当options.translate
存在时,会增加一个umi intl
命令,此命令负责提取messages
下面的国际化数据到src/locales
目录下,根据options.translate.support
的配置
如果没有对
zhTW
zhHK
指定数据,本插件默认开启了香港,台湾国际化使用node-opencc进行翻译
options.dynamicIntl
开启此功能后,umi
项目中会新增一个API: umi/withIntl
,可以通过引入这个新的API,获得动态加载国际化数据的功能
d-transLate.json
{
"t1": {
"id": "title-test",
"defaultMessage": "test",
"zhCN": "标题测试"
},
"t2": {
"id": "locale-change",
"defaultMessage": "test {type}",
"zhCN": "测试 {type}"
},
}
在组件中使用
import { formatMessage } from 'umi/locale';
import { withIntl } from 'umi/withIntl';
const transLate = props => {
...
return (
{formatMessage({
id: 'title-test',
})}
);
};
export default withIntl('TransLate')(transLate);
withIntl('TransLate')(transLate)
代表 transLate
组件会使用public/lang/**/TransLate.js
里面的国际化数据
** withIntl高阶函数还新增了options参数,支持从远程直接获取动态的国际化数据:
**
为了更多的灵活性,你必须对此API进行再次封装
项目中新建自己的工具函数,如 withIntl.js
withIntl.js
import { withIntl } from 'umi/withIntl';
export default component => withIntl(component);
withIntl高阶用法具体可见: v0.1.x 更新说明
总结
@whalecloud/portal-plugin-i18n
国际化框架的优点:
- 支持json动态加载
- 模块内用
withIntl
包装的国际化是私有资源, 有效的防止了key重复的问题 - 各语言对应的资源都放在同一个文件内,方便查看与修改
@whalecloud/portal-plugin-i18n
国际化框架的缺点:
- 更改国际化资源热更新过程不可控,需要等待一会儿
- 模块内想引用动态国际化必须使用
withIntl
函数加载对应的资源
浏览器支持
由于动态加载使用了
Dynamic import
,IE浏览器是不支持的,所以用了polyfill
做支持,``
IE / Edge | Firefox | Chrome | Safari | Opera |
---|---|---|---|---|
IE10, IE11, Edge | last 2 versions | last 2 versions | last 2 versions | last 2 versions |