weapp-vite/dist/docs/i18n.md

weapp-vite 一个现代化的小程序打包工具

# First-party i18n

`weapp.i18n` 提供微信小程序构建期 locale 编译、WXS 模板查询和逻辑层语言切换。运行时与 catalog 编译语义来自独立包 `@weapp-vite/i18n`，weapp-vite 负责扫描、模板改写、分包归属、Vite/Rolldown emit 和 HMR。

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

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

默认扫描 `srcRoot` 下的 `**/i18n/*.json`，按文件名识别 locale。嵌套对象会展开为点路径；重复叶子 key、非字符串叶子、缺失 default/fallback locale 会直接构建失败。

Native Component 和使用 Component 构造的 Page 都直接使用 `i18n.behavior`：

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

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

// 仅用于传统 Page({...}) 项目
i18n.page({})
i18n.global.locale = 'en-US'
```

Vue/Wevu 组件使用 `defineOptions({ behaviors: [i18n.behavior] })`。模板直接调用：

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

运行时导出构建实例 `i18n`，并提供 `i18n.global.t()`、`i18n.global.locale`、`i18n.global.fallbackLocale`、`i18n.global.availableLocales` 和 `i18n.global.onLocaleChange()`。写入未构建语言会抛出 `RangeError`；主包和普通分包共享实例，独立分包使用自己的实例。该能力不自动持久化 storage；`i18n.page()` 会显式组合传统 Page 的 `onLoad` / `onUnload`。

## 不使用 weapp-vite

原生微信小程序可以直接安装 `@weapp-vite/i18n`，运行 `weapp-i18n compile` 生成 `i18n/locales.js` 与 `i18n/locales.wxs`，再通过 `createI18n({ locale, fallbackLocale, messages })` 创建应用内实例。独立包同时提供 CommonJS、ESM、类型、`miniprogram` 入口和 `@weapp-vite/i18n/compiler`；完整示例见 [@weapp-vite/i18n](https://vite.weapp.dev/packages/i18n)。

v1 只编译 `{name}` 与 `{user.name}` 占位符，不支持 ICU/MessageFormat、复数、select、日期或数字格式化。当前只支持微信平台。