@fundamental-ngx/i18n 0.58.0-rc.99 → 0.58.0

package/README.md

@@ -18,36 +18,117 @@
 
 ## 1. Description
 
-`@fundamental-ngx/i18n` is a library that provides translation utilities for the Fundamental-ngx library.
-The library is tailored for the use in `fundamental-ngx` components and can be used for modifying the variety of the
-components' labels, hints, and descriptions.
+`@fundamental-ngx/i18n` provides centralized internationalization for Fundamental-ngx components with support for 37+ languages and runtime translation switching.
 
-Even though the library is tailored for the use in `fundamental-ngx` components, it can be used in any Angular application,
-where the simple translations are needed.
+### What's Included
 
-The library elements are for the runtime, which gives the possibility to swap the translations on the fly, without
-having to refresh the pages.
+- Pre-compiled translation data for 37+ languages (as `FD_LANGUAGE_*` constants)
+- Translation resolver utilities (signals, observables, and synchronous APIs)
+- `FdTranslatePipe` for template translations
+- Type-safe translation keys via `FdLanguage` interface
+
+### How It Works
+
+1. **Source**: Translation teams provide `.properties` files (Java-style format)
+2. **Build**: NX executor converts `.properties` → TypeScript modules
+3. **Export**: Language constants (`FD_LANGUAGE_ENGLISH`, `FD_LANGUAGE_GERMAN`, etc.)
+4. **Publish**: Compiled JavaScript (not source `.properties`) published to npm
+5. **Use**: Apps import language constants and translation utilities
+
+While designed for Fundamental-ngx components, this library works in any Angular application needing runtime-switchable translations.
+
+### Adding New Translation Keys
+
+> **This guide is for adding new translation keys (labels, ARIA attributes), NOT for adding new languages.**
+
+#### Quick Steps
+
+1. **Update interface**: Add key to [`FdLanguage`](src/lib/models/fd-language.ts) interface
+2. **Add to all .properties files**: Same key + English text in all 37+ language files
+3. **Run**: `nx run i18n:transform-translations`
+4. **Use**: Import and use in your component
+
+---
+
+#### Step 1: Update TypeScript Interface
+
+Add your key to `libs/i18n/src/lib/models/fd-language.ts`:
+
+```typescript
+export interface FdLanguage {
+    coreYourComponent: {
+        /** Description */
+        yourNewKey: FdLanguageKey;
+        keyWithParams: FdLanguageKey<{ count: number }>;
+    };
+}
+```
+
+> **Note**: `fd-language-key-identifier.ts` is auto-generated - don't edit it manually.
+
+#### Step 2: Add to ALL .properties Files
+
+Add to **all** files in `libs/i18n/src/lib/translations/` (use English text everywhere):
+
+```properties
+#XBUT: Button / #XFLD: Label / #XTIT: Title / #XACT: ARIA / #XMSG: Message
+coreYourComponent.yourNewKey = Your English text
+coreYourComponent.keyWithParams = Item {count}
+```
+
+**Why all files?** TypeScript requires identical keys across all languages. Translation teams will replace English placeholders later.
+
+#### Step 3: Generate TypeScript Files
+
+```bash
+nx run i18n:transform-translations
+```
+
+Auto-generates: `translations*.ts`, `fd-language-key-identifier.ts` (union type), test files
+
+#### Step 4: Use in Components
+
+**Template (pipe):**
+
+```typescript
+import { FdTranslatePipe } from '@fundamental-ngx/i18n';
+
+@Component({
+    imports: [FdTranslatePipe],
+    template: `<button>{{ 'coreYourComponent.yourNewKey' | fdTranslate }}</button>`
+})
+```
+
+**TypeScript (signal):**
+
+```typescript
+import { resolveTranslationSignal } from '@fundamental-ngx/i18n';
+
+protected readonly label = resolveTranslationSignal('coreYourComponent.yourNewKey');
+```
+
+**Post-merge**: Translation teams will provide proper translations in future releases.
 
 ## 2. Requirements
 
-To download and use Fundamental Library i18n package, you will first need to install
-the [node package manager](https://www.npmjs.com/get-npm). The library is intended for use with
-Angular 16.2 or newer. Prior knowledge of Angular is recommended, to use it fully library.
+- Node.js and npm
+- Angular 16.2 or newer
+- Prior Angular knowledge recommended
 
 ## 3. Versioning
 
-Check the [Breaking Changes](https://github.com/SAP/fundamental-ngx/wiki#breaking-changes) for the latest patches changes.
+See [Breaking Changes](https://github.com/SAP/fundamental-ngx/wiki#breaking-changes) for the latest updates.
 
 ## 4. Known Issues
 
-Please see [Issues](https://github.com/SAP/fundamental-ngx/issues).
+See [Issues](https://github.com/SAP/fundamental-ngx/issues).
 
 ## 5. Support
 
-If you encounter an issue, you can [create a ticket](https://github.com/SAP/fundamental-ngx/issues).
+[Create a ticket](https://github.com/SAP/fundamental-ngx/issues) for issues or questions.
 
 ## 6. Contributing
 
-If you want to contribute, please check the [CONTRIBUTING.md](https://github.com/SAP/fundamental-ngx/blob/main/CONTRIBUTING.md) documentation for contribution guidelines. Please follow the [Angular commit message guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit).
+Check [CONTRIBUTING.md](https://github.com/SAP/fundamental-ngx/blob/main/CONTRIBUTING.md) for guidelines. Follow [Angular commit message guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit).
 
-Check out the [NEW_COMPONENT.md](https://github.com/SAP/fundamental-ngx/blob/main/NEW_COMPONENT.md) guide on building a new component for the library and creating the necessary documentation for your new component.
+See [NEW_COMPONENT.md](https://github.com/SAP/fundamental-ngx/blob/main/NEW_COMPONENT.md) for creating new components.

package/fesm2022/fundamental-ngx-i18n.mjs

@@ -602,6 +602,9 @@ var json$z = {
     segmentedButton: {
         groupRoleDescription: 'Segmented Button Group',
         buttonRoleDescription: 'Segmented Button'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -1227,6 +1230,9 @@ var json$y = {
     segmentedButton: {
         groupRoleDescription: 'مجموعة الأزرار المقسَّمة',
         buttonRoleDescription: 'زر مقسَّم'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -1852,6 +1858,9 @@ var json$x = {
     segmentedButton: {
         groupRoleDescription: 'Група сегментирани бутони',
         buttonRoleDescription: 'Сегментиран бутон'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -2477,6 +2486,9 @@ var json$w = {
     segmentedButton: {
         groupRoleDescription: '分段式按钮组',
         buttonRoleDescription: '分段式按钮'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -3103,6 +3115,9 @@ var json$v = {
     segmentedButton: {
         groupRoleDescription: '分區按鈕群組',
         buttonRoleDescription: '分區按鈕'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -3728,6 +3743,9 @@ var json$u = {
     segmentedButton: {
         groupRoleDescription: 'Grupa segmentiranih gumbi',
         buttonRoleDescription: 'Segmentirani gumbi'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -4353,6 +4371,9 @@ var json$t = {
     segmentedButton: {
         groupRoleDescription: 'Skupina segmentovaných tlačítek',
         buttonRoleDescription: 'Segmentované tlačítko'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -4978,6 +4999,9 @@ var json$s = {
     segmentedButton: {
         groupRoleDescription: 'Segmenteret knapgruppe',
         buttonRoleDescription: 'Segmentknap'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -5603,6 +5627,9 @@ var json$r = {
     segmentedButton: {
         groupRoleDescription: 'Groep gesegmenteerde knoppen',
         buttonRoleDescription: 'Gesegmenteerde knop'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -6228,6 +6255,9 @@ var json$q = {
     segmentedButton: {
         groupRoleDescription: 'Segmented Button Group',
         buttonRoleDescription: 'Segmented Button'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -6853,6 +6883,9 @@ var json$p = {
     segmentedButton: {
         groupRoleDescription: 'Segmentoitu painikeryhmä',
         buttonRoleDescription: 'Segmentoitu painike'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -7478,6 +7511,9 @@ var json$o = {
     segmentedButton: {
         groupRoleDescription: 'Groupe de boutons segmentés',
         buttonRoleDescription: 'Bouton segmenté'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -8078,6 +8114,9 @@ var json$n = {
     segmentedButton: {
         groupRoleDescription: 'Segmented Button Group',
         buttonRoleDescription: 'Segmented Button'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -8703,6 +8742,9 @@ var json$m = {
     segmentedButton: {
         groupRoleDescription: 'Segmentierte Schaltflächengruppe',
         buttonRoleDescription: 'Segmentierte Schaltfläche'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -9328,6 +9370,9 @@ var json$l = {
     segmentedButton: {
         groupRoleDescription: 'Ομάδα Τμηματοποιημένου Κουμπιού',
         buttonRoleDescription: 'Τμηματοποιημένο Κουμπί'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -9953,6 +9998,9 @@ var json$k = {
     segmentedButton: {
         groupRoleDescription: 'קבוצת סרגלי לחצנים',
         buttonRoleDescription: 'סרגל לחצנים'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -10553,6 +10601,9 @@ var json$j = {
     segmentedButton: {
         groupRoleDescription: 'Segmented Button Group',
         buttonRoleDescription: 'Segmented Button'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -11178,6 +11229,9 @@ var json$i = {
     segmentedButton: {
         groupRoleDescription: 'Szegmentált gombcsoport',
         buttonRoleDescription: 'Szegmentált gomb'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -11803,6 +11857,9 @@ var json$h = {
     segmentedButton: {
         groupRoleDescription: 'Gruppo pulsanti segmentati',
         buttonRoleDescription: 'Pulsante segmentato'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -12428,6 +12485,9 @@ var json$g = {
     segmentedButton: {
         groupRoleDescription: 'セグメントボタングループ',
         buttonRoleDescription: 'セグメントボタン'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -13053,6 +13113,9 @@ var json$f = {
     segmentedButton: {
         groupRoleDescription: 'Сегменттелген түймелер тобы',
         buttonRoleDescription: 'Сегменттелген түйме'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -13678,6 +13741,9 @@ var json$e = {
     segmentedButton: {
         groupRoleDescription: '세그멘테이션된 버튼 그룹',
         buttonRoleDescription: '세그멘테이션된 버튼'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -14303,6 +14369,9 @@ var json$d = {
     segmentedButton: {
         groupRoleDescription: 'Kumpulan Butang Disegmenkan',
         buttonRoleDescription: 'Butang Disegmenkan'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -14928,6 +14997,9 @@ var json$c = {
     segmentedButton: {
         groupRoleDescription: 'Segmenteringsknapp-gruppe',
         buttonRoleDescription: 'Segmenteringsknapp'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -15553,6 +15625,9 @@ var json$b = {
     segmentedButton: {
         groupRoleDescription: 'Grupa przycisków podzielonych na segmenty',
         buttonRoleDescription: 'Przycisk podzielony na segmenty'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -16178,6 +16253,9 @@ var json$a = {
     segmentedButton: {
         groupRoleDescription: 'Grupo de botões segmentados',
         buttonRoleDescription: 'Botão segmentado'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -16803,6 +16881,9 @@ var json$9 = {
     segmentedButton: {
         groupRoleDescription: 'Grup de butoane segmentate',
         buttonRoleDescription: 'Buton segmentat'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -17428,6 +17509,9 @@ var json$8 = {
     segmentedButton: {
         groupRoleDescription: 'Группа сегментированных кнопок',
         buttonRoleDescription: 'Сегментированная кнопка'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -18053,6 +18137,9 @@ var json$7 = {
     segmentedButton: {
         groupRoleDescription: 'Grupa segmentirane dugmadi',
         buttonRoleDescription: 'Segmentirano dugme'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -18678,6 +18765,9 @@ var json$6 = {
     segmentedButton: {
         groupRoleDescription: 'Skupina segmentovaných tlačidiel',
         buttonRoleDescription: 'Segmentované tlačidlo'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -19303,6 +19393,9 @@ var json$5 = {
     segmentedButton: {
         groupRoleDescription: 'Skupina segmentiranih gumbov',
         buttonRoleDescription: 'Segmentirani gumb'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -19928,6 +20021,9 @@ var json$4 = {
     segmentedButton: {
         groupRoleDescription: 'Grupo de botones segmentados',
         buttonRoleDescription: 'Botón segmentado'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -20553,6 +20649,9 @@ var json$3 = {
     segmentedButton: {
         groupRoleDescription: 'Segmenterad knappgrupp',
         buttonRoleDescription: 'Segmenterad knapp'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -21178,6 +21277,9 @@ var json$2 = {
     segmentedButton: {
         groupRoleDescription: 'กลุ่มปุ่มที่แบ่งเซกเมนต์',
         buttonRoleDescription: 'ปุ่มที่แบ่งเซกเมนต์'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -21803,6 +21905,9 @@ var json$1 = {
     segmentedButton: {
         groupRoleDescription: 'Segmentlere Ayrılmış Düğme Grubu',
         buttonRoleDescription: 'Segmentlere Ayrılmış Düğme'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -22428,6 +22533,9 @@ var json = {
     segmentedButton: {
         groupRoleDescription: 'Група сегментованих кнопок',
         buttonRoleDescription: 'Сегментована кнопка'
+    },
+    coreObjectIdentifier: {
+        srOnlyAriaLabel: 'Object Identifier'
     }
 };
 
@@ -22889,6 +22997,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.1.4", ngImpor
                 }]
         }], ctorParameters: () => [{ type: i0.DestroyRef }, { type: i0.ChangeDetectorRef }] });
 
+/**
+ * @deprecated
+ * Use direct imports of components and directives.
+ */
 class I18nModule {
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.1.4", ngImport: i0, type: I18nModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule }); }
     static { this.ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "20.1.4", ngImport: i0, type: I18nModule, imports: [FdTranslatePipe, FdPatchLanguageDirective], exports: [FdTranslatePipe, FdPatchLanguageDirective] }); }