@quantabit/i18n-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuantaBit Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# @quantabit/i18n-sdk
+
+> 轻量国际化引擎：Provider/Hook/语言切换器
+
+- I18nProvider — React Context 提供者
+- useI18n / useTranslation — 翻译 Hook
+- LanguageSwitcher — 语言切换 UI (dropdown/pills)
+- I18nManager — 纯 JS 管理器（非 React 场景可用）
+
+## License
+MIT
+
+
+
+---
+
+## 🌐 Brand & Links
+- Official Mainnet: [QuantaBit Chain](https://qbitchain.io/)
+- Developer Platform: [Developer Platform](https://developer.quantabit.io/)
+- Open Platform: [Open Platform](https://open.quantabit.io/)
+- Payment Platform: [Pay Platform](https://pay.qbitwallet.io/)
+- Feedback: [Feedback](https://xwin.live/qbit)

package/dist/index.cjs

@@ -0,0 +1,620 @@
+'use strict';
+
+var React = require('react');
+
+/**
+ * @quantabit/i18n-sdk - I18nManager
+ * 
+ * 轻量级国际化管理器
+ * 特性：
+ * - 多语言消息管理与切换
+ * - 嵌套键路径支持 (e.g. 'nav.home')
+ * - 参数插值 ({name} → 'Tom')
+ * - 复数形式支持
+ * - 回退语言链
+ * - 语言自动检测 (浏览器偏好)
+ * - 懒加载语言包
+ * - 变更事件监听
+ */
+class I18nManager {
+  constructor(config = {}) {
+    this.locale = config.defaultLocale || 'en';
+    this._messages = config.messages || {};
+    this._listeners = [];
+    this._fallback = config.fallbackLocale || 'en';
+    this._loading = new Set(); // 正在加载的语言包
+    this._loaders = {}; // 语言包加载器
+    this._dateFormats = {}; // 日期格式化配置
+    this._numberFormats = {}; // 数字格式化配置
+    this._debug = config.debug || false;
+
+    // 自动检测浏览器语言
+    if (config.autoDetect !== false && typeof navigator !== 'undefined') {
+      const browserLang = this._detectBrowserLanguage();
+      if (browserLang && this._messages[browserLang]) {
+        this.locale = browserLang;
+      }
+    }
+  }
+
+  // ============ 基础 API ============
+
+  /** 当前语言代码 */
+  get currentLocale() {
+    return this.locale;
+  }
+
+  /** 可用语言列表 */
+  get availableLocales() {
+    return Object.keys(this._messages);
+  }
+
+  /**
+   * 切换语言
+   * @param {string} locale - 语言代码
+   * @returns {Promise<boolean>} 是否成功
+   */
+  async setLocale(locale) {
+    // 如果语言包不存在且有加载器，尝试懒加载
+    if (!this._messages[locale] && this._loaders[locale]) {
+      await this.loadLocale(locale);
+    }
+    if (this._messages[locale]) {
+      const oldLocale = this.locale;
+      this.locale = locale;
+
+      // 保存到浏览器
+      if (typeof localStorage !== 'undefined') {
+        try {
+          localStorage.setItem('qbit_locale', locale);
+        } catch {}
+      }
+
+      // 设置 HTML lang 属性
+      if (typeof document !== 'undefined') {
+        document.documentElement.lang = locale;
+        // RTL 语言支持
+        const rtlLocales = ['ar', 'he', 'fa', 'ur'];
+        document.documentElement.dir = rtlLocales.includes(locale) ? 'rtl' : 'ltr';
+      }
+
+      // 通知监听器
+      this._listeners.forEach(fn => fn(locale, oldLocale));
+      return true;
+    }
+    if (this._debug) {
+      console.warn(`[i18n] 语言 "${locale}" 不可用。可用语言: ${this.availableLocales.join(', ')}`);
+    }
+    return false;
+  }
+
+  /**
+   * 添加语言消息
+   * @param {string} locale - 语言代码
+   * @param {Object} messages - 消息对象（支持嵌套）
+   */
+  addMessages(locale, messages) {
+    this._messages[locale] = this._deepMerge(this._messages[locale] || {}, messages);
+  }
+
+  /**
+   * 翻译 — 核心 API
+   * @param {string} key - 翻译键（支持嵌套 'nav.home'）
+   * @param {Object} params - 插值参数
+   * @returns {string} 翻译结果
+   * 
+   * @example
+   * i18n.t('greeting', { name: 'Tom' })          // "Hello, Tom!"
+   * i18n.t('items', { count: 3 })                 // "3 items" (复数)
+   * i18n.t('nav.settings.privacy')                // 嵌套键路径
+   */
+  t(key, params = {}) {
+    // 1. 查找当前语言
+    let msg = this._getNestedValue(this._messages[this.locale], key);
+
+    // 2. 回退到默认语言
+    if (msg === undefined || msg === null) {
+      msg = this._getNestedValue(this._messages[this._fallback], key);
+    }
+
+    // 3. 都找不到，返回键名本身（开发友好）
+    if (msg === undefined || msg === null) {
+      if (this._debug) {
+        console.warn(`[i18n] 缺失翻译: "${key}" (${this.locale})`);
+      }
+      return key;
+    }
+
+    // 4. 复数处理
+    if (typeof msg === 'object' && params.count !== undefined) {
+      msg = this._resolvePlural(msg, params.count);
+    }
+
+    // 5. 参数插值
+    if (typeof msg === 'string' && params) {
+      return this._interpolate(msg, params);
+    }
+    return msg;
+  }
+
+  /**
+   * 检查翻译键是否存在
+   * @param {string} key - 翻译键
+   * @returns {boolean}
+   */
+  exists(key) {
+    return this._getNestedValue(this._messages[this.locale], key) !== undefined;
+  }
+
+  // ============ 语言包管理 ============
+
+  /**
+   * 注册语言包懒加载器
+   * @param {string} locale - 语言代码
+   * @param {Function} loader - 异步加载函数，返回 Promise<messages>
+   * 
+   * @example
+   * i18n.registerLoader('ja', () => import('./locales/ja.json'))
+   */
+  registerLoader(locale, loader) {
+    this._loaders[locale] = loader;
+  }
+
+  /**
+   * 懒加载语言包
+   * @param {string} locale - 语言代码
+   */
+  async loadLocale(locale) {
+    if (this._messages[locale] || this._loading.has(locale)) return;
+    const loader = this._loaders[locale];
+    if (!loader) {
+      if (this._debug) console.warn(`[i18n] 无 "${locale}" 加载器`);
+      return;
+    }
+    this._loading.add(locale);
+    try {
+      const messages = await loader();
+      // 兼顾 ES Module default export
+      this.addMessages(locale, messages.default || messages);
+    } catch (err) {
+      console.error(`[i18n] 加载 "${locale}" 失败:`, err);
+    } finally {
+      this._loading.delete(locale);
+    }
+  }
+
+  // ============ 格式化 ============
+
+  /**
+   * 格式化日期
+   * @param {Date|number|string} date - 日期
+   * @param {string} format - 格式名 ('short', 'long', 'full') 或自定义 Intl options
+   */
+  formatDate(date, format = 'short') {
+    const d = date instanceof Date ? date : new Date(date);
+    const presets = {
+      short: {
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit'
+      },
+      long: {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric'
+      },
+      full: {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+        weekday: 'long'
+      },
+      time: {
+        hour: '2-digit',
+        minute: '2-digit'
+      },
+      datetime: {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit'
+      }
+    };
+    const options = typeof format === 'string' ? presets[format] || presets.short : format;
+    return new Intl.DateTimeFormat(this.locale, options).format(d);
+  }
+
+  /**
+   * 格式化数字
+   * @param {number} num - 数字
+   * @param {string|Object} format - 格式名 ('decimal', 'currency', 'percent') 或自定义
+   */
+  formatNumber(num, format = 'decimal') {
+    const presets = {
+      decimal: {},
+      currency: {
+        style: 'currency',
+        currency: 'USD'
+      },
+      percent: {
+        style: 'percent',
+        minimumFractionDigits: 1
+      },
+      compact: {
+        notation: 'compact'
+      }
+    };
+    const options = typeof format === 'string' ? presets[format] || {} : format;
+    return new Intl.NumberFormat(this.locale, options).format(num);
+  }
+
+  /**
+   * 相对时间格式化
+   * @param {Date|number} date - 目标时间
+   */
+  formatRelative(date) {
+    const d = date instanceof Date ? date : new Date(date);
+    const now = Date.now();
+    const diffMs = d.getTime() - now;
+    const absDiff = Math.abs(diffMs);
+    const units = [{
+      unit: 'year',
+      ms: 31536000000
+    }, {
+      unit: 'month',
+      ms: 2592000000
+    }, {
+      unit: 'week',
+      ms: 604800000
+    }, {
+      unit: 'day',
+      ms: 86400000
+    }, {
+      unit: 'hour',
+      ms: 3600000
+    }, {
+      unit: 'minute',
+      ms: 60000
+    }, {
+      unit: 'second',
+      ms: 1000
+    }];
+    for (const {
+      unit,
+      ms
+    } of units) {
+      if (absDiff >= ms) {
+        const value = Math.round(diffMs / ms);
+        try {
+          return new Intl.RelativeTimeFormat(this.locale, {
+            numeric: 'auto'
+          }).format(value, unit);
+        } catch {
+          // Fallback: 简单文本
+          const absVal = Math.abs(value);
+          return diffMs < 0 ? `${absVal} ${unit}(s) ago` : `in ${absVal} ${unit}(s)`;
+        }
+      }
+    }
+    return this.locale.startsWith('zh') ? '刚刚' : 'just now';
+  }
+
+  // ============ 事件监听 ============
+
+  /**
+   * 监听语言变更
+   * @param {Function} callback - (newLocale, oldLocale) => void
+   * @returns {Function} 取消监听函数
+   */
+  onChange(callback) {
+    this._listeners.push(callback);
+    return () => {
+      this._listeners = this._listeners.filter(f => f !== callback);
+    };
+  }
+
+  // ============ 内部方法 ============
+
+  /** 检测浏览器语言偏好 */
+  _detectBrowserLanguage() {
+    // 先查 localStorage
+    try {
+      const saved = localStorage.getItem('qbit_locale');
+      if (saved) return saved;
+    } catch {}
+
+    // 浏览器语言
+    const lang = navigator.language || navigator.userLanguage;
+    return lang;
+  }
+
+  /** 嵌套键路径取值 (e.g. 'nav.home' → messages.nav.home) */
+  _getNestedValue(obj, key) {
+    if (!obj || !key) return undefined;
+
+    // 先精确匹配
+    if (obj[key] !== undefined) return obj[key];
+
+    // 嵌套路径
+    const parts = key.split('.');
+    let current = obj;
+    for (const part of parts) {
+      if (current === null || current === undefined || typeof current !== 'object') {
+        return undefined;
+      }
+      current = current[part];
+    }
+    return current;
+  }
+
+  /** 参数插值 {name} → value */
+  _interpolate(template, params) {
+    return template.replace(/\{(\w+)\}/g, (match, key) => {
+      return params[key] !== undefined ? params[key] : match;
+    });
+  }
+
+  /** 复数解析 */
+  _resolvePlural(obj, count) {
+    if (count === 0 && obj.zero) return obj.zero;
+    if (count === 1 && obj.one) return obj.one;
+    if (obj.other) return obj.other;
+    // 中文通常不区分单复数
+    return obj.other || obj.one || Object.values(obj)[0] || '';
+  }
+
+  /** 深合并对象 */
+  _deepMerge(target, source) {
+    const result = {
+      ...target
+    };
+    for (const key of Object.keys(source)) {
+      if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key]) && result[key] && typeof result[key] === 'object' && !Array.isArray(result[key])) {
+        result[key] = this._deepMerge(result[key], source[key]);
+      } else {
+        result[key] = source[key];
+      }
+    }
+    return result;
+  }
+
+  /** 重置 */
+  reset() {
+    this._messages = {};
+    this._listeners = [];
+    this._loading.clear();
+    this.locale = this._fallback;
+  }
+
+  // ============ 隐私合规 ============
+
+  /**
+   * 清除用户语言偏好 — GDPR 本地数据清理
+   * 仅清除 localStorage 中的语言偏好记录
+   */
+  clearUserPreference() {
+    if (typeof localStorage !== 'undefined') {
+      localStorage.removeItem('qbit_locale');
+    }
+    this.locale = this._fallback;
+    // 恢复 HTML 属性
+    if (typeof document !== 'undefined') {
+      document.documentElement.lang = this._fallback;
+      document.documentElement.dir = 'ltr';
+    }
+    return true;
+  }
+
+  /**
+   * 获取隐私数据声明
+   */
+  getDataDisclosure() {
+    return {
+      sdk: '@quantabit/i18n-sdk',
+      privacyLevel: 'essential',
+      consentRequired: false,
+      collected: [{
+        type: 'locale_preference',
+        description: 'User language choice (e.g. "en", "zh")',
+        retention: 'Until cleared',
+        storage: 'localStorage'
+      }],
+      note: 'Language preference is essential for UI rendering and does not contain PII.',
+      gdprCapabilities: ['delete']
+    };
+  }
+}
+
+/**
+ * I18n SDK - 国际化
+ */
+
+const zh = {
+  i18n: {
+    title: '语言设置',
+    currentLanguage: '当前语言',
+    languages: {
+      zh: '简体中文',
+      en: 'English',
+      ja: '日本語',
+      ko: '한국어'
+    },
+    actions: {
+      change: '切换语言',
+      save: '保存'
+    },
+    messages: {
+      changed: '语言已切换'
+    }
+  }
+};
+const en = {
+  i18n: {
+    title: 'Language Settings',
+    currentLanguage: 'Current Language',
+    languages: {
+      zh: '简体中文',
+      en: 'English',
+      ja: '日本語',
+      ko: '한국어'
+    },
+    actions: {
+      change: 'Change Language',
+      save: 'Save'
+    },
+    messages: {
+      changed: 'Language changed'
+    }
+  }
+};
+var i18nMessages = {
+  zh,
+  en
+};
+
+const I18nContext = /*#__PURE__*/React.createContext(null);
+function I18nProvider({
+  messages = {},
+  defaultLocale = 'en',
+  fallbackLocale = 'en',
+  children
+}) {
+  const manager = React.useMemo(() => new I18nManager({
+    messages,
+    defaultLocale,
+    fallbackLocale
+  }), []);
+  const [locale, setLocaleState] = React.useState(defaultLocale);
+  React.useEffect(() => {
+    return manager.onChange(l => setLocaleState(l));
+  }, [manager]);
+  const setLocale = React.useCallback(l => manager.setLocale(l), [manager]);
+  const t = React.useCallback((key, params) => manager.t(key, params), [locale, manager]);
+  const value = React.useMemo(() => ({
+    locale,
+    setLocale,
+    t,
+    availableLocales: manager.availableLocales,
+    manager
+  }), [locale, setLocale, t, manager]);
+  return /*#__PURE__*/React.createElement(I18nContext.Provider, {
+    value: value
+  }, children);
+}
+function useI18n() {
+  return React.useContext(I18nContext);
+}
+function useTranslation() {
+  const ctx = React.useContext(I18nContext);
+  return ctx?.t || (k => k);
+}
+
+const FLAGS = {
+  en: '🇬🇧',
+  zh: '🇨🇳',
+  ja: '🇯🇵',
+  ko: '🇰🇷',
+  es: '🇪🇸',
+  fr: '🇫🇷',
+  de: '🇩🇪',
+  pt: '🇧🇷',
+  ru: '🇷🇺',
+  ar: '🇸🇦'
+};
+function LanguageSwitcher({
+  variant = 'dropdown',
+  showFlag = true,
+  showLabel = true,
+  className = ''
+}) {
+  const {
+    locale,
+    setLocale,
+    availableLocales
+  } = useI18n() || {};
+  if (!availableLocales) return null;
+  if (variant === 'pills') {
+    return /*#__PURE__*/React.createElement("div", {
+      className: `qi18n-pills ${className}`,
+      style: {
+        display: 'flex',
+        gap: 4,
+        background: 'rgba(128,128,128,0.06)',
+        borderRadius: 8,
+        padding: 3
+      }
+    }, availableLocales.map(l => /*#__PURE__*/React.createElement("button", {
+      key: l,
+      onClick: () => setLocale(l),
+      style: {
+        padding: '4px 12px',
+        borderRadius: 6,
+        border: 'none',
+        background: l === locale ? '#fff' : 'transparent',
+        color: l === locale ? '#18181b' : '#71717a',
+        fontSize: 13,
+        fontWeight: l === locale ? 600 : 400,
+        cursor: 'pointer',
+        boxShadow: l === locale ? '0 1px 3px rgba(0,0,0,0.1)' : 'none',
+        transition: 'all 0.2s'
+      }
+    }, showFlag && FLAGS[l] && /*#__PURE__*/React.createElement("span", {
+      style: {
+        marginRight: 4
+      }
+    }, FLAGS[l]), showLabel && l.toUpperCase())));
+  }
+  return /*#__PURE__*/React.createElement("select", {
+    value: locale,
+    onChange: e => setLocale(e.target.value),
+    className: `qi18n-select ${className}`,
+    style: {
+      padding: '6px 12px',
+      borderRadius: 8,
+      border: '1px solid #e4e4e7',
+      fontSize: 13,
+      cursor: 'pointer',
+      background: '#fff'
+    }
+  }, availableLocales.map(l => /*#__PURE__*/React.createElement("option", {
+    key: l,
+    value: l
+  }, FLAGS[l] || '', " ", l.toUpperCase())));
+}
+
+// SUPPORTED_LANGUAGES
+const SUPPORTED_LANGUAGES = ['en', 'zh', 'ja', 'ko'];
+
+// Singleton Instance
+const i18n = new I18nManager({
+  defaultLocale: 'zh',
+  fallbackLocale: 'en',
+  messages: i18nMessages
+});
+
+// Shortcut methods wrapped safely
+const t = (key, params) => i18n.t(key, params);
+const setLanguage = locale => i18n.setLocale(locale);
+const getLanguage = () => i18n.currentLocale;
+const formatDate = (date, format) => i18n.formatDate(date, format);
+const formatNumber = (num, format) => i18n.formatNumber(num, format);
+const formatCurrency = (num, currency = 'USD') => i18n.formatNumber(num, {
+  style: 'currency',
+  currency
+});
+
+exports.I18nManager = I18nManager;
+exports.I18nProvider = I18nProvider;
+exports.LanguageSwitcher = LanguageSwitcher;
+exports.SUPPORTED_LANGUAGES = SUPPORTED_LANGUAGES;
+exports.formatCurrency = formatCurrency;
+exports.formatDate = formatDate;
+exports.formatNumber = formatNumber;
+exports.getLanguage = getLanguage;
+exports.i18n = i18n;
+exports.setLanguage = setLanguage;
+exports.t = t;
+exports.useI18n = useI18n;
+exports.useTranslation = useTranslation;
+//# sourceMappingURL=index.cjs.map