@vobs/i18n 0.3.0 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 vobsjs
+Copyright (c) 2026 vobs contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -0,0 +1,58 @@
+# @vobs/i18n
+
+Reactive i18n context with nested message lookup, a locale fallback chain, and Intl-based formatting.
+
+## Install
+
+```bash
+npm install @vobs/i18n
+```
+
+## Quick start
+
+```ts
+import { createI18n } from '@vobs/i18n'
+
+const i18n = createI18n({
+  defaultLocale: 'zh-CN',
+  fallbackLocale: 'en-US',
+  messages: {
+    'zh-CN': { common: { hello: '你好，{name}' } },
+    'en-US': { common: { cancel: 'Cancel' } }
+  }
+})
+
+i18n.t('common.hello', { name: 'Ada' }) // '你好，Ada'
+i18n.t('common.cancel') // 'Cancel' — resolved through the fallback chain
+i18n.setLocale('en-US')
+i18n.formatDate(new Date(), 'short')
+```
+
+## API
+
+| Signature | Description |
+| --- | --- |
+| `createI18n(options: I18nOptions): I18nContext` | Creates an i18n context; `defaultLocale` is required. |
+| `i18n.locale: Signal<Locale>` | Reactive current locale. |
+| `i18n.messages: Signal<LocaleMessages>` | Reactive message catalogs per locale. |
+| `i18n.t(key: string, params?): string` | Translates a dotted key with `{param}` interpolation; returns the key itself when missing. |
+| `i18n.setLocale(locale: Locale): void` | Switches the locale. |
+| `i18n.setMessages(locale: Locale, messages: Messages): void` | Deep-merges messages into an existing catalog. |
+| `i18n.loadLocale(locale: Locale, loader?): Promise<void>` | Loads a catalog lazily; concurrent calls for one locale share a single request. |
+| `i18n.isLocaleLoaded(locale: Locale): boolean` | Whether the catalog is already loaded. |
+| `i18n.formatDate(value, presetOrOptions?, options?): string` | Presets `short`, `medium`, `long`, `full`, `custom`; honors `options.timeZone`. |
+| `i18n.formatNumber(value, presetOrOptions?): string` | Presets `decimal` and `percent`, or `Intl.NumberFormatOptions`. |
+| `i18n.formatCurrency(value: number, currency: string, options?): string` | Currency formatting via `Intl`. |
+| `i18n.formatRelativeTime(value, now?): string` | Relative time via `Intl.RelativeTimeFormat`. |
+| `i18n.registerFormatter(name, formatter): () => void` | Registers a custom `{value, name, argument}` placeholder formatter. |
+| `i18n.dehydrate()` / `i18n.hydrate(snapshot)` | Serializes and restores locale state for SSR. |
+| `i18n.dispose(): void` | Disposes internal signals. |
+| `i18nPlugin(options?): VobsPlugin` | Provides the context through `I18N_KEY`. |
+| `useI18n(): I18nContext` | Injects the i18n context inside components. |
+| `I18nBoundary(props?: I18nBoundaryProps): VobsNode` | Scopes children to a local locale while inheriting the parent catalogs. |
+
+Key lookup walks a fallback chain: the current locale, its language-only part (`zh` from `zh-CN`), then `fallbackLocale` and its language part. Built-in placeholder formatters are `date`, `number`, `currency`, and `relativeTime`.
+
+## Types
+
+`Locale`, `Messages`, `MessageValue`, `LocaleMessages`, `I18nOptions`, `I18nContext`, `I18nPluginOptions`, `I18nBoundaryProps`, `I18nLocaleLoader`, `I18nFormatter`, `I18nDehydratedState`, `DatePreset`, `NumberPreset`

package/package.json

@@ -1,41 +1,20 @@
 {
-  "name": "@vobs/i18n",
-  "version": "0.3.0",
-  "description": "Instance-based translation and Intl formatting primitives for vobs.",
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
   "license": "MIT",
-  "author": "vobsjs",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vobsjs/vobs.git",
-    "directory": "packages/features/i18n"
-  },
-  "bugs": {
-    "url": "https://github.com/vobsjs/vobs/issues"
-  },
-  "homepage": "https://github.com/vobsjs/vobs#readme",
-  "dependencies": {
-    "@vobs/reactivity": "0.3.0",
-    "@vobs/runtime-core": "0.3.0"
-  },
   "files": [
-    "dist"
+    "src",
+    "README.md",
+    "LICENSE"
   ],
+  "name": "@vobs/i18n",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
+    ".": "./src/index.ts"
   },
-  "types": "./dist/index.d.ts",
-  "module": "./dist/index.js",
-  "main": "./dist/index.js",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=22.12.0"
+  "dependencies": {
+    "@vobs/reactivity": "1.0.0",
+    "@vobs/vobs": "1.0.0"
   }
 }

package/src/index.test.ts

@@ -0,0 +1,162 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import {
+  createComponent,
+  createDOMRenderer,
+  createElement,
+  createText,
+  createVobs,
+  bindText,
+  insertBefore,
+  setRenderer
+} from '@vobs/vobs'
+import {
+  createI18n,
+  I18nBoundary,
+  I18N_KEY,
+  i18nPlugin,
+  useI18n
+} from './index'
+
+describe('@vobs/i18n', () => {
+  beforeEach(() => {
+    setRenderer(createDOMRenderer())
+  })
+
+  it('按嵌套 key 查找翻译，支持 fallback、缺失 key 和参数插值', () => {
+    const i18n = createI18n({
+      defaultLocale: 'zh-CN',
+      fallbackLocale: 'en-US',
+      messages: {
+        'zh-CN': { common: { hello: '你好，{name}' } },
+        'en-US': { common: { cancel: 'Cancel' } }
+      }
+    })
+
+    expect(i18n.t('common.hello', { name: 'Ada' })).toBe('你好，Ada')
+    expect(i18n.t('common.cancel')).toBe('Cancel')
+    expect(i18n.t('common.missing')).toBe('common.missing')
+    i18n.dispose()
+  })
+
+  it('locale 变化会驱动使用 t 的节点更新', () => {
+    const i18n = createI18n({
+      defaultLocale: 'zh-CN',
+      messages: {
+        'zh-CN': { title: '中文' },
+        'en-US': { title: 'English' }
+      }
+    })
+    const container = document.createElement('div')
+    const app = createVobs({
+      render: () => {
+        const text = createText('')
+        bindText(text, () => i18n.t('title'))
+        return text
+      }
+    })
+
+    app.mount(container)
+    expect(container.textContent).toBe('中文')
+    i18n.setLocale('en-US')
+    app.update()
+    expect(container.textContent).toBe('English')
+    app.destroy()
+    i18n.dispose()
+  })
+
+  it('提供日期、数字、货币和相对时间格式化', () => {
+    const i18n = createI18n({ defaultLocale: 'en-US', timeZone: 'UTC' })
+
+    expect(i18n.formatDate(new Date('2024-01-15T00:00:00Z'), 'short')).toContain('2024')
+    expect(i18n.formatNumber(0.85, 'percent')).toContain('85')
+    expect(i18n.formatCurrency(100, 'USD')).toContain('$')
+    expect(i18n.formatRelativeTime(Date.now() - 60 * 60 * 1000)).toContain('hour')
+    i18n.dispose()
+  })
+
+  it('支持自定义 formatter 和运行时追加翻译', () => {
+    const i18n = createI18n({
+      defaultLocale: 'en-US',
+      messages: { 'en-US': { greeting: 'Hello {name, uppercase}' } }
+    })
+    const unregister = i18n.registerFormatter('uppercase', value => String(value).toUpperCase())
+
+    expect(i18n.t('greeting', { name: 'Ada' })).toBe('Hello ADA')
+    i18n.setMessages('en-US', { added: 'Added' })
+    expect(i18n.t('added')).toBe('Added')
+    unregister()
+    expect(i18n.t('greeting', { name: 'Ada' })).toBe('Hello Ada')
+    i18n.dispose()
+  })
+
+  it('按需加载语言资源时去重请求并深度合并 namespace', async () => {
+    let calls = 0
+    const i18n = createI18n({
+      defaultLocale: 'en-US',
+      messages: { 'en-US': { common: { ok: 'OK' } } },
+      localeLoaders: {
+        'zh-CN': async () => {
+          calls++
+          return { common: { cancel: '取消' }, page: { title: '首页' } }
+        }
+      }
+    })
+    await Promise.all([i18n.loadLocale('zh-CN'), i18n.loadLocale('zh-CN')])
+    expect(calls).toBe(1)
+    expect(i18n.isLocaleLoaded('zh-CN')).toBe(true)
+    i18n.setLocale('zh-CN')
+    expect(i18n.t('common.cancel')).toBe('取消')
+    expect(i18n.t('page.title')).toBe('首页')
+    i18n.dispose()
+  })
+
+  it('拒绝没有 loader 或格式错误的语言资源', async () => {
+    const i18n = createI18n({ defaultLocale: 'en-US' })
+    await expect(i18n.loadLocale('zh-CN')).rejects.toThrow('没有可用的 loader')
+    await expect(i18n.loadLocale('zh-CN', async () => ({ broken: [] as unknown as string }))).rejects.toThrow('值无效')
+    i18n.dispose()
+  })
+
+  it('i18nPlugin 注入共享上下文，I18nBoundary 的惰性 children 使用局部语言', () => {
+    const i18n = createI18n({
+      defaultLocale: 'zh-CN',
+      messages: {
+        'zh-CN': { title: '中文' },
+        'en-US': { title: 'English' }
+      }
+    })
+    function Child() {
+      return createText(useI18n().t('title'))
+    }
+    const container = document.createElement('div')
+    const app = createVobs({
+      render: () => {
+        const root = createElement('div')
+        const global = createText(useI18n().t('title'))
+        root.append(global)
+        const local = createComponent(I18nBoundary, {
+          locale: 'en-US',
+          children: () => createComponent(Child, {})
+        })
+        insertBefore(root, local, null)
+        return root
+      },
+      plugins: [i18nPlugin({ i18n })]
+    })
+
+    app.mount(container)
+    expect(container.textContent).toBe('中文English')
+    expect(container.querySelector('div')).toBeTruthy()
+    app.destroy()
+    i18n.dispose()
+  })
+
+  it('没有安装插件时，useI18n 给出明确错误', () => {
+    const app = createVobs({ render: () => {
+      void useI18n()
+      return createText('')
+    }})
+    expect(() => app.mount(document.createElement('div'))).toThrow('i18nPlugin')
+    expect(I18N_KEY).toBeDefined()
+  })
+})

package/src/index.ts

@@ -0,0 +1,460 @@
+import { getCurrentOwner, onDispose, state, type Signal } from '@vobs/reactivity'
+import {
+  createFragment,
+  createInjectionKey,
+  inject,
+  insertBefore,
+  provide,
+  type InjectionKey,
+  type VobsNode,
+  type VobsPlugin
+} from '@vobs/vobs'
+
+export type Locale = string
+export type MessageValue = string | Messages
+
+export interface Messages {
+  readonly [key: string]: MessageValue
+}
+
+export type LocaleMessages = Readonly<Record<Locale, Messages>>
+export type DatePreset = 'short' | 'medium' | 'long' | 'full' | 'custom'
+export type NumberPreset = 'decimal' | 'percent'
+export type I18nLocaleLoader = () => Promise<Messages>
+
+export interface I18nDehydratedState {
+  readonly version: 1
+  readonly locale: Locale
+  readonly messages: LocaleMessages
+}
+
+export type I18nFormatter = (
+  value: unknown,
+  locale: Locale,
+  argument?: string
+) => string
+
+export interface I18nOptions {
+  readonly defaultLocale: Locale
+  readonly messages?: LocaleMessages
+  readonly localeLoaders?: Readonly<Record<Locale, I18nLocaleLoader>>
+  readonly fallbackLocale?: Locale
+  readonly timeZone?: string
+  readonly formatters?: Record<string, I18nFormatter>
+}
+
+export interface I18nContext {
+  readonly locale: Signal<Locale>
+  readonly messages: Signal<LocaleMessages>
+  readonly fallbackLocale: Locale | undefined
+  readonly timeZone: string | undefined
+  dehydrate(): I18nDehydratedState
+  hydrate(snapshot: unknown): void
+  setLocale(locale: Locale): void
+  setMessages(locale: Locale, messages: Messages): void
+  loadLocale(locale: Locale, loader?: I18nLocaleLoader): Promise<void>
+  isLocaleLoaded(locale: Locale): boolean
+  t(key: string, params?: Record<string, unknown>): string
+  formatDate(
+    value: Date | number,
+    presetOrOptions?: DatePreset | Intl.DateTimeFormatOptions,
+    options?: Intl.DateTimeFormatOptions
+  ): string
+  formatNumber(value: number, presetOrOptions?: NumberPreset | Intl.NumberFormatOptions): string
+  formatCurrency(
+    value: number,
+    currency: string,
+    options?: Omit<Intl.NumberFormatOptions, 'currency' | 'style'>
+  ): string
+  formatRelativeTime(value: Date | number, now?: Date | number): string
+  registerFormatter(name: string, formatter: I18nFormatter): () => void
+  dispose(): void
+}
+
+export const I18N_KEY: InjectionKey<I18nContext> = createInjectionKey<I18nContext>('vobs.i18n')
+
+export interface I18nPluginOptions extends Omit<I18nOptions, 'defaultLocale'> {
+  readonly defaultLocale?: Locale
+  readonly i18n?: I18nContext
+}
+
+export interface I18nBoundaryProps {
+  readonly locale?: Locale
+  readonly children?: VobsNode | (() => VobsNode | null | undefined)
+}
+
+const DATE_PRESETS: Record<Exclude<DatePreset, 'custom'>, Intl.DateTimeFormatOptions> = {
+  short: {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit'
+  },
+  medium: {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric'
+  },
+  long: {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    weekday: 'long'
+  },
+  full: {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    weekday: 'long',
+    hour: '2-digit',
+    minute: '2-digit'
+  }
+}
+
+export function createI18n(options: I18nOptions): I18nContext {
+  const defaultLocale = validateLocale(options.defaultLocale)
+  const fallbackLocale = options.fallbackLocale === undefined
+    ? defaultLocale
+    : validateLocale(options.fallbackLocale)
+  const initialMessages = validateLocaleMessages(options.messages ?? {})
+  const locale = state(defaultLocale)
+  const messages = state<LocaleMessages>({ ...initialMessages })
+  const formatters = new Map<string, I18nFormatter>(Object.entries(options.formatters ?? {}))
+  const loadedLocales = new Set(Object.keys(initialMessages))
+  const pendingLoads = new Map<string, Promise<void>>()
+  let disposed = false
+
+  const context: I18nContext = {
+    locale,
+    messages,
+    fallbackLocale,
+    timeZone: options.timeZone,
+
+    dehydrate(): I18nDehydratedState {
+      ensureActive()
+      return { version: 1, locale: locale.value, messages: messages.value }
+    },
+
+    hydrate(snapshot: unknown): void {
+      ensureActive()
+      const restored = parseDehydratedState(snapshot)
+      locale.value = restored.locale
+      messages.value = restored.messages
+      loadedLocales.clear()
+      for (const loadedLocale of Object.keys(restored.messages)) loadedLocales.add(loadedLocale)
+    },
+
+    setLocale(nextLocale: Locale): void {
+      ensureActive()
+      locale.value = validateLocale(nextLocale)
+    },
+
+    setMessages(nextLocale: Locale, nextMessages: Messages): void {
+      ensureActive()
+      const normalizedLocale = validateLocale(nextLocale)
+      const normalizedMessages = validateMessages(nextMessages)
+      messages.value = {
+        ...messages.value,
+        [normalizedLocale]: mergeMessages(messages.value[normalizedLocale], normalizedMessages)
+      }
+      loadedLocales.add(normalizedLocale)
+    },
+
+    loadLocale(nextLocale: Locale, loader?: I18nLocaleLoader): Promise<void> {
+      ensureActive()
+      const normalizedLocale = validateLocale(nextLocale)
+      if (loadedLocales.has(normalizedLocale)) return Promise.resolve()
+      const pending = pendingLoads.get(normalizedLocale)
+      if (pending) return pending
+      const source = loader ?? options.localeLoaders?.[normalizedLocale]
+      if (!source) return Promise.reject(new Error(`Vobs I18n: locale ${normalizedLocale} 没有可用的 loader`))
+      const task = Promise.resolve()
+        .then(() => source())
+        .then(nextMessages => {
+          context.setMessages(normalizedLocale, nextMessages)
+        })
+        .finally(() => {
+          pendingLoads.delete(normalizedLocale)
+        })
+      pendingLoads.set(normalizedLocale, task)
+      return task
+    },
+
+    isLocaleLoaded(nextLocale: Locale): boolean {
+      ensureActive()
+      return loadedLocales.has(validateLocale(nextLocale))
+    },
+
+    t(key: string, params?: Record<string, unknown>): string {
+      ensureActive()
+      if (!key) return ''
+      const allMessages = messages.value
+      const template = findMessage(allMessages, locale.value, fallbackLocale, key)
+      if (template === undefined) return key
+      return interpolate(template, params, context, formatters)
+    },
+
+    formatDate(value, presetOrOptions, dateOptions): string {
+      ensureActive()
+      const date = toDate(value)
+      if (!date) return ''
+      const resolvedOptions = resolveDateOptions(presetOrOptions, dateOptions)
+      return new Intl.DateTimeFormat(locale.value, withTimeZone(resolvedOptions, options.timeZone)).format(date)
+    },
+
+    formatNumber(value, presetOrOptions): string {
+      ensureActive()
+      if (!Number.isFinite(value)) return ''
+      const numberOptions = typeof presetOrOptions === 'string'
+        ? presetOrOptions === 'percent' ? { style: 'percent' as const } : {}
+        : presetOrOptions
+      return new Intl.NumberFormat(locale.value, numberOptions).format(value)
+    },
+
+    formatCurrency(value, currency, currencyOptions): string {
+      ensureActive()
+      if (!Number.isFinite(value)) return ''
+      if (!currency) throw new Error('Vobs I18n: currency 不能为空')
+      return new Intl.NumberFormat(locale.value, {
+        ...currencyOptions,
+        style: 'currency',
+        currency
+      }).format(value)
+    },
+
+    formatRelativeTime(value, now = Date.now()): string {
+      ensureActive()
+      const target = toDate(value)?.getTime()
+      const current = toDate(now)?.getTime()
+      if (target === undefined || current === undefined) return ''
+      const difference = current - target
+      const units = [
+        ['year', 365 * 24 * 60 * 60 * 1000],
+        ['month', 30 * 24 * 60 * 60 * 1000],
+        ['day', 24 * 60 * 60 * 1000],
+        ['hour', 60 * 60 * 1000],
+        ['minute', 60 * 1000],
+        ['second', 1000]
+      ] as const
+      for (const [unit, milliseconds] of units) {
+        const amount = Math.round(difference / milliseconds)
+        if (Math.abs(amount) >= 1) {
+          return new Intl.RelativeTimeFormat(locale.value, { numeric: 'auto' })
+            .format(-amount, unit)
+        }
+      }
+      return new Intl.RelativeTimeFormat(locale.value, { numeric: 'auto' }).format(0, 'second')
+    },
+
+    registerFormatter(name: string, formatter: I18nFormatter): () => void {
+      ensureActive()
+      if (!name) throw new Error('Vobs I18n: formatter 名称不能为空')
+      const previous = formatters.get(name)
+      formatters.set(name, formatter)
+      return () => {
+        if (previous) formatters.set(name, previous)
+        else formatters.delete(name)
+      }
+    },
+
+    dispose(): void {
+      if (disposed) return
+      disposed = true
+      locale.dispose()
+      messages.dispose()
+      formatters.clear()
+      pendingLoads.clear()
+    }
+  }
+
+  if (getCurrentOwner()) onDispose(context.dispose)
+  return context
+
+  function ensureActive(): void {
+    if (disposed) throw new Error('Vobs I18n: 已销毁的上下文不能继续使用')
+  }
+}
+
+function parseDehydratedState(snapshot: unknown): I18nDehydratedState {
+  let value: unknown = snapshot
+  if (typeof snapshot === 'string') {
+    try {
+      value = JSON.parse(snapshot)
+    } catch {
+      throw new Error('Vobs I18n: 初始状态不是有效 JSON')
+    }
+  }
+  if (!value || typeof value !== 'object') throw new Error('Vobs I18n: 初始状态格式无效')
+  const candidate = value as Partial<I18nDehydratedState>
+  if (candidate.version !== 1 || typeof candidate.locale !== 'string'
+    || !candidate.messages || typeof candidate.messages !== 'object') {
+    throw new Error('Vobs I18n: 初始状态版本或字段无效')
+  }
+  return {
+    version: 1,
+    locale: validateLocale(candidate.locale),
+      messages: validateLocaleMessages(candidate.messages)
+  }
+}
+
+export function i18nPlugin(options: I18nPluginOptions = {}): VobsPlugin {
+  return {
+    name: '@vobs/i18n',
+    version: '0.1.0',
+    install(context) {
+      const ownedI18n = options.i18n ? undefined : createI18n({
+        defaultLocale: options.defaultLocale ?? 'en-US',
+        messages: options.messages,
+        localeLoaders: options.localeLoaders,
+        fallbackLocale: options.fallbackLocale,
+        timeZone: options.timeZone,
+        formatters: options.formatters
+      })
+      const i18n = options.i18n ?? ownedI18n!
+      context.provide(I18N_KEY, i18n)
+      return () => ownedI18n?.dispose()
+    }
+  }
+}
+
+export function useI18n(): I18nContext {
+  const i18n = inject(I18N_KEY)
+  if (!i18n) throw new Error('Vobs I18n: 找不到上下文，请安装 i18nPlugin')
+  return i18n
+}
+
+export function I18nBoundary(props: I18nBoundaryProps = {}): VobsNode {
+  const parent = useI18n()
+  const local = createI18n({
+    defaultLocale: props.locale ?? parent.locale.value,
+    messages: parent.messages.value,
+    fallbackLocale: parent.fallbackLocale,
+    timeZone: parent.timeZone
+  })
+  provide(I18N_KEY, local)
+
+  return createFragment((parentNode, anchor) => {
+    const child = typeof props.children === 'function' ? props.children() : props.children
+    if (child) insertBefore(parentNode, child, anchor)
+  })
+}
+
+function findMessage(
+  allMessages: LocaleMessages,
+  locale: Locale,
+  fallbackLocale: Locale | undefined,
+  key: string
+): string | undefined {
+  const locales = unique([
+    locale,
+    locale.split('-')[0],
+    fallbackLocale,
+    fallbackLocale?.split('-')[0]
+  ])
+  for (const candidate of locales) {
+    const message = getMessage(allMessages[candidate], key)
+    if (message !== undefined) return message
+  }
+  return undefined
+}
+
+function getMessage(messages: Messages | undefined, key: string): string | undefined {
+  if (!messages) return undefined
+  const direct = messages[key]
+  if (typeof direct === 'string') return direct
+
+  let current: MessageValue | undefined = messages
+  for (const segment of key.split('.')) {
+    if (!isMessages(current)) return undefined
+    current = current[segment]
+  }
+  return typeof current === 'string' ? current : undefined
+}
+
+function interpolate(
+  template: string,
+  params: Record<string, unknown> | undefined,
+  context: I18nContext,
+  formatters: Map<string, I18nFormatter>
+): string {
+  if (!params) return template
+  return template.replace(/\{([\w.-]+)(?:,\s*([\w-]+)(?:,\s*([^}]+))?)?\}/g,
+    (match, key: string, formatter?: string, argument?: string) => {
+      if (!(key in params)) return match
+      const value = params[key]
+      if (!formatter) return String(value)
+      if (formatter === 'date') return context.formatDate(toDate(value) ?? Number.NaN, argument as DatePreset | undefined)
+      if (formatter === 'number') return context.formatNumber(Number(value))
+      if (formatter === 'currency') return context.formatCurrency(Number(value), argument ?? 'USD')
+      if (formatter === 'relativeTime') return context.formatRelativeTime(toDate(value) ?? Number.NaN)
+      const custom = formatters.get(formatter)
+      return custom ? custom(value, context.locale.value, argument) : String(value)
+    })
+}
+
+function toDate(value: Date | number | unknown): Date | undefined {
+  const date = value instanceof Date ? new Date(value.getTime()) : typeof value === 'number' ? new Date(value) : undefined
+  return date && Number.isFinite(date.getTime()) ? date : undefined
+}
+
+function resolveDateOptions(
+  presetOrOptions: DatePreset | Intl.DateTimeFormatOptions | undefined,
+  options: Intl.DateTimeFormatOptions | undefined
+): Intl.DateTimeFormatOptions {
+  if (presetOrOptions === undefined) return DATE_PRESETS.medium
+  if (typeof presetOrOptions === 'object') return presetOrOptions
+  if (presetOrOptions === 'custom') return options ?? {}
+  return { ...DATE_PRESETS[presetOrOptions], ...options }
+}
+
+function withTimeZone(options: Intl.DateTimeFormatOptions, timeZone: string | undefined): Intl.DateTimeFormatOptions {
+  return timeZone && options.timeZone === undefined ? { ...options, timeZone } : options
+}
+
+function validateLocale(locale: Locale): Locale {
+  if (typeof locale !== 'string' || !locale.trim()) throw new Error('Vobs I18n: locale 不能为空')
+  return locale
+}
+
+function validateMessages(value: Messages): Messages {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Vobs I18n: messages 必须是对象')
+  }
+  for (const [key, message] of Object.entries(value)) {
+    if (typeof message === 'string') continue
+    if (!message || typeof message !== 'object' || Array.isArray(message)) {
+      throw new Error(`Vobs I18n: 翻译字段 ${key} 的值无效`)
+    }
+    validateMessages(message)
+  }
+  return value
+}
+
+function validateLocaleMessages(value: LocaleMessages): LocaleMessages {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Vobs I18n: locale messages 必须是对象')
+  }
+  for (const [locale, messages] of Object.entries(value)) {
+    validateLocale(locale)
+    validateMessages(messages)
+  }
+  return value
+}
+
+function mergeMessages(parent: Messages | undefined, next: Messages): Messages {
+  const merged: Record<string, MessageValue> = { ...(parent ?? {}) }
+  for (const [key, value] of Object.entries(next)) {
+    const previous = merged[key]
+    merged[key] = typeof value === 'object' && typeof previous === 'object'
+      ? mergeMessages(previous, value)
+      : value
+  }
+  return merged
+}
+
+function isMessages(value: MessageValue | undefined): value is Messages {
+  return Boolean(value) && typeof value === 'object'
+}
+
+function unique(values: Array<string | undefined>): string[] {
+  return [...new Set(values.filter((value): value is string => value !== undefined))]
+}

package/dist/index.d.ts

@@ -1,107 +0,0 @@
-/** @license MIT
- * Copyright (c) 2026 vobsjs
- * @vobs/i18n
- */
-import { type WritableSignal } from '@vobs/reactivity';
-import { type InjectionKey, type Owner } from '@vobs/runtime-core';
-export type LocaleCode = string;
-export type MessageValue = string;
-export type MessageParams = Readonly<Record<string, string | number | boolean | null | undefined>>;
-export type LocaleMessages = Readonly<Record<string, MessageValue>>;
-export type LocaleMessageCatalog = Readonly<Record<LocaleCode, LocaleMessages | undefined>>;
-/** DI injection key: provide(I18nKey, i18n) at app assembly; components/pages consume via useI18n (resolved along the InjectionScope parent chain). */
-export declare const I18nKey: InjectionKey<I18nInstance>;
-/** The injection capability subset useI18n needs (structurally compatible with ComponentSetupContext/PageSetupContext provide/maybeInject). */
-export interface I18nInjectionHost {
-    provide<T>(key: InjectionKey<T>, value: T): () => void;
-    maybeInject<T>(key: InjectionKey<T>): T | undefined;
-}
-/**
- * App assembly: provides the I18n instance into the injection chain in root component/page setup;
- * child components get it via useI18n along the InjectionScope parent chain (multiple instances can coexist, isolated by assembly level).
- */
-export declare function provideI18n(context: I18nInjectionHost, instance: I18nInstance): () => void;
-/**
- * Gets the I18n instance in a component/page (composition API):
- * - component setup: `const i18n = useI18n(context)`, context is ComponentSetupContext
- * - page setup: `const i18n = useI18n(context)`, context is PageSetupContext
- * - the app must provideI18n(context, i18n) at the root; returns undefined when not injected, the caller decides the fallback (e.g. show the raw key).
- */
-export declare function useI18n<Schema extends LocaleCatalogSchema = LocaleCatalogSchema>(context: I18nInjectionHost): I18nInstance<Schema> | undefined;
-/** Nested message schema: values are either strings (leaves) or nested objects (`menu.file.save` dotted paths). */
-export interface LocaleMessageSchema {
-    readonly [key: string]: MessageValue | LocaleMessageSchema;
-}
-/** Nested schema organized by locale (for defineMessages/createI18n generic inference). */
-export type LocaleCatalogSchema = Readonly<Record<LocaleCode, LocaleMessageSchema | undefined>>;
-/** Decrements recursion depth (P0-C: prevents deep schemas from triggering TS combinatorial explosion/depth limits). Any N returns a decreased value; recursion stops at zero. */
-type DecrementDepth<N extends number> = N extends 0 | 1 ? 0 : N extends 2 ? 1 : N extends 3 ? 2 : N extends 4 ? 3 : N extends 5 ? 4 : N extends 6 ? 5 : N extends 7 ? 6 : 7;
-/**
- * Derives all leaf keys of a nested schema (dotted-path union): `{ menu: { file: { save } }, hello }` → `'menu.file.save' | 'hello'`.
- * `Depth` (default 5) caps recursion; subtrees degrade to `string` at zero — deep schemas do not hit TS depth limits/union
- * explosion, and top-level type safety is unaffected (P0-C).
- */
-export type MessageKey<Schema extends LocaleMessageSchema, Depth extends number = 5> = {
-    readonly [Key in keyof Schema & string]: Schema[Key] extends MessageValue ? Key : Schema[Key] extends LocaleMessageSchema ? Depth extends 0 ? string : `${Key}.${MessageKey<Schema[Key], DecrementDepth<Depth>>}` : never;
-}[keyof Schema & string];
-/** Derives the message key union from a catalog schema (takes the first locale's schema). Depth is passed through to MessageKey (P0-C). */
-export type CatalogMessageKey<Schema extends LocaleCatalogSchema, Depth extends number = 5> = Schema[keyof Schema] extends LocaleMessageSchema ? MessageKey<Schema[keyof Schema], Depth> : string;
-/** Declares a message schema type-safely: keeps the nested structure for createI18n's key union inference. */
-export declare function defineMessages<const Schema extends LocaleMessageSchema>(messages: Schema): Schema;
-/** Missing level: 'fallback' = missing in the active locale but the fallback hit (translation fell back); 'all' = missing from every catalog. */
-export type MissingMessageLevel = 'fallback' | 'all';
-/** Diagnostic data for the missing handler: distinguishes missing levels to locate catalog configuration issues. */
-export interface MissingMessageInfo {
-    /** Missing level (see MissingMessageLevel). */
-    readonly level: MissingMessageLevel;
-    /** Configured fallback locale (undefined when not configured). */
-    readonly fallbackLocale?: LocaleCode;
-}
-export interface I18nOptions {
-    readonly locale: LocaleCode;
-    readonly fallbackLocale?: LocaleCode;
-    /**
-     * Message catalog: flat or nested (dotted paths); nested catalogs are flattened at creation.
-     * Broadly typed (LocaleCatalogSchema values may nest) — type safety comes from explicit `createI18n<typeof messages>`.
-     */
-    readonly messages?: LocaleCatalogSchema;
-    /**
-     * Missing-key handler (default console.warn + return the key).
-     * The third arg info.level distinguishes: 'fallback' (missing in the active locale, translation fell back, return value ignored),
-     * 'all' (missing from every catalog, return value is used as display text).
-     */
-    readonly missing?: (key: string, locale: LocaleCode, info?: MissingMessageInfo) => string;
-    /** Owner the I18n instance belongs to (default currentOwner); the instance is released on Owner disposal. */
-    readonly owner?: Owner;
-}
-export interface I18nInstance<Schema extends LocaleCatalogSchema = LocaleCatalogSchema> {
-    readonly locale: WritableSignal<LocaleCode>;
-    readonly fallbackLocale: LocaleCode | undefined;
-    /** Flattened catalog (dotted-path keys). */
-    readonly messages: LocaleMessageCatalog;
-    /** Translate: key is constrained by the schema type (nested keys use dotted paths). */
-    t<Key extends CatalogMessageKey<Schema>>(key: Key, params?: MessageParams): string;
-    setLocale(locale: LocaleCode): void;
-    addMessages(locale: LocaleCode, messages: LocaleMessageSchema): void;
-    hasMessage(key: string, locale?: LocaleCode): boolean;
-    formatDate(value: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
-    formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
-    formatCurrency(value: number, currency: string, options?: Intl.NumberFormatOptions): string;
-    formatRelativeTime(value: number, unit: Intl.RelativeTimeFormatUnit): string;
-    /** Releases the instance (idempotent). Called automatically on Owner disposal. */
-    dispose(): void;
-}
-export interface SerializedI18nState {
-    readonly locale: LocaleCode;
-    readonly fallbackLocale?: LocaleCode;
-    readonly messages: LocaleMessageCatalog;
-}
-export declare function createI18n<const Schema extends LocaleCatalogSchema = LocaleCatalogSchema>(options: I18nOptions): I18nInstance<Schema>;
-export declare function serializeI18nState(instance: I18nInstance): SerializedI18nState;
-/**
- * Symmetrically rebuilds an I18n instance from serialized state (contract §4):
- * serialize and hydrate are a pair — SSR serializes, and before client hydration this rebuilds,
- * keeping first-screen translations identical to the SSR output (see the Security contract's SSR state boundary).
- */
-export declare function createI18nFromState(state: SerializedI18nState, options?: Pick<I18nOptions, 'missing' | 'owner'>): I18nInstance;
-export {};

package/dist/index.js

@@ -1,337 +0,0 @@
-/** @license MIT
- * Copyright (c) 2026 vobsjs
- * @vobs/i18n
- */
-import { signal } from '@vobs/reactivity';
-import { createInjectionKey, currentOwner, TranslationAdapterKey, } from '@vobs/runtime-core';
-/** DI injection key: provide(I18nKey, i18n) at app assembly; components/pages consume via useI18n (resolved along the InjectionScope parent chain). */
-export const I18nKey = createInjectionKey('vobs.i18n');
-/**
- * App assembly: provides the I18n instance into the injection chain in root component/page setup;
- * child components get it via useI18n along the InjectionScope parent chain (multiple instances can coexist, isolated by assembly level).
- */
-export function provideI18n(context, instance) {
-    const undoI18n = context.provide(I18nKey, instance);
-    // Register the TranslationAdapter port: template {{@key}} / :attr="@key" is translated through it (overridable by a user-defined adapter)
-    const undoAdapter = context.provide(TranslationAdapterKey, {
-        t: (key, params) => instance.t(key, params),
-        locale: instance.locale,
-    });
-    return () => {
-        undoI18n();
-        undoAdapter();
-    };
-}
-/**
- * Gets the I18n instance in a component/page (composition API):
- * - component setup: `const i18n = useI18n(context)`, context is ComponentSetupContext
- * - page setup: `const i18n = useI18n(context)`, context is PageSetupContext
- * - the app must provideI18n(context, i18n) at the root; returns undefined when not injected, the caller decides the fallback (e.g. show the raw key).
- */
-export function useI18n(context) {
-    return context.maybeInject(I18nKey);
-}
-/** Declares a message schema type-safely: keeps the nested structure for createI18n's key union inference. */
-export function defineMessages(messages) {
-    return messages;
-}
-/** Flattens a nested schema into a dotted-path flat map (internal storage/lookup shape). */
-function flattenMessages(schema, prefix = '') {
-    const flattened = {};
-    for (const [key, value] of Object.entries(schema)) {
-        const path = prefix === '' ? key : `${prefix}.${key}`;
-        if (typeof value === 'string') {
-            flattened[path] = value;
-        }
-        else {
-            Object.assign(flattened, flattenMessages(value, path));
-        }
-    }
-    return flattened;
-}
-export function createI18n(options) {
-    const locale = signal(options.locale);
-    const catalogVersion = signal(0);
-    const catalogs = {};
-    for (const [messageLocale, catalog] of Object.entries(options.messages ?? {})) {
-        if (catalog !== undefined && catalog !== null && typeof catalog === 'object') {
-            catalogs[messageLocale] = flattenMessages(catalog);
-        }
-    }
-    const missing = options.missing ??
-        ((key, locale, info) => {
-            if (typeof console !== 'undefined') {
-                if (info?.level === 'fallback') {
-                    console.warn(`[vobs i18n] Missing message: "${key}" in locale "${locale}" (fallback "${info.fallbackLocale ?? ''}")`);
-                }
-                else {
-                    console.warn(`[vobs i18n] Missing message: "${key}"`);
-                }
-            }
-            return key;
-        });
-    const resolveMessage = (key, activeLocale, params, depth) => {
-        if (depth > 8)
-            return key;
-        const activeMessage = catalogs[activeLocale]?.[key];
-        const fallbackMessage = options.fallbackLocale === undefined ? undefined : catalogs[options.fallbackLocale]?.[key];
-        if (activeMessage === undefined && fallbackMessage === undefined) {
-            // missing from every catalog: the missing return value is used as display text.
-            return missing(key, activeLocale, {
-                level: 'all',
-                ...(options.fallbackLocale === undefined ? {} : { fallbackLocale: options.fallbackLocale }),
-            });
-        }
-        const message = activeMessage ?? fallbackMessage;
-        if (message === undefined)
-            return key;
-        if (activeMessage === undefined) {
-            // missing in the active locale but the fallback hit: diagnostics distinguish the level; translation still uses the fallback text (the missing return value is ignored).
-            void missing(key, activeLocale, {
-                level: 'fallback',
-                ...(options.fallbackLocale === undefined ? {} : { fallbackLocale: options.fallbackLocale }),
-            });
-        }
-        return formatMessage(message, activeLocale, params, (nestedKey) => resolveMessage(nestedKey, activeLocale, params, depth + 1));
-    };
-    let disposed = false;
-    const dispose = () => {
-        if (disposed)
-            return;
-        disposed = true;
-    };
-    const owner = options.owner ?? currentOwner();
-    if (owner !== undefined) {
-        owner.own(dispose);
-    }
-    const instance = {
-        locale,
-        fallbackLocale: options.fallbackLocale,
-        get messages() {
-            return catalogs;
-        },
-        t(key, params) {
-            void catalogVersion.value;
-            return resolveMessage(key, locale.value, params, 0);
-        },
-        setLocale(nextLocale) {
-            locale.value = nextLocale;
-        },
-        addMessages(messageLocale, nextMessages) {
-            catalogs[messageLocale] = {
-                ...(catalogs[messageLocale] ?? {}),
-                ...flattenMessages(nextMessages),
-            };
-            catalogVersion.value += 1;
-        },
-        hasMessage(key, messageLocale = locale.value) {
-            return catalogs[messageLocale]?.[key] !== undefined;
-        },
-        formatDate(value, formatOptions) {
-            return cachedDateTimeFormat(locale.value, formatOptions).format(new Date(value));
-        },
-        formatNumber(value, formatOptions) {
-            return cachedNumberFormat(locale.value, formatOptions).format(value);
-        },
-        formatCurrency(value, currency, formatOptions) {
-            return cachedNumberFormat(locale.value, {
-                style: 'currency',
-                currency,
-                ...formatOptions,
-            }).format(value);
-        },
-        formatRelativeTime(value, unit) {
-            return cachedRelativeTimeFormat(locale.value).format(value, unit);
-        },
-        dispose,
-    };
-    return instance;
-}
-export function serializeI18nState(instance) {
-    return {
-        locale: instance.locale.value,
-        ...(instance.fallbackLocale === undefined ? {} : { fallbackLocale: instance.fallbackLocale }),
-        messages: instance.messages,
-    };
-}
-/**
- * Symmetrically rebuilds an I18n instance from serialized state (contract §4):
- * serialize and hydrate are a pair — SSR serializes, and before client hydration this rebuilds,
- * keeping first-screen translations identical to the SSR output (see the Security contract's SSR state boundary).
- */
-export function createI18nFromState(state, options = {}) {
-    return createI18n({
-        locale: state.locale,
-        ...(state.fallbackLocale === undefined ? {} : { fallbackLocale: state.fallbackLocale }),
-        messages: state.messages,
-        ...(options.missing === undefined ? {} : { missing: options.missing }),
-        ...(options.owner === undefined ? {} : { owner: options.owner }),
-    });
-}
-function formatMessage(message, locale, params, resolveKey) {
-    if (!message.includes('{'))
-        return message;
-    let result = '';
-    let cursor = 0;
-    while (cursor < message.length) {
-        const open = message.indexOf('{', cursor);
-        if (open < 0) {
-            result += message.slice(cursor);
-            break;
-        }
-        result += message.slice(cursor, open);
-        const close = findClosingBrace(message, open);
-        if (close < 0) {
-            result += message.slice(open);
-            break;
-        }
-        result += formatPlaceholder(message.slice(open + 1, close), locale, params, resolveKey);
-        cursor = close + 1;
-    }
-    return result;
-}
-function formatPlaceholder(source, locale, params, resolveKey) {
-    const content = source.trim();
-    if (content === '')
-        return '{}';
-    if (content.startsWith('@')) {
-        return resolveKey(content.slice(1).trim());
-    }
-    const parts = splitTopLevel(content, ',');
-    const name = parts[0]?.trim() ?? '';
-    const type = parts[1]?.trim();
-    if (type === 'plural') {
-        return formatPlural(name, parts.slice(2).join(','), locale, params, resolveKey);
-    }
-    if (type === 'select') {
-        return formatSelect(name, parts.slice(2).join(','), locale, params, resolveKey);
-    }
-    if (name === '')
-        return `{${content}}`;
-    const value = params?.[name];
-    return value === null || value === undefined ? `{${name}}` : String(value);
-}
-function findClosingBrace(message, open) {
-    let depth = 0;
-    for (let index = open; index < message.length; index += 1) {
-        const char = message[index];
-        if (char === '{')
-            depth += 1;
-        else if (char === '}') {
-            depth -= 1;
-            if (depth === 0)
-                return index;
-        }
-    }
-    return -1;
-}
-function splitTopLevel(source, separator) {
-    const parts = [];
-    let depth = 0;
-    let current = '';
-    for (const char of source) {
-        if (char === '{') {
-            depth += 1;
-            current += char;
-        }
-        else if (char === '}') {
-            depth -= 1;
-            current += char;
-        }
-        else if (char === separator && depth === 0) {
-            parts.push(current);
-            current = '';
-        }
-        else {
-            current += char;
-        }
-    }
-    parts.push(current);
-    return parts;
-}
-function parseCases(body) {
-    const cases = [];
-    let index = 0;
-    while (index < body.length) {
-        while (index < body.length && /\s/u.test(body[index] ?? ''))
-            index += 1;
-        if (index >= body.length)
-            break;
-        const open = body.indexOf('{', index);
-        if (open < 0)
-            break;
-        const match = body.slice(index, open).trim();
-        const close = findClosingBrace(body, open);
-        if (close < 0)
-            break;
-        cases.push({ match, content: body.slice(open + 1, close) });
-        index = close + 1;
-    }
-    return cases;
-}
-function formatPlural(name, body, locale, params, resolveKey) {
-    const cases = parseCases(body);
-    const value = params?.[name];
-    if (typeof value === 'number') {
-        const category = cachedPluralRules(locale).select(value);
-        const exact = cases.find((entry) => entry.match === `=${value}`);
-        if (exact !== undefined)
-            return formatMessage(exact.content, locale, params, resolveKey);
-        const matched = cases.find((entry) => entry.match === category);
-        if (matched !== undefined)
-            return formatMessage(matched.content, locale, params, resolveKey);
-    }
-    const other = cases.find((entry) => entry.match === 'other');
-    return other === undefined ? '' : formatMessage(other.content, locale, params, resolveKey);
-}
-function formatSelect(name, body, locale, params, resolveKey) {
-    const cases = parseCases(body);
-    const value = params?.[name];
-    const stringValue = value === null || value === undefined ? undefined : String(value);
-    if (stringValue !== undefined) {
-        const matched = cases.find((entry) => entry.match === stringValue);
-        if (matched !== undefined)
-            return formatMessage(matched.content, locale, params, resolveKey);
-    }
-    const other = cases.find((entry) => entry.match === 'other');
-    return other === undefined ? '' : formatMessage(other.content, locale, params, resolveKey);
-}
-// Intl constructor cache: PluralRules/NumberFormat/DateTimeFormat/RelativeTimeFormat are expensive to construct;
-// instances for the same locale are reusable (allowed by the Intl spec, results unchanged). Module-level caches are
-// shared across instances and use an LRU limit so request-specific options cannot grow the process indefinitely.
-const FORMATTER_CACHE_LIMIT = 100;
-const pluralRulesCache = new Map();
-const numberFormatCache = new Map();
-const dateTimeFormatCache = new Map();
-const relativeTimeFormatCache = new Map();
-function readCachedFormatter(cache, key, create) {
-    const existing = cache.get(key);
-    if (existing !== undefined) {
-        cache.delete(key);
-        cache.set(key, existing);
-        return existing;
-    }
-    const formatter = create();
-    cache.set(key, formatter);
-    while (cache.size > FORMATTER_CACHE_LIMIT) {
-        const oldest = cache.keys().next().value;
-        if (oldest === undefined)
-            break;
-        cache.delete(oldest);
-    }
-    return formatter;
-}
-function cachedPluralRules(locale) {
-    return readCachedFormatter(pluralRulesCache, locale, () => new Intl.PluralRules(locale));
-}
-function cachedNumberFormat(locale, options) {
-    const key = options === undefined ? locale : `${locale}\u0000${JSON.stringify(options)}`;
-    return readCachedFormatter(numberFormatCache, key, () => new Intl.NumberFormat(locale, options));
-}
-function cachedDateTimeFormat(locale, options) {
-    const key = options === undefined ? locale : `${locale}\u0000${JSON.stringify(options)}`;
-    return readCachedFormatter(dateTimeFormatCache, key, () => new Intl.DateTimeFormat(locale, options));
-}
-function cachedRelativeTimeFormat(locale) {
-    return readCachedFormatter(relativeTimeFormatCache, locale, () => new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }));
-}