@weapp-vite/i18n

@weapp-vite/i18n 是一方维护的微信小程序 i18n 运行时与编译器。它不依赖 Vite、Vue、Wevu、Intlify、i18next 或 messageformat，可以直接用于原生微信小程序；weapp-vite 的 weapp.i18n 也复用同一套消息和运行时语义。

安装与生成

pnpm add @weapp-vite/i18n
pnpm exec weapp-i18n compile \
  --src-root miniprogram \
  --default-locale zh-CN \
  --fallback-locale en-US

命令扫描 <src-root>/**/i18n/*.json，生成 <src-root>/i18n/locales.js 与 locales.wxs。这些是原生项目的显式生成源码；weapp-vite 项目不调用该命令，最终文件仍全部由 Vite/Rolldown emit。

创建实例

const { createI18n } = require('@weapp-vite/i18n')
const catalog = require('./i18n/locales')

// locales.js 是 compile 命令生成的预编译 catalog
const i18n = createI18n(catalog)

module.exports = i18n

推荐使用 createI18n()，每个实例独立持有 locale、订阅者和页面/组件集合。不提供 @miniprogram-i18n/core 的 singleton 兼容入口；迁移仍需按 v1 消息语义调整旧的 select/ICU 消息。

Page 与 Component

Component 和使用 Component 构造的 Page 直接添加 Behavior：

const { i18n } = require('../../i18n')

Component({
  behaviors: [i18n.behavior],
})

传统 Page({...}) 使用显式适配器：

const { i18n } = require('../../i18n')

i18n.page({
  data: {},
})

不提供 I18nComponent：Component 已原生支持 Behavior，额外构造器只会隐藏 behavior 合并顺序。i18n.page() 只解决传统 Page 不支持 behaviors 的平台限制。

WXML

原生模式不自动修改 WXML，显式引用生成的 WXS：

<wxs module="i18n" src="/i18n/locales.wxs" />
<view>{{ i18n.t(__wv_i18n_locale, 'common.greeting', { user }) }}</view>

运行 i18n.global.locale = locale 后，当前实例内已接入的 Page 和 Component 会更新。非法 locale 抛出 RangeError；当前语言缺 key 时读取 fallback，仍缺失时返回 key；缺少参数时保留原占位符。

编译器

Node 构建工具可以从 @weapp-vite/i18n/compiler 导入 compileI18nCatalog()、compileI18nMessage()、generateI18nWxsSource() 和 compileNativeI18n()。运行时根入口同时提供 ESM、CommonJS、类型与微信 miniprogram 产物。

v1 只识别 {name} 与 {user.name}，不支持旧包的 select、ICU、plural、日期、数字或货币格式化。迁移含 select 的旧词典时应先改写消息，不能把它视为完全无语义差异的替换。