UNPKG

@voerkai18n/runtime

Version:
656 lines (625 loc) 24.5 kB
import * as flexvars from 'flexvars'; import { FlexFilter, FlexVars } from 'flexvars'; import * as ts_mixer_dist_types_types from 'ts-mixer/dist/types/types'; import { LiteEvent, LiteEventListener, LiteEventSubscriber } from 'flex-tools/events/liteEvent'; import { IAsyncSignal } from 'flex-tools/async/asyncSignal'; import { IAsyncSignal as IAsyncSignal$1 } from 'asyncsignal'; import { BCP47LanguageTagName } from 'bcp47-language-tags'; type VoerkaI18nLoggerLevels = 'warn' | 'error' | 'info' | 'debug'; type VoerkaI18nLogger = { [key in VoerkaI18nLoggerLevels]: (message: string, ...args: any[]) => void; }; type VoerkaI18nLoggerOutput = (level: VoerkaI18nLoggerLevels, message: string) => void; /** * * 事件发射器混入 * */ declare class EventEmitterMixin { private _eventEmitter; protected _getEventEmitter(this: VoerkaI18nScope): LiteEvent<VoerkaI18nEvents>; on(this: VoerkaI18nScope, event: keyof VoerkaI18nEvents, callback: VoerkaI18nEventListener): VoerkaI18nEventSubscriber; once(this: VoerkaI18nScope, event: keyof VoerkaI18nEvents, callback: VoerkaI18nEventListener): VoerkaI18nEventSubscriber; off(this: VoerkaI18nScope, event: keyof VoerkaI18nEvents, callback: VoerkaI18nEventListener): void; waitFor(this: VoerkaI18nScope, event: keyof VoerkaI18nEvents, timeout?: number): Promise<any>; emit(this: VoerkaI18nScope, event: keyof VoerkaI18nEvents, payload?: any, retain?: boolean): Promise<any>; } /** * 语言包补丁 * */ declare class PatchMessageMixin { protected _patching: IAsyncSignal | undefined; private _getPatchKey; /** * 清除保存在本地的补丁语言包 * @param language */ clearPatchedMessages(this: VoerkaI18nScope, language?: string): void; /** * 当指定了默认语言包加载器后,会从服务加载语言补丁包来更新本地的语言包 * * 补丁包会自动存储到本地的LocalStorage中 * * @param {*} messages * @param {*} language * @returns {Promise<number>} 返回补丁包的数量 */ protected _patch(this: VoerkaI18nScope, language?: string): Promise<void>; /** * 从本地存储中读取语言包补丁合并到当前语言包中 */ protected _restorePatchedMessages(this: VoerkaI18nScope, messages: VoerkaI18nLanguageMessages, language: string): void; /** * 将读取的补丁包保存到本地的LocalStorage中 * * 为什么要保存到本地的LocalStorage中? * * 因为默认语言是静态嵌入到源码中的,而加载语言包补丁是延后异步的, * 当应用启动第一次就会渲染出来的是没有打过补丁的内容。 * * - 如果还需要等待从服务器加载语言补丁合并后再渲染会影响速度 * - 如果不等待从服务器加载语言补丁就渲染,则会先显示未打补丁的内容,然后在打完补丁后再对应用进行重新渲染生效 * 这明显不是个好的方式 * * 因此,采用的方式是: * - 加载语言包补丁后,将之保存到到本地的LocalStorage中 * - 当应用加载时会查询是否存在补丁,如果存在就会合并渲染 * * @param {*} messages */ protected _setPatchedMessages(this: VoerkaI18nScope, messages: VoerkaI18nLanguageMessages, language: string): void; /** * 从本地缓存中读取补丁语言包 * @param {*} language * @returns */ protected _getPatchedMessages(this: VoerkaI18nScope, language: string): any; } /** * * * 加载语言包 * */ declare class ChangeLanguageMixin { protected _refreshSignal?: IAsyncSignal$1; /** * 刷新语言包 * @param language */ refresh(this: VoerkaI18nScope, language?: string, options?: { fallback?: boolean; patch: boolean; }): Promise<string>; /** * * 通过加载器从远程加载指定语言的语言包 * * - 简单的对象{} * - 或者是一个返回Promise<VoerkaI18nLanguageMessages>的异步函数 * - 或者是全局的默认加载器 * * @param language 语言名称 * @returns */ private _loadLanguageMessages; /** * * 从远程加载信息包 * * @param this * @param language */ protected _loadMessagesFromLoader(this: VoerkaI18nScope, language: string): Promise<void | VoerkaI18nLanguageMessages>; /** * * - 如果正在刷新语言包,则等待刷新完成 * * i18nScope.ready(callback,timeout) * * @param this * @returns */ ready(this: VoerkaI18nScope, timeout?: number): Promise<void>; ready(this: VoerkaI18nScope, callback: (activeLanguage: string) => void, timeout?: number): void; /** * await changing() * * @param this * @param timeout * @returns */ changing(this: VoerkaI18nScope, timeout?: number): Promise<void>; } /** * * * formatters:{ * x1:(value,args,context)=>{ return value} * x2:VoerkaI18nFormatter * x3:VoerkaI18nFormatterBuilder * $options: { // 对原有的formatters进行配置 * en:{}, * zh:{} * } * } * * * * */ type VoerkaI18nFormatterContext<Config extends Dict = Dict> = { getConfig: () => Config; scope: VoerkaI18nScope; }; type VoerkaI18nFormatter<Args extends Dict = Dict, Config extends Dict = Args> = FlexFilter<Args, VoerkaI18nFormatterContext<Config>> & { global?: boolean; }; type VoerkaI18nFormatterName = string; interface VoerkaI18nFormatterConfig extends Record<VoerkaI18nFormatterName, Record<string, any>> { } interface VoerkaI18nFormatterBuilder<Args extends Dict = Dict, Config extends Dict = Args> { (scope: VoerkaI18nScope): VoerkaI18nFormatter<Args, Config>; } type VoerkaI18nFormatters = any[][]; /** * * 保存所有格式化器数据 * */ interface VoerkaI18nScopeCache { activeLanguage: string | null; typedFormatters: VoerkaI18nFormatters; formatters: VoerkaI18nFormatters; } declare class FormattersNotLoadedError extends Error { constructor(language: string); } declare class VoerkaI18nFormatterManager { private _formatters; private _scope; constructor(scope: VoerkaI18nScope); get scope(): VoerkaI18nScope<any, any>; get formatters(): VoerkaI18nFormatters; /** * 加载所有格式化器 */ private _registerFormatters; private _addFormatter; register<Args extends Dict, Config extends Dict = Args>(formatter: VoerkaI18nFormatter<Args, Config>, configs?: Partial<Record<LanguageName, Partial<Config>>>, defaultConfig?: Partial<Config>): void; } declare class LanguageMixin { /** * 获取指定语言信息 * @param {*} language * @returns */ getLanguage(this: VoerkaI18nScope, language: string): VoerkaI18nLanguage | undefined; /** * 获取指定语言的备用语言。如果指定的语言存在备用语言选项,则返回该备用语言;否则返回默认语言。 * @param this - VoerkaI18nScope 实例 * @param language - 需要获取备用语言的目标语言代码 * @returns 返回备用语言代码或默认语言代码 */ getFallbackLanguage(this: VoerkaI18nScope, language: string): string; /** * 返回是否存在指定的语言 * @param {*} language 语言名称 * @returns */ hasLanguage(this: VoerkaI18nScope, language: string): boolean; } declare class TranslateMixin { /** * 根据值的单数和复数形式,从messages中取得相应的消息 * * @param {*} messages 复数形式的文本内容 = [<=0时的内容>,<=1时的内容>,<=2时的内容>,...,<>=N的内容>] * @param {*} value */ private _getPluraMessage; private _getPluraValue; /** * 翻译组件 * */ protected _getTranslateComponent(this: VoerkaI18nScope): any; protected _getTranslateTransformer(this: VoerkaI18nScope): any; private _getActiveMessages; translate<R = string>(this: VoerkaI18nScope, message: string, vars?: VoerkaI18nTranslateVars, options?: VoerkaI18nTranslateOptions): R; } declare class RestoreMixin { private _getStorage; /** * * @param this */ private _getStorageKey; /** * 从存储器加载语言配置 */ restoreLanguage(this: VoerkaI18nScope): void; /** * * 将当前语言保存到Storage * */ saveLanguage(this: VoerkaI18nScope): void; clearLanguage(this: VoerkaI18nScope): void; } declare class InterpolatorMixin { protected _flexVars?: FlexVars<VoerkaI18nFormatterContext>; protected _initInterpolators(this: VoerkaI18nScope): void; } interface VoerkaI18nScopeOptions<TranslateComponent = any, TranslateTransformResult = any> { id?: string; debug?: boolean; library?: boolean; languages: VoerkaI18nLanguage[]; fallback?: string; messages: VoerkaI18nLanguageMessagePack; paragraphs: VoerkaI18nParagraphs; idMap?: Voerkai18nIdMap; storage?: IVoerkaI18nStorage; formatters?: VoerkaI18nFormatters; log?: VoerkaI18nLoggerOutput; attached?: boolean; storageKey?: string; loader?: VoerkaI18nLanguageLoader; cachePatch?: boolean; injectLangAttr?: boolean | string; namespaces?: Record<string, string>; patterns?: string[]; component?: VoerkaI18nTranslateComponentBuilder<TranslateComponent>; transform?: VoerkaI18nTranslateTransformBuilder<TranslateTransformResult>; onTranslated?: (result: string) => string; } declare const VoerkaI18nScope_base: ts_mixer_dist_types_types.Class<any[], EventEmitterMixin & PatchMessageMixin & ChangeLanguageMixin & LanguageMixin & TranslateMixin & InterpolatorMixin & RestoreMixin, typeof EventEmitterMixin & typeof PatchMessageMixin & typeof ChangeLanguageMixin & typeof LanguageMixin & typeof TranslateMixin & typeof InterpolatorMixin & typeof RestoreMixin>; declare class VoerkaI18nScope<TranslateComponent = any, TranslateTransformResult = any> extends VoerkaI18nScope_base { __VoerkaI18nScope__: boolean; static idSeq: number; private _options; private _manager; private _formatterManager; private _logger; protected _defaultLanguage: string; protected _activeLanguage: string; protected _activeMessages: VoerkaI18nLanguageMessages; protected _patchedMessages: VoerkaI18nLanguagePack; protected _translateComponent?: TranslateComponent; protected _translateTransformer?: VoerkaI18nTranslateTransformer<TranslateTransformResult>; protected _activeParagraphs: VoerkaI18nLanguageParagraphs; $id: number; /** * * @param options */ constructor(options: VoerkaI18nScopeOptions); get id(): string; get options(): Required<VoerkaI18nScopeOptions<TranslateComponent, any>>; get attached(): boolean; get debug(): boolean; get library(): boolean; get formatters(): VoerkaI18nFormatterManager; get defaultLanguage(): string; get defaultMessages(): VoerkaI18nLanguageMessages | VoerkaI18nLanguageLoader | VoerkaI18nLanguageAsyncChunk; get messages(): VoerkaI18nLanguageMessagePack; get paragraphs(): VoerkaI18nParagraphs; get idMap(): Voerkai18nIdMap; get languages(): VoerkaI18nLanguage[]; get manager(): VoerkaI18nManager; get appScope(): VoerkaI18nScope<any, any>; get interpolator(): flexvars.FlexVars<VoerkaI18nFormatterContext>; get logger(): VoerkaI18nLogger; get t(): VoerkaI18nTranslate; set t(t: Function); get Translate(): TranslateComponent; get activeMessages(): VoerkaI18nLanguageMessages; get activeParagraphs(): VoerkaI18nLanguageParagraphs; get activeLanguage(): string; get storage(): IVoerkaI18nStorage | undefined; get loader(): VoerkaI18nLanguageLoader | undefined; get $t(): VoerkaI18nTranslate<TranslateTransformResult>; /** * 有些配置项是以appScope为准 * @param name * @returns */ private getScopeOption; private _initOptions; /** * 对输入的语言配置进行处理 * - 将en配置为默认回退语言 * - 确保提供了有效的默认语言和活动语言 */ private _init; /** * * 当scope上在全局应用scope创建之后时,会调用此方法 * 本方法在注册到全局VoerkaI18nManager时由Manager调用, * * 注意:本方法仅当 * scope是在全局应用scope创建之前时才会调用 * * 如果scope是在全局应用scope创建之后时创建的,则不会调用此方法 * 因为此时scope会直接注册到全局VoerkaI18nManager中,不会保存到全局变量__VoerkaI18nScopes__中 * * @param manager * @returns */ bind(manager: VoerkaI18nManager): void; /** * 第一次初始化时刷新语言 */ private _initRefresh; /** * 注册当前作用域到全局作用域 * @param callback */ private registerToManager; change(language: string): Promise<string>; /** * 检查当前环境是是否是在浏览器环境中,如果是,则在body上添加language=<activeLanguage>属性 */ protected _setLanguageAttr(): void; /** * * @param message * @returns */ getRawMessage(message: string): any; getMessageId(message: any): any; } /** * 多语言管理类 * * 当导入编译后的多语言文件时(import("./languages")),会自动生成全局实例VoerkaI18n * * VoerkaI18n.languages // 返回支持的语言列表 * VoerkaI18n.defaultLanguage // 默认语言 * VoerkaI18n.language // 当前语言 * VoerkaI18n.change(language) // 切换到新的语言 * * * VoerkaI18n.on("change",(language)=>{}) // 注册语言切换事件 * VoerkaI18n.off("change",(language)=>{}) * * */ declare class VoerkaI18nManager extends LiteEvent<VoerkaI18nEvents> { __VoerkaI18nManager__: boolean; static instance?: VoerkaI18nManager; private _scopes; private _appScope; constructor(appScope?: VoerkaI18nScope); get debug(): boolean; get logger(): VoerkaI18nLogger; get scopes(): VoerkaI18nScope<any, any>[]; get activeLanguage(): string; get defaultLanguage(): string; get loader(): VoerkaI18nLanguageLoader | undefined; get storage(): IVoerkaI18nStorage | undefined; get languages(): VoerkaI18nLanguage[]; get scope(): VoerkaI18nScope<any, any>; /** * 注册所有i18nScope作用域。 * 该方法会检查全局对象中的 `__VoerkaI18nScopes__` 属性, * 如果该属性存在且为数组,则遍历数组并注册每个作用域。 * 这是内部实现细节,不对外暴露。 */ private _registerScopes; getScope(id: string | undefined | null): VoerkaI18nScope<any, any> | undefined; private _loadPlugins; registerPlugin(plugin: VoerkaI18nPlugin): void; /** * 将应用Scope注册到管理器中 */ private _registerAppScope; /** * * 注册一个新的作用域 * * 每一个库均对应一个作用域,每个作用域可以有多个语言包,且对应一个翻译函数 * 除了默认语言外,其他语言采用动态加载的方式 * * @param {*} scope */ register(scope: VoerkaI18nScope): void; /** * 切换语言 */ change(language: string): Promise<string>; /** * 当切换语言时调用此方法来加载更新语言包 * @param {*} newLanguage */ private _refreshScopes; /** * 刷新所有作用域 */ refresh(): Promise<void>; /** * 等待管理器初始化完成 * * @returns */ ready(callback: (language: string) => void, timeout?: number): Promise<void>; /** * 清除所有作用域的翻译补丁信息 */ clearPatchedMessages(): void; /** * 返回是否存在指定的语言 * @param {*} language 语言名称 * @returns */ hasLanguage(language: string): boolean; clearLanguage(): void; saveLanguage(): void; restoreLanguage(): void; } type SupportedDateTypes = "String" | "Number" | "Boolean" | "Object" | "Array" | "Function" | "Error" | "Symbol" | "RegExp" | "Date" | "Null" | "Undefined" | "Set" | "Map" | "WeakSet" | "WeakMap"; type VoerkaI18nLanguageMessages = Record<string, string | string[] | VoerkaI18nFormatterConfig | boolean>; type VoerkaI18nLanguageMessagePack = Record<LanguageName, VoerkaI18nLanguageMessages | VoerkaI18nLanguageLoader | VoerkaI18nLanguageAsyncChunk>; type VoerkaI18nLanguageAsyncChunk = () => Promise<any>; type VoerkaI18nDynamicLanguageMessages = Record<string, string | string[]> & { $config?: VoerkaI18nFormatterConfig; }; interface VoerkaI18nLanguagePack { [language: string]: VoerkaI18nLanguageMessages; } type Voerkai18nIdMap = Record<string, number>; type VoerkaI18nToBeTranslatedMessage = string | ((language: string, vars?: VoerkaI18nTranslateVars, options?: VoerkaI18nTranslateOptions) => string | Promise<string>); interface VoerkaI18nLanguage { name: string; title?: string; nativeTitle?: string; default?: boolean; active?: boolean; fallback?: string; } interface IVoerkaI18nStorage { get(key: string): any; set(key: string, value: any): void; remove(key: string): any; } type VoerkaI18nNamespaces = Record<string, string | string[] | ((file: string) => boolean)>; type VoerkaI18nLanguageLoader = (newLanguage: string, scope: VoerkaI18nScope) => Promise<VoerkaI18nLanguageMessages | undefined | void>; type VoerkaI18nTranslateOptions = { language?: LanguageCodes; transform?: boolean; }; type VoerkaI18nTranslateVars = Record<string, any> | number | boolean | string | (number | boolean | string)[] | (() => VoerkaI18nTranslateVars); type VoerkaI18nTranslate<R = string> = (message: string, vars?: VoerkaI18nTranslateVars, options?: VoerkaI18nTranslateOptions) => R; interface VoerkaI18nSupportedLanguages { [key: string]: VoerkaI18nLanguage; } type VoerkaI18nPlugin = (manager: VoerkaI18nManager) => void; type LanguageName = string; declare global { export var VoerkaI18n: VoerkaI18nManager; export var __VoerkaI18nScopes__: VoerkaI18nScope[]; export var __VoerkaI18nPlugins__: VoerkaI18nPlugin[]; } type VoerkaI18nEvents = { log: { level: string; message: string; }; init: () => string; ready: string; change: string; restore: { scope: string; language: string; }; patched: { scope: string; language: string; }; error: Error; "scope/change": { scope: string; language: string; }; "scope/fallback": { scope: string; from: string; to: string; }; }; type Dict<T = any> = Record<string, T>; type LanguageCodes = BCP47LanguageTagName; type VoerkaI18nSettings = { entry?: string; readonly defaultLanguage: string; readonly activeLanguage: string; } & Omit<VoerkaI18nScopeOptions, 'storage' | 'idMap' | 'formatters' | 'log' | 'attached' | 'loader' | 'messages'>; type VoerkaI18nLanguageParagraphs = Record<string, any>; type VoerkaI18nParagraphs = Record<LanguageName, Record<string, VoerkaI18nLanguageParagraphs>>; type VoerkaI18nTranslateProps<Options extends VoerkaI18nTranslateOptions = VoerkaI18nTranslateOptions, Children = any> = { id?: string; message?: VoerkaI18nToBeTranslatedMessage; vars?: VoerkaI18nTranslateVars; default?: any; tag?: string; options?: Options; children?: Children; style?: any; className?: string; }; type VoerkaI18nTranslateComponentBuilder<Component = any> = (scope: VoerkaI18nScope) => Component; type VoerkaI18nTranslateTransformer<R> = (result: string, vars?: VoerkaI18nTranslateVars, options?: VoerkaI18nTranslateOptions) => R; type VoerkaI18nTranslateTransformBuilder<R> = (scope: VoerkaI18nScope) => VoerkaI18nTranslateTransformer<R>; type VoerkaI18nEventListener = LiteEventListener; type VoerkaI18nEventSubscriber = LiteEventSubscriber; declare function getId(): string; /** * 文本id必须是一个数字 * @param {*} content * @returns */ declare function isMessageId(content: string): boolean; declare function isI18nScope(obj: any): any; declare function loadAsyncModule(this: any, module: Function): Promise<any>; declare function isStorage(obj: any): obj is IVoerkaI18nStorage; /** * 异步执行一组Promise,并返回所有Promise的结果 * * 该函数会处理所有Promise,无论成功或失败都会返回结果。 * 如果环境支持Promise.allSettled,则直接使用; * 否则会手动包装每个Promise,确保不会抛出未捕获的异常。 * * @template T Promise的返回值类型 * @param {Promise<T>[]} promises 要执行的Promise数组 * @returns {Promise<(T | Error)[]>} 返回一个Promise,resolve为包含所有结果的数组, * 每个元素要么是Promise的返回值,要么是Error对象 */ declare function execAsyncs<T = any>(promises: Promise<T>[]): Promise<(T | Error)[]>; declare function isBrowser(): boolean; declare const DefaultFallbackLanguage = "en"; declare const DefaultLanguageSettings: ({ name: string; title: string; default: boolean; active: boolean; } | { name: string; title: string; default?: undefined; active?: undefined; })[]; declare const DataTypes: string[]; declare const VOERKAI18N_FORMATTER: unique symbol; declare const VOERKAI18N_FORMATTER_BUILDER: unique symbol; declare const defaultLanguageSettings: { debug: boolean; storage: IVoerkaI18nStorage; languages: ({ name: string; title: string; default: boolean; active: boolean; } | { name: string; title: string; default?: undefined; active?: undefined; })[]; }; declare const TEleClassName = "vt-msg"; declare const TEleMsgIdAttr = "data-id"; declare const TEleScopeIdAttr = "data-scope"; declare class VoerkaI18nError extends Error { } declare class VoerkaI18nInvalidLanguageError extends VoerkaI18nError { } declare class VoerkaI18nOnlyOneAppScopeError extends VoerkaI18nError { } declare class VoerkaI18nChangeLanguageError extends VoerkaI18nError { } declare class VoerkaI18nLoadLanguageError extends VoerkaI18nError { } declare const LocalStorage: IVoerkaI18nStorage; declare function createFormatter<Args extends Dict, Config extends Dict = Args>(formatter: VoerkaI18nFormatter<Args, Config>, configs?: Partial<Record<LanguageName, Partial<Config>>>, defaultConfig?: Partial<Config>): VoerkaI18nFormatterBuilder<Args, Config>; declare function definePlugin(plugin: VoerkaI18nPlugin): void; export { DataTypes, DefaultFallbackLanguage, DefaultLanguageSettings, type Dict, FormattersNotLoadedError, type IVoerkaI18nStorage, type LanguageCodes, type LanguageName, LocalStorage, type SupportedDateTypes, TEleClassName, TEleMsgIdAttr, TEleScopeIdAttr, VOERKAI18N_FORMATTER, VOERKAI18N_FORMATTER_BUILDER, VoerkaI18nChangeLanguageError, type VoerkaI18nDynamicLanguageMessages, VoerkaI18nError, type VoerkaI18nEventListener, type VoerkaI18nEventSubscriber, type VoerkaI18nEvents, type VoerkaI18nFormatter, type VoerkaI18nFormatterBuilder, type VoerkaI18nFormatterConfig, type VoerkaI18nFormatterContext, VoerkaI18nFormatterManager, type VoerkaI18nFormatterName, type VoerkaI18nFormatters, VoerkaI18nInvalidLanguageError, type VoerkaI18nLanguage, type VoerkaI18nLanguageAsyncChunk, type VoerkaI18nLanguageLoader, type VoerkaI18nLanguageMessagePack, type VoerkaI18nLanguageMessages, type VoerkaI18nLanguagePack, type VoerkaI18nLanguageParagraphs, VoerkaI18nLoadLanguageError, VoerkaI18nManager, type VoerkaI18nNamespaces, VoerkaI18nOnlyOneAppScopeError, type VoerkaI18nParagraphs, type VoerkaI18nPlugin, VoerkaI18nScope, type VoerkaI18nScopeCache, type VoerkaI18nScopeOptions, type VoerkaI18nSettings, type VoerkaI18nSupportedLanguages, type VoerkaI18nToBeTranslatedMessage, type VoerkaI18nTranslate, type VoerkaI18nTranslateComponentBuilder, type VoerkaI18nTranslateOptions, type VoerkaI18nTranslateProps, type VoerkaI18nTranslateTransformBuilder, type VoerkaI18nTranslateTransformer, type VoerkaI18nTranslateVars, type Voerkai18nIdMap, createFormatter, defaultLanguageSettings, definePlugin, execAsyncs, getId, isBrowser, isI18nScope, isMessageId, isStorage, loadAsyncModule };