@whalecloud/portal-plugin-i18n

基于umi-plugin-locale-paik的一款国际化插件

是umi多语言国际化插件，官方umi-plugin-locale的改进版本

• 支持json格式数据
• 支持命令行进行国际化数据提取
• 支持动态加载国际化数据
• 支持远程获取国际化数据 v0.0.6
• 支持国际化数据热更新 v0.1.0
• 支持加载动态json格式的国际化数据 v0.1.3

v0.1.x 更新说明

@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目录下放置国际化数据,格式规定如下

1. 对象形式
2. 必须包含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