# @whalecloud/portal-plugin-i18n > A umi plugin for provide internationalization function. Latest version **0.1.37** (published 2020-09-22) · MIT license · 0 weekly downloads ## Install ```sh npm install @whalecloud/portal-plugin-i18n pnpm add @whalecloud/portal-plugin-i18n yarn add @whalecloud/portal-plugin-i18n bun add @whalecloud/portal-plugin-i18n ``` Provides the command `paik-intl`. ## Health **Score 20/100 (F)** — status: abandoned. Positive: esm support; no vulnerabilities. Warnings: low downloads; no types; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.1.37 | | Published | 2020-09-22 | | First published | 2019-04-11 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | ESM + CommonJS | | Dependencies | 23 | | Unpacked size | 94.9 KB | | Known vulnerabilities | 0 (+24 in 1 direct dependencies) | | Install scripts | no | | Maintainers | whalecloud-developer | | Keywords | umi, locale | ## Links - npm: https://www.npmjs.com/package/@whalecloud/portal-plugin-i18n - Repository: http://gitlab.iwhalecloud.com/fish-x/portal-plugin-i18n - Issues: http://gitlab.iwhalecloud.com/fish-x/portal-plugin-i18n/issues - npm.io page: https://npm.io/package/@whalecloud/portal-plugin-i18n ## Dependencies (23) - [ora](https://npm.io/package/ora.md) ^3.1.0 - [intl](https://npm.io/package/intl.md) ^1.2.5 - [path](https://npm.io/package/path.md) ^0.12.7 - [axios](https://npm.io/package/axios.md) ^0.18.0 - [execa](https://npm.io/package/execa.md) ^1.0.0 - [react](https://npm.io/package/react.md) ^16.8.2 - [globby](https://npm.io/package/globby.md) ^9.0.0 - [mkdirp](https://npm.io/package/mkdirp.md) 0.5.1 - [moment](https://npm.io/package/moment.md) 2.x - [rimraf](https://npm.io/package/rimraf.md) ^2.6.3 - [signale](https://npm.io/package/signale.md) ^1.3.0 - [mustache](https://npm.io/package/mustache.md) ^3.0.1 - [deepmerge](https://npm.io/package/deepmerge.md) ^3.2.0 - [invariant](https://npm.io/package/invariant.md) ^2.2.4 - [umi-utils](https://npm.io/package/umi-utils.md) ^1.3.1 - [react-intl](https://npm.io/package/react-intl.md) ^2.8.0 - [@babel/core](https://npm.io/package/@babel/core.md) ^7.3.3 - [node-opencc](https://npm.io/package/node-opencc.md) 2.0.1 - [lodash.groupby](https://npm.io/package/lodash.groupby.md) ^4.6.0 - [@babel/polyfill](https://npm.io/package/@babel/polyfill.md) ^7.2.5 - [@whalecloud/fdx](https://npm.io/package/@whalecloud/fdx.md) ^0.0.9 - [@babel/preset-env](https://npm.io/package/@babel/preset-env.md) ^7.3.1 - [hoist-non-react-statics](https://npm.io/package/hoist-non-react-statics.md) ^3.3.0 ## Alternatives - [messageformat](https://npm.io/package/messageformat.md) — 329.7K weekly downloads - [@mintlify/scraping](https://npm.io/package/@mintlify/scraping.md) — 294.8K weekly downloads - [@mintlify/previewing](https://npm.io/package/@mintlify/previewing.md) — 209.5K weekly downloads - [@mintlify/prebuild](https://npm.io/package/@mintlify/prebuild.md) — 209.5K weekly downloads - [@mintlify/link-rot](https://npm.io/package/@mintlify/link-rot.md) — 206.3K weekly downloads ## Recent versions - 0.1.37 (latest) — 2020-09-22 - 0.1.36 — 2020-09-17 - 0.1.35 — 2020-09-17 - 0.1.34 — 2020-04-14 - 0.1.33 — 2020-04-13 - 0.1.32 — 2020-04-13 - 0.1.31 — 2019-10-11 - 0.1.30 — 2019-10-11 - 0.1.29 — 2019-10-11 - 0.1.28 — 2019-08-30 - 0.1.27 — 2019-08-30 - 0.1.26 — 2019-06-27 - 0.1.25 — 2019-06-24 - 0.1.24 — 2019-06-24 - 0.1.23 — 2019-06-16 - … 14 more at https://npm.io/package/@whalecloud/portal-plugin-i18n/versions ## README # @whalecloud/portal-plugin-i18n 基于[umi-plugin-locale-paik](https://github.com/onpaik/umi-lib-paik/tree/master/packages/umi-plugin-locale-paik)的一款国际化插件 是`umi`多语言国际化插件，官方[umi-plugin-locale](https://github.com/umijs/umi/tree/master/packages/umi-plugin-locale)的改进版本 + 支持json格式数据 + 支持命令行进行国际化数据提取 + 支持动态加载国际化数据 + 支持远程获取国际化数据 `v0.0.6` + 支持国际化数据热更新 `v0.1.0` + 支持加载动态json格式的国际化数据 `v0.1.3` [v0.1.x 更新说明](http://gitlab.ztesoft.com/fish-x/portal-plugin-i18n/blob/master/v0.1.x.md) `@whalecloud/portal-plugin-i18n`基于`umi-plugin-locale-paik`做了以下改进： + `dev`与`build`之前首先会对资源重新编译 + 全局与局部的国际化调用统一用`umi/locale`,局部的国际化资源也可从`props.intl`内获取 + 修复`locales/`目录不存在时直接编译报错的问题 + 修复编译之前读取本地语言包失败的问题 + 支持远程加载子系统内的国际化 + `shell`脚本兼容`windows`环境 ## demo `请务必查看实例仓库代码` [portal-plugin-il8n-demo](http://gitlab.ztesoft.com/fish-x/portal-plugin-i18n/tree/master/src/demo/portal-plugin-il8n-demo) ## 注意 - `umi intl` 命令会根据配置提取国际化到`public` - **国际化资源统一放在名为`messages/`的目录下 - 动态资源必须以`d-`或者`D-`开头命名，才能编译到`public` - 增加了webpack配置，build模式下，public/lang下面的文件不进行编译，减少体积 ## 使用 `yarn` 或者 `npm` ```bash $ yarn add @whalecloud/portal-plugin-i18n ``` ## 配置说明 本插件需要禁用官方插件`umi-locale-plugin`的`locale`功能 `config/config.js` 或者 `.umirc.js`配置如下 ```javascript export default [ [ '@whalecloud/portal-plugin-i18n', { ... locale:false, // 禁用官方locale, 默认关闭 ... }, ], ['@whalecloud/portal-plugin-i18n', options], ]; ``` ## options 默认值 ```javascript { 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格式) ```dir ├── 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` ```json { "test":{ "id":"title-test", "defaultMessage":"title-test {title}", "zhCN":"全局标题{title}" ... } } ``` `test.js` ```javascript export default { test:{ id:'title-test', defaultMessage:'title-test {title}', zhCN:'全局标题{title}', zhTW:'全域性標題{title}', zhHK:'全局標題{title}', }, } ``` ## options 所有配置 ```javascript { 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`举例说明,如下配置 ```javascript { 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` 包含 ```json { ... "title-test"："title-test {title}" ... } ``` ## options.translate 当`options.translate`存在时，会增加一个`umi intl` 命令，此命令负责提取`messages`下面的国际化数据到`src/locales`目录下，根据`options.translate.support`的配置 >如果没有对`zhTW` `zhHK`指定数据，本插件默认开启了香港，台湾国际化使用[node-opencc](https://github.com/compulim/node-opencc)进行翻译 ## options.dynamicIntl 开启此功能后，`umi`项目中会新增一个API: `umi/withIntl`，可以通过引入这个新的API，获得动态加载国际化数据的功能 `d-transLate.json` ```js { "t1": { "id": "title-test", "defaultMessage": "test", "zhCN": "标题测试" }, "t2": { "id": "locale-change", "defaultMessage": "test {type}", "zhCN": "测试 {type}" }, } ``` 在组件中使用 ```js 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` ```js import { withIntl } from 'umi/withIntl'; export default component => withIntl(component); ``` withIntl高阶用法具体可见: [v0.1.x 更新说明](http://gitlab.ztesoft.com/fish-x/portal-plugin-i18n/blob/master/v0.1.x.md) ## 总结 `@whalecloud/portal-plugin-i18n`国际化框架的优点： + 支持json动态加载 + 模块内用`withIntl`包装的国际化是私有资源， 有效的防止了key重复的问题 + 各语言对应的资源都放在同一个文件内，方便查看与修改 `@whalecloud/portal-plugin-i18n`国际化框架的缺点： + 更改国际化资源热更新过程不可控，需要等待一会儿 + 模块内想引用动态国际化必须使用`withIntl`函数加载对应的资源 ## 浏览器支持 > 由于动态加载使用了`Dynamic import`,IE浏览器是不支持的，所以用了`polyfill`做支持，`` | [IE / Edge](http://godban.github.io/browsers-support-badges/)
IE / Edge | [Firefox](http://godban.github.io/browsers-support-badges/)
Firefox | [Chrome](http://godban.github.io/browsers-support-badges/)
Chrome | [Safari](http://godban.github.io/browsers-support-badges/)
Safari | [Opera](http://godban.github.io/browsers-support-badges/)
Opera | | --------- | --------- | --------- | --------- | --------- | | IE10, IE11, Edge| last 2 versions| last 2 versions| last 2 versions| last 2 versions --- _Source: https://npm.io/package/@whalecloud/portal-plugin-i18n · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._