I18n API

Yumeri 提供了一个轻量级的国际化（i18n）文本管理，用于注册、获取与替换多语言文本点，支持用户语言优先级和系统回退语言双重机制。

3.0 之后，I18n 不仅能注册单一键值，还支持对象扁平化、ctx.i18n() 自动注册，以及和 Schema.key() 的联动。

---

构造参数

constructor(fallback?: string[])

• fallback: string[]
  系统默认回退语言列表，按优先级从高到低排列。
  当用户语言中无匹配时，会依次使用此列表查找。
  默认值：['en']

---

注册方式

register(key: string, lang: Record<string, string>): void

注册一个文本点及其多语言翻译：

core.i18n.register('app.title', {
  zh: '示例应用',
  en: 'Sample App',
})

register(map: Record<string, any>): void

以对象方式批量注册，并自动展开嵌套对象：

ctx.i18n({
  app: {
    title: { zh: '示例应用', en: 'Sample App' },
    subtitle: { zh: '欢迎', en: 'Welcome' },
  },
})

这会被自动转换为：

{
  'app.title': { zh: '示例应用', en: 'Sample App' },
  'app.subtitle': { zh: '欢迎', en: 'Welcome' },
}

语言映射不会被限制为固定的 zh / en 字段。只要对象的值全部是字符串，就会被视为语言表，因此也可以使用 ja、ko、fr 或项目自定义的语言标识：

ctx.i18n({
  greeting: {
    'zh-CN': '你好',
    en: 'Hello',
    ja: 'こんにちは',
  },
})

嵌套对象会继续展开为点号路径；只有叶子节点的语言映射会被注册为文本点。

ctx.i18n() 是实际最常用的注册入口，因为它会把注册结果挂到当前插件的上下文生命周期中，并在插件卸载时自动清理。

---

获取与回退

get(key: string, langs?: string[]): string

根据语言优先级列表获取对应翻译文本：

const text = core.i18n.get('app.title', ['zh', 'en'])
// => '示例应用'

行为：

1. 优先按 langs 顺序匹配。
2. 若未匹配到，则使用系统回退语言列表。
3. 若仍无结果，则返回 key 本身。

---

setFallback(fallback: string[]): void

设置系统回退语言列表：

core.i18n.setFallback(['zh', 'en'])

---

replaceAll(input: string, langs?: string[]): string

批量替换字符串中的文本点：

const value = core.i18n.replaceAll('Hello {{app.title}}', ['en'])
// => 'Hello Sample App'

---

查验与删除

isRegistered(key: string): boolean

判断某个文本点是否已注册。

delete(key: string): void

删除某个文本点的所有语言内容。

all(): Record<string, Record<string, string>>

返回当前所有已注册的翻译数据：

const all = core.i18n.all()

---

与 Schema 配置联动

在 3.0 中，配置字段说明文字可以绑定到 i18n key：

export const config = Schema.object({
  port: Schema.number('监听端口')
    .key('demo.config.port')
    .default(14510),
})

当请求语言是 ['zh', 'en'] 时，Yumeri 会优先按语言取对应文案；如果没有命中，则回退到原始 description。这让配置面板、控制台文本和页面展示保持一致。

---

典型用法

ctx.i18n({
  plugin: {
    name: { zh: '插件示例', en: 'Plugin Example' },
    tip: { zh: '欢迎使用', en: 'Welcome' },
  },
})

const text = ctx.getCore().i18n.get('plugin.name', ['zh', 'en'])

---

与 session / request 语言结合

实际使用中，语言通常来自 session 或 request 的 accept-language 解析结果，形如：

['zh-cn', 'zh', 'en']

Yumeri 会按这个顺序寻找匹配项，若未命中，则再回退到系统默认语言列表。这样能兼顾用户偏好与框架默认文案。