@gears-frontx/i18n 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,328 @@
+import { I18nRegistry, Language, I18nConfig, TranslationDictionary, TranslationLoader, TranslationParams, LanguageMetadata, TranslationMap } from './types.js';
+export { HTML_DIR_ATTRIBUTE, HTML_LANG_ATTRIBUTE, I18N_DEFAULT_NAMESPACE, I18N_NAMESPACE_SEPARATOR, I18N_PATH_SEPARATOR, LanguageCode, LanguageDisplayMode, TextDirection } from './types.js';
+
+/**
+ * I18n Registry - Central translation management
+ *
+ * Implements namespace-based translation loading with:
+ * - Lazy loading for screenset/screen translations
+ * - RTL/LTR support
+ * - Parameter interpolation
+ *
+ * SDK Layer: L1 (Zero @gears-frontx dependencies)
+ */
+
+/**
+ * I18n Registry Implementation
+ *
+ * Central registry for managing translations across the application.
+ * Supports lazy loading, namespace isolation, and RTL languages.
+ */
+declare class I18nRegistryImpl implements I18nRegistry {
+    /** Configuration */
+    private config;
+    /** Current language */
+    private currentLanguage;
+    /** Translation dictionaries: namespace -> language -> dictionary */
+    private dictionaries;
+    /** Translation loaders: namespace -> loader function */
+    private loaders;
+    /** Subscribers for translation changes */
+    private subscribers;
+    /** Version counter for React re-rendering */
+    private version;
+    /** Language file mapping */
+    static readonly LANGUAGE_FILE_MAP: Record<Language, string>;
+    constructor(config: I18nConfig);
+    /**
+     * Register translations for a namespace.
+     */
+    register(namespace: string, language: Language, translations: TranslationDictionary): void;
+    /**
+     * Subscribe to translation changes.
+     * Returns an unsubscribe function.
+     */
+    subscribe(callback: () => void): () => void;
+    /**
+     * Notify all subscribers of a change.
+     */
+    private notifySubscribers;
+    /**
+     * Get the current version number.
+     * Used by React to detect changes.
+     */
+    getVersion(): number;
+    /**
+     * Register a translation loader for a namespace.
+     */
+    registerLoader(namespace: string, loader: TranslationLoader): void;
+    /**
+     * Check if namespace is registered.
+     */
+    hasNamespace(namespace: string): boolean;
+    /**
+     * Get all registered namespaces.
+     */
+    getNamespaces(): string[];
+    /**
+     * Translate a key.
+     * Format: 'namespace:key.subkey' or just 'key' for default namespace
+     */
+    t(key: string, params?: TranslationParams): string;
+    /**
+     * Parse a translation key into namespace and path.
+     */
+    private parseKey;
+    /**
+     * Get a translation from the dictionary.
+     */
+    private getTranslation;
+    /**
+     * Find a translation in the dictionary.
+     */
+    private findTranslation;
+    /**
+     * Interpolate parameters into a translation string.
+     */
+    private interpolate;
+    /**
+     * Set current language and load translations.
+     */
+    setLanguage(language: Language): Promise<void>;
+    /**
+     * Get current language.
+     */
+    getLanguage(): Language | null;
+    /**
+     * Update HTML lang and dir attributes.
+     */
+    private updateHtmlAttributes;
+    /**
+     * Get language metadata.
+     */
+    getLanguageMetadata(code?: Language): LanguageMetadata | undefined;
+    /**
+     * Get all supported languages.
+     */
+    getSupportedLanguages(): LanguageMetadata[];
+    /**
+     * Check if a language is RTL.
+     */
+    isRTL(code?: Language): boolean;
+    /**
+     * Load translations for a language.
+     * Excludes screen.* and screenset.* namespaces which are lazy-loaded:
+     * - screen.* namespaces: loaded when screen mounts
+     * - screenset.* namespaces: loaded when screenset is activated
+     */
+    loadLanguage(language: Language): Promise<void>;
+    /**
+     * Load translations for a specific namespace.
+     */
+    private loadNamespace;
+    /**
+     * Load translations for a specific screenset.
+     */
+    loadScreensetTranslations(screensetId: string, language?: Language): Promise<void>;
+    /**
+     * Preload translations for multiple languages.
+     */
+    preloadLanguages(languages: Language[]): Promise<void>;
+    /**
+     * Create a translation loader from a translation map.
+     *
+     * @example
+     * ```typescript
+     * const loader = I18nRegistry.createLoader({
+     *   [Language.English]: () => import('./i18n/en.json'),
+     *   [Language.Spanish]: () => import('./i18n/es.json'),
+     * });
+     * ```
+     */
+    static createLoader(translationMap: TranslationMap): TranslationLoader;
+    /**
+     * Create a translation loader from a directory.
+     * Maps Language enum values to file names automatically.
+     *
+     * @param basePath - Base path for translation files
+     * @param importFn - Dynamic import function
+     */
+    static createLoaderFromDirectory(importFn: (filename: string) => Promise<{
+        default: TranslationDictionary;
+    }>): TranslationLoader;
+}
+/**
+ * Default i18n registry instance.
+ * Use this instance throughout the application.
+ */
+declare const i18nRegistry: I18nRegistryImpl;
+/**
+ * Create a new i18n registry with custom configuration.
+ *
+ * @param config - I18n configuration
+ * @returns New I18nRegistry instance
+ */
+declare function createI18nRegistry(config: I18nConfig): I18nRegistryImpl;
+
+/**
+ * Supported Languages - All 36 HAI3 supported languages
+ *
+ * Based on major platforms (Google, Facebook, Microsoft, Apple).
+ * Includes native names, English names, and text direction.
+ */
+
+/**
+ * All supported languages with metadata.
+ * This list defines what languages the application can use.
+ */
+declare const SUPPORTED_LANGUAGES: LanguageMetadata[];
+/**
+ * Get language metadata by code.
+ *
+ * @param code - Language code
+ * @returns Language metadata or undefined
+ */
+declare function getLanguageMetadata(code: Language): LanguageMetadata | undefined;
+/**
+ * Get RTL language codes.
+ *
+ * @returns Array of RTL language codes
+ */
+declare function getRTLLanguages(): Language[];
+/**
+ * Check if a language code is valid.
+ *
+ * @param code - Language code to check
+ * @returns True if valid
+ */
+declare function isValidLanguage(code: string): code is Language;
+
+/**
+ * Date formatter - Locale-aware date and time formatting
+ *
+ * Uses i18nRegistry.getLanguage() for locale; fallback to Language.English when null.
+ * Invalid date inputs return ''.
+ */
+type DateFormatStyle = 'short' | 'medium' | 'long' | 'full';
+type TimeFormatStyle = 'short' | 'medium';
+type DateInput = Date | number | string | null | undefined;
+/**
+ * Format a date according to the current locale.
+ *
+ * @param date - Date, timestamp, or ISO string
+ * @param format - 'short' | 'medium' | 'long' | 'full'
+ * @returns Formatted date string, or '' if input is invalid
+ */
+declare function formatDate(date: DateInput, format: DateFormatStyle): string;
+/**
+ * Format the time portion of a date according to the current locale.
+ *
+ * @param date - Date, timestamp, or ISO string
+ * @param format - 'short' | 'medium'
+ * @returns Formatted time string, or '' if input is invalid
+ */
+declare function formatTime(date: DateInput, format: TimeFormatStyle): string;
+/**
+ * Format date and time according to the current locale.
+ *
+ * @param date - Date, timestamp, or ISO string
+ * @param dateFormat - Date style: 'short' | 'medium' | 'long' | 'full'
+ * @param timeFormat - Time style: 'short' | 'medium'
+ * @returns Formatted date-time string, or '' if input is invalid
+ */
+declare function formatDateTime(date: DateInput, dateFormat: DateFormatStyle, timeFormat: TimeFormatStyle): string;
+/**
+ * Format a date as relative time (e.g. "2 hours ago", "in 3 days").
+ *
+ * @param date - Date, timestamp, or ISO string
+ * @param base - Reference date for "now"; defaults to new Date()
+ * @returns Relative time string, or '' if input is invalid
+ */
+declare function formatRelative(date: DateInput, base?: DateInput): string;
+
+/**
+ * Number formatter - Locale-aware number formatting
+ *
+ * Uses i18nRegistry.getLanguage() for locale; fallback to Language.English when null.
+ * null, undefined, and NaN return ''.
+ */
+/**
+ * Format a number according to the current locale.
+ *
+ * @param value - Number to format
+ * @param options - Intl.NumberFormatOptions (e.g. minimumFractionDigits)
+ * @returns Formatted number string, or '' if input is null, undefined, or NaN
+ */
+declare function formatNumber(value: number | null | undefined, options?: Intl.NumberFormatOptions): string;
+/**
+ * Format a value as a percentage (0.15 -> "15%").
+ *
+ * @param value - Decimal value (e.g. 0.15 for 15%)
+ * @param decimals - Optional decimal places
+ * @returns Formatted percent string, or '' if input is null, undefined, or NaN
+ */
+declare function formatPercent(value: number | null | undefined, decimals?: number): string;
+/**
+ * Format a number in compact notation (e.g. "1.2K", "3.4M").
+ *
+ * @param value - Number to format
+ * @returns Compact formatted string, or '' if input is null, undefined, or NaN
+ */
+declare function formatCompact(value: number | null | undefined): string;
+
+/**
+ * Currency formatter - Locale-aware currency formatting
+ *
+ * Uses i18nRegistry.getLanguage() for locale; fallback to Language.English when null.
+ * null, undefined, and NaN return ''; invalid currencyCode also returns '' and does not throw.
+ */
+/**
+ * Format a value as currency for the given currency code.
+ *
+ * @param value - Numeric amount
+ * @param currencyCode - ISO 4217 currency code (e.g. 'USD', 'EUR')
+ * @returns Formatted currency string, or '' if value is null, undefined, NaN, or currencyCode is invalid
+ */
+declare function formatCurrency(value: number | null | undefined, currencyCode: string): string;
+
+/**
+ * Sort utilities - Locale-aware string comparison
+ *
+ * Uses i18nRegistry.getLanguage() for locale; fallback to Language.English when null.
+ */
+/**
+ * Compare two strings according to the current locale (for sorting).
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @param options - Intl.Collator options (e.g. sensitivity, numeric)
+ * @returns Negative if a < b, 0 if equal, positive if a > b
+ */
+declare function compareStrings(a: string, b: string, options?: Intl.CollatorOptions): number;
+/**
+ * Create a Collator for the current locale (reuse for many comparisons, e.g. in tables).
+ *
+ * @param options - Intl.Collator options
+ * @returns Intl.Collator instance
+ */
+declare function createCollator(options?: Intl.CollatorOptions): Intl.Collator;
+
+/**
+ * Formatters type - Canonical type for the locale-aware formatters object.
+ * Use this (e.g. UseFormattersReturn) instead of re-declaring the 10 function signatures.
+ */
+
+interface Formatters {
+    formatDate: typeof formatDate;
+    formatTime: typeof formatTime;
+    formatDateTime: typeof formatDateTime;
+    formatRelative: typeof formatRelative;
+    formatNumber: typeof formatNumber;
+    formatPercent: typeof formatPercent;
+    formatCompact: typeof formatCompact;
+    formatCurrency: typeof formatCurrency;
+    compareStrings: typeof compareStrings;
+    createCollator: typeof createCollator;
+}
+
+export { type DateFormatStyle, type DateInput, type Formatters, I18nConfig, I18nRegistry, I18nRegistryImpl, Language, LanguageMetadata, SUPPORTED_LANGUAGES, type TimeFormatStyle, TranslationDictionary, TranslationLoader, TranslationMap, TranslationParams, compareStrings, createCollator, createI18nRegistry, formatCompact, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, formatRelative, formatTime, getLanguageMetadata, getRTLLanguages, i18nRegistry, isValidLanguage };