如果你的 JavaScript 对应的 WXML 里已经使用了国际化文本，换言之，即 Component 构造器已经引入了 I18n Behavior，那么所有的实例方法都会被直接挂载到 this 上，你可以通过 this 调用它们。

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')
  }
})

构建

在编写完 i18n 文本并在 WXML 或 JavaScript 中调用之后，你需要运行 gulp 命令对 .wxml 文件进行转译并对 i18n 文本进行打包合并。

特性

目前 miniprogram-i18n 仅支持纯文本及文本插值，后续会对其他 i18n 特性进行支持。

文本插值

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

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

为了方便调用深层嵌套的对象，当前支持使用 . 点语法来访问对象属性。

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

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

select 语句

{
  "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 语句支持子语句文本插值：

{
  "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 语句支持子句嵌套 select 语句

其他尚未支持的特性有：

Pseudo 字符串
单复数处理
日期、数字、货币处理
定义文件的命名空间
支持 WXML 与 JavaScript 独立定义

接口文档

miniprogram-i18n API 是运行时在 JavaScript 侧操作 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 运行时

initI18n(localesConfig: object): I18n

在 app.js 调用 initI18n 来加载 i18n 文本并指定默认语言。若未进行指定，i18n运行时将默认从 /i18n/locales.js 中读取文本及配置。

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

initI18n(locales)

App({})

获取 I18n 运行时

getI18nInstance(): I18n

该接口会返回 I18n 运行时实例。

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

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

I18n 接口

以下五个接口用来获取或操作 I18n，均可在 I18n 实例或拥有 I18n Behavior 的组件或 I18nPage 上进行调用。通过组件直接访问成员函数：

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 实例调用:

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

最主要的翻译函数，通过该函数可以获得预先定义的 i18n 文本。

getLocale(): string

获取当前设置的语言。默认语言应在 gulp 构建脚本中配置，详见 Gulp插件配置文档。

setLocale(currentLocale: string): void

设置当前语言。该值应与 i18n 定义文件名相对应。

getFallbackLocale(): string

获取备选语言。该值在构建脚本中进行配置，一旦设置之后无法在运行时通过接口修改。详见 Gulp插件配置文档。

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

当前语言被修改时触发的事件回调。返回值 object，可通过返回值对象取消事件监听。

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

Gulp 插件配置文档

miniprogram-i18n 在构建阶段依赖两个 Gulp 插件，分别是 @miniprogram-i18n/gulp-i18n-wxml 和 @miniprogram-i18n/gulp-i18n-locales，gulp-i18n-wxml 负责转译 wxml 文件中的 i18n 自定义语法，gulp-i18n-locales 则负责合并 i18n 定义文件，并进行预处理生成运行时所需的文件。

若使用 CLI 进行构建，则可忽略 Gulp 构建的配置。

安装

因此在使用 i18n 的构建插件之前，需要先安装相关依赖。

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

依赖安装完成之后，需要建立 gulp 所需的配置并引入 i18n 构建插件。示例如下：

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/'))
}

更详细的配置请参考 examples。

gulp-i18n-wxml 配置

该构建函数支持如下参数：

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

wxsPath指定 locales.wxs 所在路径，应与 gulp-i18n-locales 中的配置一致，默认为 src/i18n/locales.wxs。
wxsModuleName指定 wxs 模块名称，默认为 i18n。
i18nFunctionName指定 wxml 中的 i18n 函数名，默认为t，可修改为任意合法的函数名。

gulp-i18n-locales 配置

该构建函数支持如下参数：

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

wxsFileName指定 locales wxs 文件名，需以 .wxs 作为后缀，默认为 locales.wxs。
jsFileName指定 locales js 文件名，需以 .js 作为后缀，默认为locales.js。
defaultLocale指定默认语言，默认为 en-US。该值需与 i18n 定义文件名对应。
fallbackLocale指定备选语言，默认为 en-US。该值需与 i18n 定义文件名对应。在运行时无法找到对应语言下的文本时，会从备选语言中进行查找。注：该值无法在运行进行修改。

标签：微信小程序

返回前面的内容