@cocoar/localization 0.1.0-beta.155 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocoar/localization",
-  "version": "0.1.0-beta.155",
+  "version": "0.1.0",
   "description": "Localization and language management for the Cocoar Design System",
   "author": "Cocoar",
   "license": "Apache-2.0",
@@ -26,12 +26,12 @@
   },
   "peerDependencies": {
     "@js-temporal/polyfill": "^0.5.1",
-    "@angular/common": "21.0.6",
+    "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
     "rxjs": "^7.0.0"
   },
   "dependencies": {
-    "@cocoar/ts-utils": "0.1.0-beta.155",
+    "@cocoar/ts-utils": "0.1.0",
     "tslib": "^2.3.0"
   },
   "sideEffects": false,

package/types/cocoar-localization.d.ts

@@ -226,12 +226,19 @@ declare abstract class CoarLocalizationDataLoader {
     static ɵprov: i0.ɵɵInjectableDeclaration<CoarLocalizationDataLoader>;
 }
 /**
- * HTTP-based locale data loader.
- * Loads locale data from JSON files via HTTP.
+ * HTTP-based locale data loader with BCP 47 fallback.
  *
- * Supports custom URL patterns and headers for authentication/configuration.
+ * Loads locale data from JSON files via HTTP.
  * Typically used as a second source (after Intl) to provide business-specific overrides.
  *
+ * When a full BCP 47 tag is used (e.g., `de-AT`), the loader:
+ * 1. Loads the base language file (`de.json`)
+ * 2. Tries to load the regional file (`de-AT.json`)
+ * 3. Deep-merges them — regional fields override base fields
+ *
+ * If the regional file doesn't exist, the base file is used as-is.
+ * If the base file doesn't exist either, the loader fails (propagated to caller).
+ *
  * @example
  * ```typescript
  * // Simple base path
@@ -247,6 +254,15 @@ declare abstract class CoarLocalizationDataLoader {
  *   { 'Authorization': 'Bearer token' }
  * )
  * ```
+ *
+ * ## Expected file structure
+ * ```
+ * /locales/
+ *   en.json       ← base English overrides
+ *   en-AT.json    ← optional: Austrian-specific overrides on top of en.json
+ *   de.json       ← base German overrides
+ *   de-AT.json    ← optional: Austrian-specific overrides on top of de.json
+ * ```
  */
 declare class CoarHttpLocaleDataLoader extends CoarLocalizationDataLoader {
     private readonly httpClient;
@@ -254,6 +270,7 @@ declare class CoarHttpLocaleDataLoader extends CoarLocalizationDataLoader {
     private readonly headers?;
     constructor(httpClient: HttpClient, urlFn: (language: string) => string, headers?: Record<string, string> | undefined);
     loadLocaleData(locale: string): Observable<CoarLocalizationData>;
+    private loadFile;
 }
 
 /**
@@ -451,6 +468,8 @@ declare class CoarLocalizationDataStore {
      * Clear all loaded locale data.
      */
     clear(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CoarLocalizationDataStore, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CoarLocalizationDataStore>;
 }
 
 /**
@@ -1073,10 +1092,21 @@ declare abstract class CoarTranslationLoader {
     abstract loadTranslations(language: string): Observable<CoarTranslations>;
 }
 /**
- * HTTP-based translation loader.
+ * HTTP-based translation loader with BCP 47 fallback.
  *
  * Loads translation JSON files from a configurable URL function.
  *
+ * When a full BCP 47 tag is used (e.g., `de-AT`), the loader:
+ * 1. Loads the base language file (`de.json`)
+ * 2. Tries to load the regional file (`de-AT.json`)
+ * 3. Merges them — regional keys override base keys
+ *
+ * If the regional file doesn't exist, the base file is used as-is.
+ * If the base file doesn't exist either, the loader fails (propagated to caller).
+ *
+ * This means `en.json` serves all English variants. An optional `en-AT.json`
+ * only needs to contain keys that differ from the base.
+ *
  * ## Usage
  * ```ts
  * const loader = new CoarHttpTranslationLoader();
@@ -1084,6 +1114,15 @@ declare abstract class CoarTranslationLoader {
  * loader.headers = { 'Authorization': 'Bearer token' };
  * ```
  *
+ * ## Expected file structure
+ * ```
+ * /i18n/
+ *   en.json       ← base English (used for en-US, en-GB, en-AT, etc.)
+ *   en-AT.json    ← optional: only keys that differ from en.json
+ *   de.json       ← base German
+ *   de-AT.json    ← optional: Austrian overrides (if any)
+ * ```
+ *
  * ## Expected JSON format
  * ```json
  * {
@@ -1100,6 +1139,7 @@ declare class CoarHttpTranslationLoader implements CoarTranslationLoader {
     /** Optional HTTP headers */
     headers?: Record<string, string>;
     loadTranslations(language: string): Observable<CoarTranslations>;
+    private loadFile;
     static ɵfac: i0.ɵɵFactoryDeclaration<CoarHttpTranslationLoader, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<CoarHttpTranslationLoader>;
 }