i18n 配置

weapp.i18n 为微信小程序提供一方维护的轻量国际化链路。底层运行时和 catalog 编译器来自独立包 @weapp-vite/i18n；weapp-vite 负责扫描 JSON、模板改写、分包归属、Vite/Rolldown emit 和 HMR。模板中的 t(...) 会改写为 WXS 调用，逻辑层通过 weapp-vite/i18n 切换语言。

import { defineConfig } from 'weapp-vite/config'

export default defineConfig({
  weapp: {
    i18n: {
      defaultLocale: 'zh-CN',
      fallbackLocale: 'en-US',
    },
  },
})

默认扫描 srcRoot 下的 **/i18n/*.json，文件名就是 locale：

// src/i18n/zh-CN.json
{
  "common": {
    "greeting": "你好 {user.name}"
  }
}

配置项

字段	类型	默认值	说明
defaultLocale	string	必填	初始语言，必须存在对应 JSON 文件
fallbackLocale	string	defaultLocale	当前语言缺 key 时使用的语言
include	string | string[]	**/i18n/*.json	相对 srcRoot 的 locale glob
functionName	string	t	模板翻译函数名
moduleName	string	i18n	注入模板的 WXS module 名

同一 locale 可以由多个文件组成，但叶子 key 不能重复。叶子值必须是字符串；缺少 default/fallback locale、重复 key 或非法值都会在构建期报错并指出来源文件。

Native 接入

Native Component 和使用 Component 构造的 Page 都显式添加 i18n.behavior：

import { i18n } from 'weapp-vite/i18n'

Component({
  behaviors: [i18n.behavior],
  lifetimes: {
    attached() {
      i18n.global.locale = 'en-US'
    },
  },
})

// 仅用于传统 Page({...}) 项目
i18n.page({})

<view>{{ t('common.greeting', { user }) }}</view>

Vue / Wevu 接入

<script setup lang="ts">
import { i18n } from 'weapp-vite/i18n'

defineOptions({ behaviors: [i18n.behavior] })
</script>

<template>
  <view @tap="i18n.global.locale = 'en-US'">
    {{ t('common.greeting', { user }) }}
  </view>
</template>

Wevu 编译器只对白名单中的当前 i18n 函数保留模板调用。其他函数调用仍在逻辑线程计算；t(resolveKey()) 这类混合调用也不会被错误放宽。

运行时语义

weapp-vite/i18n 导出当前构建实例 i18n、global、behavior 和 page；推荐通过 i18n.global 显式访问运行时。

• i18n.global.locale 只接受构建时发现的 locale，非法值抛出 RangeError。
• 有效变化会更新当前运行时实例中已接入的 Page 和 Component。
• 主包与普通分包共享实例；独立分包从 defaultLocale 创建自己的实例。
• 不自动读取或写入宿主 storage，也不全局修改用户的 Page/Component 定义。
• i18n.page() 只用于传统 Page({...})，会显式组合该 Page 的 onLoad / onUnload；Component Page 不需要它。
• 当前语言缺 key 时读取 fallback；仍缺失则返回 key。
• 缺少插值参数时保留原占位符，便于定位数据问题。

v1 只识别 {name} 和 {user.name}。其他花括号保持字面量，不包含 ICU/MessageFormat、复数、select、日期或数字格式化能力。

该能力当前仅支持 platform: 'weapp'。构建器会通过 Vite/Rolldown emit 为各包生成固定的 i18n/locales.js 与 i18n/locales.wxs，不要手工维护这些产物。

原生无 Vite 使用

完全不使用 weapp-vite 的原生项目可以直接安装 @weapp-vite/i18n。独立包提供 factory-first 运行时、CommonJS/ESM/miniprogram 入口、WXS 生成器和 weapp-i18n compile 命令。原生模式显式引用生成的 WXS，不自动改写 WXML；它不是旧包的无差异 drop-in replacement。