@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/i18n.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Module for internationalization (i18n) support
+ *
+ * Features:
+ * - Translation file loading (JSON, YAML, JS)
+ * - Lazy loading with deduplication
+ * - Background preloading for multiple locales
+ * - Nested key access (e.g., 'messages.welcome')
+ * - Parameter replacement (e.g., ':name' → 'John')
+ * - Basic pluralization support
+ * - ICU MessageFormat support
+ * - Translation caching with invalidation
+ *
+ * ## Lazy Loading
+ *
+ * Translations are loaded lazily with request deduplication:
+ * ```ts
+ * // Multiple simultaneous calls share the same promise
+ * const [t1, t2] = await Promise.all([
+ *   loadTranslation('en', options),
+ *   loadTranslation('en', options), // Reuses same request
+ * ])
+ * ```
+ *
+ * ## Background Preloading
+ *
+ * Preload translations in the background:
+ * ```ts
+ * // Fire and forget - doesn't block
+ * preloadTranslationsBackground({
+ *   locales: ['en', 'es', 'fr', 'de'],
+ *   parallel: true,
+ *   onLocaleLoaded: (locale) => console.log(`${locale} ready`)
+ * }, options)
+ *
+ * // Later, check if loaded or wait
+ * if (isLoaded('es')) {
+ *   const translations = getTranslationSync('es')
+ * }
+else {
+ *   await waitForLocale('es', 5000) // Wait up to 5s
+ * }
+ * ```
+ *
+ * ## Pluralization
+ *
+ * Use the `|` separator to define plural forms:
+ * ```yaml
+ * items: "One item|:count items"
+ * ```
+ *
+ * Or for more complex pluralization:
+ * ```yaml
+ * apples: "{0} No apples|{1} One apple|[2,*] :count apples"
+ * ```
+ *
+ * ## Cache Management
+ *
+ * The translation cache can be managed via:
+ * - `clearTranslationCache()` - Clear all cached translations
+ * - `clearTranslationCache('en')` - Clear specific locale
+ * - `getTranslationCacheStats()` - Get cache statistics
+ */
+import type { I18nConfig, StxOptions } from './types';
+export declare const defaultI18nConfig: I18nConfig;
+/**
+ * Loading state for async translation loading
+ */
+type LoadingState = 'idle' | 'loading' | 'loaded' | 'error';
+/**
+ * Preload configuration
+ */
+export interface PreloadConfig {
+    /** Locales to preload */
+    locales: string[];
+    /** Whether to load in parallel (true) or sequentially (false) */
+    parallel?: boolean;
+    /** Priority order - higher priority locales load first in sequential mode */
+    priority?: Record<string, number>;
+    /** Callback when a locale finishes loading */
+    onLocaleLoaded?: (locale: string) => void;
+    /** Callback when all locales are loaded */
+    onComplete?: () => void;
+    /** Callback on error */
+    onError?: (locale: string, error: Error) => void;
+}
+/**
+ * Clear the translation cache
+ * @param locale - Optional locale to clear. If not provided, clears all.
+ */
+export declare function clearTranslationCache(locale?: string): void;
+/**
+ * Get translation cache statistics
+ */
+export declare function getTranslationCacheStats(): {
+    size: number;
+    locales: string[];
+    entries: Array<{
+        locale: string;
+        loadedAt: Date;
+        keyCount: number;
+    }>;
+};
+/**
+ * Get the loading state for a locale
+ *
+ * @param locale - The locale to check
+ * @returns The current loading state
+ */
+export declare function getLoadingState(locale: string): LoadingState;
+/**
+ * Check if a locale is currently being loaded
+ *
+ * @param locale - The locale to check
+ * @returns True if the locale is currently loading
+ */
+export declare function isLoading(locale: string): boolean;
+/**
+ * Check if a locale has been loaded (cached)
+ *
+ * @param locale - The locale to check
+ * @returns True if the locale is loaded and cached
+ */
+export declare function isLoaded(locale: string): boolean;
+/**
+ * Preload translations for specified locales in the background.
+ * This is non-blocking and returns immediately.
+ *
+ * @param config - Preload configuration
+ * @param options - stx options with i18n configuration
+ * @returns A promise that resolves when all preloading is complete
+ *
+ * @example
+ * // Preload common locales in parallel
+ * preloadTranslations({
+ *   locales: ['en', 'es', 'fr', 'de'],
+ *   parallel: true,
+ *   onLocaleLoaded: (locale) => console.log(`${locale} ready`),
+ *   onComplete: () => console.log('All translations loaded')
+ * }, options)
+ *
+ * @example
+ * // Preload with priority (user's locale first)
+ * preloadTranslations({
+ *   locales: ['en', 'es', 'fr', 'de'],
+ *   parallel: false,
+ *   priority: { 'es': 10, 'en': 5 }, // Spanish first, then English
+ * }, options)
+ */
+export declare function preloadTranslations(config: PreloadConfig, options: StxOptions): Promise<void>;
+/**
+ * Start preloading translations in the background without blocking.
+ * This function returns immediately and loads in the background.
+ *
+ * @param config - Preload configuration
+ * @param options - stx options with i18n configuration
+ *
+ * @example
+ * // Fire and forget background preloading
+ * preloadTranslationsBackground({
+ *   locales: ['en', 'es', 'fr'],
+ *   parallel: true
+ * }, options)
+ * // Execution continues immediately
+ */
+export declare function preloadTranslationsBackground(config: PreloadConfig, options: StxOptions): void;
+/**
+ * Lazy load a translation file with deduplication.
+ * If a load is already in progress for this locale, returns the existing promise.
+ * This prevents multiple simultaneous loads of the same locale.
+ *
+ * @param locale - Locale code (e.g., 'en', 'fr', 'de')
+ * @param options - stx options with i18n configuration
+ * @returns Promise resolving to translation dictionary
+ *
+ * @example
+ * // Multiple calls during loading period share the same promise
+ * const p1 = loadTranslationLazy('en', options)
+ * const p2 = loadTranslationLazy('en', options)
+ * // p1 === p2 (same promise instance)
+ */
+export declare function loadTranslationLazy(locale: string, options: StxOptions): Promise<Record<string, any>>;
+/**
+ * Get a translation synchronously if already cached, otherwise return undefined.
+ * This is useful for non-blocking render patterns where you want to show
+ * a fallback while translations load.
+ *
+ * @param locale - Locale code
+ * @returns Cached translations or undefined if not loaded
+ *
+ * @example
+ * const translations = getTranslationSync('en')
+ * if (translations) {
+ *   // Use translations
+ * }
+else {
+ *   // Show loading state or fallback
+ *   loadTranslationLazy('en', options).then(handleLoaded)
+ * }
+ */
+export declare function getTranslationSync(locale: string): Record<string, any> | undefined;
+/**
+ * Get translation with automatic loading.
+ * Returns cached translations immediately if available,
+ * otherwise loads them and returns.
+ *
+ * This is the recommended async API for most use cases.
+ *
+ * @param locale - Locale code
+ * @param options - stx options
+ * @returns Promise resolving to translations
+ */
+export declare function getTranslationAsync(locale: string, options: StxOptions): Promise<Record<string, any>>;
+/**
+ * Wait for a locale to finish loading.
+ * Useful when you've started a background preload and need to wait for it.
+ *
+ * @param locale - Locale to wait for
+ * @param timeoutMs - Optional timeout in milliseconds
+ * @returns Promise that resolves when loaded, or rejects on timeout/error
+ *
+ * @example
+ * preloadTranslationsBackground({ locales: ['en', 'es'] }, options)
+ * // ... later
+ * await waitForLocale('en', 5000) // Wait up to 5 seconds
+ */
+export declare function waitForLocale(locale: string, timeoutMs?: number): Promise<Record<string, any>>;
+/**
+ * Get all currently loading locales
+ *
+ * @returns Array of locale codes currently being loaded
+ */
+export declare function getLoadingLocales(): string[];
+/**
+ * Cancel pending translation loads (clears pending state).
+ * Note: This doesn't actually abort HTTP requests, but clears tracking state.
+ *
+ * @param locale - Optional locale to cancel. If not provided, cancels all.
+ */
+export declare function cancelPendingLoads(locale?: string): void;
+/**
+ * Load a translation file.
+ *
+ * This is the main entry point for loading translations. It uses lazy loading
+ * with deduplication internally, so multiple calls for the same locale will
+ * share the same promise.
+ *
+ * For more control over loading behavior, see:
+ * - `loadTranslationLazy()` - Explicit lazy loading with deduplication
+ * - `preloadTranslations()` - Preload multiple locales
+ * - `getTranslationSync()` - Get cached translations without loading
+ * - `getTranslationAsync()` - Get with automatic loading
+ *
+ * @param locale - Locale code (e.g., 'en', 'fr', 'de')
+ * @param options - stx options with i18n configuration
+ * @returns Translation dictionary
+ */
+export declare function loadTranslation(locale: string, options: StxOptions): Promise<Record<string, any>>;
+/**
+ * ICU MessageFormat parser and formatter
+ *
+ * Supports:
+ * - Simple replacement: {name}
+ * - Plural: {count, plural, =0{none} one{# item} other{# items}}
+ * - Select: {gender, select, male{He} female{She} other{They}}
+ * - SelectOrdinal: {pos, selectordinal, one{#st} two{#nd} few{#rd} other{#th}}
+ * - Number formatting: {amount, number}
+ * - Date formatting: {date, date, short|medium|long|full}
+ *
+ * @example
+ * formatICU('{count, plural, =0{No items} one{# item} other{# items}}', { count: 5 })
+ * // => '5 items'
+ *
+ * @example
+ * formatICU('{gender, select, male{He} female{She} other{They}} liked this', { gender: 'female' })
+ * // => 'She liked this'
+ */
+export declare function formatICU(message: string, params?: Record<string, unknown>): string;
+/**
+ * Check if a message uses ICU format
+ */
+export declare function isICUFormat(message: string): boolean;
+/**
+ * Get a translation by key with parameter replacement and pluralization.
+ *
+ * Supports both Laravel-style (:param, |plural) and ICU MessageFormat.
+ *
+ * @param key - Dot-notation key (e.g., 'messages.welcome')
+ * @param translations - Translation dictionary
+ * @param fallbackToKey - Return key if translation not found
+ * @param params - Parameters for replacement (use 'count' for pluralization)
+ * @returns The translated string
+ *
+ * @example
+ * // Simple parameter replacement
+ * getTranslation('greeting', { greeting: 'Hello :name' }, true, { name: 'John' })
+ * // => 'Hello John'
+ *
+ * @example
+ * // Pluralization (Laravel-style)
+ * getTranslation('items', { items: 'One item|:count items' }, true, { count: 5 })
+ * // => '5 items'
+ *
+ * @example
+ * // ICU MessageFormat
+ * getTranslation('items', { items: '{count, plural, one{# item} other{# items}}' }, true, { count: 5 })
+ * // => '5 items'
+ */
+export declare function getTranslation(key: string, translations: Record<string, any>, fallbackToKey?: boolean, params?: Record<string, any>): string;
+/** Text direction of a document or element. */
+export type TextDirection = 'ltr' | 'rtl';
+/**
+ * Resolve the writing direction of a BCP 47 locale tag.
+ *
+ * An explicit script subtag decides on its own; otherwise the language subtag
+ * does. Anything unrecognised is `'ltr'`, which is both the CSS initial value
+ * and the safer guess.
+ *
+ * @example
+ * getLocaleDirection('en')        // 'ltr'
+ * getLocaleDirection('ar-EG')     // 'rtl'
+ * getLocaleDirection('ha-Arab')   // 'rtl' — script overrides the language
+ * getLocaleDirection('fa-Latn')   // 'ltr' — and in the other direction too
+ */
+export declare function getLocaleDirection(locale: string | undefined | null): TextDirection;
+/**
+ * Whether a locale is written right-to-left.
+ *
+ * @example
+ * isRtlLocale('he')  // true
+ * isRtlLocale('en')  // false
+ */
+export declare function isRtlLocale(locale: string | undefined | null): boolean;
+/**
+ * Process @translate directive
+ */
+export declare function processTranslateDirective(template: string, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;
+/**
+ * Create a translation filter for expressions
+ */
+export declare function createTranslateFilter(translations: Record<string, any>, fallbackToKey?: boolean): (value: string, params?: Record<string, any>) => string;
+export {};