tang-ui-x 1.1.1 → 1.1.2

package/composables/i18n/error.uts

@@ -0,0 +1,82 @@
+/**
+ * i18n 错误处理工具类
+ * 提供统一的错误和警告输出
+ */
+export class I18nError {
+  /**
+   * 警告：语言代码不存在
+   * @param locale 语言代码
+   */
+  static warnLocaleNotFound(locale: string): void {
+    console.warn(`[Tang UI I18n] Locale "${locale}" not found, using fallback locale`)
+  }
+  
+  /**
+   * 警告：翻译键不存在
+   * @param key 翻译键
+   * @param locale 语言代码
+   */
+  static warnKeyNotFound(key: string, locale: string): void {
+    // 仅在开发环境输出警告
+    if (process.env.NODE_ENV === 'development') {
+      console.warn(`[Tang UI I18n] Translation key "${key}" not found in locale "${locale}"`)
+    }
+  }
+  
+  /**
+   * 错误：语言包格式无效
+   * @param locale 语言代码
+   */
+  static errorInvalidMessages(locale: string): void {
+    console.error(`[Tang UI I18n] Invalid messages format for locale "${locale}"`)
+  }
+  
+  /**
+   * 警告：参数缺失
+   * @param key 翻译键
+   * @param param 参数名
+   */
+  static warnMissingParam(key: string, param: string): void {
+    // 仅在开发环境输出警告
+    if (process.env.NODE_ENV === 'development') {
+      console.warn(`[Tang UI I18n] Missing parameter "${param}" for key "${key}"`)
+    }
+  }
+  
+  /**
+   * 警告：翻译键格式无效
+   * @param key 翻译键
+   */
+  static warnInvalidKey(key: string): void {
+    if (process.env.NODE_ENV === 'development') {
+      console.warn(`[Tang UI I18n] Invalid translation key format: "${key}". Expected format: "moduleName.key"`)
+    }
+  }
+  
+  /**
+   * 错误：语言包不是有效的对象
+   * @param locale 语言代码
+   */
+  static errorMessagesNotObject(locale: string): void {
+    console.error(`[Tang UI I18n] Messages for locale "${locale}" must be a valid object`)
+  }
+  
+  /**
+   * 错误：模块不是有效的对象
+   * @param locale 语言代码
+   * @param moduleName 模块名
+   */
+  static errorModuleNotObject(locale: string, moduleName: string): void {
+    console.error(`[Tang UI I18n] Module "${moduleName}" in locale "${locale}" must be a valid object`)
+  }
+  
+  /**
+   * 错误：键值不是字符串
+   * @param locale 语言代码
+   * @param moduleName 模块名
+   * @param key 键名
+   */
+  static errorValueNotString(locale: string, moduleName: string, key: string): void {
+    console.error(`[Tang UI I18n] Value for key "${key}" in module "${moduleName}" of locale "${locale}" must be a string`)
+  }
+}

package/composables/i18n/index.uts

@@ -0,0 +1,188 @@
+/**
+ * i18n 全局导出函数
+ * 提供全局访问的便捷方法
+ */
+
+import { I18nManager } from './manager.uts'
+import type { ModularLocaleMessages } from './types.uts'
+
+/**
+ * 设置语言（全局）
+ * 切换整个应用的显示语言
+ * 
+ * @param locale 语言代码（如 'zh-CN', 'en-US', 'zh-TW'）
+ * @returns 是否切换成功
+ * 
+ * @example
+ * ```typescript
+ * import { setLanguage } from 'tang-ui-x'
+ * 
+ * // 切换到英语
+ * const success = setLanguage('en-US')
+ * if (success) {
+ *   console.log('语言切换成功')
+ * } else {
+ *   console.log('语言切换失败，语言包未注册')
+ * }
+ * ```
+ */
+export function setLanguage(locale: string): boolean {
+  const manager = I18nManager.getInstance()
+  return manager.setLocale(locale)
+}
+
+/**
+ * 注册语言包（默认使用合并模式）
+ * 添加新语言或覆盖现有语言的翻译
+ * 默认使用合并模式，新内容会与现有内容合并，新键覆盖旧键，未覆盖的键保留
+ * 
+ * @param locale 语言代码
+ * @param messages 模块化语言包
+ * 
+ * @example
+ * ```typescript
+ * import { registerLocale } from 'tang-ui-x'
+ * 
+ * // 注册日语语言包
+ * registerLocale('ja-JP', {
+ *   common: {
+ *     confirm: '確認',
+ *     cancel: 'キャンセル',
+ *     ok: 'OK'
+ *   },
+ *   dialog: {
+ *     title: 'ヒント',
+ *     confirmText: '確認',
+ *     cancelText: 'キャンセル'
+ *   }
+ * })
+ * 
+ * // 覆盖部分中文翻译（合并模式）
+ * registerLocale('zh-CN', {
+ *   common: {
+ *     confirm: '好的'  // 只覆盖这个键，其他保持不变
+ *   }
+ * })
+ * ```
+ */
+export function registerLocale(locale: string, messages: ModularLocaleMessages): void {
+  const manager = I18nManager.getInstance()
+  manager.registerMessages(locale, messages)
+}
+
+/**
+ * 注册语言包（指定模式）
+ * 支持合并模式和替换模式
+ * - 合并模式：新内容与现有内容合并，新键覆盖旧键，未覆盖的键保留
+ * - 替换模式：完全替换现有语言包，不保留任何原有内容
+ * 
+ * @param locale 语言代码
+ * @param messages 模块化语言包
+ * @param mode 注册模式：'merge' 合并（默认），'replace' 替换
+ * 
+ * @example
+ * ```typescript
+ * import { registerLocaleWithMode } from 'tang-ui-x'
+ * 
+ * // 使用合并模式（与 registerLocale 相同）
+ * registerLocaleWithMode('zh-CN', {
+ *   common: {
+ *     confirm: '好的'  // 只覆盖这个键，其他保持不变
+ *   }
+ * }, 'merge')
+ * 
+ * // 使用替换模式（完全替换）
+ * registerLocaleWithMode('zh-CN', {
+ *   common: {
+ *     confirm: '好的',
+ *     cancel: '取消'
+ *   }
+ *   // 必须提供所有模块，否则缺失的模块将为空
+ * }, 'replace')
+ * ```
+ */
+export function registerLocaleWithMode(
+  locale: string,
+  messages: ModularLocaleMessages,
+  mode: 'merge' | 'replace'
+): void {
+  const manager = I18nManager.getInstance()
+  manager.registerMessagesWithMode(locale, messages, mode)
+}
+
+/**
+ * 替换语言包（完全替换）
+ * 完全替换指定语言的所有翻译内容，不保留任何原有内容
+ * 这是 registerLocaleWithMode(locale, messages, 'replace') 的便捷方法
+ * 
+ * @param locale 语言代码
+ * @param messages 模块化语言包
+ * 
+ * @example
+ * ```typescript
+ * import { replaceLocale } from 'tang-ui-x'
+ * 
+ * // 完全替换中文翻译
+ * replaceLocale('zh-CN', {
+ *   common: {
+ *     confirm: '好的',
+ *     cancel: '取消',
+ *     ok: 'OK'
+ *   },
+ *   dialog: {
+ *     title: '提示',
+ *     confirmText: '好的',
+ *     cancelText: '取消'
+ *   }
+ *   // 必须提供所有模块，否则缺失的模块将为空
+ * })
+ * ```
+ */
+export function replaceLocale(locale: string, messages: ModularLocaleMessages): void {
+  const manager = I18nManager.getInstance()
+  manager.replaceMessages(locale, messages)
+}
+
+/**
+ * 获取当前语言
+ * 返回当前激活的语言代码
+ * 
+ * @returns 当前语言代码
+ * 
+ * @example
+ * ```typescript
+ * import { getCurrentLocale } from 'tang-ui-x'
+ * 
+ * const current = getCurrentLocale()
+ * console.log('当前语言:', current)  // 输出: '当前语言: zh-CN'
+ * ```
+ */
+export function getCurrentLocale(): string {
+  const manager = I18nManager.getInstance()
+  return manager.getCurrentLocale()
+}
+
+/**
+ * 获取可用语言列表
+ * 返回所有已注册语言的语言代码数组
+ * 
+ * @returns 可用语言代码数组
+ * 
+ * @example
+ * ```typescript
+ * import { getAvailableLocales } from 'tang-ui-x'
+ * 
+ * const locales = getAvailableLocales()
+ * console.log('可用语言:', locales)  // 输出: ['zh-CN', 'en-US', 'zh-TW']
+ * 
+ * // 在语言选择器中使用
+ * locales.forEach(locale => {
+ *   console.log(`语言选项: ${locale}`)
+ * })
+ * ```
+ */
+export function getAvailableLocales(): string[] {
+  const manager = I18nManager.getInstance()
+  // 注意：这里返回的是计算属性的当前值，而不是响应式引用
+  return manager.getAvailableLocales().value
+}

package/composables/i18n/manager-demo.uts

@@ -0,0 +1,104 @@
+/**
+ * I18nManager 功能演示
+ * 演示语言切换功能的使用
+ */
+
+import { I18nManager } from './manager.uts'
+import type { ModularLocaleMessages } from './types.uts'
+
+// 获取管理器实例
+const manager = I18nManager.getInstance()
+
+// 注册测试语言包
+const zhCN: ModularLocaleMessages = {
+  common: {
+    confirm: '确定',
+    cancel: '取消',
+    hello: '你好，{name}'
+  },
+  dialog: {
+    title: '提示'
+  }
+}
+
+const enUS: ModularLocaleMessages = {
+  common: {
+    confirm: 'Confirm',
+    cancel: 'Cancel',
+    hello: 'Hello, {name}'
+  },
+  dialog: {
+    title: 'Notice'
+  }
+}
+
+const zhTW: ModularLocaleMessages = {
+  common: {
+    confirm: '確定',
+    cancel: '取消',
+    hello: '你好，{name}'
+  }
+}
+
+// 注册语言包
+manager.registerMessages('zh-CN', zhCN)
+manager.registerMessages('en-US', enUS)
+manager.registerMessages('zh-TW', zhTW)
+
+console.log('=== 语言切换功能演示 ===\n')
+
+// 测试 1: 检查语言包是否已注册
+console.log('1. 检查语言包是否已注册:')
+console.log('   hasLocale("zh-CN"):', manager.hasLocale('zh-CN'))
+console.log('   hasLocale("en-US"):', manager.hasLocale('en-US'))
+console.log('   hasLocale("zh-TW"):', manager.hasLocale('zh-TW'))
+console.log('   hasLocale("ja-JP"):', manager.hasLocale('ja-JP'))
+console.log('')
+
+// 测试 2: 切换到有效的语言
+console.log('2. 切换到有效的语言:')
+console.log('   当前语言:', manager.getCurrentLocale())
+console.log('   翻译 "common.confirm":', manager.translate('common.confirm'))
+
+const success1 = manager.setLocale('en-US')
+console.log('   setLocale("en-US") 返回:', success1)
+console.log('   当前语言:', manager.getCurrentLocale())
+console.log('   翻译 "common.confirm":', manager.translate('common.confirm'))
+console.log('')
+
+// 测试 3: 切换到另一个有效语言
+console.log('3. 切换到繁体中文:')
+const success2 = manager.setLocale('zh-TW')
+console.log('   setLocale("zh-TW") 返回:', success2)
+console.log('   当前语言:', manager.getCurrentLocale())
+console.log('   翻译 "common.confirm":', manager.translate('common.confirm'))
+console.log('')
+
+// 测试 4: 尝试切换到无效的语言
+console.log('4. 尝试切换到无效的语言:')
+console.log('   当前语言:', manager.getCurrentLocale())
+const success3 = manager.setLocale('invalid-locale')
+console.log('   setLocale("invalid-locale") 返回:', success3)
+console.log('   当前语言（应保持不变）:', manager.getCurrentLocale())
+console.log('   翻译 "common.confirm"（应保持繁体中文）:', manager.translate('common.confirm'))
+console.log('')
+
+// 测试 5: 验证响应式更新
+console.log('5. 验证响应式状态:')
+console.log('   currentLocale.value:', manager.currentLocale.value)
+manager.setLocale('zh-CN')
+console.log('   切换后 currentLocale.value:', manager.currentLocale.value)
+console.log('')
+
+// 测试 6: 获取可用语言列表
+console.log('6. 获取可用语言列表:')
+const availableLocales = manager.getAvailableLocales()
+console.log('   可用语言:', availableLocales.value)
+console.log('')
+
+console.log('=== 演示完成 ===')
+console.log('✅ setLocale() 方法已实现')
+console.log('✅ hasLocale() 辅助方法已实现')
+console.log('✅ 验证语言代码是否已注册')
+console.log('✅ 更新 currentLocale ref 以触发响应式更新')
+console.log('✅ 返回切换成功/失败状态')

package/composables/i18n/manager.test.uts

@@ -0,0 +1,182 @@
+/**
+ * I18nManager 单元测试
+ * 测试核心管理器的基本功能
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import { I18nManager } from './manager.uts'
+import type { ModularLocaleMessages } from './types.uts'
+
+describe('I18nManager', () => {
+  let manager: I18nManager
+  
+  beforeEach(() => {
+    // 获取单例实例
+    manager = I18nManager.getInstance()
+    
+    // 注册测试语言包
+    const zhCN: ModularLocaleMessages = {
+      common: {
+        confirm: '确定',
+        cancel: '取消',
+        hello: '你好，{name}'
+      },
+      dialog: {
+        title: '提示'
+      }
+    }
+    
+    const enUS: ModularLocaleMessages = {
+      common: {
+        confirm: 'Confirm',
+        cancel: 'Cancel',
+        hello: 'Hello, {name}'
+      }
+    }
+    
+    manager.registerMessages('zh-CN', zhCN)
+    manager.registerMessages('en-US', enUS)
+    manager.setLocale('zh-CN')
+  })
+  
+  describe('translate()', () => {
+    it('should translate simple keys', () => {
+      const result = manager.translate('common.confirm')
+      expect(result).toBe('确定')
+    })
+    
+    it('should translate with module name', () => {
+      const result = manager.translate('dialog.title')
+      expect(result).toBe('提示')
+    })
+    
+    it('should return key if translation not found', () => {
+      const result = manager.translate('common.notexist')
+      expect(result).toBe('common.notexist')
+    })
+    
+    it('should return key if invalid format', () => {
+      const result = manager.translate('invalidkey')
+      expect(result).toBe('invalidkey')
+    })
+  })
+  
+  describe('interpolate()', () => {
+    it('should interpolate parameters', () => {
+      const result = manager.translate('common.hello', { name: '张三' })
+      expect(result).toBe('你好，张三')
+    })
+    
+    it('should handle missing parameters', () => {
+      const result = manager.translate('common.hello', {})
+      expect(result).toBe('你好，{name}')
+    })
+    
+    it('should handle multiple parameters', () => {
+      // 注册带多个参数的消息
+      manager.registerMessages('zh-CN', {
+        test: {
+          multi: '{greeting}, {name}! 你有 {count} 条消息'
+        }
+      })
+      
+      const result = manager.translate('test.multi', {
+        greeting: '你好',
+        name: '李四',
+        count: 5
+      })
+      expect(result).toBe('你好, 李四! 你有 5 条消息')
+    })
+  })
+  
+  describe('setLocale()', () => {
+    it('should switch locale successfully', () => {
+      const success = manager.setLocale('en-US')
+      expect(success).toBe(true)
+      expect(manager.getCurrentLocale()).toBe('en-US')
+    })
+    
+    it('should translate in new locale after switch', () => {
+      manager.setLocale('en-US')
+      const result = manager.translate('common.confirm')
+      expect(result).toBe('Confirm')
+    })
+    
+    it('should return false for invalid locale', () => {
+      const success = manager.setLocale('invalid-locale')
+      expect(success).toBe(false)
+      expect(manager.getCurrentLocale()).toBe('zh-CN')
+    })
+  })
+  
+  describe('fallback mechanism', () => {
+    it('should fallback to default locale when key not found', () => {
+      manager.setLocale('en-US')
+      // dialog.title 只在 zh-CN 中存在
+      const result = manager.translate('dialog.title')
+      expect(result).toBe('提示')
+    })
+  })
+  
+  describe('registerMessages()', () => {
+    it('should register new locale', () => {
+      const zhTW: ModularLocaleMessages = {
+        common: {
+          confirm: '確定'
+        }
+      }
+      
+      manager.registerMessages('zh-TW', zhTW)
+      manager.setLocale('zh-TW')
+      const result = manager.translate('common.confirm')
+      expect(result).toBe('確定')
+    })
+    
+    it('should merge messages for existing locale', () => {
+      const additional: ModularLocaleMessages = {
+        common: {
+          ok: '好的'
+        },
+        newModule: {
+          test: '测试'
+        }
+      }
+      
+      manager.registerMessages('zh-CN', additional)
+      
+      // 原有的键应该保留
+      expect(manager.translate('common.confirm')).toBe('确定')
+      // 新增的键应该可用
+      expect(manager.translate('common.ok')).toBe('好的')
+      expect(manager.translate('newModule.test')).toBe('测试')
+    })
+    
+    it('should override existing keys when merging', () => {
+      const override: ModularLocaleMessages = {
+        common: {
+          confirm: '好的'
+        }
+      }
+      
+      manager.registerMessages('zh-CN', override)
+      const result = manager.translate('common.confirm')
+      expect(result).toBe('好的')
+    })
+  })
+  
+  describe('getAvailableLocales()', () => {
+    it('should return all registered locales', () => {
+      const locales = manager.getAvailableLocales()
+      expect(locales.value).toContain('zh-CN')
+      expect(locales.value).toContain('en-US')
+    })
+  })
+  
+  describe('singleton pattern', () => {
+    it('should return same instance', () => {
+      const instance1 = I18nManager.getInstance()
+      const instance2 = I18nManager.getInstance()
+      expect(instance1).toBe(instance2)
+    })
+  })
+})