@cocoar/localization 0.1.0-beta.114

package/fesm2022/cocoar-localization.mjs

@@ -0,0 +1,1752 @@
+import * as i0 from '@angular/core';
+import { signal, InjectionToken, makeEnvironmentProviders, APP_INITIALIZER, inject, Injectable, Pipe, ChangeDetectorRef, computed, effect, untracked } from '@angular/core';
+import { Subject, lastValueFrom, of, startWith, map, distinctUntilChanged, tap, switchMap, catchError } from 'rxjs';
+import { HttpClient } from '@angular/common/http';
+import { Temporal } from '@js-temporal/polyfill';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { BehaviorSubjectProxy } from '@cocoar/ts-utils';
+
+/**
+ * Signal-based storage for locale data.
+ * Provides reactive access to loaded locale formatting rules.
+ */
+class CoarLocalizationDataStore {
+    store = signal(new Map(), ...(ngDevMode ? [{ debugName: "store" }] : []));
+    /**
+     * Set locale data for a specific locale.
+     * @param locale Locale code (e.g., 'en', 'de', 'en-US')
+     * @param data Locale data
+     */
+    setLocaleData(locale, data) {
+        const current = this.store();
+        const updated = new Map(current);
+        updated.set(locale, data);
+        this.store.set(updated);
+    }
+    /**
+     * Get locale data for a specific locale.
+     * @param locale Locale code (e.g., 'en', 'de', 'en-US')
+     * @returns Locale data or undefined if not loaded
+     */
+    getLocaleData(locale) {
+        return this.store().get(locale);
+    }
+    /**
+     * Check if locale data is loaded for a specific locale.
+     * @param locale Locale code (e.g., 'en', 'de', 'en-US')
+     * @returns True if locale data is loaded
+     */
+    hasLocaleData(locale) {
+        return this.store().has(locale);
+    }
+    /**
+     * Remove locale data for a specific locale.
+     * @param locale Locale code (e.g., 'en', 'de', 'en-US')
+     */
+    removeLocaleData(locale) {
+        const current = this.store();
+        const updated = new Map(current);
+        updated.delete(locale);
+        this.store.set(updated);
+    }
+    /**
+     * Clear all loaded locale data.
+     */
+    clear() {
+        this.store.set(new Map());
+    }
+}
+
+/**
+ * Injection token for locale configuration.
+ */
+const COAR_LOCALIZATION_CONFIG = new InjectionToken('COAR_LOCALIZATION_CONFIG');
+/**
+ * Injection token for locale data loaders (multi-provider).
+ * Loaders are executed in order and results are deep-merged.
+ * Intl loader is always first (provides complete defaults).
+ */
+const COAR_LOCALIZATION_DATA_LOADERS = new InjectionToken('COAR_LOCALIZATION_DATA_LOADERS');
+/**
+ * Provides the core locale system (language management).
+ *
+ * This only provides the language service - no locale data sources.
+ * Add locale data sources separately with:
+ * - `provideCoarIntlLocalizationSource()` - Browser Intl API (recommended as first source)
+ * - `provideCoarHttpLocalizationSource()` - Load from JSON files
+ * - Custom sources via `COAR_LOCALIZATION_DATA_LOADERS` multi-provider
+ *
+ * Sources are executed in registration order and deep-merged.
+ *
+ * @example
+ * ```ts
+ * // Minimal setup (no formatting data)
+ * provideCoarLocalization({
+ *   availableLanguages: ['en', 'de'],
+ *   defaultLanguage: 'en',
+ * })
+ *
+ * // With Intl defaults
+ * provideCoarLocalization({...}),
+ * provideCoarIntlLocalizationSource(),
+ *
+ * // With Intl + HTTP overrides
+ * provideCoarLocalization({...}),
+ * provideCoarIntlLocalizationSource(),
+ * provideCoarHttpLocalizationSource({
+ *   url: (lang) => `/locales/${lang}.json`
+ * }),
+ * ```
+ */
+function provideCoarLocalization(config) {
+    return makeEnvironmentProviders([
+        {
+            provide: COAR_LOCALIZATION_CONFIG,
+            useValue: config,
+        },
+        CoarLocalizationService,
+        CoarLocalizationDataStore,
+        {
+            provide: APP_INITIALIZER,
+            multi: true,
+            useFactory: (service) => {
+                return async () => {
+                    // Preload default language from all sources
+                    try {
+                        await service.setLanguage(config.defaultLanguage);
+                    }
+                    catch (error) {
+                        console.warn(`[CoarLocale] Failed to preload locale data for '${config.defaultLanguage}':`, error);
+                    }
+                };
+            },
+            deps: [CoarLocalizationService],
+        },
+    ]);
+}
+
+/**
+ * Deep merge utility for locale data.
+ * Later sources override earlier sources at the field level.
+ *
+ * @example
+ * ```ts
+ * const intl = { date: { pattern: 'dd.mm.yyyy', firstDayOfWeek: 1 }, number: {...} };
+ * const http = { date: { firstDayOfWeek: 0 } }; // Only override firstDayOfWeek
+ *
+ * const result = mergeLocalizationData([intl, http]);
+ * // Result: { date: { pattern: 'dd.mm.yyyy', firstDayOfWeek: 0 }, number: {...} }
+ * ```
+ */
+function mergeLocalizationData(sources) {
+    if (sources.length === 0)
+        return null;
+    const result = {};
+    for (const source of sources) {
+        if (!source)
+            continue;
+        // Merge code
+        if (source.code) {
+            result.code = source.code;
+        }
+        // Deep merge date
+        if (source.date) {
+            result.date = { ...result.date, ...source.date };
+        }
+        // Deep merge number
+        if (source.number) {
+            result.number = { ...result.number, ...source.number };
+        }
+        // Deep merge currency
+        if (source.currency) {
+            result.currency = {
+                ...result.currency,
+                ...source.currency,
+                symbols: { ...result.currency?.symbols, ...source.currency.symbols },
+            };
+        }
+        // Deep merge percent
+        if (source.percent) {
+            result.percent = { ...result.percent, ...source.percent };
+        }
+    }
+    // Ensure we have at least a code
+    if (!result.code)
+        return null;
+    return result;
+}
+
+/**
+ * Core locale service responsible for language management.
+ *
+ * This service manages the current language state and notifies consumers
+ * about language changes. It serves as the single source of truth for
+ * the application's current language.
+ *
+ * Other systems (i18n, localization/formatting) can subscribe to language
+ * changes and react accordingly.
+ *
+ * @example
+ * ```typescript
+ * import { inject } from '@angular/core';
+ * import { CoarLocalizationService } from '@cocoar/localization';
+ *
+ * export class MyComponent {
+ *   private readonly locale = inject(CoarLocalizationService);
+ *
+ *   constructor() {
+ *     // Get current language
+ *     console.log(this.locale.getCurrentLanguage());
+ *
+ *     // React to changes via Signal
+ *     effect(() => {
+ *       console.log('Language changed:', this.locale.language());
+ *     });
+ *
+ *     // React to changes via Observable
+ *     this.locale.languageChanged$.subscribe(lang => {
+ *       console.log('Language changed:', lang);
+ *     });
+ *   }
+ *
+ *   changeLanguage() {
+ *     this.locale.setLanguage('de');
+ *   }
+ * }
+ * ```
+ */
+class CoarLocalizationService {
+    config = inject(COAR_LOCALIZATION_CONFIG, { optional: true });
+    localeDataStore = inject(CoarLocalizationDataStore);
+    localeDataLoaders = inject(COAR_LOCALIZATION_DATA_LOADERS, { optional: true }) ?? [];
+    languageSignal = signal(this.config?.defaultLanguage ?? 'en', ...(ngDevMode ? [{ debugName: "languageSignal" }] : []));
+    languageChangedSubject = new Subject();
+    /**
+     * Signal containing the current language.
+     * Updates automatically when the language changes.
+     *
+     * @example
+     * ```typescript
+     * const locale = inject(CoarLocalizationService);
+     *
+     * // Use in computed
+     * const greeting = computed(() =>
+     *   locale.language() === 'de' ? 'Hallo' : 'Hello'
+     * );
+     *
+     * // Use in effect
+     * effect(() => {
+     *   console.log('Current language:', locale.language());
+     * });
+     * ```
+     */
+    language = this.languageSignal.asReadonly();
+    /**
+     * Observable that emits when the language changes.
+     * Emits the new language code immediately after the change.
+     *
+     * @example
+     * ```typescript
+     * locale.languageChanged$.subscribe(newLang => {
+     *   console.log('Language changed to:', newLang);
+     *   // Reload translations, update formatting rules, etc.
+     * });
+     * ```
+     */
+    languageChanged$ = this.languageChangedSubject.asObservable();
+    /**
+     * Get the current language code.
+     *
+     * @returns The current language code (e.g., 'en', 'de', 'en-US')
+     *
+     * @example
+     * ```typescript
+     * const currentLang = locale.getCurrentLanguage();
+     * console.log(currentLang); // 'en'
+     * ```
+     */
+    getCurrentLanguage() {
+        return this.languageSignal();
+    }
+    /**
+     * Set the current language.
+     *
+     * Automatically loads locale data from all configured sources (Intl, HTTP, etc.)
+     * and deep-merges them in order. Later sources override earlier ones.
+     *
+     * Cached data is not reloaded, so switching back to a previous language is instant.
+     *
+     * @param language - The new language code (e.g., 'en', 'de', 'en-US')
+     *
+     * @example
+     * ```typescript
+     * // Change to German (loads from Intl + HTTP, merges overrides)
+     * await locale.setLanguage('de');
+     *
+     * // Change back to English (uses cached data, instant)
+     * await locale.setLanguage('en');
+     * ```
+     */
+    async setLanguage(language) {
+        const current = this.languageSignal();
+        // Load locale data if not already loaded (cached)
+        if (!this.localeDataStore.hasLocaleData(language)) {
+            try {
+                await this.loadAndmergeLocalizationData(language);
+            }
+            catch (error) {
+                console.warn(`[CoarLocalizationService] Failed to load locale data for '${language}':`, error);
+                // Continue with language switch even if locale data fails to load
+                // Formatting pipes will use fallback values
+            }
+        }
+        // Only notify if language actually changed
+        if (current !== language) {
+            this.languageSignal.set(language);
+            this.languageChangedSubject.next(language);
+        }
+    }
+    /**
+     * Load locale data from all sources and deep-merge them.
+     *
+     * Sources are executed in order:
+     * 1. Intl (always first, provides complete defaults)
+     * 2. HTTP (if configured, merges business overrides)
+     * 3. Custom sources (if provided, can add dynamic updates)
+     *
+     * @param language - Language code to load
+     */
+    async loadAndmergeLocalizationData(language) {
+        if (this.localeDataLoaders.length === 0) {
+            return;
+        }
+        // Load from all sources in parallel
+        const loadPromises = this.localeDataLoaders.map((loader) => lastValueFrom(loader.loadLocaleData(language)).catch((err) => {
+            console.warn(`[CoarLocale] Source failed to load '${language}':`, err);
+            return null; // Return null for failed sources
+        }));
+        const results = await Promise.all(loadPromises);
+        // Deep merge all sources (nulls are ignored)
+        const merged = mergeLocalizationData(results.filter((r) => r !== null));
+        if (merged) {
+            this.localeDataStore.setLocaleData(language, merged);
+        }
+    }
+    /**
+     * Preload locale data for a language without switching to it.
+     * Useful for avoiding UI flicker when switching languages.
+     *
+     * @param language - The language code to preload
+     *
+     * @example
+     * ```typescript
+     * // Preload German locale data before switching
+     * await locale.preloadLocaleData('de');
+     * await locale.setLanguage('de'); // Instant switch, no loading delay
+     * ```
+     */
+    async preloadLocaleData(language) {
+        // Skip if already loaded
+        if (this.localeDataStore.hasLocaleData(language)) {
+            return;
+        }
+        try {
+            await this.loadAndmergeLocalizationData(language);
+        }
+        catch (error) {
+            console.warn(`[CoarLocalizationService] Failed to preload locale data for '${language}':`, error);
+            throw error;
+        }
+    }
+    /**
+     * Get the list of available languages configured for the application.
+     *
+     * @returns Array of available language codes, or empty array if not configured
+     *
+     * @example
+     * ```typescript
+     * const langs = locale.getAvailableLanguages(); // ['en', 'de', 'fr']
+     * ```
+     */
+    getAvailableLanguages() {
+        return this.config?.availableLanguages ?? [];
+    }
+    /**
+     * Get the default language configured for the application.
+     *
+     * @returns The default language code
+     *
+     * @example
+     * ```typescript
+     * const defaultLang = locale.getDefaultLanguage(); // 'en'
+     * ```
+     */
+    getDefaultLanguage() {
+        return this.config?.defaultLanguage ?? 'en';
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarLocalizationService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarLocalizationService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarLocalizationService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }] });
+
+/**
+ * Locale data structure for date and number formatting.
+ *
+ * This data can be loaded from various sources:
+ * - Browser Intl API (CoarIntlLocaleDataLoader) - default
+ * - JSON files (CoarHttpLocaleDataLoader) - for overrides
+ * - SignalR (future) - for dynamic backend-controlled formatting
+ */
+
+/**
+ * Abstract loader for locale data.
+ * Implement this interface to load locale data from any source (HTTP, memory, database, etc.).
+ */
+class CoarLocalizationDataLoader {
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarLocalizationDataLoader, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarLocalizationDataLoader, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarLocalizationDataLoader, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+/**
+ * HTTP-based locale data loader.
+ * Loads locale data from JSON files via HTTP.
+ *
+ * Supports custom URL patterns and headers for authentication/configuration.
+ * Typically used as a second source (after Intl) to provide business-specific overrides.
+ *
+ * @example
+ * ```typescript
+ * // Simple base path
+ * new CoarHttpLocaleDataLoader(httpClient, (lang) => `/locales/${lang}.json`)
+ *
+ * // Custom URL pattern
+ * new CoarHttpLocaleDataLoader(httpClient, (lang) => `/api/config/intl-${lang}.json`)
+ *
+ * // With headers
+ * new CoarHttpLocaleDataLoader(
+ *   httpClient,
+ *   (lang) => `/api/locales/${lang}.json`,
+ *   { 'Authorization': 'Bearer token' }
+ * )
+ * ```
+ */
+class CoarHttpLocaleDataLoader extends CoarLocalizationDataLoader {
+    httpClient;
+    urlFn;
+    headers;
+    constructor(httpClient, urlFn, headers) {
+        super();
+        this.httpClient = httpClient;
+        this.urlFn = urlFn;
+        this.headers = headers;
+    }
+    loadLocaleData(locale) {
+        const url = this.urlFn(locale);
+        return this.httpClient.get(url, {
+            headers: this.headers,
+        });
+    }
+}
+
+/**
+ * Locale data loader that detects formatting from browser's Intl API.
+ *
+ * This is the default loader and works for all locales without requiring JSON files.
+ * Use this when you want formatting to match the user's browser locale automatically.
+ *
+ * For business-specific overrides (e.g., force Monday as first day of week),
+ * use CoarHttpLocaleDataLoader to load custom JSON files.
+ */
+class CoarIntlLocaleDataLoader extends CoarLocalizationDataLoader {
+    loadLocaleData(locale) {
+        return of(this.detectFromIntl(locale));
+    }
+    /**
+     * Detect all locale formatting from browser Intl API.
+     */
+    detectFromIntl(locale) {
+        return {
+            code: locale,
+            date: this.detectDateFormat(locale),
+            number: this.detectNumberFormat(locale),
+            currency: this.detectCurrencyFormat(locale),
+            percent: this.detectPercentFormat(locale),
+        };
+    }
+    /**
+     * Detect date formatting from Intl.DateTimeFormat.
+     */
+    detectDateFormat(locale) {
+        // Detect pattern and separator
+        const formatter = new Intl.DateTimeFormat(locale, {
+            day: '2-digit',
+            month: '2-digit',
+            year: 'numeric',
+        });
+        const parts = formatter.formatToParts(new Date(2024, 11, 25)); // Dec 25, 2024
+        const order = [];
+        for (const part of parts) {
+            if (part.type === 'day')
+                order.push('d');
+            else if (part.type === 'month')
+                order.push('m');
+            else if (part.type === 'year')
+                order.push('y');
+        }
+        const orderStr = order.join('');
+        const formatted = formatter.format(new Date(2024, 11, 25));
+        const separator = formatted.match(/[.\-/]/)?.[0] ?? '.';
+        let pattern;
+        if (orderStr === 'mdy') {
+            pattern = 'mm/dd/yyyy';
+        }
+        else if (orderStr === 'ymd') {
+            pattern = 'yyyy-mm-dd';
+        }
+        else if (separator === '/') {
+            pattern = 'dd/mm/yyyy';
+        }
+        else {
+            pattern = 'dd.mm.yyyy';
+        }
+        // Detect first day of week
+        const sundayFirstLocales = ['en-US', 'en-CA', 'ja-JP', 'ko-KR', 'zh-TW', 'he-IL'];
+        const baseLocale = locale.split('-')[0];
+        const firstDayOfWeek = sundayFirstLocales.some((l) => locale.startsWith(l) || (baseLocale === 'en' && locale.includes('US')))
+            ? 0 // Sunday
+            : 1; // Monday
+        // Generate month names
+        const monthFormatter = new Intl.DateTimeFormat(locale, { month: 'long' });
+        const monthFormatterShort = new Intl.DateTimeFormat(locale, { month: 'short' });
+        const monthNames = [];
+        const monthNamesShort = [];
+        for (let m = 0; m < 12; m++) {
+            const date = new Date(2024, m, 1);
+            monthNames.push(monthFormatter.format(date));
+            monthNamesShort.push(monthFormatterShort.format(date));
+        }
+        // Generate day names (start from Monday)
+        const dayFormatter = new Intl.DateTimeFormat(locale, { weekday: 'long' });
+        const dayFormatterShort = new Intl.DateTimeFormat(locale, { weekday: 'short' });
+        const dayNames = [];
+        const dayNamesShort = [];
+        for (let d = 0; d < 7; d++) {
+            // Jan 1, 2024 is Monday
+            const date = new Date(2024, 0, 1 + d);
+            dayNames.push(dayFormatter.format(date));
+            dayNamesShort.push(dayFormatterShort.format(date));
+        }
+        // Detect AM/PM
+        const amPmFormatter = new Intl.DateTimeFormat(locale, { hour: 'numeric', hour12: true });
+        const amDate = new Date(2024, 0, 1, 9, 0);
+        const pmDate = new Date(2024, 0, 1, 21, 0);
+        const amFormatted = amPmFormatter.format(amDate);
+        const pmFormatted = amPmFormatter.format(pmDate);
+        const amPm = [
+            amFormatted.replace(/\d+/g, '').trim() || 'AM',
+            pmFormatted.replace(/\d+/g, '').trim() || 'PM',
+        ];
+        return {
+            pattern,
+            firstDayOfWeek,
+            monthNames,
+            monthNamesShort,
+            dayNames,
+            dayNamesShort,
+            amPm,
+        };
+    }
+    /**
+     * Detect number formatting from Intl.NumberFormat.
+     */
+    detectNumberFormat(locale) {
+        const formatter = new Intl.NumberFormat(locale);
+        const formatted = formatter.format(1234.56);
+        // Extract decimal separator
+        const decimal = formatted.match(/[.,]/)?.[0] ?? '.';
+        // Extract group separator (find character between thousands)
+        const formattedThousands = formatter.format(1234567);
+        const groupMatch = formattedThousands.match(/1(.)234/);
+        const group = groupMatch ? groupMatch[1] : ',';
+        return {
+            decimal,
+            group,
+            grouping: [3], // Standard grouping by 3 digits
+        };
+    }
+    /**
+     * Detect currency formatting from Intl.NumberFormat.
+     */
+    detectCurrencyFormat(locale) {
+        // Try to get default currency for the locale
+        let defaultCurrency = 'USD';
+        try {
+            // Extract region from locale (e.g., 'US' from 'en-US')
+            const region = locale.split('-')[1];
+            if (region) {
+                // Common currency mappings
+                const currencyMap = {
+                    US: 'USD',
+                    GB: 'GBP',
+                    DE: 'EUR',
+                    FR: 'EUR',
+                    AT: 'EUR',
+                    JP: 'JPY',
+                    CN: 'CNY',
+                    IN: 'INR',
+                };
+                defaultCurrency = currencyMap[region] || 'USD';
+            }
+        }
+        catch {
+            // Fallback
+        }
+        const formatter = new Intl.NumberFormat(locale, {
+            style: 'currency',
+            currency: defaultCurrency,
+        });
+        const formatted = formatter.format(1234.56);
+        // Detect symbol position
+        const numberPart = formatted.match(/\d/)?.[0];
+        const symbolIndex = formatted.indexOf(defaultCurrency.substring(0, 1));
+        const numberIndex = formatted.indexOf(numberPart || '1');
+        const position = symbolIndex < numberIndex ? 'before' : 'after';
+        // Detect spacing
+        const spacing = /\s/.test(formatted);
+        // Get currency symbols
+        const symbols = {
+            USD: '$',
+            EUR: '€',
+            GBP: '£',
+            JPY: '¥',
+            CNY: '¥',
+            INR: '₹',
+        };
+        return {
+            default: defaultCurrency,
+            symbols,
+            position,
+            spacing,
+            decimals: 2,
+        };
+    }
+    /**
+     * Detect percent formatting from Intl.NumberFormat.
+     */
+    detectPercentFormat(locale) {
+        const formatter = new Intl.NumberFormat(locale, { style: 'percent' });
+        const formatted = formatter.format(0.25);
+        // Detect spacing
+        const spacing = /\d\s%/.test(formatted);
+        return {
+            symbol: '%',
+            spacing,
+            decimals: 0,
+        };
+    }
+}
+
+/**
+ * Provides browser Intl API as a locale data source.
+ *
+ * This loader detects date/number formatting from the browser's Intl API
+ * and provides complete locale data for any language without requiring JSON files.
+ *
+ * **Recommended as the first source** to provide complete defaults that other
+ * sources can override.
+ *
+ * @example
+ * ```ts
+ * // Intl only (pure browser defaults)
+ * provideCoarLocalization({ defaultLanguage: 'en', availableLanguages: ['en', 'de'] }),
+ * provideCoarIntlLocalizationSource(),
+ *
+ * // Intl + HTTP overrides (recommended)
+ * provideCoarLocalization({...}),
+ * provideCoarIntlLocalizationSource(), // First source (complete defaults)
+ * provideCoarHttpLocalizationSource({  // Second source (business overrides)
+ *   url: (lang) => `/locales/${lang}.json`
+ * }),
+ * ```
+ */
+function provideCoarIntlLocalizationSource() {
+    return makeEnvironmentProviders([
+        {
+            provide: COAR_LOCALIZATION_DATA_LOADERS,
+            multi: true,
+            useClass: CoarIntlLocaleDataLoader,
+        },
+    ]);
+}
+
+/**
+ * Provides HTTP as a locale data source.
+ *
+ * This loader fetches locale data from JSON files via HTTP.
+ * Typically used as a second source (after Intl) to provide business-specific
+ * overrides like forced firstDayOfWeek, custom separators, etc.
+ *
+ * @example
+ * ```ts
+ * // Basic usage (default URL pattern)
+ * provideCoarHttpLocalizationSource({
+ *   url: (lang) => `/locales/${lang}.json`
+ * })
+ *
+ * // Custom URL pattern
+ * provideCoarHttpLocalizationSource({
+ *   url: (lang) => `/api/config/intl-${lang}.json`
+ * })
+ *
+ * // With authentication
+ * provideCoarHttpLocalizationSource({
+ *   url: (lang) => `/api/locales/${lang}.json`,
+ *   headers: {
+ *     'Authorization': 'Bearer ' + getToken()
+ *   }
+ * })
+ * ```
+ *
+ * Expected file structure:
+ * ```
+ * public/locales/
+ *   en.json  - English overrides
+ *   de.json  - German overrides
+ * ```
+ *
+ * JSON files should contain partial CoarLocalizationData:
+ * ```json
+ * {
+ *   "code": "de",
+ *   "date": {
+ *     "firstDayOfWeek": 1
+ *   }
+ * }
+ * ```
+ */
+function provideCoarHttpLocalizationSource(config) {
+    return makeEnvironmentProviders([
+        {
+            provide: COAR_LOCALIZATION_DATA_LOADERS,
+            multi: true,
+            useFactory: (http) => {
+                return new CoarHttpLocaleDataLoader(http, config.url, config.headers);
+            },
+            deps: [HttpClient],
+        },
+    ]);
+}
+
+/**
+ * Pipe for formatting dates using locale-specific configuration.
+ *
+ * @example
+ * ```html
+ * <span>{{ myDate | coarDate }}</span>
+ * <span>{{ myDate | coarDate:'de' }}</span>
+ * ```
+ */
+class CoarDatePipe {
+    localeDataStore = inject(CoarLocalizationDataStore);
+    localeService = inject(CoarLocalizationService);
+    transform(value, locale) {
+        if (!value)
+            return '';
+        // Convert to Temporal.PlainDate
+        let date;
+        if (value instanceof Date) {
+            date = Temporal.PlainDate.from({
+                year: value.getFullYear(),
+                month: value.getMonth() + 1,
+                day: value.getDate(),
+            });
+        }
+        else if (typeof value === 'string') {
+            try {
+                date = Temporal.PlainDate.from(value);
+            }
+            catch {
+                return '';
+            }
+        }
+        else {
+            date = value;
+        }
+        const effectiveLocale = locale ?? this.localeService.getCurrentLanguage();
+        const localeData = this.localeDataStore.getLocaleData(effectiveLocale);
+        if (!localeData) {
+            // Fallback to ISO format
+            return date.toString();
+        }
+        const { pattern } = localeData.date;
+        const sep = pattern.includes('.') ? '.' : pattern.includes('/') ? '/' : '-';
+        const day = String(date.day).padStart(2, '0');
+        const month = String(date.month).padStart(2, '0');
+        const year = String(date.year);
+        switch (pattern) {
+            case 'dd.mm.yyyy':
+            case 'dd/mm/yyyy':
+                return `${day}${sep}${month}${sep}${year}`;
+            case 'mm/dd/yyyy':
+                return `${month}${sep}${day}${sep}${year}`;
+            case 'yyyy-mm-dd':
+                return `${year}${sep}${month}${sep}${day}`;
+            default:
+                return `${day}${sep}${month}${sep}${year}`;
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarDatePipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
+    static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "21.0.6", ngImport: i0, type: CoarDatePipe, isStandalone: true, name: "coarDate", pure: false });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarDatePipe, decorators: [{
+            type: Pipe,
+            args: [{
+                    name: 'coarDate',
+                    standalone: true,
+                    pure: false, // Impure to react to language changes
+                }]
+        }] });
+
+/**
+ * Pipe for formatting numbers using locale-specific configuration.
+ *
+ * @example
+ * ```html
+ * <span>{{ 1234.56 | coarNumber }}</span>
+ * <span>{{ 1234.56 | coarNumber:'de':2 }}</span>
+ * ```
+ */
+class CoarNumberPipe {
+    localeDataStore = inject(CoarLocalizationDataStore);
+    localeService = inject(CoarLocalizationService);
+    transform(value, locale, decimals = 2) {
+        if (value == null || isNaN(value))
+            return '';
+        const effectiveLocale = locale ?? this.localeService.getCurrentLanguage();
+        const localeData = this.localeDataStore.getLocaleData(effectiveLocale);
+        if (!localeData) {
+            // Fallback to standard formatting
+            return value.toFixed(decimals);
+        }
+        const { decimal, group } = localeData.number;
+        // Split into integer and decimal parts
+        const [integerPart, decimalPart = ''] = value.toFixed(decimals).split('.');
+        // Add thousand separators
+        const formattedInteger = integerPart.replace(/\B(?=(\d{3})+(?!\d))/g, group);
+        // Combine with decimal separator
+        if (decimals > 0 && decimalPart) {
+            return `${formattedInteger}${decimal}${decimalPart}`;
+        }
+        return formattedInteger;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarNumberPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
+    static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "21.0.6", ngImport: i0, type: CoarNumberPipe, isStandalone: true, name: "coarNumber", pure: false });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarNumberPipe, decorators: [{
+            type: Pipe,
+            args: [{
+                    name: 'coarNumber',
+                    standalone: true,
+                    pure: false, // Impure to react to language changes
+                }]
+        }] });
+
+/**
+ * Pipe for formatting currency using locale-specific configuration.
+ *
+ * @example
+ * ```html
+ * <span>{{ 1234.56 | coarCurrency }}</span>
+ * <span>{{ 1234.56 | coarCurrency:'de':'EUR' }}</span>
+ * ```
+ */
+class CoarCurrencyPipe {
+    localeDataStore = inject(CoarLocalizationDataStore);
+    localeService = inject(CoarLocalizationService);
+    transform(value, locale, currency) {
+        if (value == null || isNaN(value))
+            return '';
+        const effectiveLocale = locale ?? this.localeService.getCurrentLanguage();
+        const localeData = this.localeDataStore.getLocaleData(effectiveLocale);
+        if (!localeData) {
+            // Fallback to standard formatting
+            return `${currency ?? 'USD'} ${value.toFixed(2)}`;
+        }
+        const { decimal, group } = localeData.number;
+        const currencyConfig = localeData.currency;
+        const effectiveCurrency = currency ?? currencyConfig.default;
+        const symbol = currencyConfig.symbols[effectiveCurrency] ?? effectiveCurrency;
+        const decimals = currencyConfig.decimals;
+        // Format number part
+        const [integerPart, decimalPart = ''] = value.toFixed(decimals).split('.');
+        const formattedInteger = integerPart.replace(/\B(?=(\d{3})+(?!\d))/g, group);
+        const formattedNumber = decimals > 0 && decimalPart
+            ? `${formattedInteger}${decimal}${decimalPart}`
+            : formattedInteger;
+        // Add currency symbol
+        const space = currencyConfig.spacing ? ' ' : '';
+        if (currencyConfig.position === 'before') {
+            return `${symbol}${space}${formattedNumber}`;
+        }
+        else {
+            return `${formattedNumber}${space}${symbol}`;
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarCurrencyPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
+    static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "21.0.6", ngImport: i0, type: CoarCurrencyPipe, isStandalone: true, name: "coarCurrency", pure: false });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarCurrencyPipe, decorators: [{
+            type: Pipe,
+            args: [{
+                    name: 'coarCurrency',
+                    standalone: true,
+                    pure: false, // Impure to react to language changes
+                }]
+        }] });
+
+/**
+ * Pipe for formatting percentages using locale-specific configuration.
+ *
+ * Expects a decimal value (0.25 = 25%).
+ *
+ * @example
+ * ```html
+ * <span>{{ 0.25 | coarPercent }}</span>
+ * <span>{{ 0.25 | coarPercent:'de':1 }}</span>
+ * ```
+ */
+class CoarPercentPipe {
+    localeDataStore = inject(CoarLocalizationDataStore);
+    localeService = inject(CoarLocalizationService);
+    transform(value, locale, decimals) {
+        if (value == null || isNaN(value))
+            return '';
+        const effectiveLocale = locale ?? this.localeService.getCurrentLanguage();
+        const localeData = this.localeDataStore.getLocaleData(effectiveLocale);
+        if (!localeData) {
+            // Fallback to standard formatting
+            return `${(value * 100).toFixed(decimals ?? 0)}%`;
+        }
+        const { decimal, group } = localeData.number;
+        const percentConfig = localeData.percent;
+        const effectiveDecimals = decimals ?? percentConfig.decimals;
+        // Convert to percentage (0.25 -> 25)
+        const percentValue = value * 100;
+        // Format number part
+        const [integerPart, decimalPart = ''] = percentValue.toFixed(effectiveDecimals).split('.');
+        const formattedInteger = integerPart.replace(/\B(?=(\d{3})+(?!\d))/g, group);
+        const formattedNumber = effectiveDecimals > 0 && decimalPart
+            ? `${formattedInteger}${decimal}${decimalPart}`
+            : formattedInteger;
+        // Add percent symbol
+        const space = percentConfig.spacing ? ' ' : '';
+        return `${formattedNumber}${space}${percentConfig.symbol}`;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarPercentPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
+    static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "21.0.6", ngImport: i0, type: CoarPercentPipe, isStandalone: true, name: "coarPercent", pure: false });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarPercentPipe, decorators: [{
+            type: Pipe,
+            args: [{
+                    name: 'coarPercent',
+                    standalone: true,
+                    pure: false, // Impure to react to language changes
+                }]
+        }] });
+
+/**
+ * Injection token for the i18n provider implementation.
+ *
+ * Apps should provide this token with their chosen i18n backend (Transloco, custom, etc.).
+ */
+const COAR_I18N_PROVIDER = new InjectionToken('COAR_I18N_PROVIDER');
+
+/**
+ * Determines if a translation result should be considered "missing".
+ *
+ * A translation is considered missing if it is:
+ * - null or undefined
+ * - an empty string (after trim)
+ * - exactly equal to the requested key
+ *
+ * This provides unified missing-key semantics across different i18n engines.
+ *
+ * @param key - The translation key that was requested
+ * @param result - The result returned by the i18n service
+ * @returns true if the translation is missing, false otherwise
+ *
+ * @example
+ * ```ts
+ * coarIsMissingTranslation('coar.button.save', null) // true
+ * coarIsMissingTranslation('coar.button.save', '') // true
+ * coarIsMissingTranslation('coar.button.save', 'coar.button.save') // true
+ * coarIsMissingTranslation('coar.button.save', 'Save') // false
+ * ```
+ */
+function coarIsMissingTranslation(key, result) {
+    if (result == null) {
+        return true;
+    }
+    const trimmed = result.trim();
+    if (!trimmed) {
+        return true;
+    }
+    return trimmed === key;
+}
+
+/**
+ * Interpolates {placeholders} in a template string using the given params.
+ *
+ * This is the official Cocoar placeholder syntax for i18n strings.
+ * Placeholders use curly braces: {name}, {count}, etc.
+ *
+ * @param template - The template string containing {placeholder} patterns
+ * @param params - Optional key-value pairs for interpolation
+ * @returns The interpolated string
+ *
+ * @example
+ * ```ts
+ * coarInterpolate("Hello {name}, you have {count} items.", { name: 'Alice', count: 3 })
+ * // => "Hello Alice, you have 3 items."
+ * ```
+ */
+function coarInterpolate(template, params) {
+    if (!params) {
+        return template;
+    }
+    return template.replace(/\{(\w+)\}/g, (_, key) => {
+        const value = params[key];
+        return value == null ? '' : String(value);
+    });
+}
+
+class CoarI18n {
+    provider = inject(COAR_I18N_PROVIDER);
+    locale = inject(CoarLocalizationService);
+    t(key, fallbackOrParams, maybeParams) {
+        let fallback;
+        let params;
+        if (typeof fallbackOrParams === 'string') {
+            // t(key, 'Fallback') or t(key, 'Fallback', params)
+            fallback = fallbackOrParams;
+            params = maybeParams;
+        }
+        else {
+            // t(key) or t(key, params)
+            params = fallbackOrParams;
+            fallback = undefined;
+        }
+        const raw = this.provider.t(key, params);
+        const base = coarIsMissingTranslation(key, raw) ? (fallback ?? key) : (raw ?? '');
+        // Important: the fallback (and even the key) may contain {placeholders}
+        return coarInterpolate(base, params);
+    }
+    /**
+     * Reactive variant that updates when the language changes.
+     * Uses CoarLocalizationService to detect language changes.
+     */
+    t$(key, params, fallback) {
+        // Re-evaluate on every language change from CoarLocalizationService
+        // startWith ensures initial emission
+        return this.locale.languageChanged$.pipe(startWith(undefined), map(() => this.callT(key, params, fallback)), distinctUntilChanged());
+    }
+    /**
+     * Signal variant that updates when the language changes.
+     * Uses CoarLocalizationService to detect language changes.
+     */
+    tSignal(key, params, fallback) {
+        const obs$ = this.t$(key, params, fallback);
+        return toSignal(obs$, {
+            initialValue: this.callT(key, params, fallback),
+        });
+    }
+    // Small helper so t$ doesn't need to replicate the overload matrix.
+    callT(key, params, fallback) {
+        if (params && fallback !== undefined) {
+            // t(key, fallback, params)
+            return this.t(key, fallback, params);
+        }
+        if (params) {
+            // t(key, params)
+            return this.t(key, params);
+        }
+        if (fallback !== undefined) {
+            // t(key, fallback)
+            return this.t(key, fallback);
+        }
+        // t(key)
+        return this.t(key);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18n, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18n, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18n, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+class CoarI18nPipe {
+    i18n = inject(CoarI18n);
+    cdr = inject(ChangeDetectorRef);
+    subject = new BehaviorSubjectProxy('');
+    lastKey;
+    lastParamsJson;
+    lastFallback;
+    transform(key, paramsOrFallback, maybeFallbackOrParams) {
+        if (!key) {
+            // If there's no key, return fallback if one exists
+            if (typeof paramsOrFallback === 'string') {
+                return paramsOrFallback;
+            }
+            if (typeof maybeFallbackOrParams === 'string') {
+                return maybeFallbackOrParams;
+            }
+            return '';
+        }
+        // Normal param/fallback dispatching
+        let params;
+        let fallback;
+        // Case A — first argument is fallback (string)
+        if (typeof paramsOrFallback === 'string') {
+            fallback = paramsOrFallback;
+            if (maybeFallbackOrParams && typeof maybeFallbackOrParams === 'object') {
+                params = maybeFallbackOrParams;
+            }
+        }
+        else {
+            // Case B — first argument is params (object)
+            params = paramsOrFallback ?? undefined;
+            if (typeof maybeFallbackOrParams === 'string') {
+                fallback = maybeFallbackOrParams;
+            }
+        }
+        // Compare inputs to determine if a new subscription is needed
+        const paramsJson = params ? JSON.stringify(params) : undefined;
+        if (key !== this.lastKey ||
+            fallback !== this.lastFallback ||
+            paramsJson !== this.lastParamsJson) {
+            this.lastKey = key;
+            this.lastFallback = fallback;
+            this.lastParamsJson = paramsJson;
+            // Switch Observable completely using BehaviorSubjectProxy
+            this.subject.next(this.i18n.t$(key, params, fallback));
+            // Update the view when new translated values arrive
+            this.subject.subscribe(() => {
+                this.cdr.markForCheck();
+            });
+        }
+        return this.subject.value;
+    }
+    ngOnDestroy() {
+        this.subject.unsubscribe();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18nPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
+    static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "21.0.6", ngImport: i0, type: CoarI18nPipe, isStandalone: true, name: "coarI18n", pure: false });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18nPipe, decorators: [{
+            type: Pipe,
+            args: [{
+                    name: 'coarI18n',
+                    standalone: true,
+                    pure: false, // Required because translations can change at runtime
+                }]
+        }] });
+
+/**
+ * Context service providing i18n-related information to translation providers.
+ *
+ * This service acts as a coordination layer between the core locale system
+ * and translation provider implementations (e.g., Transloco, custom providers).
+ *
+ * Providers should inject this service to:
+ * - Get the current language
+ * - Subscribe to language changes
+ * - Access future i18n-related features (caching, preloading, etc.)
+ *
+ * This abstraction decouples providers from direct CoarLocalizationService dependency,
+ * making the system more maintainable and testable.
+ *
+ * @example
+ * ```typescript
+ * // In a translation provider implementation
+ * export function provideMyI18nBackend(): Provider {
+ *   return {
+ *     provide: COAR_I18N_PROVIDER,
+ *     useFactory: (context: CoarI18nContext, backend: MyBackend) => {
+ *       // Subscribe to language changes
+ *       context.language$.subscribe(lang => {
+ *         backend.switchLanguage(lang);
+ *       });
+ *
+ *       return {
+ *         t(key: string): string {
+ *           return backend.translate(key);
+ *         }
+ *       };
+ *     },
+ *     deps: [CoarI18nContext, MyBackend],
+ *   };
+ * }
+ * ```
+ */
+class CoarI18nContext {
+    localeService = inject(CoarLocalizationService);
+    /**
+     * Observable that emits whenever the language changes.
+     *
+     * Translation providers should subscribe to this observable to stay
+     * synchronized with the current language state.
+     *
+     * @example
+     * ```typescript
+     * context.language$.subscribe(newLang => {
+     *   console.log('Language changed to:', newLang);
+     *   translationBackend.loadLanguage(newLang);
+     * });
+     * ```
+     */
+    language$ = this.localeService.languageChanged$;
+    /**
+     * Get the current language code.
+     *
+     * @returns The current language code (e.g., 'en', 'de', 'en-US')
+     *
+     * @example
+     * ```typescript
+     * const currentLang = context.getCurrentLanguage();
+     * console.log(currentLang); // 'en'
+     * ```
+     */
+    getCurrentLanguage() {
+        return this.localeService.getCurrentLanguage();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18nContext, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18nContext, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18nContext, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * Abstract loader for translation data.
+ *
+ * Implement this interface to load translations from any source:
+ * - HTTP endpoints
+ * - SignalR real-time updates
+ * - Static imports
+ * - IndexedDB
+ * - etc.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class MyCustomLoader implements CoarTranslationLoader {
+ *   loadTranslations(language: string): Observable<CoarTranslations> {
+ *     // Load from your custom source
+ *     return this.myService.getTranslations(language);
+ *   }
+ * }
+ * ```
+ */
+class CoarTranslationLoader {
+}
+/**
+ * HTTP-based translation loader.
+ *
+ * Loads translation JSON files from a configurable base path.
+ *
+ * ## Default behavior
+ * - Base path: `/i18n/`
+ * - File pattern: `{language}.json`
+ * - Example: `/i18n/en.json`, `/i18n/de.json`
+ *
+ * ## Custom path
+ * ```ts
+ * const loader = new CoarHttpTranslationLoader();
+ * loader.basePath = '/assets/translations/';
+ * // Loads: /assets/translations/en.json
+ * ```
+ *
+ * ## Expected JSON format
+ * ```json
+ * {
+ *   "hello": "Hello",
+ *   "goodbye": "Goodbye",
+ *   "welcome": "Welcome, {{name}}!"
+ * }
+ * ```
+ */
+class CoarHttpTranslationLoader {
+    http = inject(HttpClient);
+    /** Base path for translation files */
+    basePath = '/i18n/';
+    loadTranslations(language) {
+        const url = `${this.basePath}${language}.json`;
+        return this.http.get(url);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarHttpTranslationLoader, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarHttpTranslationLoader });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarHttpTranslationLoader, decorators: [{
+            type: Injectable
+        }] });
+
+/**
+ * Reactive store for translation data.
+ *
+ * Stores translations for multiple languages in memory and provides
+ * Signal-based API for reactive updates.
+ *
+ * ## Features
+ * - Signal-based reactive API
+ * - Language-scoped storage
+ * - Simple Map-based implementation
+ * - Zero dependencies beyond Angular core
+ *
+ * @example
+ * ```ts
+ * const store = inject(CoarTranslationStore);
+ *
+ * // Load translations
+ * store.setTranslations('en', { 'hello': 'Hello' });
+ * store.setTranslations('de', { 'hello': 'Hallo' });
+ *
+ * // Check if language is loaded
+ * if (store.hasLanguage('en')) {
+ *   const translations = store.getTranslations('en');
+ * }
+ *
+ * // Get specific translation
+ * const value = store.getTranslation('en', 'hello'); // 'Hello'
+ *
+ * // Check for missing keys
+ * const missing = store.getTranslation('en', 'unknown'); // undefined
+ * ```
+ */
+class CoarTranslationStore {
+    /**
+     * Internal storage: Map<language, Map<key, translation>>
+     *
+     * Why nested Maps instead of Record:
+     * - Faster lookups for large translation sets
+     * - No prototype chain pollution
+     * - Clear separation between languages
+     */
+    storage = signal(new Map(), ...(ngDevMode ? [{ debugName: "storage" }] : []));
+    /**
+     * Set of all loaded languages.
+     * Used for quick existence checks.
+     */
+    loadedLanguages = computed(() => {
+        const map = this.storage();
+        return new Set(map.keys());
+    }, ...(ngDevMode ? [{ debugName: "loadedLanguages" }] : []));
+    /**
+     * Stores all translations for a specific language.
+     *
+     * Replaces any existing translations for that language.
+     *
+     * @param language - Language code (e.g., 'en', 'de')
+     * @param translations - Translation key-value pairs
+     *
+     * @example
+     * ```ts
+     * // HTTP: Load entire language at once
+     * store.setTranslations('en', { 'hello': 'Hello', 'goodbye': 'Goodbye' });
+     * ```
+     */
+    setTranslations(language, translations) {
+        const translationMap = new Map(Object.entries(translations));
+        this.storage.update((current) => {
+            const next = new Map(current);
+            next.set(language, translationMap);
+            return next;
+        });
+    }
+    /**
+     * Updates a single translation key for a specific language.
+     *
+     * Creates the language if it doesn't exist.
+     * Useful for real-time updates via SignalR.
+     *
+     * @param language - Language code
+     * @param key - Translation key
+     * @param value - Translation value
+     *
+     * @example
+     * ```ts
+     * // SignalR: Update single key in real-time
+     * signalR.on('TranslationUpdated', ({ lang, key, value }) => {
+     *   store.setTranslation(lang, key, value);
+     * });
+     * ```
+     */
+    setTranslation(language, key, value) {
+        this.storage.update((current) => {
+            const next = new Map(current);
+            const langMap = next.get(language) ?? new Map();
+            const updatedLangMap = new Map(langMap);
+            updatedLangMap.set(key, value);
+            next.set(language, updatedLangMap);
+            return next;
+        });
+    }
+    /**
+     * Merges partial translations into an existing language.
+     *
+     * Only updates/adds the provided keys, keeps existing keys intact.
+     * Creates the language if it doesn't exist.
+     *
+     * @param language - Language code
+     * @param partialTranslations - Partial translation key-value pairs to merge
+     *
+     * @example
+     * ```ts
+     * // Existing: { 'hello': 'Hello', 'goodbye': 'Goodbye' }
+     * store.updateTranslations('en', { 'hello': 'Hi' });
+     * // Result: { 'hello': 'Hi', 'goodbye': 'Goodbye' }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // SignalR: Batch update multiple keys
+     * signalR.on('TranslationsBatchUpdated', ({ lang, updates }) => {
+     *   store.updateTranslations(lang, updates);
+     * });
+     * ```
+     */
+    updateTranslations(language, partialTranslations) {
+        this.storage.update((current) => {
+            const next = new Map(current);
+            const langMap = next.get(language) ?? new Map();
+            const updatedLangMap = new Map(langMap);
+            // Merge partial updates into existing translations
+            for (const [key, value] of Object.entries(partialTranslations)) {
+                updatedLangMap.set(key, value);
+            }
+            next.set(language, updatedLangMap);
+            return next;
+        });
+    }
+    /**
+     * Checks if translations for a language are loaded.
+     *
+     * @param language - Language code to check
+     * @returns True if language is loaded
+     */
+    hasLanguage(language) {
+        return this.storage().has(language);
+    }
+    /**
+     * Gets all translations for a specific language.
+     *
+     * @param language - Language code
+     * @returns Translation map, or undefined if language not loaded
+     */
+    getTranslations(language) {
+        return this.storage().get(language);
+    }
+    /**
+     * Gets a specific translation value.
+     *
+     * @param language - Language code
+     * @param key - Translation key
+     * @returns Translation value, or undefined if not found
+     */
+    getTranslation(language, key) {
+        return this.storage().get(language)?.get(key);
+    }
+    /**
+     * Clears all translations from the store.
+     *
+     * Used primarily for testing.
+     */
+    clear() {
+        this.storage.set(new Map());
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarTranslationStore, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarTranslationStore, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarTranslationStore, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * Core i18n service implementation.
+ *
+ * Integrates:
+ * - `CoarLocalizationService` - Language state management
+ * - `CoarTranslationStore` - Translation storage
+ * - `CoarTranslationLoader` - Translation loading
+ * - `CoarI18nContext` - Coordination layer
+ *
+ * ## Features
+ * - Automatic translation loading when language changes
+ * - Missing translation detection
+ * - Parameter interpolation
+ * - Reactive Signal-based API
+ *
+ * ## Usage
+ * Use `provideCoarI18n()` to configure - don't instantiate directly.
+ *
+ * @example
+ * ```ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideCoarLocalization({
+ *       availableLanguages: ['en', 'de'],
+ *       defaultLanguage: 'en',
+ *     }),
+ *     provideCoarI18n({
+ *       loader: CoarHttpTranslationLoader,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+class CoarI18nService {
+    locale = inject(CoarLocalizationService);
+    store = inject(CoarTranslationStore);
+    loader = inject(CoarTranslationLoader);
+    /**
+     * Signal containing all translations for the current language.
+     *
+     * Returns undefined if language not yet loaded.
+     */
+    currentTranslations = computed(() => {
+        const lang = this.locale.language();
+        return this.store.getTranslations(lang);
+    }, ...(ngDevMode ? [{ debugName: "currentTranslations" }] : []));
+    constructor() {
+        // Auto-load translations when language changes
+        effect(() => {
+            const lang = this.locale.language();
+            // If language already loaded, do nothing
+            if (untracked(() => this.store.hasLanguage(lang))) {
+                return;
+            }
+            // Load translations for new language
+            this.loadLanguage(lang).subscribe();
+        }, { allowSignalWrites: true });
+    }
+    t(key, params) {
+        const translations = this.currentTranslations();
+        // Language not loaded yet - return key
+        if (!translations) {
+            return key;
+        }
+        const value = translations.get(key);
+        // Missing translation - return key
+        if (value === undefined) {
+            return key;
+        }
+        // No params - return value as-is
+        if (!params) {
+            return value;
+        }
+        // Interpolate params
+        return coarInterpolate(value, params);
+    }
+    /**
+     * Loads translations for a specific language.
+     *
+     * Called automatically when language changes via effect.
+     * Can also be called manually to preload languages.
+     *
+     * @param language - Language code to load
+     * @returns Observable that completes when loading finishes
+     */
+    loadLanguage(language) {
+        return this.loader.loadTranslations(language).pipe(tap((translations) => {
+            this.store.setTranslations(language, translations);
+        }), switchMap(() => of(void 0)), catchError((error) => {
+            console.error(`Failed to load translations for language: ${language}`, error);
+            // Store empty translations to prevent repeated load attempts
+            this.store.setTranslations(language, {});
+            return of(void 0);
+        }));
+    }
+    /**
+     * Preloads translations for a specific language.
+     *
+     * Used by APP_INITIALIZER to prevent flash of untranslated content.
+     *
+     * @param language - Language code to preload
+     * @returns Promise that resolves when loading completes
+     */
+    preloadLanguage(language) {
+        // Already loaded - return immediately
+        if (this.store.hasLanguage(language)) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.loadLanguage(language).subscribe(() => resolve());
+        });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18nService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18nService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18nService, decorators: [{
+            type: Injectable
+        }], ctorParameters: () => [] });
+
+/**
+ * Default/fallback implementation of CoarI18nProvider.
+ *
+ * This is a minimal passthrough implementation that returns the key unchanged,
+ * with placeholder interpolation applied if params are provided.
+ *
+ * Used when the app does not provide a custom i18n provider.
+ * The CoarI18n service wraps this and adds the tWithDefault method.
+ *
+ * @example
+ * ```ts
+ * import { provideCoarDefaultI18n } from '@cocoar/localization';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [provideCoarDefaultI18n()],
+ * };
+ * ```
+ */
+class CoarDefaultI18n {
+    t(key, params) {
+        // Return the key as-is with interpolation applied
+        return coarInterpolate(key, params);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarDefaultI18n, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarDefaultI18n });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarDefaultI18n, decorators: [{
+            type: Injectable
+        }] });
+
+/**
+ * Provides complete Cocoar i18n system.
+ *
+ * Sets up translation loading, storage, and automatic language synchronization.
+ *
+ * ## Features
+ * - Automatic translation loading when language changes
+ * - Preloads initial language (prevents flash of untranslated content)
+ * - Signal-based reactive updates
+ * - Customizable loader (HTTP, SignalR, static, etc.)
+ *
+ * ## Basic usage
+ * ```ts
+ * import { provideCoarLocalization } from '@cocoar/localization';
+ * import { provideCoarI18n } from '@cocoar/localization';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideHttpClient(),
+ *     provideCoarLocalization({
+ *       availableLanguages: ['en', 'de', 'fr'],
+ *       defaultLanguage: 'en',
+ *     }),
+ *     provideCoarI18n(),
+ *   ],
+ * };
+ * ```
+ *
+ * ## Custom HTTP path
+ * ```ts
+ * provideCoarI18n({
+ *   basePath: '/assets/translations/',
+ * })
+ * ```
+ *
+ * ## Custom loader (e.g., SignalR)
+ * ```ts
+ * @Injectable()
+ * class SignalRTranslationLoader implements CoarTranslationLoader {
+ *   loadTranslations(lang: string): Observable<CoarTranslations> {
+ *     return this.signalR.getTranslations(lang);
+ *   }
+ * }
+ *
+ * provideCoarI18n({
+ *   loader: SignalRTranslationLoader,
+ * })
+ * ```
+ *
+ * @param config - Optional configuration
+ * @returns Environment providers for the i18n system
+ */
+function provideCoarI18n(config) {
+    const loaderClass = config?.loader ?? CoarHttpTranslationLoader;
+    const basePath = config?.basePath ?? '/i18n/';
+    const providers = [
+        // Provide the loader
+        {
+            provide: CoarTranslationLoader,
+            useFactory: () => {
+                const instance = new loaderClass();
+                // For HTTP loader, set basePath
+                if (instance instanceof CoarHttpTranslationLoader) {
+                    instance.basePath = basePath;
+                }
+                return instance;
+            },
+        },
+        // Provide the i18n service as COAR_I18N_PROVIDER
+        {
+            provide: COAR_I18N_PROVIDER,
+            useClass: CoarI18nService,
+        },
+        // Preload initial language to prevent flash of untranslated content
+        {
+            provide: APP_INITIALIZER,
+            multi: true,
+            useFactory: () => {
+                const service = inject(COAR_I18N_PROVIDER);
+                const locale = inject(CoarLocalizationService);
+                return async () => {
+                    const initialLanguage = locale.getCurrentLanguage();
+                    await service.preloadLanguage(initialLanguage);
+                };
+            },
+        },
+    ];
+    return makeEnvironmentProviders(providers);
+}
+
+/**
+ * Provides the default i18n provider.
+ *
+ * This minimal provider returns keys unchanged with interpolation applied.
+ * Use this as a fallback when no translation engine is configured.
+ *
+ * @example
+ * ```ts
+ * import { provideCoarDefaultI18n } from '@cocoar/localization';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [provideCoarDefaultI18n()],
+ * };
+ * ```
+ */
+function provideCoarDefaultI18n() {
+    return {
+        provide: COAR_I18N_PROVIDER,
+        useClass: CoarDefaultI18n,
+    };
+}
+
+// Locale (language management)
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { COAR_I18N_PROVIDER, COAR_LOCALIZATION_CONFIG, COAR_LOCALIZATION_DATA_LOADERS, CoarCurrencyPipe, CoarDatePipe, CoarDefaultI18n, CoarHttpLocaleDataLoader, CoarHttpTranslationLoader, CoarI18n, CoarI18nContext, CoarI18nPipe, CoarI18nService, CoarIntlLocaleDataLoader, CoarLocalizationDataLoader, CoarLocalizationDataStore, CoarLocalizationService, CoarNumberPipe, CoarPercentPipe, CoarTranslationLoader, CoarTranslationStore, coarInterpolate, coarIsMissingTranslation, mergeLocalizationData, provideCoarDefaultI18n, provideCoarHttpLocalizationSource, provideCoarI18n, provideCoarIntlLocalizationSource, provideCoarLocalization };
+//# sourceMappingURL=cocoar-localization.mjs.map