@cocoar/localization 0.1.0-beta.114

package/types/cocoar-localization.d.ts

@@ -0,0 +1,1194 @@
+import * as i0 from '@angular/core';
+import { Signal, InjectionToken, EnvironmentProviders, PipeTransform, OnDestroy, Type, Provider } from '@angular/core';
+import { Observable } from 'rxjs';
+import { HttpClient } from '@angular/common/http';
+import { Temporal } from '@js-temporal/polyfill';
+
+/**
+ * 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');
+ *   }
+ * }
+ * ```
+ */
+declare class CoarLocalizationService {
+    private readonly config;
+    private readonly localeDataStore;
+    private readonly localeDataLoaders;
+    private readonly languageSignal;
+    private readonly languageChangedSubject;
+    /**
+     * 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());
+     * });
+     * ```
+     */
+    readonly language: Signal<string>;
+    /**
+     * 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.
+     * });
+     * ```
+     */
+    readonly languageChanged$: Observable<string>;
+    /**
+     * 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(): string;
+    /**
+     * 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');
+     * ```
+     */
+    setLanguage(language: string): Promise<void>;
+    /**
+     * 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
+     */
+    private loadAndmergeLocalizationData;
+    /**
+     * 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
+     * ```
+     */
+    preloadLocaleData(language: string): Promise<void>;
+    /**
+     * 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(): string[];
+    /**
+     * Get the default language configured for the application.
+     *
+     * @returns The default language code
+     *
+     * @example
+     * ```typescript
+     * const defaultLang = locale.getDefaultLanguage(); // 'en'
+     * ```
+     */
+    getDefaultLanguage(): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarLocalizationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CoarLocalizationService>;
+}
+
+/**
+ * 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
+ */
+/**
+ * Complete locale data for a specific language/region.
+ */
+interface CoarLocalizationData {
+    /** Locale code (e.g., 'en', 'de', 'en-US', 'de-DE') */
+    code: string;
+    /** Date formatting configuration */
+    date: CoarDateFormatData;
+    /** Number formatting configuration */
+    number: CoarNumberFormatData;
+    /** Currency formatting configuration */
+    currency: CoarCurrencyFormatData;
+    /** Percent formatting configuration */
+    percent: CoarPercentFormatData;
+}
+/**
+ * Date formatting configuration.
+ */
+interface CoarDateFormatData {
+    /**
+     * Date format pattern: 'dd.mm.yyyy', 'dd/mm/yyyy', 'mm/dd/yyyy', 'yyyy-mm-dd'
+     */
+    pattern: 'dd.mm.yyyy' | 'dd/mm/yyyy' | 'mm/dd/yyyy' | 'yyyy-mm-dd';
+    /**
+     * First day of week (0 = Sunday, 1 = Monday, ..., 6 = Saturday).
+     */
+    firstDayOfWeek: number;
+    /** Localized month names (full) */
+    monthNames: string[];
+    /** Localized month names (short) */
+    monthNamesShort: string[];
+    /** Localized day names (full) */
+    dayNames: string[];
+    /** Localized day names (short) */
+    dayNamesShort: string[];
+    /** AM/PM labels */
+    amPm: [string, string];
+}
+/**
+ * Number formatting configuration.
+ */
+interface CoarNumberFormatData {
+    /** Decimal separator (e.g., "." for English, "," for German) */
+    decimal: string;
+    /** Thousands/group separator (e.g., "," for English, "." for German) */
+    group: string;
+    /** Grouping pattern ([3] means group every 3 digits) */
+    grouping: number[];
+}
+/**
+ * Currency formatting configuration.
+ */
+interface CoarCurrencyFormatData {
+    /** Default currency code (e.g., "USD", "EUR") */
+    default: string;
+    /** Currency symbols map (e.g., { "USD": "$", "EUR": "€" }) */
+    symbols: Record<string, string>;
+    /** Symbol position: 'before' ($1,234) or 'after' (1,234 €) */
+    position: 'before' | 'after';
+    /** Space between symbol and number */
+    spacing: boolean;
+    /** Decimal places for currency display */
+    decimals: number;
+}
+/**
+ * Percent formatting configuration.
+ */
+interface CoarPercentFormatData {
+    /** Percent symbol (usually "%") */
+    symbol: string;
+    /** Space between number and symbol (e.g., "25%" vs "25 %") */
+    spacing: boolean;
+    /** Decimal places for percent display */
+    decimals: number;
+}
+
+/**
+ * Abstract loader for locale data.
+ * Implement this interface to load locale data from any source (HTTP, memory, database, etc.).
+ */
+declare abstract class CoarLocalizationDataLoader {
+    /**
+     * Load locale data for a specific locale.
+     * @param locale Locale code (e.g., 'en', 'de', 'en-US')
+     * @returns Observable that emits the locale data
+     */
+    abstract loadLocaleData(locale: string): Observable<CoarLocalizationData>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarLocalizationDataLoader, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CoarLocalizationDataLoader>;
+}
+/**
+ * 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' }
+ * )
+ * ```
+ */
+declare class CoarHttpLocaleDataLoader extends CoarLocalizationDataLoader {
+    private readonly httpClient;
+    private readonly urlFn;
+    private readonly headers?;
+    constructor(httpClient: HttpClient, urlFn: (language: string) => string, headers?: Record<string, string> | undefined);
+    loadLocaleData(locale: string): Observable<CoarLocalizationData>;
+}
+
+/**
+ * Configuration for the locale system.
+ */
+interface CoarLocalizationConfig {
+    /**
+     * List of available languages in the application.
+     */
+    availableLanguages: string[];
+    /**
+     * Default language to use on initialization.
+     */
+    defaultLanguage: string;
+}
+/**
+ * Injection token for locale configuration.
+ */
+declare const COAR_LOCALIZATION_CONFIG: InjectionToken<CoarLocalizationConfig>;
+/**
+ * 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).
+ */
+declare const COAR_LOCALIZATION_DATA_LOADERS: InjectionToken<CoarLocalizationDataLoader[]>;
+/**
+ * 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`
+ * }),
+ * ```
+ */
+declare function provideCoarLocalization(config: CoarLocalizationConfig): EnvironmentProviders;
+
+/**
+ * Signal-based storage for locale data.
+ * Provides reactive access to loaded locale formatting rules.
+ */
+declare class CoarLocalizationDataStore {
+    private readonly store;
+    /**
+     * Set locale data for a specific locale.
+     * @param locale Locale code (e.g., 'en', 'de', 'en-US')
+     * @param data Locale data
+     */
+    setLocaleData(locale: string, data: CoarLocalizationData): void;
+    /**
+     * 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: string): CoarLocalizationData | undefined;
+    /**
+     * 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: string): boolean;
+    /**
+     * Remove locale data for a specific locale.
+     * @param locale Locale code (e.g., 'en', 'de', 'en-US')
+     */
+    removeLocaleData(locale: string): void;
+    /**
+     * Clear all loaded locale data.
+     */
+    clear(): void;
+}
+
+/**
+ * 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.
+ */
+declare class CoarIntlLocaleDataLoader extends CoarLocalizationDataLoader {
+    loadLocaleData(locale: string): Observable<CoarLocalizationData>;
+    /**
+     * Detect all locale formatting from browser Intl API.
+     */
+    private detectFromIntl;
+    /**
+     * Detect date formatting from Intl.DateTimeFormat.
+     */
+    private detectDateFormat;
+    /**
+     * Detect number formatting from Intl.NumberFormat.
+     */
+    private detectNumberFormat;
+    /**
+     * Detect currency formatting from Intl.NumberFormat.
+     */
+    private detectCurrencyFormat;
+    /**
+     * Detect percent formatting from Intl.NumberFormat.
+     */
+    private detectPercentFormat;
+}
+
+/**
+ * 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`
+ * }),
+ * ```
+ */
+declare function provideCoarIntlLocalizationSource(): EnvironmentProviders;
+
+/**
+ * Configuration for HTTP locale data source.
+ */
+interface CoarHttpLocaleSourceConfig {
+    /**
+     * URL generator function that returns the URL for a given language.
+     *
+     * @param language - Language code (e.g., 'en', 'de', 'en-US')
+     * @returns URL to load locale data from
+     *
+     * @example
+     * ```ts
+     * url: (lang) => `/locales/${lang}.json`
+     * url: (lang) => `/api/config/intl-${lang}.json`
+     * url: (lang) => `https://cdn.example.com/locales/${lang}.json`
+     * ```
+     */
+    url: (language: string) => string;
+    /**
+     * Optional HTTP headers to include in requests.
+     *
+     * @example
+     * ```ts
+     * headers: {
+     *   'Authorization': 'Bearer token123',
+     *   'X-Custom-Header': 'value'
+     * }
+     * ```
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * 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
+ *   }
+ * }
+ * ```
+ */
+declare function provideCoarHttpLocalizationSource(config: CoarHttpLocaleSourceConfig): EnvironmentProviders;
+
+/**
+ * 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: {...} }
+ * ```
+ */
+declare function mergeLocalizationData(sources: Partial<CoarLocalizationData>[]): CoarLocalizationData | null;
+
+/**
+ * Pipe for formatting dates using locale-specific configuration.
+ *
+ * @example
+ * ```html
+ * <span>{{ myDate | coarDate }}</span>
+ * <span>{{ myDate | coarDate:'de' }}</span>
+ * ```
+ */
+declare class CoarDatePipe implements PipeTransform {
+    private readonly localeDataStore;
+    private readonly localeService;
+    transform(value: Temporal.PlainDate | Date | string | null | undefined, locale?: string): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarDatePipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<CoarDatePipe, "coarDate", true>;
+}
+
+/**
+ * Pipe for formatting numbers using locale-specific configuration.
+ *
+ * @example
+ * ```html
+ * <span>{{ 1234.56 | coarNumber }}</span>
+ * <span>{{ 1234.56 | coarNumber:'de':2 }}</span>
+ * ```
+ */
+declare class CoarNumberPipe implements PipeTransform {
+    private readonly localeDataStore;
+    private readonly localeService;
+    transform(value: number | null | undefined, locale?: string, decimals?: number): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarNumberPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<CoarNumberPipe, "coarNumber", true>;
+}
+
+/**
+ * Pipe for formatting currency using locale-specific configuration.
+ *
+ * @example
+ * ```html
+ * <span>{{ 1234.56 | coarCurrency }}</span>
+ * <span>{{ 1234.56 | coarCurrency:'de':'EUR' }}</span>
+ * ```
+ */
+declare class CoarCurrencyPipe implements PipeTransform {
+    private readonly localeDataStore;
+    private readonly localeService;
+    transform(value: number | null | undefined, locale?: string, currency?: string): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarCurrencyPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<CoarCurrencyPipe, "coarCurrency", true>;
+}
+
+/**
+ * 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>
+ * ```
+ */
+declare class CoarPercentPipe implements PipeTransform {
+    private readonly localeDataStore;
+    private readonly localeService;
+    transform(value: number | null | undefined, locale?: string, decimals?: number): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarPercentPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<CoarPercentPipe, "coarPercent", true>;
+}
+
+declare class CoarI18n {
+    private readonly provider;
+    private readonly locale;
+    /**
+     * Translate a key into a localized string.
+     *
+     * Overloads:
+     *  - t(key)
+     *  - t(key, fallback)
+     *  - t(key, params)
+     *  - t(key, fallback, params)
+     */
+    t(key: string): string;
+    t(key: string, fallback: string): string;
+    t(key: string, params: Record<string, unknown>): string;
+    t(key: string, fallback: string, params?: Record<string, unknown>): string;
+    /**
+     * Reactive variant that updates when the language changes.
+     * Uses CoarLocalizationService to detect language changes.
+     */
+    t$(key: string, params?: Record<string, unknown>, fallback?: string): Observable<string>;
+    /**
+     * Signal variant that updates when the language changes.
+     * Uses CoarLocalizationService to detect language changes.
+     */
+    tSignal(key: string, params?: Record<string, unknown>, fallback?: string): Signal<string>;
+    private callT;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarI18n, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CoarI18n>;
+}
+
+declare class CoarI18nPipe implements PipeTransform, OnDestroy {
+    private readonly i18n;
+    private readonly cdr;
+    private readonly subject;
+    private lastKey?;
+    private lastParamsJson?;
+    private lastFallback?;
+    transform(key: string | null | undefined, paramsOrFallback?: Record<string, unknown> | string, maybeFallbackOrParams?: string | Record<string, unknown>): string;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarI18nPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<CoarI18nPipe, "coarI18n", true>;
+}
+
+/**
+ * Core i18n provider interface for translation engines.
+ *
+ * Providers (Transloco, custom, etc.) only need to implement this minimal interface.
+ * The CoarI18n service wraps this provider and adds convenience methods.
+ */
+interface CoarI18nProvider {
+    /**
+     * Translate a key into a localized string.
+     *
+     * @param key i18n key, e.g. 'coar.datePicker.today'
+     * @param params optional interpolation parameters for placeholders like {name}
+     * @returns the translated and interpolated string
+     */
+    t(key: string, params?: Record<string, unknown>): string;
+}
+/**
+ * Injection token for the i18n provider implementation.
+ *
+ * Apps should provide this token with their chosen i18n backend (Transloco, custom, etc.).
+ */
+declare const COAR_I18N_PROVIDER: InjectionToken<CoarI18nProvider>;
+
+/**
+ * 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],
+ *   };
+ * }
+ * ```
+ */
+declare class CoarI18nContext {
+    private readonly localeService;
+    /**
+     * 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);
+     * });
+     * ```
+     */
+    readonly language$: Observable<string>;
+    /**
+     * 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(): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarI18nContext, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CoarI18nContext>;
+}
+
+/**
+ * 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,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+declare class CoarI18nService implements CoarI18nProvider {
+    private readonly locale;
+    private readonly store;
+    private readonly loader;
+    /**
+     * Signal containing all translations for the current language.
+     *
+     * Returns undefined if language not yet loaded.
+     */
+    private readonly currentTranslations;
+    constructor();
+    t(key: string, params?: Record<string, unknown>): string;
+    /**
+     * 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
+     */
+    private loadLanguage;
+    /**
+     * 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: string): Promise<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarI18nService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CoarI18nService>;
+}
+
+/**
+ * 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()],
+ * };
+ * ```
+ */
+declare class CoarDefaultI18n implements CoarI18nProvider {
+    t(key: string, params?: Record<string, unknown>): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarDefaultI18n, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CoarDefaultI18n>;
+}
+
+/**
+ * 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."
+ * ```
+ */
+declare function coarInterpolate(template: string, params?: Record<string, unknown>): string;
+
+/**
+ * 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
+ * ```
+ */
+declare function coarIsMissingTranslation(key: string, result: string | null | undefined): boolean;
+
+/**
+ * Translation storage for a single language.
+ * Maps translation keys to their values.
+ */
+type CoarTranslations = Record<string, string>;
+/**
+ * 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
+ * ```
+ */
+declare 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
+     */
+    private readonly storage;
+    /**
+     * Set of all loaded languages.
+     * Used for quick existence checks.
+     */
+    readonly loadedLanguages: Signal<Set<string>>;
+    /**
+     * 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: string, translations: CoarTranslations): void;
+    /**
+     * 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: string, key: string, value: string): void;
+    /**
+     * 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: string, partialTranslations: CoarTranslations): void;
+    /**
+     * Checks if translations for a language are loaded.
+     *
+     * @param language - Language code to check
+     * @returns True if language is loaded
+     */
+    hasLanguage(language: string): boolean;
+    /**
+     * Gets all translations for a specific language.
+     *
+     * @param language - Language code
+     * @returns Translation map, or undefined if language not loaded
+     */
+    getTranslations(language: string): Map<string, string> | undefined;
+    /**
+     * Gets a specific translation value.
+     *
+     * @param language - Language code
+     * @param key - Translation key
+     * @returns Translation value, or undefined if not found
+     */
+    getTranslation(language: string, key: string): string | undefined;
+    /**
+     * Clears all translations from the store.
+     *
+     * Used primarily for testing.
+     */
+    clear(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarTranslationStore, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CoarTranslationStore>;
+}
+
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+declare abstract class CoarTranslationLoader {
+    /**
+     * Loads translation data for a specific language.
+     *
+     * @param language - Language code to load (e.g., 'en', 'de')
+     * @returns Observable that emits translation key-value pairs
+     */
+    abstract loadTranslations(language: string): Observable<CoarTranslations>;
+}
+/**
+ * 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}}!"
+ * }
+ * ```
+ */
+declare class CoarHttpTranslationLoader implements CoarTranslationLoader {
+    private readonly http;
+    /** Base path for translation files */
+    basePath: string;
+    loadTranslations(language: string): Observable<CoarTranslations>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarHttpTranslationLoader, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CoarHttpTranslationLoader>;
+}
+
+/**
+ * Configuration for Cocoar i18n system.
+ */
+interface CoarI18nConfig {
+    /**
+     * Translation loader to use.
+     *
+     * Provide a class that implements `CoarTranslationLoader`.
+     *
+     * ## Built-in loaders
+     * - `CoarHttpTranslationLoader` - Load from HTTP (default)
+     *
+     * ## Custom loader
+     * ```ts
+     * @Injectable()
+     * class MyLoader implements CoarTranslationLoader {
+     *   loadTranslations(lang: string): Observable<CoarTranslations> {
+     *     // Your implementation
+     *   }
+     * }
+     *
+     * provideCoarI18n({ loader: MyLoader })
+     * ```
+     */
+    loader?: Type<CoarTranslationLoader>;
+    /**
+     * Base path for HTTP loader.
+     *
+     * Only used when `loader` is `CoarHttpTranslationLoader`.
+     *
+     * @default '/i18n/'
+     */
+    basePath?: string;
+}
+/**
+ * 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
+ */
+declare function provideCoarI18n(config?: CoarI18nConfig): EnvironmentProviders;
+
+/**
+ * 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()],
+ * };
+ * ```
+ */
+declare function provideCoarDefaultI18n(): Provider;
+
+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 };
+export type { CoarCurrencyFormatData, CoarDateFormatData, CoarHttpLocaleSourceConfig, CoarI18nConfig, CoarI18nProvider, CoarLocalizationConfig, CoarLocalizationData, CoarNumberFormatData, CoarPercentFormatData, CoarTranslations };