微信小程序 工具庫(kù)類(lèi)·國(guó)際化

快速入門(mén)

概覽

miniprogram-i18n 的用法主要分為四部分。分別是：構(gòu)建腳本與i18配置、i18n文本定義、WXML中的用法及JavaScript中的用法。

安裝

該方案目前需要依賴(lài) Gulp 并且對(duì)源文件目錄結(jié)構(gòu)有一定的要求，需要確保小程序源文件放置在特定目錄下（例如 src/ 目錄）。

1. 首先在項(xiàng)目根目錄運(yùn)行以下命令安裝 gulp 及 miniprogram-i18n 的 gulp 插件。

npm i -D gulp @miniprogram-i18n/gulp-i18n-locales @miniprogram-i18n/gulp-i18n-wxml

1. 在小程序運(yùn)行環(huán)境下安裝國(guó)際化運(yùn)行時(shí)并在開(kāi)發(fā)工具"構(gòu)建npm"。

npm i -S @miniprogram-i18n/core

1. 在項(xiàng)目根目錄新建 gulpfile.js，并編寫(xiě)構(gòu)建腳本，可參考 examples/gulpfile.js。

更多 Gulp 相關(guān)配置請(qǐng)參考 Gulp插件配置文檔。

使用

i18n文本定義

miniprogram-i18n 目前采用 JSON 文件對(duì) i18n 文本進(jìn)行定義。使用之前，需要在項(xiàng)目源文件下新建 i18n 目錄。

目錄結(jié)構(gòu)如下：

├── dist               // 小程序構(gòu)建目錄
├── gulpfile.js
├── node_modules
├── package.json
└── src                // 小程序源文件目錄
|   ├── app.js
|   ├── app.json
|   ├── app.wxss
|   ├── i18n           // 國(guó)際化文本目錄
|   |   ├── en-US.json
|   |   └── zh-CN.json

i18n 目錄可以放置在源文件目錄下的任意位置，例如可以跟 Page 或 Component 放在一起。但是需要注意的是，多個(gè) i18n 目錄下的文件在構(gòu)建時(shí)會(huì)被合并打包，因此如果翻譯文本有重復(fù)的 key 可能會(huì)發(fā)生覆蓋。如果分開(kāi)多個(gè) i18n 目錄定義需要自行確保 key 是全局唯一的。例如使用 page.index.testKey 這樣的能確保唯一的名稱(chēng)。

下面我們定義文本：

// i18n/en-US.json
{
  "plainText": "This is a plain text",
  "withParams": "{value} is what you pass in"
}

// i18n/zh-CN.json
{
  "plainText": "這是一段純文本",
  "withParams": "你傳入的值是{value}"
}

WXML 中的用法

定義好 i18n 文本之后，就可以在 WXML 文件里使用了。首先，需要在 WXML 文件對(duì)應(yīng)的 JavaScript 文件里引入國(guó)際化運(yùn)行時(shí)。

// pages/index/index.js
import { I18n } from '@miniprogram-i18n/core'

Component({
  behaviors: [I18n]
})

注意：這里建議 Page 以及 Component 都采用 Component 構(gòu)造器進(jìn)行定義，這樣可以使用 I18n 這個(gè) Behavior。如果需要在 Page 構(gòu)造上使用 I18n 則需要引入 I18nPage 代替 Page 構(gòu)造器。

接著可以在 WXML 文件中獲取預(yù)先定義好的 i18n 文本。

<!-- pages/index/index.wxml -->
<view>{{ t('plainText') }}</view>
<input placeholder="{{ t('withParams', {value}) }}"></input>

在 WXML 中使用 t 函數(shù)（或其他你指定的函數(shù)名）來(lái)獲取文本。 t函數(shù)簽名如下：

t(key: string, params: object)

它可以接受兩個(gè)參數(shù)，第一個(gè)參數(shù)是 i18n 文本的 key，第二個(gè)參數(shù)是需要傳入的插值對(duì)象（可以是從 AppService 傳過(guò)來(lái)的值）。

JavaScript 中的用法

在 JavaScript 里可以直接引用 @miniprogram-i18n/core 這個(gè) NPM 包來(lái)獲取翻譯文本。

import { getI18nInstance } from '@miniprogram-i18n/core'

const i18n = getI18nInstance()

Component({
  attached() {
    const text = i18n.t('withParams', { value: 'Test' })
    console.log(text)    // Test is what you pass in
    i18n.setLocale('en-US')
  }
})

同樣的，在 i18n 實(shí)例上，還暴露了其他一些接口，例如獲取當(dāng)前語(yǔ)言、動(dòng)態(tài)設(shè)置當(dāng)前語(yǔ)言等。具體接口請(qǐng)參考 接口文檔。

如果你的 JavaScript 對(duì)應(yīng)的 WXML 里已經(jīng)使用了國(guó)際化文本，換言之，即 Component 構(gòu)造器已經(jīng)引入了 I18n Behavior，那么所有的實(shí)例方法都會(huì)被直接掛載到 this 上，你可以通過(guò) this 調(diào)用它們。

import { I18n } from '@miniprogram-i18n/core'

Component({
  behaviors: [I18n],
  attached() {
    const text = this.t('withParams', { value: 'Test' })
    console.log(text)    // Test is what you pass in
    this.setLocale('en-US')
  }
})

構(gòu)建

在編寫(xiě)完 i18n 文本并在 WXML 或 JavaScript 中調(diào)用之后，你需要運(yùn)行 gulp 命令對(duì) .wxml 文件進(jìn)行轉(zhuǎn)譯并對(duì) i18n 文本進(jìn)行打包合并。

特性

目前 miniprogram-i18n 僅支持純文本及文本插值，后續(xù)會(huì)對(duì)其他 i18n 特性進(jìn)行支持。

文本插值

{
  "key": "Inserted value: {value}"
}

i18n.t('key', { value: 'Hello!' })  // Inserted value: Hello!

為了方便調(diào)用深層嵌套的對(duì)象，當(dāng)前支持使用 . 點(diǎn)語(yǔ)法來(lái)訪問(wèn)對(duì)象屬性。

{
   "dotted": "Nested value is: { obj.nested.value }"
}

const value = {
  obj: {
    nested: {
      value: 'Catch you!'
    }
  }
}
i18n.t('dotted', value)  // Nested value is: Catch you!

select 語(yǔ)句

{
  "key": "{gender, select, male {His inbox} female {Her inbox} other {Their inbox}}"
}

i18n.t('key', { gender: 'male' })    // His inbox
i18n.t('key', { gender: 'female' })  // Her inbox
i18n.t('key')                        // Their inbox

select 語(yǔ)句支持子語(yǔ)句文本插值：

{
  "key": "{mood, select, good {{how} day!} sad {{how} day.} other {Whatever!}}"
}

i18n.t('key', { mood: 'good', how: 'Awesome'  })  // Awesome day!
i18n.t('key', { mood: 'sad', how: 'Unhappy'  })   // Unhappy day.
i18n.t('key')                                     // Whatever!

注：select 語(yǔ)句支持子句嵌套 select 語(yǔ)句

其他尚未支持的特性有：

• Pseudo 字符串
• 單復(fù)數(shù)處理
• 日期、數(shù)字、貨幣處理
• 定義文件的命名空間
• 支持 WXML 與 JavaScript 獨(dú)立定義

接口文檔

miniprogram-i18n API 是運(yùn)行時(shí)在 JavaScript 側(cè)操作 i18n 的接口。

接口列表

• initI18n(localesConfig: object): I18n
• getI18nInstance(): I18n
• t(key: string, params: object): string
• getLocale(): string
• setLocale(currentLocale: string): void
• getFallbackLocale(): string
• onLocaleChange(handler: (currentLocale: string) => void): object

初始化 I18n 運(yùn)行時(shí)

initI18n(localesConfig: object): I18n

在 app.js 調(diào)用 initI18n 來(lái)加載 i18n 文本并指定默認(rèn)語(yǔ)言。若未進(jìn)行指定，i18n運(yùn)行時(shí)將默認(rèn)從 /i18n/locales.js 中讀取文本及配置。

// src/app.js
import { initI18n } from '@miniprogram-i18n/core'
import locales from '/i18n/locales.js'

initI18n(locales)

App({})

獲取 I18n 運(yùn)行時(shí)

getI18nInstance(): I18n

該接口會(huì)返回 I18n 運(yùn)行時(shí)實(shí)例。

import { getI18nInstance } from '@miniprogram-i18n/core'

const i18n = getI18nInstance()
i18n.t('key')

I18n 接口

以下五個(gè)接口用來(lái)獲取或操作 I18n，均可在 I18n 實(shí)例或 擁有 I18n Behavior 的組件或 I18nPage 上進(jìn)行調(diào)用。 通過(guò)組件直接訪問(wèn)成員函數(shù)：

import { I18n } from '@miniprogram-i18n/core'
Component({
  behaviors: [I18n],

  attached() {
    this.t('key')
    this.getLocale()  // en-US
    this.setLocale('zh-CN')
    this.getFallbackLocale()  // zh-CN
    this.onLocaleChange((currentLocale) => {
      console.log('Locale changed to', currentLocale)
    })
  }
})

或從 I18n 實(shí)例調(diào)用:

import { I18n } from '@miniprogram-i18n/core'

const i18n = getI18nInstance()

i18n.t('key')
i18n.getLocale()  // en-US
i18n.setLocale('zh-CN')
i18n.getFallbackLocale()  // zh-CN
i18n.onLocaleChange((currentLocale) => {
  console.log('Locale changed to', currentLocale)
})

t(key: string, params: object): string

最主要的翻譯函數(shù)，通過(guò)該函數(shù)可以獲得預(yù)先定義的 i18n 文本。

getLocale(): string

獲取當(dāng)前設(shè)置的語(yǔ)言。默認(rèn)語(yǔ)言應(yīng)在 gulp 構(gòu)建腳本中配置，詳見(jiàn) Gulp插件配置文檔。

setLocale(currentLocale: string): void

設(shè)置當(dāng)前語(yǔ)言。該值應(yīng)與 i18n 定義文件名相對(duì)應(yīng)。

getFallbackLocale(): string

獲取備選語(yǔ)言。該值在構(gòu)建腳本中進(jìn)行配置，一旦設(shè)置之后無(wú)法在運(yùn)行時(shí)通過(guò)接口修改。詳見(jiàn) Gulp插件配置文檔。

onLocaleChange(handler: (currentLocale: string) => void): object

當(dāng)前語(yǔ)言被修改時(shí)觸發(fā)的事件回調(diào)。返回值 object，可通過(guò)返回值對(duì)象取消事件監(jiān)聽(tīng)。

const event = i18n.onLocaleChange(() => {})
event.off()

Gulp 插件配置文檔

miniprogram-i18n 在構(gòu)建階段依賴(lài)兩個(gè) Gulp 插件，分別是 @miniprogram-i18n/gulp-i18n-wxml 和 @miniprogram-i18n/gulp-i18n-locales，gulp-i18n-wxml 負(fù)責(zé)轉(zhuǎn)譯 wxml 文件中的 i18n 自定義語(yǔ)法，gulp-i18n-locales 則負(fù)責(zé)合并 i18n 定義文件，并進(jìn)行預(yù)處理生成運(yùn)行時(shí)所需的文件。

若使用 CLI 進(jìn)行構(gòu)建，則可忽略 Gulp 構(gòu)建的配置。

安裝

因此在使用 i18n 的構(gòu)建插件之前，需要先安裝相關(guān)依賴(lài)。

npm i -D gulp @miniprogram-i18n/gulp-i18n-locales @miniprogram-i18n/gulp-i18n-wxml

依賴(lài)安裝完成之后，需要建立 gulp 所需的配置并引入 i18n 構(gòu)建插件。示例如下：

const gulpWxmlTransformer = require('@miniprogram-i18n/gulp-i18n-wxml')
const gulpLocalesLoader = require('@miniprogram-i18n/gulp-i18n-locales')

function transpileWxml() {
  return src('src/**/*.wxml')
    .pipe(gulpWxmlTransformer())
    .pipe(dest('dist/'))
}
function mergeAndGenerateLocales() {
  return src('src/**/i18n/*.json')
    .pipe(gulpLocalesLoader({ defaultLocale: 'zh-CN', fallbackLocale: 'zh-CN' }))
    .pipe(dest('dist/i18n/'))
}

更詳細(xì)的配置請(qǐng)參考 examples。

gulp-i18n-wxml 配置

該構(gòu)建函數(shù)支持如下參數(shù)：

interface Options {
  wxsPath: string,
  wxsModuleName?: string,
  i18nFunctionName?: string,
}

• wxsPath指定 locales.wxs 所在路徑，應(yīng)與 gulp-i18n-locales 中的配置一致，默認(rèn)為 src/i18n/locales.wxs。
• wxsModuleName指定 wxs 模塊名稱(chēng)，默認(rèn)為 i18n。
• i18nFunctionName指定 wxml 中的 i18n 函數(shù)名，默認(rèn)為t，可修改為任意合法的函數(shù)名。

gulp-i18n-locales 配置

該構(gòu)建函數(shù)支持如下參數(shù)：

interface Options {
  wxsFileName?: string
  jsFileName?: string
  defaultLocale?: string
  fallbackLocale?: string
}

• wxsFileName指定 locales wxs 文件名，需以 .wxs 作為后綴，默認(rèn)為 locales.wxs。
• jsFileName指定 locales js 文件名，需以 .js 作為后綴，默認(rèn)為locales.js。
• defaultLocale指定默認(rèn)語(yǔ)言，默認(rèn)為 en-US。該值需與 i18n 定義文件名對(duì)應(yīng)。
• fallbackLocale指定備選語(yǔ)言，默認(rèn)為 en-US。該值需與 i18n 定義文件名對(duì)應(yīng)。在運(yùn)行時(shí)無(wú)法找到對(duì)應(yīng)語(yǔ)言下的文本時(shí)，會(huì)從備選語(yǔ)言中進(jìn)行查找。注：該值無(wú)法在運(yùn)行進(jìn)行修改。