# 国际化i18n

Mpx 支持国际化 i18n，使用方式及支持能力与 vue-i18n 非常接近。

# 使用方法

Mpx 自带 i18n 能力，无需额外安装插件。由于小程序模板中的 i18n 函数是通过 wxs 编译注入进行实现，我们需要将 i18n 配置传入到 MpxWebpackPlugin 中来使 i18n 生效，这是与 vue-i18n 最大的区别。

# 配置方法

I18n 配置传入到 MpxWebpackPlugin 选项中即可生效，额外支持 messagesPath/dateTimeFormatsPath/numberFormatsPath 配置，通过模块路径传入语言集，其余配置参考 vue-i18n。

由于小程序的双线程特性，默认情况下在模板中调用的 i18n 函数由 wxs 实现，而 js 中调用的 i18n 函数由 js 实现，该设计能够将视图层和逻辑层之间的通信开销降至最低，得到最优的性能表现，但是由于 wxs 和 js 之间无法共享数据，在最终的编译产物中语言集会同时存在于 js 和 wxs 当中，对包体积产生负面影响。

为了平衡上述影响，自2.6.56版本之后我们新增了编译配置项 i18n.useComputed ，改配置项开启的情况下对于模板中的 i18n 调用将不再使用 wxs 实现，而是通过在 computed 进行实现，语言集将只存在于 js 逻辑层当中，对于节省了包体积的同时双线程通信成本也会增加，用时间换空间，具体是否开启可以根据实际项目的使用情况及资源瓶颈由开发者自行决定。

开启 i18n.useComputed 配置时，由于 computed 技术架构的限制，i18n 函数无法对模板循环渲染中的 item 或 index 生效。

new MpxWebpackPlugin({
  i18n: {
    locale: 'en-US',
    // messages既可以通过对象字面量传入，也可以通过messagesPath指定一个js模块路径，在该模块中定义配置并导出，dateTimeFormats/dateTimeFormatsPath和numberFormats/numberFormatsPath同理
    messages: {
      'en-US': {
        message: {
          hello: '{msg} world'
        }
      },
      'zh-CN': {
        message: {
          hello: '{msg} 世界'
        }
      }
    },
    useComputed: false // 默认 false,  此开关将模板中的 i18n 函数注入 computed，在包体积空间紧张的情况下可以使用
    // messagesPath: path.resolve(__dirname, '../src/i18n.js')
  }
})

# 在js中使用

同 vue-i18n，在组件中直接调用翻译函数使用，由于 wxs 执行环境的限制，目前 js 中支持了 vue-i18n 中 $t/$tc/$te 翻译函数，$d/$n 暂不支持，详细使用方法参考 vue-i18n。

createComponent({
  ready () {
    console.log(this.$t('message.hello', { msg: 'hello' }))
  },
  computed: {
    isMessageExist () {
      return this.$te('message.hello')
    }
  }
})

# 在模板中使用

类似于 vue-i18n，在模板的 Mustache 插值中直接调用翻译函数，目前由于 wxs 执行环境的限制，模板上可直接使用的翻译函数包括 $t/$tc/$te ，如果需要格式化数字或日期可以使用对应的 js 翻译函数和 Mpx 提供的计算属性结合实现。

<view>
  <!-- isMessageExist计算属性定义见上例 -->
  <view wx:if="{{isMessageExist}}">{{ $t('message.hello', { msg: 'hello' }) }}</view>
</view>

# 动态变更locale

类似于 vue-i18n，可实现全局 local 变更及局部 local 变更，并自动更新视图，使用方式如下：

import mpx, { createComponent } from '@mpxjs/core'

createComponent({
  ready () {
    // 局部locale变更，生效范围为当前组件内
    this.$i18n.locale = 'en-US'
    setTimeout(() => {
      // 全局locale变更，生效范围为项目全局
      mpx.i18n.locale = 'zh-CN'
    }, 1000)
  }
})

# 动态更新语言集

在模板中没有使用 i18n 函数或开启了 i18n.useComputed 配置时，允许通过 mpx.i18n.mergeMessages 或 mpx.i18n.mergeLocaleMessage 对语言集进行动态更新，使用方式如下：

import mpx, { createComponent } from '@mpxjs/core'

createComponent({
  ready () {
    // 扩展更新现有语言集
    mpx.i18n.mergeMessages({
      'en-US': {
        message: {
          bye: 'bye'
        }
      },
      'zh-CN': {
        message: {
          bye: '再见'
        }
      }
    })
    setTimeout(() => {
      // 新增一门语言或针对特定语言更新语言集
      mpx.i18n.mergeLocaleMessage('ja-JP', {
        message: {
          hello: 'こにちは',
          bye: 'さよなら'
        }
      })
    }, 1000)
  }
})

# 平台支持

由于 Mpx 中 i18n 实现依赖类 wxs 能力，目前支持业内所有小程序平台(微信/支付宝/qq/百度/头条)，在输出 web 时，构建会自动引入 vue-i18n 并进行安装配置，无需修改任何代码即可按照预期正常工作。

← 单元测试 →