@zucker-framework/i18n 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,282 @@
+import { NestInterceptor, ExecutionContext, CallHandler, Type, DynamicModule, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { BusinessException } from '@zucker-framework/core';
+
+/**
+ * MessageSource — i18n message resolution interface.
+ */
+interface MessageSource {
+    getMessage(code: string, args?: unknown[], defaultMessage?: string, locale?: string): string;
+}
+/**
+ * FileMessageSource — loads messages from JSON files.
+ *
+ * Expected file structure: {basePath}/{locale}.json
+ * JSON format: flat key-value pairs, e.g. { "error.notFound": "Resource not found" }
+ *
+ * Supports message interpolation with positional args: "Hello {0}, welcome to {1}"
+ */
+declare class FileMessageSource implements MessageSource {
+    private readonly basePath;
+    private readonly logger;
+    private readonly messages;
+    private readonly defaultLocale;
+    constructor(basePath: string, options?: {
+        defaultLocale?: string;
+    });
+    getMessage(code: string, args?: unknown[], defaultMessage?: string, locale?: string): string;
+    private loadLocale;
+    private flatten;
+    private interpolate;
+    clearCache(): void;
+}
+/**
+ * CompositeMessageSource — aggregates multiple message sources.
+ * Checks sources in order, returns the first match.
+ */
+declare class CompositeMessageSource implements MessageSource {
+    private readonly sources;
+    constructor(sources: MessageSource[]);
+    getMessage(code: string, args?: unknown[], defaultMessage?: string, locale?: string): string;
+    addSource(source: MessageSource): void;
+    /**
+     * Add multiple sources at once.
+     */
+    addSources(sources: MessageSource[]): void;
+    /**
+     * Get the number of registered sources.
+     */
+    getSourceCount(): number;
+}
+
+/**
+ * LocaleContext -- uses AsyncLocalStorage to bind the current locale
+ * to the execution context (request scope).
+ */
+declare class LocaleContext {
+    private static defaultLocale;
+    static setDefault(locale: string): void;
+    static getCurrent(): string;
+    static run<T>(locale: string, fn: () => T): T;
+    static runAsync<T>(locale: string, fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * NestJS interceptor that sets the locale from the Accept-Language header.
+ */
+declare class LocaleInterceptor implements NestInterceptor {
+    private readonly supportedLocales;
+    private readonly defaultLocale;
+    constructor(options?: {
+        supportedLocales?: string[];
+        defaultLocale?: string;
+    });
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    private parseLocale;
+}
+
+/**
+ * I18nException — an exception whose message is resolved via i18n at response time.
+ *
+ * Stores a message code and interpolation args. The actual i18n resolution
+ * happens when getMessage() is called (typically in an exception filter).
+ */
+declare class I18nException extends BusinessException {
+    readonly i18nCode: string;
+    readonly i18nArgs: unknown[];
+    constructor(code: string, args?: unknown[], fallbackMessage?: string);
+}
+
+/**
+ * I18nSpec — supports nested i18n parameter resolution.
+ *
+ * Allows i18n message codes whose arguments themselves need i18n resolution.
+ *
+ * Reference: jetlinks I18nSpec
+ *
+ * @example
+ * ```ts
+ * const spec = I18nSpec.of('message.scene.term.full_name', 'Property: {0}/{1}',
+ *   'Temperature',
+ *   I18nSpec.of('message.property.recent', 'Current Value'),
+ * );
+ * const resolved = spec.resolve(messageSource);
+ * // => "Property: Temperature/Current Value" (or localized)
+ * ```
+ */
+declare class I18nSpec {
+    /** i18n message code; if empty, defaultMessage is returned as-is */
+    code?: string;
+    /** Fallback message when code is not found or not provided */
+    defaultMessage?: string;
+    /** Nested i18n-aware arguments */
+    args: I18nSpec[];
+    constructor(code?: string, defaultMessage?: string, args?: I18nSpec[]);
+    /**
+     * Create an I18nSpec with optional nested args.
+     * Args can be strings (treated as plain defaults) or I18nSpec instances.
+     */
+    static of(code: string, defaultMessage?: string, ...args: Array<string | I18nSpec>): I18nSpec;
+    /**
+     * Add a nested i18n argument.
+     */
+    withArg(code: string, defaultMessage?: string, ...args: Array<string | I18nSpec>): this;
+    /**
+     * Add an existing I18nSpec as a nested argument.
+     */
+    withArgSpec(spec: I18nSpec): this;
+    /**
+     * Resolve this spec to a final message using the given MessageSource.
+     * Recursively resolves nested args first.
+     */
+    resolve(messageSource: MessageSource, locale?: string): string;
+    /**
+     * Create a shallow copy of this spec.
+     */
+    copy(): I18nSpec;
+    private resolveMessage;
+}
+
+/**
+ * Format a message template with positional or named parameters.
+ *
+ * Supports positional arguments `{0}, {1}` and named arguments `{name}, {count}`.
+ *
+ * @example formatMessage('Hello {0}, you have {1} messages', ['Alice', 5])
+ * @example formatMessage('Hello {name}, you have {count} messages', { name: 'Alice', count: 5 })
+ */
+declare function formatMessage(template: string, params: unknown[] | Record<string, unknown>): string;
+/**
+ * Simple plural selection (ICU MessageFormat style).
+ *
+ * Chooses among `zero`, `one` and `other` forms based on `count`.
+ * The selected form is then interpolated with `{count}` replaced by the actual
+ * number (formatted according to `locale` when provided).
+ *
+ * @example pluralize(0, { zero: '没有消息', one: '1 条消息', other: '{count} 条消息' })
+ * @example pluralize(5, { zero: '没有消息', one: '1 条消息', other: '{count} 条消息' })
+ */
+declare function pluralize(count: number, forms: {
+    zero?: string;
+    one?: string;
+    other: string;
+}, locale?: string): string;
+/**
+ * Format a date using `Intl.DateTimeFormat`.
+ *
+ * @param date   Date instance or epoch-milliseconds timestamp
+ * @param style  Predefined date style — `'short'`, `'medium'` (default),
+ *               `'long'` or `'full'`
+ * @param locale BCP-47 locale tag; defaults to the current context locale
+ */
+declare function formatDate(date: Date | number, style?: 'short' | 'medium' | 'long' | 'full', locale?: string): string;
+/**
+ * Format a number using `Intl.NumberFormat`.
+ *
+ * @param value   The numeric value
+ * @param style   `'decimal'` (default), `'currency'` or `'percent'`
+ * @param options Additional options — currently only `currency` (ISO 4217 code,
+ *                required when `style` is `'currency'`)
+ * @param locale  BCP-47 locale tag; defaults to the current context locale
+ */
+declare function formatNumber(value: number, style?: 'decimal' | 'currency' | 'percent', options?: {
+    currency?: string;
+}, locale?: string): string;
+/**
+ * Format a date as a human-friendly relative time string
+ * (e.g. "3 hours ago", "in 2 days") using `Intl.RelativeTimeFormat`.
+ *
+ * @param date   Date instance or epoch-milliseconds timestamp
+ * @param locale BCP-47 locale tag; defaults to the current context locale
+ */
+declare function formatRelativeTime(date: Date | number, locale?: string): string;
+/**
+ * LocaleUtils — static utility for i18n message resolution.
+ *
+ * Provides convenient methods for resolving messages using the current locale
+ * context and a configured MessageSource.
+ */
+declare class LocaleUtils {
+    private static messageSource;
+    /**
+     * Set the global message source used by resolve helpers.
+     */
+    static setMessageSource(source: MessageSource): void;
+    /**
+     * Get the currently configured global message source.
+     */
+    static getMessageSource(): MessageSource | null;
+    /**
+     * Resolve a message using the current locale context.
+     */
+    static resolveMessage(code: string, ...args: unknown[]): string;
+    /**
+     * Resolve a message with a default fallback using the current locale context.
+     */
+    static resolveMessageWithDefault(code: string, defaultMessage: string, ...args: unknown[]): string;
+    /**
+     * Resolve a message using a specific MessageSource and the current locale.
+     */
+    static resolveMessageFrom(source: MessageSource, code: string, defaultMessage?: string, ...args: unknown[]): string;
+    /**
+     * Resolve a message using a specific locale (ignoring the context locale).
+     */
+    static resolveMessageForLocale(code: string, locale: string, defaultMessage?: string, ...args: unknown[]): string;
+    /**
+     * Execute a function within a specific locale context.
+     */
+    static doWith<T>(locale: string, fn: () => T): T;
+    /**
+     * Execute an async function within a specific locale context.
+     */
+    static doWithAsync<T>(locale: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get the current locale.
+     */
+    static current(): string;
+}
+
+/**
+ * @I18n(code) -- marks a field/property for i18n text resolution.
+ *
+ * When applied, the field value is treated as an i18n message code
+ * that should be resolved through the MessageSource at display time.
+ */
+declare function I18n(code: string): PropertyDecorator;
+/**
+ * Get the i18n code associated with a property.
+ */
+declare function getI18nCode(target: object, propertyKey: string | symbol): string | undefined;
+/**
+ * Check if a property has an i18n code.
+ */
+declare function hasI18n(target: object, propertyKey: string | symbol): boolean;
+
+declare const MESSAGE_SOURCE = "MESSAGE_SOURCE";
+interface I18nModuleOptions {
+    /** Path to message files directory */
+    basePath?: string;
+    /** Default locale */
+    defaultLocale?: string;
+    /** Supported locales */
+    supportedLocales?: string[];
+    /** Additional message sources */
+    messageSources?: MessageSource[];
+}
+interface I18nModuleAsyncOptions {
+    imports?: Array<Type | DynamicModule>;
+    useFactory?: (...args: unknown[]) => I18nModuleOptions | Promise<I18nModuleOptions>;
+    useClass?: Type<I18nModuleOptionsFactory>;
+    useExisting?: Type<I18nModuleOptionsFactory>;
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+}
+interface I18nModuleOptionsFactory {
+    createI18nOptions(): I18nModuleOptions | Promise<I18nModuleOptions>;
+}
+declare class ZuckerI18nModule {
+    static forRoot(options?: I18nModuleOptions): DynamicModule;
+    static forRootAsync(options: I18nModuleAsyncOptions): DynamicModule;
+    private static buildProviders;
+    private static createAsyncProviders;
+}
+
+export { CompositeMessageSource, FileMessageSource, I18n, I18nException, type I18nModuleAsyncOptions, type I18nModuleOptions, type I18nModuleOptionsFactory, I18nSpec, LocaleContext, LocaleInterceptor, LocaleUtils, MESSAGE_SOURCE, type MessageSource, ZuckerI18nModule, formatDate, formatMessage, formatNumber, formatRelativeTime, getI18nCode, hasI18n, pluralize };