@cocoar/localization 0.1.0-beta.114 → 0.1.0-beta.115

package/types/cocoar-localization.d.ts

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { Signal, InjectionToken, EnvironmentProviders, PipeTransform, OnDestroy, Type, Provider } from '@angular/core';
+import { Signal, InjectionToken, EnvironmentProviders, PipeTransform, OnDestroy } from '@angular/core';
 import { Observable } from 'rxjs';
 import { HttpClient } from '@angular/common/http';
 import { Temporal } from '@js-temporal/polyfill';
@@ -139,17 +139,6 @@ declare class CoarLocalizationService {
      * ```
      */
     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.
      *
@@ -298,10 +287,6 @@ declare class CoarHttpLocaleDataLoader extends CoarLocalizationDataLoader {
  * Configuration for the locale system.
  */
 interface CoarLocalizationConfig {
-    /**
-     * List of available languages in the application.
-     */
-    availableLanguages: string[];
     /**
      * Default language to use on initialization.
      */
@@ -318,34 +303,33 @@ declare const COAR_LOCALIZATION_CONFIG: InjectionToken<CoarLocalizationConfig>;
  */
 declare const COAR_LOCALIZATION_DATA_LOADERS: InjectionToken<CoarLocalizationDataLoader[]>;
 /**
- * Provides the core locale system (language management).
+ * Provides the core localization system (language management + L10n + i18n).
+ *
+ * Automatically includes:
+ * - Language management (CoarLocalizationService)
+ * - L10n: Browser Intl API for number/date formatting (always first source)
+ * - i18n: Translation system (CoarI18nService + CoarTranslationStore)
  *
- * 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
+ * Add optional data sources with:
+ * - `provideCoarL10nHttpSource()` - Load L10n overrides from JSON files
+ * - `provideCoarI18nHttpSource()` - Load i18n translations from JSON files
+ * - Custom sources via multi-providers
  *
  * Sources are executed in registration order and deep-merged.
  *
  * @example
  * ```ts
- * // Minimal setup (no formatting data)
+ * // Basic setup (Intl formatting only, no i18n loader)
  * provideCoarLocalization({
- *   availableLanguages: ['en', 'de'],
  *   defaultLanguage: 'en',
  * })
  *
- * // With Intl defaults
- * provideCoarLocalization({...}),
- * provideCoarIntlLocalizationSource(),
- *
- * // With Intl + HTTP overrides
- * provideCoarLocalization({...}),
- * provideCoarIntlLocalizationSource(),
- * provideCoarHttpLocalizationSource({
+ * // With L10n overrides and i18n translations
+ * provideCoarLocalization({ defaultLanguage: 'en' }),
+ * provideCoarL10nHttpSource({
  *   url: (lang) => `/locales/${lang}.json`
  * }),
+ * provideCoarI18nHttpSource(),  // Defaults to /i18n/{lang}.json
  * ```
  */
 declare function provideCoarLocalization(config: CoarLocalizationConfig): EnvironmentProviders;
@@ -418,31 +402,6 @@ declare class CoarIntlLocaleDataLoader extends CoarLocalizationDataLoader {
     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.
  */
@@ -450,6 +409,8 @@ interface CoarHttpLocaleSourceConfig {
     /**
      * URL generator function that returns the URL for a given language.
      *
+     * @default (lang) => `/locales/${lang}.json`
+     *
      * @param language - Language code (e.g., 'en', 'de', 'en-US')
      * @returns URL to load locale data from
      *
@@ -460,7 +421,7 @@ interface CoarHttpLocaleSourceConfig {
      * url: (lang) => `https://cdn.example.com/locales/${lang}.json`
      * ```
      */
-    url: (language: string) => string;
+    url?: (language: string) => string;
     /**
      * Optional HTTP headers to include in requests.
      *
@@ -483,18 +444,16 @@ interface CoarHttpLocaleSourceConfig {
  *
  * @example
  * ```ts
- * // Basic usage (default URL pattern)
- * provideCoarHttpLocalizationSource({
- *   url: (lang) => `/locales/${lang}.json`
- * })
+ * // Basic usage (default: /locales/{lang}.json)
+ * provideCoarL10nHttpSource()
  *
  * // Custom URL pattern
- * provideCoarHttpLocalizationSource({
+ * provideCoarL10nHttpSource({
  *   url: (lang) => `/api/config/intl-${lang}.json`
  * })
  *
  * // With authentication
- * provideCoarHttpLocalizationSource({
+ * provideCoarL10nHttpSource({
  *   url: (lang) => `/api/locales/${lang}.json`,
  *   headers: {
  *     'Authorization': 'Bearer ' + getToken()
@@ -519,7 +478,7 @@ interface CoarHttpLocaleSourceConfig {
  * }
  * ```
  */
-declare function provideCoarHttpLocalizationSource(config: CoarHttpLocaleSourceConfig): EnvironmentProviders;
+declare function provideCoarL10nHttpSource(config?: CoarHttpLocaleSourceConfig): EnvironmentProviders;
 
 /**
  * Deep merge utility for locale data.
@@ -759,19 +718,16 @@ declare class CoarI18nContext {
  * - Reactive Signal-based API
  *
  * ## Usage
- * Use `provideCoarI18n()` to configure - don't instantiate directly.
+ * Use `provideCoarLocalization()` + `provideCoarI18nHttpSource()` to configure.
  *
  * @example
  * ```ts
  * export const appConfig: ApplicationConfig = {
  *   providers: [
  *     provideCoarLocalization({
- *       availableLanguages: ['en', 'de'],
  *       defaultLanguage: 'en',
  *     }),
- *     provideCoarI18n({
- *       loader: CoarHttpTranslationLoader,
- *     }),
+ *     provideCoarI18nHttpSource(),
  *   ],
  * };
  * ```
@@ -811,30 +767,6 @@ declare class CoarI18nService implements CoarI18nProvider {
     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.
  *
@@ -933,17 +865,22 @@ declare class CoarTranslationStore {
      * Stores all translations for a specific language.
      *
      * Replaces any existing translations for that language.
+     * Automatically flattens nested objects into dot notation.
      *
      * @param language - Language code (e.g., 'en', 'de')
-     * @param translations - Translation key-value pairs
+     * @param translations - Translation key-value pairs (flat or nested)
      *
      * @example
      * ```ts
-     * // HTTP: Load entire language at once
-     * store.setTranslations('en', { 'hello': 'Hello', 'goodbye': 'Goodbye' });
+     * // Flat format
+     * store.setTranslations('en', { 'hello': 'Hello', 'app.title': 'My App' });
+     *
+     * // Nested format (auto-flattened)
+     * store.setTranslations('en', { app: { title: 'My App' }, hello: 'Hello' });
+     * // Both produce the same result
      * ```
      */
-    setTranslations(language: string, translations: CoarTranslations): void;
+    setTranslations(language: string, translations: CoarTranslations | Record<string, unknown>): void;
     /**
      * Updates a single translation key for a specific language.
      *
@@ -968,12 +905,14 @@ declare class CoarTranslationStore {
      *
      * Only updates/adds the provided keys, keeps existing keys intact.
      * Creates the language if it doesn't exist.
+     * Automatically flattens nested objects into dot notation.
      *
      * @param language - Language code
-     * @param partialTranslations - Partial translation key-value pairs to merge
+     * @param partialTranslations - Partial translation key-value pairs to merge (flat or nested)
      *
      * @example
      * ```ts
+     * // Flat format
      * // Existing: { 'hello': 'Hello', 'goodbye': 'Goodbye' }
      * store.updateTranslations('en', { 'hello': 'Hi' });
      * // Result: { 'hello': 'Hi', 'goodbye': 'Goodbye' }
@@ -981,13 +920,20 @@ declare class CoarTranslationStore {
      *
      * @example
      * ```ts
+     * // Nested format (auto-flattened)
+     * store.updateTranslations('en', { app: { title: 'New Title' } });
+     * // Updates 'app.title' key
+     * ```
+     *
+     * @example
+     * ```ts
      * // SignalR: Batch update multiple keys
      * signalR.on('TranslationsBatchUpdated', ({ lang, updates }) => {
      *   store.updateTranslations(lang, updates);
      * });
      * ```
      */
-    updateTranslations(language: string, partialTranslations: CoarTranslations): void;
+    updateTranslations(language: string, partialTranslations: CoarTranslations | Record<string, unknown>): void;
     /**
      * Checks if translations for a language are loaded.
      *
@@ -1053,18 +999,13 @@ declare abstract 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`
+ * Loads translation JSON files from a configurable URL function.
  *
- * ## Custom path
+ * ## Usage
  * ```ts
  * const loader = new CoarHttpTranslationLoader();
- * loader.basePath = '/assets/translations/';
- * // Loads: /assets/translations/en.json
+ * loader.urlFn = (lang) => `/i18n/${lang}.json`;
+ * loader.headers = { 'Authorization': 'Bearer token' };
  * ```
  *
  * ## Expected JSON format
@@ -1078,117 +1019,102 @@ declare abstract class CoarTranslationLoader {
  */
 declare class CoarHttpTranslationLoader implements CoarTranslationLoader {
     private readonly http;
-    /** Base path for translation files */
-    basePath: string;
+    /** URL generator function */
+    urlFn: (language: string) => string;
+    /** Optional HTTP headers */
+    headers?: Record<string, string>;
     loadTranslations(language: string): Observable<CoarTranslations>;
     static ɵfac: i0.ɵɵFactoryDeclaration<CoarHttpTranslationLoader, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<CoarHttpTranslationLoader>;
 }
 
 /**
- * Configuration for Cocoar i18n system.
+ * Configuration for HTTP translation source.
  */
-interface CoarI18nConfig {
+interface CoarI18nHttpSourceConfig {
     /**
-     * Translation loader to use.
+     * URL generator function that returns the URL for a given language.
      *
-     * Provide a class that implements `CoarTranslationLoader`.
+     * @default (lang) => `/i18n/${lang}.json`
      *
-     * ## Built-in loaders
-     * - `CoarHttpTranslationLoader` - Load from HTTP (default)
+     * @param language - Language code (e.g., 'en', 'de', 'en-US')
+     * @returns URL to load translations from
      *
-     * ## Custom loader
+     * @example
      * ```ts
-     * @Injectable()
-     * class MyLoader implements CoarTranslationLoader {
-     *   loadTranslations(lang: string): Observable<CoarTranslations> {
-     *     // Your implementation
-     *   }
-     * }
-     *
-     * provideCoarI18n({ loader: MyLoader })
+     * url: (lang) => `/i18n/${lang}.json`
+     * url: (lang) => `/api/translations/${lang}.json`
+     * url: (lang) => `https://cdn.example.com/i18n/${lang}.json`
      * ```
      */
-    loader?: Type<CoarTranslationLoader>;
+    url?: (language: string) => string;
     /**
-     * Base path for HTTP loader.
-     *
-     * Only used when `loader` is `CoarHttpTranslationLoader`.
+     * Optional HTTP headers to include in requests.
      *
-     * @default '/i18n/'
+     * @example
+     * ```ts
+     * headers: {
+     *   'Authorization': 'Bearer token123',
+     *   'X-Custom-Header': 'value'
+     * }
+     * ```
      */
-    basePath?: string;
+    headers?: Record<string, string>;
 }
 /**
- * Provides complete Cocoar i18n system.
+ * Provides HTTP as a translation source.
  *
- * Sets up translation loading, storage, and automatic language synchronization.
+ * This loader fetches translation files from HTTP endpoints.
+ * Typically used for standard i18n scenarios where translations are stored as JSON files.
  *
- * ## 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.)
+ * **Note:** The i18n system is automatically included by `provideCoarLocalization()`.
+ * This function only registers the HTTP loader for loading translations.
  *
- * ## Basic usage
+ * @example
  * ```ts
- * import { provideCoarLocalization } from '@cocoar/localization';
- * import { provideCoarI18n } from '@cocoar/localization';
+ * // Basic usage (default: /i18n/{lang}.json)
+ * provideCoarI18nHttpSource()
  *
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     provideHttpClient(),
- *     provideCoarLocalization({
- *       availableLanguages: ['en', 'de', 'fr'],
- *       defaultLanguage: 'en',
- *     }),
- *     provideCoarI18n(),
- *   ],
- * };
- * ```
+ * // Custom path
+ * provideCoarI18nHttpSource({
+ *   url: (lang) => `/assets/translations/${lang}.json`
+ * })
  *
- * ## Custom HTTP path
- * ```ts
- * provideCoarI18n({
- *   basePath: '/assets/translations/',
+ * // With authentication
+ * provideCoarI18nHttpSource({
+ *   url: (lang) => `/api/translations/${lang}.json`,
+ *   headers: {
+ *     'Authorization': 'Bearer ' + getToken()
+ *   }
  * })
  * ```
  *
- * ## Custom loader (e.g., SignalR)
- * ```ts
- * @Injectable()
- * class SignalRTranslationLoader implements CoarTranslationLoader {
- *   loadTranslations(lang: string): Observable<CoarTranslations> {
- *     return this.signalR.getTranslations(lang);
+ * Expected file structure:
+ * ```
+ * public/i18n/
+ *   en.json  - English translations
+ *   de.json  - German translations
+ * ```
+ *
+ * JSON files should contain flat or nested translations:
+ * ```json
+ * {
+ *   "app": {
+ *     "title": "My App",
+ *     "button": {
+ *       "save": "Save",
+ *       "cancel": "Cancel"
+ *     }
  *   }
  * }
- *
- * 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.
+ * @returns Angular environment providers
  *
- * @example
- * ```ts
- * import { provideCoarDefaultI18n } from '@cocoar/localization';
- *
- * export const appConfig: ApplicationConfig = {
- *   providers: [provideCoarDefaultI18n()],
- * };
- * ```
+ * @see {@link CoarI18nHttpSourceConfig} for configuration options
  */
-declare function provideCoarDefaultI18n(): Provider;
+declare function provideCoarI18nHttpSource(config?: CoarI18nHttpSourceConfig): EnvironmentProviders;
 
-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 };
+export { COAR_I18N_PROVIDER, COAR_LOCALIZATION_CONFIG, COAR_LOCALIZATION_DATA_LOADERS, CoarCurrencyPipe, CoarDatePipe, CoarHttpLocaleDataLoader, CoarHttpTranslationLoader, CoarI18n, CoarI18nContext, CoarI18nPipe, CoarI18nService, CoarIntlLocaleDataLoader, CoarLocalizationDataLoader, CoarLocalizationDataStore, CoarLocalizationService, CoarNumberPipe, CoarPercentPipe, CoarTranslationLoader, CoarTranslationStore, coarInterpolate, coarIsMissingTranslation, mergeLocalizationData, provideCoarI18nHttpSource, provideCoarL10nHttpSource, provideCoarLocalization };
+export type { CoarCurrencyFormatData, CoarDateFormatData, CoarHttpLocaleSourceConfig, CoarI18nHttpSourceConfig, CoarI18nProvider, CoarLocalizationConfig, CoarLocalizationData, CoarNumberFormatData, CoarPercentFormatData, CoarTranslations };