@miaixz/sdk 0.5.0

package/dist/i18n/i18n.d.ts

@@ -0,0 +1,248 @@
+import { MiaixzSdkError } from "../api/errors.js";
+/**
+ * Identifies a locale supported by the Miaixz internationalization runtime.
+ *
+ * @public
+ */
+export type MiaixzLocale = string;
+/**
+ * Maps named message placeholders to scalar replacement values.
+ *
+ * @public
+ */
+export type MiaixzMessageParams = Readonly<Record<string, string | number | boolean>>;
+/**
+ * Maps translation keys to localized strings for one locale.
+ *
+ * @public
+ */
+export type MiaixzMessages = Readonly<Record<string, string>>;
+/**
+ * Maps locale identifiers to flat message collections.
+ *
+ * @public
+ */
+export type MiaixzMessageCatalog = Readonly<Record<MiaixzLocale, MiaixzMessages>>;
+/**
+ * Identifies whether messages originate from a package or the consuming project.
+ *
+ * @public
+ */
+export type MiaixzMessageSource = "builtin" | "project";
+/**
+ * Describes an ES module whose default export contains localized messages.
+ *
+ * @public
+ */
+export interface MiaixzMessageModule {
+    /**
+     * Contains the localized messages exported by the language module.
+     */
+    readonly default: MiaixzMessages;
+}
+/**
+ * Represents direct messages or a dynamically imported language module.
+ *
+ * @public
+ */
+export type MiaixzMessageLoaderResult = MiaixzMessages | MiaixzMessageModule;
+/**
+ * Loads project-owned messages for one namespace and locale.
+ *
+ * @public
+ */
+export type MiaixzMessageLoader = (namespace: string, locale: MiaixzLocale) => Promise<MiaixzMessageLoaderResult>;
+/**
+ * Maps namespaces and locales to project-owned dynamic import functions.
+ *
+ * @public
+ */
+export type MiaixzMessageLoaderMap = Readonly<Record<string, Readonly<Record<MiaixzLocale, () => Promise<MiaixzMessageLoaderResult>>>>>;
+/**
+ * Translates a message key with optional interpolation and fallback text.
+ *
+ * @public
+ */
+export type MiaixzTranslator = (key: string, params?: MiaixzMessageParams, fallback?: string) => string;
+/**
+ * Reports the current locale and asynchronous language-loading state.
+ *
+ * @public
+ */
+export interface MiaixzI18nSnapshot {
+    /**
+     * Contains the active canonical BCP 47 locale.
+     */
+    readonly locale: MiaixzLocale;
+    /**
+     * Reports whether requested project messages are ready, loading, or unavailable.
+     */
+    readonly loadStatus: "ready" | "loading" | "error";
+    /**
+     * Contains the latest project-language loading failure when present.
+     */
+    readonly loadError?: MiaixzI18nLoadError;
+}
+/**
+ * Configures the Miaixz internationalization runtime.
+ *
+ * @public
+ */
+export interface MiaixzI18nOptions {
+    /**
+     * Selects the initial active locale.
+     */
+    readonly locale?: MiaixzLocale;
+    /**
+     * Selects the locale used after active-locale resources are exhausted.
+     */
+    readonly fallbackLocale?: MiaixzLocale;
+    /**
+     * Registers static project resources during construction.
+     */
+    readonly messages?: MiaixzMessageCatalog;
+    /**
+     * Loads project-owned language files by namespace and locale.
+     */
+    readonly loadMessages?: MiaixzMessageLoader;
+    /**
+     * Receives each project-language loading failure.
+     */
+    readonly onLoadError?: (error: MiaixzI18nLoadError) => void;
+}
+/**
+ * Provides the built-in SDK messages in English and Simplified Chinese.
+ *
+ * @public
+ */
+export declare const miaixzSdkMessages: MiaixzMessageCatalog;
+/**
+ * Creates a deduplicating loader from project-owned language module mappings.
+ * Failed imports are evicted so a later call can retry them.
+ *
+ * @param loaders - Namespace and locale keys mapped to dynamic import functions.
+ * @returns Message loader implementing exact and base-language lookup.
+ * @public
+ */
+export declare function createMiaixzMessageLoader(loaders: MiaixzMessageLoaderMap): MiaixzMessageLoader;
+/**
+ * Error raised when a project language file fails to load or validate.
+ *
+ * @public
+ */
+export declare class MiaixzI18nLoadError extends MiaixzSdkError {
+    /**
+     * Contains the canonical locale whose language file failed.
+     */
+    readonly locale: MiaixzLocale;
+    /**
+     * Contains the namespace whose language file failed.
+     */
+    readonly namespace: string;
+    /**
+     * Creates a project language-file loading error.
+     *
+     * @param locale - Canonical requested locale.
+     * @param namespace - Requested message namespace.
+     * @param message - Localized public failure message.
+     * @param cause - Original loader or validation error.
+     */
+    constructor(locale: MiaixzLocale, namespace: string, message: string, cause?: unknown);
+}
+/**
+ * Runtime translator with namespace isolation, deterministic fallbacks, and lazy loading.
+ *
+ * @public
+ */
+export declare class MiaixzI18n {
+    #private;
+    /**
+     * Creates an internationalization runtime and registers built-in SDK resources first.
+     *
+     * @param options - Initial locale, fallback, static project messages, and loader.
+     */
+    constructor(options?: MiaixzI18nOptions);
+    /**
+     * Returns the currently active canonical locale.
+     *
+     * @returns Active locale identifier.
+     */
+    get locale(): MiaixzLocale;
+    /**
+     * Returns the immutable current internationalization snapshot.
+     *
+     * @returns Current locale and loading state.
+     */
+    getSnapshot(): Readonly<MiaixzI18nSnapshot>;
+    /**
+     * Registers messages synchronously within an isolated namespace and source layer.
+     *
+     * @param namespace - Valid package or module namespace.
+     * @param locale - Locale that owns the messages.
+     * @param messages - Flat messages whose keys start with the namespace.
+     * @param source - Built-in or project precedence layer.
+     */
+    registerMessages(namespace: string, locale: MiaixzLocale, messages: MiaixzMessages, source: MiaixzMessageSource): void;
+    /**
+     * Loads the initial active and fallback locales for sorted unique namespaces.
+     *
+     * @param namespaces - Namespaces to initialize; defaults to the SDK namespace.
+     * @returns Promise settled after all requested messages are ready.
+     */
+    initialize(namespaces?: readonly string[]): Promise<void>;
+    /**
+     * Loads one project namespace and locale with in-flight request deduplication.
+     *
+     * @param namespace - Namespace to load.
+     * @param locale - Locale to load.
+     * @returns Promise settled after project messages are registered.
+     * @throws MiaixzI18nLoadError When loading or validation fails.
+     */
+    loadNamespace(namespace: string, locale: MiaixzLocale): Promise<void>;
+    /**
+     * Loads every known namespace before applying the latest requested locale switch.
+     *
+     * @param locale - Target locale to load and activate.
+     * @returns Promise settled after the request either becomes active or is superseded.
+     * @throws MiaixzI18nLoadError When the target locale cannot be loaded.
+     */
+    changeLocale(locale: MiaixzLocale): Promise<void>;
+    /**
+     * Registers a snapshot listener and returns its unsubscribe function.
+     *
+     * @param listener - Callback invoked after locale, resource, or loading changes.
+     * @returns Function that removes the listener.
+     */
+    subscribe(listener: (snapshot: Readonly<MiaixzI18nSnapshot>) => void): () => void;
+    /**
+     * Translates a key using project, built-in, configured locale, and explicit fallbacks.
+     *
+     * @param key - Translation key to resolve.
+     * @param params - Optional named scalar values.
+     * @param fallback - Optional final human-readable fallback.
+     * @returns Localized and interpolated message.
+     */
+    readonly t: MiaixzTranslator;
+}
+/**
+ * Resolves and canonicalizes the browser's preferred locale.
+ *
+ * @returns Browser locale, or `en-US` in non-browser runtimes.
+ * @public
+ */
+export declare function getMiaixzBrowserLocale(): MiaixzLocale;
+/**
+ * Creates a runtime translator and project-language loader.
+ *
+ * @param options - Optional locale, catalogs, and project loader.
+ * @returns Configured internationalization runtime.
+ * @public
+ */
+export declare function createMiaixzI18n(options?: MiaixzI18nOptions): MiaixzI18n;
+/**
+ * Provides the default internationalization runtime used by standalone SDK modules.
+ *
+ * @public
+ */
+export declare const miaixzDefaultI18n: MiaixzI18n;
+//# sourceMappingURL=i18n.d.ts.map

package/dist/i18n/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../../src/i18n/i18n.ts"],"names":[],"mappings":"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"}