@xiaonoodles/meetfun-i18n 1.2.14

package/dist/index.d.ts

@@ -0,0 +1,348 @@
+import { I18n } from 'vue-i18n';
+
+/**
+ * 语言包缓存数据接口
+ */
+interface LangDictCacheData {
+    /** 缓存时间戳 */
+    timestamp: number;
+    /** 语言包版本号 */
+    version: string;
+    /** 语言包数据 */
+    data: LangDictResponse;
+}
+/**
+ * 领域代码字典键
+ */
+interface DomainCodeDictKey {
+    /** 缺失的字典key列表 */
+    missingDictKeyList: string[];
+    /** 领域编码，必填 */
+    domainCode: string;
+    /** 已使用的字典key列表 */
+    usedDictKeyList: string[];
+}
+/**
+ * 查询冷数据参数
+ */
+interface QueryLangDictColdDataParams {
+    langDictColdDataCmdList: DomainCodeDictKey[];
+}
+/**
+ * 系统语言包数据
+ */
+interface SystemLangDict {
+    [dictKey: string]: string;
+}
+/**
+ * 语言包数据
+ */
+interface LangDictData {
+    [systemCode: string]: SystemLangDict;
+}
+/**
+ * 完整的语言包响应数据
+ */
+interface LangDictResponse {
+    [langCode: string]: LangDictData;
+}
+/**
+ * 缺失键缓存机制配置
+ */
+interface MissingKeyCache {
+    [domainCode: string]: Set<string>;
+}
+/**
+ * 已使用键缓存机制配置
+ */
+interface UsedKeyCache {
+    [domainCode: string]: Set<string>;
+}
+/**
+ * 语言配置枚举
+ */
+declare enum LANGUAGE_OPTIONS_CONFIGURATION {
+    FOLLOW_SYSTEM = "followSystem",
+    EN = "en",
+    ZH_HANS = "zh-Hans",
+    ZH_HANT = "zh-Hant"
+}
+type LanguageOptionsConfigurationType = `${LANGUAGE_OPTIONS_CONFIGURATION}`;
+/**
+ * 语言切换钩子函数参数
+ */
+interface LocaleChangedPayload {
+    /** 目标语言代码 */
+    targetLocale: string;
+    /** 目标语言的语言包数据 */
+    messages: any;
+}
+/**
+ * 国际化配置选项
+ */
+interface I18nConfig {
+    /** 默认语言 */
+    defaultLocale?: string;
+    /** 默认领域代码 */
+    defaultLangDictDomainCode?: string;
+    /** 语言代码映射 */
+    localeMap?: Record<string, string>;
+    /** 缓存键名 */
+    localeCacheKey?: string;
+    /** 语言包缓存键名 */
+    langDictCacheKey?: string;
+    /** 缓存最大有效期（毫秒），默认365天 */
+    cacheMaxAge?: number;
+    /** 上报延迟时间（毫秒），默认5000ms */
+    reportDelay?: number;
+    /** 系统代码（用于获取语言包） */
+    systemCode?: string;
+    /** 语言切换钩子函数 */
+    onLocaleChanged?: (payload: LocaleChangedPayload) => void;
+    /** 是否启用调试模式，默认false */
+    debug?: boolean;
+    /** 已上报键缓存最大数量，默认10000，0表示不限制 */
+    maxReportedKeysCache?: number;
+}
+/**
+ * 变量替换配置选项
+ */
+interface InterpolateOptions {
+    /** 是否在替换失败时返回原始占位符，默认 true */
+    fallbackToOriginal?: boolean;
+    /** 是否记录警告日志，默认 true */
+    logWarnings?: boolean;
+    /** 是否转义HTML，默认 false */
+    escapeHtml?: boolean;
+}
+/**
+ * 国际化代理类配置
+ */
+interface I18nProxyConfig {
+    /** 是否在找不到翻译时返回原始键值 */
+    fallbackToKey?: boolean;
+    /** 是否启用调试日志 */
+    debug?: boolean;
+}
+/**
+ * API 请求函数类型
+ */
+interface ApiRequestFunction<T = any> {
+    post<R = T>(url: string, data?: any, config?: any): Promise<{
+        data: R;
+    }>;
+}
+/**
+ * 获取语言包热数据的 API 函数类型
+ */
+type QueryLangDictHotDataFunction = (params: {
+    systemCode: string;
+}) => Promise<{
+    data: LangDictResponse;
+}>;
+/**
+ * 获取语言包冷数据的 API 函数类型
+ */
+type QueryLangDictColdDataFunction = (params: QueryLangDictColdDataParams) => Promise<{
+    data: LangDictResponse;
+}>;
+/**
+ * API 函数配置
+ */
+interface ApiConfig {
+    /** 获取热数据的 API 函数 */
+    queryLangDictHotData: QueryLangDictHotDataFunction;
+    /** 获取冷数据的 API 函数 */
+    queryLangDictColdData: QueryLangDictColdDataFunction;
+}
+/**
+ * 翻译键统计信息
+ */
+interface TranslationKeysStats {
+    missingKeys: {
+        [domainCode: string]: number;
+    };
+    usedKeys: {
+        [domainCode: string]: number;
+    };
+}
+
+/**
+ * MeetFun I18n 实例
+ */
+declare class MeetFunI18n {
+    private config;
+    private i18n;
+    private cacheManager;
+    private translateManager;
+    constructor(baseMessages: Record<string, any>, apiConfig: ApiConfig, userConfig?: Partial<I18nConfig>);
+    /**
+     * 获取初始语言设置
+     */
+    private getInitialLocale;
+    /**
+     * 获取 i18n 实例
+     */
+    getI18n(): I18n;
+    /**
+     * 翻译函数
+     */
+    $t: (key: string, params?: any) => string;
+    /**
+     * 获取语言包热数据
+     */
+    fetchLangDictHotData: () => Promise<void>;
+    /**
+     * 更新国际化语言包
+     */
+    updateI18nMessages: (langDictData: any, saveToCache?: boolean) => Promise<void>;
+    /**
+     * 切换语言
+     */
+    switchLocale: (locale: any) => void;
+    /**
+     * 获取当前语言
+     */
+    getCurrentLocale: () => string;
+    /**
+     * 获取 i18n 语言标识
+     */
+    getI18nLang: () => string;
+    /**
+     * 获取请求头语言标识
+     */
+    getHeaderLang: () => string;
+    /**
+     * 立即上报缺失键
+     */
+    flushMissingKeys: () => Promise<void>;
+    /**
+     * 获取翻译键统计信息
+     */
+    getTranslationKeysStats: () => TranslationKeysStats & {
+        reportedKeys?: {
+            [domainCode: string]: number;
+        };
+    };
+    /**
+     * 检查语言包是否存在
+     */
+    hasLocale: (locale: string) => boolean;
+    /**
+     * 变量替换
+     */
+    interpolateVariables: (template: string, params?: any, options?: any) => string;
+    /**
+     * 获取缓存的语言设置
+     */
+    getCachedLocale: () => string | null;
+    /**
+     * 保存语言设置到缓存
+     */
+    saveLocaleToCache: (locale: string) => void;
+    /**
+     * 清除语言包缓存
+     */
+    clearLangDictCache: () => void;
+    /**
+     * 清空已上报键缓存
+     */
+    clearReportedKeysCache: () => void;
+    /**
+     * 获取缓存内存使用情况（用于监控和调试）
+     */
+    getCacheMemoryInfo: () => {
+        reportedKeysCount: number;
+        maxReportedKeysCache: number;
+        usagePercentage: number;
+        missingKeysCount: number;
+        usedKeysCount: number;
+    };
+    /**
+     * 创建国际化代理对象
+     * 用于创建一个对象，当访问属性时自动通过翻译函数进行国际化转换
+     *
+     * @param data 原始数据对象
+     * @param config 配置选项
+     * @returns 代理对象
+     *
+     * @example
+     * ```typescript
+     * const roleNames = i18nInstance.createI18nProxy({
+     *   PRODUCING_AREA: 'role.PRODUCING_AREA',
+     *   PRESENTATION_AREA: 'role.PRESENTATION_AREA'
+     * })
+     *
+     * // 访问时会自动调用翻译函数
+     * console.log(roleNames.PRODUCING_AREA)
+     * console.log(roleNames['PRODUCING_AREA'])
+     * ```
+     */
+    createI18nProxy: <T extends Record<string, string>>(data: T, config?: I18nProxyConfig) => T;
+    /**
+     * 创建枚举类型的国际化代理
+     * 专门用于处理枚举值到翻译键的映射
+     *
+     * @param enumObject 枚举对象
+     * @param config 额外配置
+     * @returns 代理对象
+     *
+     * @example
+     * ```typescript
+     * const statusEnum = i18nInstance.createEnumI18nProxy({
+     *   ACTIVE: 'status.active',
+     *   INACTIVE: 'status.inactive'
+     * })
+     * ```
+     */
+    createEnumI18nProxy: <T extends Record<string, string>>(enumObject: T, config?: I18nProxyConfig) => T;
+}
+/**
+ * 创建 MeetFun I18n 实例的工厂函数
+ *
+ * @param baseMessages 基础语言包
+ * @param apiConfig API 配置
+ * @param userConfig 用户配置
+ * @returns MeetFunI18n 实例
+ *
+ * @example
+ * ```typescript
+ * import { createMeetFunI18n } from '@meetfun/i18n'
+ * import zhHans from './locales/zh-Hans.json'
+ * import zhHant from './locales/zh-Hant.json'
+ * import en from './locales/en.json'
+ * import { queryLangDictHotData, queryLangDictColdData } from './api/translate'
+ *
+ * const baseMessages = {
+ *   'zh-Hans': zhHans,
+ *   'zh-Hant': zhHant,
+ *   en: en,
+ * }
+ *
+ * const apiConfig = {
+ *   queryLangDictHotData,
+ *   queryLangDictColdData,
+ * }
+ *
+ * const i18nInstance = createMeetFunI18n(baseMessages, apiConfig, {
+ *   defaultLocale: 'zh-Hans',
+ *   defaultLangDictDomainCode: 'TALENTS',
+ *   systemCode: 'TALENTS_STUDENT',
+ *   debug: true, // 启用调试模式，会输出详细日志
+ *   onLocaleChanged: (payload) => {
+ *     console.log('语言已切换:', payload.targetLocale)
+ *     // 可以在这里执行其他需要的操作
+ *   }
+ * })
+ *
+ * // 在 main.ts 中安装
+ * app.use(i18nInstance.getI18n())
+ *
+ * // 使用翻译函数
+ * const text = i18nInstance.$t('welcomeMessage')
+ * ```
+ */
+declare function createMeetFunI18n(baseMessages: Record<string, any>, apiConfig: ApiConfig, userConfig?: Partial<I18nConfig>): MeetFunI18n;
+
+export { LANGUAGE_OPTIONS_CONFIGURATION, MeetFunI18n, createMeetFunI18n, createMeetFunI18n as default };
+export type { ApiConfig, ApiRequestFunction, DomainCodeDictKey, I18nConfig, I18nProxyConfig, InterpolateOptions, LangDictCacheData, LangDictData, LangDictResponse, LanguageOptionsConfigurationType, LocaleChangedPayload, MissingKeyCache, QueryLangDictColdDataFunction, QueryLangDictColdDataParams, QueryLangDictHotDataFunction, SystemLangDict, TranslationKeysStats, UsedKeyCache };