Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wechat-miniprogram/miniprogram-i18n
小程序国际化方案 / The internationalizational (i18n) library for wechat miniprogram
https://github.com/wechat-miniprogram/miniprogram-i18n
Last synced: about 2 months ago
JSON representation
小程序国际化方案 / The internationalizational (i18n) library for wechat miniprogram
- Host: GitHub
- URL: https://github.com/wechat-miniprogram/miniprogram-i18n
- Owner: wechat-miniprogram
- License: mit
- Created: 2018-12-12T03:04:01.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2021-09-30T08:11:51.000Z (over 3 years ago)
- Last Synced: 2024-11-08T12:13:43.536Z (about 2 months ago)
- Language: TypeScript
- Homepage:
- Size: 148 KB
- Stars: 136
- Watchers: 6
- Forks: 37
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# miniprogram-i18n
[](https://circleci.com/gh/wechat-miniprogram/miniprogram-i18n)
微信小程序的国际化 (i18n) 方案。为小程序的双线程模型定制，使用 WXS 环境作为 WXML 国际化的运行时，很大程度上减少了国际化在小程序中运行所需的开销。使用上，只需在 WXML 或 JavaScript 中调用翻译函数即可获得翻译文本。i18n 文本可以定义在任意位置，在构建过程中会被统一打包至指定路径。
## 文档
- [快速入门](./docs/quickstart.md)
- [接口文档](./docs/api.md)
- [Gulp插件配置文档](./docs/gulp.md)
- [example 示例工程文档](./examples/README.md)
## 安装
该方案目前需要依赖 Gulp 并且对源文件目录结构有一定的要求，需要确保小程序源文件放置在特定目录下（例如 src/ 目录）：
1. 首先在项目根目录运行以下命令安装 gulp 及 miniprogram-i18n 的 gulp 插件。
```
npm i -D gulp @miniprogram-i18n/gulp-i18n-locales @miniprogram-i18n/gulp-i18n-wxml
```
2. 在小程序运行环境下安装国际化运行时并在开发工具"构建npm"。
```
npm i -S @miniprogram-i18n/core
```
3. 在项目根目录新建 gulpfile.js，并编写构建脚本，可参考 [examples/gulpfile.js](./examples/gulpfile.js)。具体配置详见 [Gulp插件配置文档](./docs/gulp.md)。
## 使用
### 定义 i18n
对所需翻译文本进行定义。例如在 `src/i18n/en-US.json` 中定义：
```
{
"greeting": "hello {toWhom}!"
}
```
其他语言文本在相应语言文件下进行定义即可。
### 使用 i18n
定义好 i18n 文本之后，即可在 WXML 及 JavaScript 文件中使用了。
#### WXML
```html
{{ t('greeting', { toWhom: 'i18n' }) }}
```
另外，需要在 WXML 对应的 JavaScript 文件中进行一些定义，这里以 Component 构造器为例。
```js
// src/pages/index/index.js
import { I18n } from '@miniprogram-i18n/core'
Component({
behaviors: [I18n]
})
```
最终，实际运行时，以上 WXML 会被解析成如下片段并显示。
```
hello i18n!
```
### JavaScript
在 JavaScript 调用接口可能也有文本需要进行国际化处理，此时可以使用 i18n 接口进行文本翻译。
```js
// src/pages/index/index.js
Component({
behaviors: [I18n],
attached() {
const text = this.t('greeting', { toWhom: 'JavaScript' })
console.log(text)
}
})
```
更多使用细节请参考以下文档：
- [快速入门](./docs/quickstart.md)
- [接口文档](./docs/api.md)
- [Gulp插件配置文档](./docs/gulp.md)
### 特性
目前 miniprogram-i18n 仅支持纯文本及文本插值，后续会对其他 i18n 特性进行支持。
#### 文本插值
```js
{
"key": "Inserted value: {value}"
}
```
```js
i18n.t('key', { value: 'Hello!' }) // Inserted value: Hello!
```
为了方便调用深层嵌套的对象，当前支持使用 `.` 点语法来访问对象属性。
```json
{
"dotted": "Nested value is: { obj.nested.value }"
}
```
```js
const value = {
obj: {
nested: {
value: 'Catch you!'
}
}
}
i18n.t('dotted', value) // Nested value is: Catch you!
```
#### select 语句
```json
{
"key": "{gender, select, male {His inbox} female {Her inbox} other {Their inbox}}"
}
```
```js
i18n.t('key', { gender: 'male' }) // His inbox
i18n.t('key', { gender: 'female' }) // Her inbox
i18n.t('key') // Their inbox
```
select 语句支持子语句文本插值：
```
{
"key": "{mood, select, good {{how} day!} sad {{how} day.} other {Whatever!}}"
}
```
```js
i18n.t('key', { mood: 'good', how: 'Awesome' }) // Awesome day!
i18n.t('key', { mood: 'sad', how: 'Unhappy' }) // Unhappy day.
i18n.t('key') // Whatever!
```
> 注：select 语句支持子句嵌套 select 语句
其他尚未支持的特性有：
- Pseudo 字符串
- 单复数处理
- 日期、数字、货币处理
- 定义文件的命名空间
- 支持 WXML 与 JavaScript 独立定义