@lhy-meta-server/meta-i18n 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,1239 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @lhy-meta-server/meta-i18n
+
+面向 Bun 设计、兼容 Node.js 的服务端国际化插件，支持深层属性插值、语言回退、命名空间、复数、上下文、格式化、异步资源加载和请求级语言隔离。
+
+## 安装
+
+```bash
+bun add @lhy-meta-server/meta-i18n
+```
+
+```bash
+npm install @lhy-meta-server/meta-i18n
+```
+
+要求 Bun >= 1.1 或 Node.js >= 18.18，仅支持 ESM。
+
+## 导入入口
+
+```ts
+import { createI18n } from '@lhy-meta-server/meta-i18n'
+import { withI18n } from '@lhy-meta-server/meta-i18n/http'
+import { createFsBackend } from '@lhy-meta-server/meta-i18n/loaders'
+```
+
+| 入口 | 内容 |
+| --- | --- |
+| `@lhy-meta-server/meta-i18n` | 核心实例、类型、格式化器和工具函数 |
+| `@lhy-meta-server/meta-i18n/http` | 请求语言检测和 Web 标准 HTTP 包装器 |
+| `@lhy-meta-server/meta-i18n/loaders` | 文件系统、内存和懒加载资源后端 |
+
+## 快速开始
+
+```ts
+import { createI18n } from '@lhy-meta-server/meta-i18n'
+
+const i18n = createI18n({
+  lng: 'zh-CN',
+  fallbackLng: 'en',
+  supportedLngs: ['zh-CN', 'en'],
+  resources: {
+    'zh-CN': {
+      translation: {
+        welcome: '欢迎，{{user.profile.name}}！',
+        item_one: '{{count}} 件商品',
+        item_other: '{{count}} 件商品',
+      },
+    },
+    en: {
+      translation: {
+        welcome: 'Welcome, {{user.profile.name}}!',
+        item_one: '{{count}} item',
+        item_other: '{{count}} items',
+      },
+    },
+  },
+})
+
+await i18n.init()
+
+i18n.t('welcome', { user: { profile: { name: 'Tom' } } })
+// 欢迎，Tom！
+
+i18n.t('item', { lng: 'en', count: 3 })
+// 3 items
+```
+## 创建实例
+
+`createI18n(options)` 返回一个独立的 `I18n` 实例。内联资源在实例创建后即可使用；配置异步资源后端或插件初始化钩子时，应先等待 `init()`。
+
+```ts
+const i18n = createI18n(options)
+await i18n.init()
+```
+
+`init()` 是幂等的，多次调用会复用同一个初始化任务。
+
+也可以直接创建类实例：
+
+```ts
+import { I18n } from '@lhy-meta-server/meta-i18n'
+
+const i18n = new I18n(options)
+```
+
+## 翻译
+
+### 基础翻译
+
+```ts
+i18n.t('home.title')
+i18n.translate('home.title')
+```
+
+`t` 已绑定到实例，可以安全解构：
+
+```ts
+const { t } = i18n
+t('home.title')
+```
+
+可以提供多个候选键，插件会依次查找，返回第一个存在的翻译：
+
+```ts
+i18n.t(['error.network.timeout', 'error.network.default', 'error.default'])
+```
+
+### 默认值
+
+```ts
+i18n.t('unknown.key', { defaultValue: '默认内容' })
+i18n.t('unknown.key', { defaultValue: '你好，{{name}}', name: 'Tom' })
+```
+
+没有 `defaultValue` 时，缺失键默认返回键本身。
+
+### 检查键是否存在
+
+```ts
+i18n.exists('home.title')
+i18n.exists('item', { lng: 'en', count: 2 })
+i18n.exists('friend', { context: 'male' })
+```
+
+`exists()` 会应用语言回退、命名空间、上下文和复数规则。
+
+## 插值
+
+### 深层属性
+
+插值支持任意深度的对象和数组属性：
+
+```json
+{
+  "profile": "姓名：{{user.profile.name}}",
+  "firstItem": "商品：{{order.items[0].title}}",
+  "lastItem": "最后一项：{{order.items[-1].title}}",
+  "specialKey": "值：{{data[\"key.with.dot\"]}}"
+}
+```
+
+```ts
+const result = i18n.t('profile', {
+  user: {
+    profile: {
+      name: 'Tom',
+    },
+  },
+})
+```
+
+支持的路径语法：
+
+| 语法 | 示例 | 说明 |
+| --- | --- | --- |
+| 点号属性 | `user.profile.name` | 深层对象属性 |
+| 数组下标 | `items[0].title` | 数组元素 |
+| 点号下标 | `items.0.title` | 数组元素的简写形式 |
+| 负数下标 | `items[-1].title` | 从数组末尾读取 |
+| 引号键名 | `data["a.b"]` | 属性名包含点号或空格 |
+| `Map` 键 | `settings.theme` | `settings` 可以是 `Map` |
+
+路径中间值为 `null`、`undefined` 或属性不存在时，会按缺失插值处理，不会抛出异常。
+
+如果插值对象本身含有名为 `a.b` 的扁平属性，该属性优先于深层路径：
+
+```ts
+i18n.t('key', {
+  values: {
+    'a.b': '扁平值',
+    a: { b: '嵌套值' },
+  },
+})
+```
+
+### 插值变量
+
+变量可以直接放在翻译选项顶层：
+
+```ts
+i18n.t('welcome', {
+  user: { profile: { name: 'Tom' } },
+})
+```
+
+也可以放在 `values` 中。`values` 适用于变量名与 `lng`、`ns`、`count` 等保留选项冲突的场景，并且同名变量优先于顶层变量：
+
+```ts
+i18n.t('message', {
+  lng: 'zh-CN',
+  values: {
+    lng: 'zh-CN 也是模板变量',
+  },
+})
+```
+
+### HTML 转义
+
+插值默认启用 HTML 转义：
+
+```ts
+i18n.t('welcome', { name: '<script>alert(1)</script>' })
+// &lt;script&gt;alert(1)&lt;/script&gt;
+```
+
+单个插值使用 `{{- path}}` 跳过转义：
+
+```json
+{
+  "trustedHtml": "内容：{{- html}}"
+}
+```
+
+关闭单次调用的转义：
+
+```ts
+i18n.t('welcome', {
+  name: '<b>Tom</b>',
+  interpolation: { escapeValue: false },
+})
+```
+
+关闭整个实例的转义：
+
+```ts
+createI18n({
+  interpolation: {
+    escapeValue: false,
+  },
+})
+```
+
+只有在纯文本或可信内容场景中才应关闭转义。
+
+### 缺失插值
+
+```ts
+createI18n({
+  interpolation: {
+    missingValue: 'keep',
+  },
+})
+```
+
+| 值 | 行为 |
+| --- | --- |
+| `'empty'` | 替换为空字符串，默认行为 |
+| `'keep'` | 保留原始 `{{path}}` |
+| `(path, key) => string` | 使用回调返回值 |
+
+```ts
+createI18n({
+  interpolation: {
+    missingValue: (path, key) => `[missing ${key}:${path}]`,
+  },
+})
+```
+
+单次翻译也可以覆盖：
+
+```ts
+i18n.t('welcome', {
+  interpolation: { missingValue: 'keep' },
+})
+```
+
+### 自定义插值标记
+
+```ts
+const i18n = createI18n({
+  interpolation: {
+    prefix: '${',
+    suffix: '}',
+  },
+  resources: {
+    en: {
+      translation: {
+        welcome: 'Hello ${user.name}',
+      },
+    },
+  },
+})
+```
+
+### 独立读取深层属性
+
+```ts
+import { getByPath, parsePath } from '@lhy-meta-server/meta-i18n'
+
+getByPath({ a: { b: [{ c: 1 }] } }, 'a.b[0].c')
+// 1
+
+parsePath('a.b[0].c')
+// ['a', 'b', 0, 'c']
+```
+## 命名空间
+
+资源按“语言 → 命名空间 → 翻译键”组织：
+
+```ts
+const i18n = createI18n({
+  lng: 'zh-CN',
+  ns: ['common', 'user'],
+  defaultNS: 'common',
+  fallbackNS: 'common',
+  resources: {
+    'zh-CN': {
+      common: {
+        button: {
+          ok: '确定',
+          cancel: '取消',
+        },
+      },
+      user: {
+        title: '用户中心',
+      },
+    },
+  },
+})
+```
+
+```ts
+i18n.t('button.ok')
+i18n.t('user:title')
+i18n.t('title', { ns: 'user' })
+i18n.t('title', { ns: ['user', 'common'] })
+```
+
+命名空间分隔符默认为 `:`，可修改或关闭：
+
+```ts
+createI18n({ nsSeparator: '::' })
+createI18n({ nsSeparator: false })
+```
+
+## 复数
+
+复数规则基于 `Intl.PluralRules` 和 CLDR。资源键使用 `_zero`、`_one`、`_two`、`_few`、`_many`、`_other` 后缀：
+
+```json
+{
+  "item_zero": "没有商品",
+  "item_one": "{{count}} item",
+  "item_other": "{{count}} items"
+}
+```
+
+```ts
+i18n.t('item', { lng: 'en', count: 0 })
+i18n.t('item', { lng: 'en', count: 1 })
+i18n.t('item', { lng: 'en', count: 5 })
+```
+
+精确数量资源会优先匹配：
+
+```json
+{
+  "member_0": "暂无成员",
+  "member_1": "只有你",
+  "member_other": "共有 {{count}} 位成员"
+}
+```
+
+序数使用 `_ordinal_*` 后缀：
+
+```json
+{
+  "place_ordinal_one": "{{count}}st",
+  "place_ordinal_two": "{{count}}nd",
+  "place_ordinal_few": "{{count}}rd",
+  "place_ordinal_other": "{{count}}th"
+}
+```
+
+```ts
+i18n.t('place', { lng: 'en', count: 2, ordinal: true })
+// 2nd
+```
+
+后缀分隔符可以通过 `pluralSeparator` 修改。
+
+## 上下文
+
+使用上下文选择同一个键的不同变体：
+
+```json
+{
+  "friend": "一位朋友",
+  "friend_male": "一位男性朋友",
+  "friend_female": "一位女性朋友"
+}
+```
+
+```ts
+i18n.t('friend', { context: 'male' })
+i18n.t('friend', { context: 'female' })
+i18n.t('friend', { context: 'unknown' })
+// 未找到 friend_unknown 时回退到 friend
+```
+
+上下文和复数可以组合：
+
+```json
+{
+  "guest_male_one": "{{count}} 位男宾",
+  "guest_male_other": "{{count}} 位男宾",
+  "guest_female_one": "{{count}} 位女宾",
+  "guest_female_other": "{{count}} 位女宾"
+}
+```
+
+上下文分隔符可以通过 `contextSeparator` 修改。
+
+## 嵌套翻译
+
+使用 `$t(key)` 在翻译文本中引用其他翻译：
+
+```json
+{
+  "brand": "Meta",
+  "welcome": "欢迎使用 $t(brand)",
+  "summary": "状态：$t(status.ready)",
+  "cart": "你有 $t(item, {\"count\": 3})"
+}
+```
+
+嵌套翻译继承父级语言、命名空间和插值变量。嵌套选项必须是合法 JSON。
+
+```ts
+createI18n({
+  interpolation: {
+    nesting: true,
+    maxNestingDepth: 10,
+  },
+})
+```
+
+最大深度用于阻止循环引用。达到限制后，未展开的 `$t(...)` 会保留在结果中。
+
+## 格式化
+
+格式化器名称放在插值路径之后，用逗号分隔。推荐资源模板只声明“如何格式化”，具体参数使用标准 `Intl` 选项从代码传入：
+
+```json
+{
+  "amount": "金额：{{price, currency}}",
+  "number": "数量：{{count, number}}",
+  "percent": "进度：{{progress, percent}}",
+  "date": "日期：{{createdAt, datetime}}",
+  "relative": "{{days, relativetime}}",
+  "users": "用户：{{names, list}}",
+  "upper": "{{name, uppercase}}"
+}
+```
+
+```ts
+i18n.t('amount', {
+  price: 99,
+  formatParams: {
+    price: {
+      currency: 'CNY',
+      currencyDisplay: 'symbol',
+    },
+  },
+})
+```
+
+`formatParams` 的键是插值路径，值直接使用对应的 ECMA-402 `Intl` 选项。资源模板只声明格式化器名称，不解析或保存业务参数；货币、时区等选项由代码统一提供。
+
+### 直接格式化
+
+不需要翻译模板时，可以调用 `format()`。选项同样遵循标准 `Intl`：
+
+```ts
+i18n.format(12345.67, 'number', {
+  minimumFractionDigits: 2,
+})
+
+i18n.format(99, 'currency', {
+  currency: 'CNY',
+  currencyDisplay: 'symbol',
+})
+
+i18n.format(new Date(), 'datetime', {
+  dateStyle: 'long',
+  timeStyle: 'short',
+  timeZone: 'Asia/Shanghai',
+})
+
+i18n.format(-1, 'relativetime', {
+  unit: 'day',
+  numeric: 'auto',
+})
+```
+
+第四个参数可以覆盖格式化语言：
+
+```ts
+i18n.format(99, 'currency', { currency: 'EUR' }, 'de-DE')
+```
+
+多个字符串格式化器会从左到右执行：
+
+```json
+{
+  "name": "{{name, lowercase, capitalize}}"
+}
+```
+
+| 格式化器 | 关键选项 | 底层标准 |
+| --- | --- | --- |
+| `number` | `minimumFractionDigits`、`notation`、`useGrouping` | `Intl.NumberFormat` |
+| `currency` | `currency`、`currencyDisplay`、`currencySign` | `Intl.NumberFormat` |
+| `percent` | `minimumFractionDigits`、`maximumFractionDigits` | `Intl.NumberFormat` |
+| `datetime` / `date` | `dateStyle`、`timeStyle`、`timeZone` | `Intl.DateTimeFormat` |
+| `relativetime` | `unit`、`numeric`、`style` | `Intl.RelativeTimeFormat` |
+| `list` | `type`、`style` | `Intl.ListFormat` |
+| `uppercase` | 无 | `toLocaleUpperCase` |
+| `lowercase` | 无 | `toLocaleLowerCase` |
+| `capitalize` | 无 | 本地化大小写转换 |
+
+
+### 自定义格式化器
+
+初始化时注册：
+
+```ts
+const i18n = createI18n({
+  formatters: {
+    mask(value, _lng, options) {
+      const text = String(value)
+      const char = String(options.value ?? '*')
+      return char.repeat(Math.max(0, text.length - 4)) + text.slice(-4)
+    },
+  },
+})
+```
+
+运行时注册：
+
+```ts
+i18n.addFormatter('trim', (value) => String(value).trim())
+```
+
+资源中使用：
+
+```json
+{
+  "phone": "手机号：{{phone, mask(*)}}"
+}
+```
+## 语言与回退
+
+### 切换语言
+
+```ts
+await i18n.changeLanguage('en')
+i18n.language
+// en
+```
+
+`changeLanguage()` 会按需加载目标语言资源并修改实例默认语言。服务端并发请求不应通过它切换请求语言，请使用请求作用域。
+
+### 固定语言翻译函数
+
+```ts
+const t = i18n.getFixedT('zh-CN', 'common', 'button')
+
+t('ok')
+// 等价于 i18n.t('button.ok', { lng: 'zh-CN', ns: 'common' })
+```
+
+参数依次为固定语言、固定命名空间和键前缀，均可省略。调用固定函数时显式传入的 `lng` 或 `ns` 仍可覆盖固定值。
+
+### 请求级语言作用域
+
+```ts
+const result = await i18n.runWithLanguage('en', async () => {
+  await loadUser()
+  return i18n.t('welcome')
+})
+```
+
+语言会沿异步调用链传递，多个并发作用域互不影响。作用域结束后实例默认语言不变。
+
+### 语言规范化
+
+```ts
+i18n.resolveLanguage('zh_cn')
+// zh-CN
+
+i18n.resolveLanguage('EN-us')
+// en-US 或配置中匹配到的受支持语言
+```
+
+配置 `supportedLngs` 后，语言按以下顺序匹配：
+
+1. 完整语言标识。
+2. 主语言标识，例如 `zh-TW` 匹配 `zh`。
+3. 同主语言的受支持地区，例如 `en-AU` 匹配 `en-US`。
+4. 第一个回退语言。
+
+### 回退语言
+
+单个回退语言：
+
+```ts
+createI18n({ fallbackLng: 'en' })
+```
+
+多个回退语言：
+
+```ts
+createI18n({ fallbackLng: ['zh-CN', 'en'] })
+```
+
+按请求语言配置：
+
+```ts
+createI18n({
+  fallbackLng: {
+    'zh-TW': ['zh-CN'],
+    'en-AU': ['en-GB', 'en'],
+    default: ['en'],
+  },
+})
+```
+
+动态回退：
+
+```ts
+createI18n({
+  fallbackLng: (lng) => (lng.startsWith('zh-') ? ['zh-CN', 'en'] : ['en']),
+})
+```
+
+关闭回退：
+
+```ts
+createI18n({ fallbackLng: false })
+```
+
+默认情况下，`zh-Hant-TW` 会形成 `zh-Hant-TW → zh-Hant → zh → fallbackLng` 的查找链。设置 `loadCurrentOnly: true` 后不再追加主语言变体。
+
+## 资源
+
+资源结构为语言、命名空间和资源树三层：
+
+```ts
+const resources = {
+  en: {
+    common: {
+      button: {
+        ok: 'OK',
+      },
+    },
+  },
+  'zh-CN': {
+    common: {
+      button: {
+        ok: '确定',
+      },
+    },
+  },
+}
+```
+
+资源树也可以使用扁平键，或嵌套与扁平混用：
+
+```ts
+{
+  'button.ok': '确定',
+  dialog: {
+    'button.cancel': '取消',
+  },
+}
+```
+
+### 文件系统后端
+
+默认文件路径为 `<baseDir>/<lng>/<ns>.json`：
+
+```ts
+import { createI18n } from '@lhy-meta-server/meta-i18n'
+import { createFsBackend } from '@lhy-meta-server/meta-i18n/loaders'
+
+const i18n = createI18n({
+  lng: 'zh-CN',
+  fallbackLng: 'en',
+  supportedLngs: ['zh-CN', 'en'],
+  ns: ['common', 'user'],
+  defaultNS: 'common',
+  preload: ['en'],
+  backend: createFsBackend({
+    baseDir: './locales',
+    pathTemplate: '{{lng}}/{{ns}}.json',
+  }),
+})
+
+await i18n.init()
+```
+
+目录示例：
+
+```text
+locales/
+├── en/
+│   ├── common.json
+│   └── user.json
+└── zh-CN/
+    ├── common.json
+    └── user.json
+```
+
+自定义解析器可用于 YAML、JSON5 等格式：
+
+```ts
+createFsBackend({
+  baseDir: './locales',
+  pathTemplate: '{{lng}}/{{ns}}.yaml',
+  parse: (content, filePath) => parseYaml(content),
+})
+```
+
+文件后端会校验语言与命名空间，并同时检查规范路径和真实路径，拒绝 `../` 与符号链接造成的目录逃逸。
+
+### 内存后端
+
+```ts
+import { createMemoryBackend } from '@lhy-meta-server/meta-i18n/loaders'
+
+const backend = createMemoryBackend(resources)
+const i18n = createI18n({ backend })
+```
+
+直接配置 `resources` 通常更简单；内存后端主要用于组合后端和统一加载流程。
+
+### 懒加载后端
+
+```ts
+import { createLazyBackend } from '@lhy-meta-server/meta-i18n/loaders'
+
+const backend = createLazyBackend({
+  en: {
+    common: () => import('./locales/en/common.json', { with: { type: 'json' } }),
+  },
+  'zh-CN': {
+    common: () => import('./locales/zh-CN/common.json', { with: { type: 'json' } }),
+  },
+})
+```
+
+懒加载函数可返回资源树，或返回包含 `default` 资源树的模块。
+
+### 组合后端
+
+```ts
+import {
+  chainBackends,
+  createLazyBackend,
+  createMemoryBackend,
+} from '@lhy-meta-server/meta-i18n/loaders'
+
+const backend = chainBackends(
+  remoteBackend,
+  createLazyBackend(lazyResources),
+  createMemoryBackend(fallbackResources),
+)
+```
+
+后端按传入顺序读取，返回第一个非 `undefined` 的资源。
+
+### 自定义后端
+
+```ts
+import type { ResourceBackend } from '@lhy-meta-server/meta-i18n'
+
+const backend: ResourceBackend = {
+  async read(lng, ns) {
+    const value = await redis.get(`i18n:${lng}:${ns}`)
+    return value ? JSON.parse(value) : undefined
+  },
+}
+```
+
+`read(lng, ns)` 应返回资源树或 `undefined`，也可以同步返回。抛出的异常会被转换为 `I18nError` 并触发 `failedLoading` 事件。默认的 `loadFailureMode: 'throw'` 会同时让当前加载操作失败，避免生产请求静默返回错误语言。
+
+### 动态加载资源
+
+```ts
+await i18n.loadLanguages('ja')
+await i18n.loadLanguages(['ja', 'ko'])
+await i18n.loadNamespaces('admin')
+await i18n.loadNamespaces(['admin', 'report'])
+```
+
+加载语言时会同时加载其语言回退链以及当前登记的全部命名空间。并发加载相同“语言 + 命名空间”时只调用一次后端。
+
+重新加载资源：
+
+```ts
+await i18n.reloadResources()
+await i18n.reloadResources('en')
+await i18n.reloadResources(['en', 'zh-CN'], ['common', 'user'])
+```
+
+### 运行时修改资源
+
+```ts
+i18n.addResourceBundle(
+  'zh-CN',
+  'common',
+  {
+    button: {
+      save: '保存',
+    },
+  },
+  true,
+  true,
+)
+```
+
+`addResourceBundle` 最后两个参数分别表示是否深度合并和是否覆盖已有值，默认均为 `true`。
+
+```ts
+i18n.addResource('zh-CN', 'common', 'button.delete', '删除')
+
+i18n.getResourceBundle('zh-CN', 'common') // 返回与内部状态隔离的资源快照
+i18n.hasResourceBundle('zh-CN', 'common')
+i18n.removeResourceBundle('zh-CN', 'common')
+
+i18n.toJSON()
+```
+## HTTP 集成
+
+HTTP 子入口基于 Web 标准的 `Request` 和 `Response`，适用于 Bun.serve、Elysia、Hono 以及其他兼容 Fetch API 的框架。
+
+### Bun.serve
+
+```ts
+import { createI18n } from '@lhy-meta-server/meta-i18n'
+import { withI18n } from '@lhy-meta-server/meta-i18n/http'
+
+const i18n = createI18n(options)
+await i18n.init()
+
+Bun.serve({
+  port: 3000,
+  fetch: withI18n(i18n, (request, { lng, t }) => {
+    return Response.json({
+      language: lng,
+      message: t('welcome', {
+        user: { profile: { name: 'Tom' } },
+      }),
+    })
+  }),
+})
+```
+
+`withI18n()` 会执行以下操作：
+
+1. 从请求中检测语言。
+2. 按需加载目标语言资源。
+3. 在请求级语言作用域中调用处理函数。
+4. 默认向响应添加 `Content-Language`。
+5. 根据启用的检测来源合并 `Vary`，防止 CDN 或反向代理混用不同语言响应。
+
+Cookie、语言请求头和 `Accept-Language` 会加入 `Vary`；查询参数已属于 URL 缓存键，无需加入。使用自定义检测器时默认写入 `Vary: *`。如应用已自行构造精确缓存键，可以设置 `setVary: false` 后自行管理响应头。
+
+请求处理函数内直接调用 `i18n.t()`，也会读取当前请求语言：
+
+```ts
+const handler = withI18n(i18n, async () => {
+  await loadData()
+  return new Response(i18n.t('welcome'))
+})
+```
+
+### 框架上下文
+
+```ts
+import { createRequestContext } from '@lhy-meta-server/meta-i18n/http'
+
+const context = createRequestContext(i18n, request)
+
+context.lng
+context.t('welcome')
+```
+
+Elysia 示例：
+
+```ts
+new Elysia()
+  .derive(({ request }) => createRequestContext(i18n, request))
+  .get('/', ({ t }) => t('welcome'))
+```
+
+`createRequestContext()` 只检测和绑定语言，不会加载资源。使用异步资源时，应提前预加载，或者先调用 `loadLanguages(context.lng)`。
+
+### 语言检测
+
+默认检测顺序：
+
+1. 查询参数 `language` 或 `lng`
+2. Cookie `language` 或 `lng`
+3. 请求头 `x-language`
+4. `Accept-Language`
+
+查询参数名和 Cookie 名不区分大小写，因此 `?LANGUAGE=zh-CN`、`?Lng=zh-CN`、`Language=zh-CN` Cookie 都可以识别。若同一来源同时存在两个关键字，按请求中出现的先后顺序取第一个非空值。
+
+```ts
+withI18n(i18n, handler, {
+  order: ['query', 'cookie', 'header', 'accept-language'],
+  languageKeys: ['locale', 'lang'],
+  headerName: 'x-language',
+  setContentLanguage: true,
+})
+```
+
+`languageKeys` 同时作用于查询参数和 Cookie，并且始终不区分大小写。传入空数组可以关闭这两种来源的内置关键字读取。
+
+支持自定义检测器，可从会话、JWT、数据库映射或其他位置读取语言：
+
+```ts
+withI18n(i18n, handler, {
+  order: [
+    (request) => {
+      const token = request.headers.get('authorization')
+      return token ? readLanguageFromToken(token) : undefined
+    },
+    'query',
+    'cookie',
+    'accept-language',
+  ],
+})
+```
+
+检测器可返回单个语言、按优先级排列的语言数组或 `undefined`。
+
+单独创建检测函数：
+
+```ts
+import {
+  createLanguageDetector,
+  parseAcceptLanguage,
+} from '@lhy-meta-server/meta-i18n/http'
+
+const detect = createLanguageDetector(i18n, {
+  order: ['accept-language'],
+})
+
+const lng = detect(request)
+
+parseAcceptLanguage('zh-CN,zh;q=0.9,en;q=0.8')
+// ['zh-CN', 'zh', 'en']
+```
+
+## 插件
+
+插件可注册格式化器、订阅事件、异步初始化和后处理翻译结果：
+
+```ts
+import type { I18nPlugin } from '@lhy-meta-server/meta-i18n'
+
+const debugPlugin: I18nPlugin = {
+  name: 'debug',
+
+  setup(i18n) {
+    i18n.addFormatter('debug', (value) => `[${String(value)}]`)
+    i18n.on('missingKey', ({ namespace, key }) => {
+      console.warn(`Missing translation: ${namespace}:${key}`)
+    })
+  },
+
+  async init(i18n) {
+    await preparePlugin()
+  },
+
+  postProcess(value, context) {
+    return context.missing ? `⚠ ${value}` : value
+  },
+}
+```
+
+初始化时注册：
+
+```ts
+const i18n = createI18n({
+  plugins: [debugPlugin],
+})
+```
+
+运行时注册：
+
+```ts
+i18n.use(debugPlugin)
+```
+
+同名插件只注册一次。带 `init` 钩子的插件必须在 `i18n.init()` 前注册；实例初始化完成后只能注册不需要初始化的插件，否则会抛出 `INVALID_OPTION`。钩子执行顺序：
+
+| 钩子 | 时机 |
+| --- | --- |
+| `setup(i18n)` | 调用 `use()` 时同步执行 |
+| `init(i18n)` | `init()` 加载资源前按注册顺序等待执行 |
+| `postProcess(value, context)` | 每次翻译完成后按注册顺序执行 |
+
+## 事件
+
+```ts
+const unsubscribe = i18n.on('languageChanged', (lng) => {
+  console.log(`Language changed to ${lng}`)
+})
+
+unsubscribe()
+```
+
+一次性监听：
+
+```ts
+i18n.once('initialized', (options) => {
+  console.log(options)
+})
+```
+
+移除监听器：
+
+```ts
+i18n.off('languageChanged', listener)
+i18n.off('languageChanged')
+```
+
+| 事件 | 回调参数 | 触发时机 |
+| --- | --- | --- |
+| `initialized` | `options` | 初始化完成 |
+| `languageChanged` | `lng` | 实例默认语言发生变化 |
+| `loaded` | `{ [lng]: ns[] }` | 一批资源加载成功 |
+| `failedLoading` | `lng, ns, error` | 资源加载失败 |
+| `added` | `lng, ns` | 添加资源 |
+| `removed` | `lng, ns` | 移除资源 |
+| `missingKey` | `info` | 翻译键缺失 |
+
+事件监听器抛出的异常不会中断其他监听器和翻译流程。
+
+## 缺失键处理
+
+```ts
+const i18n = createI18n({
+  missingKeyHandler(info) {
+    reporter.add({
+      language: info.languages[0],
+      namespace: info.namespace,
+      key: info.key,
+      defaultValue: info.defaultValue,
+    })
+  },
+
+  parseMissingKeyHandler(key, defaultValue) {
+    return defaultValue ?? `[[${key}]]`
+  },
+})
+```
+
+`missingKeyHandler` 用于记录或上报缺失键；`parseMissingKeyHandler` 用于生成最终返回值。默认行为是返回 `defaultValue`，未提供时返回键。
+
+空字符串默认被视为有效翻译。若希望空字符串继续执行回退查找：
+
+```ts
+createI18n({ returnEmptyString: false })
+```
+## 克隆实例
+
+```ts
+const cloned = i18n.cloneInstance({
+  lng: 'en',
+})
+
+await cloned.init()
+```
+
+克隆实例复制当前资源和插件，并允许覆盖配置。克隆后的默认语言、事件监听和初始化状态相互独立。
+
+## 配置
+
+### I18nOptions
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `lng` | `string` | 第一个回退语言或 `'en'` | 实例初始语言 |
+| `fallbackLng` | `string \| string[] \| Record<string, string[]> \| function \| false` | `'en'` | 回退语言配置 |
+| `supportedLngs` | `string[]` | 未限制 | 允许使用的语言 |
+| `loadCurrentOnly` | `boolean` | `false` | 只使用完整语言标识，不追加主语言 |
+| `ns` | `string \| string[]` | `[defaultNS]` | 需要加载的命名空间 |
+| `defaultNS` | `string` | `'translation'` | 默认命名空间 |
+| `fallbackNS` | `string \| string[]` | `[]` | 当前命名空间缺失时尝试的命名空间 |
+| `resources` | `Resources` | `undefined` | 内联资源 |
+| `backend` | `ResourceBackend` | `undefined` | 异步资源后端 |
+| `preload` | `string[]` | `[]` | 初始化时额外加载的语言 |
+| `loadFailureMode` | `'throw' \| 'fallback'` | `'throw'` | 加载失败时抛错，或触发事件后继续回退 |
+| `keySeparator` | `string \| false` | `'.'` | 翻译键层级分隔符 |
+| `nsSeparator` | `string \| false` | `':'` | 命名空间分隔符 |
+| `pluralSeparator` | `string` | `'_'` | 复数后缀分隔符 |
+| `contextSeparator` | `string` | `'_'` | 上下文后缀分隔符 |
+| `returnEmptyString` | `boolean` | `true` | 是否将空字符串视为有效翻译 |
+| `interpolation` | `InterpolationOptions` | 见下表 | 插值配置 |
+| `formatters` | `Record<string, Formatter>` | `{}` | 自定义格式化器 |
+| `missingKeyHandler` | `(info) => void` | `undefined` | 缺失键通知函数 |
+| `parseMissingKeyHandler` | `(key, defaultValue) => string` | 默认值或键 | 缺失键返回值转换 |
+| `plugins` | `I18nPlugin[]` | `[]` | 初始化时注册的插件 |
+
+### InterpolationOptions
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `prefix` | `string` | `'{{'` | 插值起始标记 |
+| `suffix` | `string` | `'}}'` | 插值结束标记 |
+| `escapeValue` | `boolean` | `true` | 是否转义插值结果 |
+| `escape` | `(value) => string` | HTML 转义 | 自定义转义函数 |
+| `formatSeparator` | `string` | `','` | 插值路径和格式化器之间的分隔符 |
+| `missingValue` | `'empty' \| 'keep' \| function` | `'empty'` | 插值变量缺失时的行为 |
+| `nesting` | `boolean` | `true` | 是否启用 `$t()` 嵌套翻译 |
+| `maxNestingDepth` | `number` | `10` | 最大嵌套深度 |
+
+### TranslateOptions
+
+| 选项 | 类型 | 说明 |
+| --- | --- | --- |
+| `lng` | `string` | 覆盖本次翻译语言 |
+| `ns` | `string \| string[]` | 覆盖本次翻译命名空间 |
+| `defaultValue` | `string` | 键缺失时使用的文本，支持插值 |
+| `count` | `number` | 复数计数，同时作为 `{{count}}` 变量 |
+| `ordinal` | `boolean` | 使用序数复数规则 |
+| `context` | `string` | 上下文后缀 |
+| `values` | `Record<string, unknown>` | 显式插值变量，优先于顶层变量 |
+| `formatParams` | `Record<string, Record<string, unknown>>` | 按插值路径覆盖格式化参数 |
+| `interpolation.escapeValue` | `boolean` | 覆盖本次转义设置 |
+| `interpolation.missingValue` | `'empty' \| 'keep' \| function` | 覆盖本次缺失插值策略 |
+| 其他字段 | `unknown` | 作为插值变量 |
+
+### FsBackendOptions
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `baseDir` | `string` | 必填 | 资源根目录 |
+| `pathTemplate` | `string` | `'{{lng}}/{{ns}}.json'` | 相对文件路径模板 |
+| `parse` | `(content, filePath) => unknown` | `JSON.parse` | 文件内容解析函数 |
+
+### LanguageDetectorOptions
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `order` | `(DetectionSource \| CustomDetector)[]` | `['query', 'cookie', 'header', 'accept-language']` | 检测顺序，可插入自定义检测函数 |
+| `languageKeys` | `string[]` | `['language', 'lng']` | 查询参数与 Cookie 共用的关键字，不区分大小写 |
+| `headerName` | `string` | `'x-language'` | 自定义语言请求头 |
+
+`languageKeys` 可以改为任意关键字或设为空数组。需要从会话、JWT 等位置读取语言时，在 `order` 中传入 `CustomDetector`。
+
+`withI18n()` 还支持 `setContentLanguage` 和 `setVary`，两者默认均为 `true`。
+
+## API
+
+### 实例属性
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `language` | `string` | 当前作用域语言或实例默认语言 |
+| `languages` | `readonly string[]` | 当前语言的完整查找链 |
+| `isInitialized` | `boolean` | 是否完成初始化 |
+| `options` | `Readonly<I18nOptions>` | 实例配置 |
+| `t` | `TFunction` | 已绑定实例的翻译函数 |
+| `store` | `ResourceStore` | 资源存储 |
+| `formatters` | `FormatterRegistry` | 格式化器注册表 |
+| `languageUtils` | `LanguageUtils` | 语言处理工具 |
+
+### 实例方法
+
+| 方法 | 返回值 | 说明 |
+| --- | --- | --- |
+| `init()` | `Promise<this>` | 初始化插件并加载资源 |
+| `t(keys, options?)` | `string` | 翻译 |
+| `translate(keys, options?)` | `string` | `t` 的方法形式 |
+| `exists(keys, options?)` | `boolean` | 判断翻译是否存在 |
+| `getFixedT(lng?, ns?, keyPrefix?)` | `TFunction` | 创建固定上下文翻译函数 |
+| `changeLanguage(lng)` | `Promise<TFunction>` | 切换实例默认语言 |
+| `runWithLanguage(lng, operation)` | `Result` | 在请求级语言作用域运行函数 |
+| `resolveLanguage(lng)` | `string` | 规范化并匹配受支持语言 |
+| `loadLanguages(lngs)` | `Promise<void>` | 加载语言资源 |
+| `loadNamespaces(ns)` | `Promise<void>` | 登记并加载命名空间 |
+| `reloadResources(lngs?, ns?)` | `Promise<void>` | 强制重新加载资源 |
+| `addResourceBundle(lng, ns, resources, deep?, overwrite?)` | `this` | 添加资源包 |
+| `addResource(lng, ns, key, value)` | `this` | 添加单个翻译 |
+| `getResourceBundle(lng, ns)` | `ResourceTree \| undefined` | 获取与内部状态隔离的资源快照 |
+| `hasResourceBundle(lng, ns)` | `boolean` | 判断资源包是否存在 |
+| `removeResourceBundle(lng, ns)` | `this` | 删除资源包 |
+| `toJSON()` | `Resources` | 导出资源快照 |
+| `format(value, formatter, options?, lng?)` | `string` | 使用标准 `Intl` 选项直接格式化值 |
+| `addFormatter(name, formatter)` | `void` | 注册格式化器 |
+| `use(plugin)` | `this` | 注册插件 |
+| `on(event, listener)` | `() => void` | 订阅事件 |
+| `once(event, listener)` | `() => void` | 订阅一次性事件 |
+| `off(event, listener?)` | `void` | 取消事件订阅 |
+| `cloneInstance(overrides?)` | `I18n` | 克隆实例 |
+
+## 错误处理
+
+```ts
+import { I18nError } from '@lhy-meta-server/meta-i18n'
+
+try {
+  i18n.t('price', { value: 10 })
+} catch (error) {
+  if (error instanceof I18nError) {
+    console.error(error.code, error.message, error.cause)
+  }
+}
+```
+
+| 错误码 | 说明 |
+| --- | --- |
+| `INVALID_OPTION` | 初始化配置无效 |
+| `INVALID_PATH` | 直接调用 `parsePath()` 或 `getByPath()` 时路径语法无效 |
+| `FORMATTER_NOT_FOUND` | 模板使用了未注册的格式化器 |
+| `FORMAT_FAILED` | 格式化值或 `Intl` 选项无效 |
+| `INVALID_RESOURCE_IDENTIFIER` | 语言或命名空间含非法字符 |
+| `LOAD_FAILED` | 资源后端读取失败 |
+
+资源加载错误始终触发 `failedLoading`。默认 `loadFailureMode: 'throw'` 还会使 `init()`、资源加载方法和 HTTP 包装器拒绝当前操作；初始化失败后可以再次调用 `init()` 重试：
+
+```ts
+i18n.on('failedLoading', (lng, ns, error) => {
+  console.error(`Failed to load ${lng}/${ns}`, error)
+})
+```
+
+如果业务明确允许资源加载失败后继续使用已有资源或键名，可以配置：
+
+```ts
+const i18n = createI18n({
+  loadFailureMode: 'fallback',
+})
+```