@flusys/ng-localization 1.2.0-rc.1

package/README.md

@@ -0,0 +1,144 @@
+# @flusys/ng-localization
+
+Database-driven i18n for FLUSYS Angular apps — translations loaded from the backend at startup, signal-reactive `TranslatePipe`, RTL/LTR auto-switching, and a built-in language selector for the topbar.
+
+[![npm version](https://img.shields.io/npm/v/@flusys/ng-localization.svg)](https://www.npmjs.com/package/@flusys/ng-localization)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Installation
+
+```bash
+npm install @flusys/ng-localization
+```
+
+## 1. Register Providers
+
+Call `provideLocalization()` once in `app.config.ts`. It registers ``(consumed by`TranslatePipe`from`ng-shared`), an `APP_INITIALIZER` that loads translations before the first render, and optionally the topbar language selector.
+
+```typescript
+// app.config.ts
+import { provideLocalization } from "@flusys/ng-localization";
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideLocalization({
+      defaultLanguageCode: "en", // required — fallback when no saved preference
+      loadStrategy: "modules", // optional — 'modules' (default) or 'all'
+      initialModules: [], // optional — modules to pre-load at startup
+      enableLayoutSelector: true, // optional — renders language picker in AppTopbar
+    }),
+  ],
+};
+```
+
+`loadStrategy: 'modules'` defers loading until a route resolver requests a module. Use `'all'` only for small translation sets.
+
+## 2. Use TranslatePipe in Templates
+
+Import `TranslatePipe` from `@flusys/ng-shared` (not from this package). The pipe is signal-reactive and re-renders automatically on language change.
+language
+
+```typescript
+import { TranslatePipe } from "@flusys/ng-shared";
+
+@Component({
+  imports: [TranslatePipe],
+  template: `
+    <h1>{{ "dashboard.title" | translate }}</h1>
+    <button>{{ "shared.save" | translate }}</button>
+    <input [placeholder]="'form.search.placeholder' | translate" />
+
+    <!-- With interpolation -->
+    <p>{{ "pagination.showing" | translate: { from: 1, to: 10, total: 100 } }}</p>
+  `,
+})
+export class DashboardComponent {}
+```
+
+Translation values stored in the database use `{{variableName}}` syntax:
+
+```
+Key:   pagination.showing
+Value: Showing {{from}}-{{to}} of {{total}} results
+```
+
+## 3. Load Translations Per Route (Module Strategy)
+
+Use `resolveTranslationModule()` in your route definition so translations for a feature load before the page renders. Pass `fallbackMessages` so the UI works even without a backend.
+
+```typescript
+// Inside a feature's routes file
+import { resolveTranslationModule } from "@flusys/ng-shared";
+import { MY_FEATURE_MESSAGES } from "./constants/messages";
+
+export const MY_ROUTES: Routes = [
+  {
+    path: "",
+    resolve: {
+      translations: resolveTranslationModule({
+        modules: ["myFeature"], // module name used by the backend
+        fallbackMessages: MY_FEATURE_MESSAGES, // static fallback map
+      }),
+    },
+    loadComponent: () => import("./my-feature-container.component").then((m) => m.MyFeatureContainerComponent),
+    children: [
+      /* ... */
+    ],
+  },
+];
+```
+
+Already-loaded modules are cached — navigating back to the same route does not re-fetch.
+
+## 4. Translate Imperatively in Services / Components
+
+Inject `TranslateService` when you need a string outside a template (e.g., toast messages, computed labels).
+
+```typescript
+import { inject } from "@angular/core";
+import { TranslateService } from "@flusys/ng-localization";
+
+export class MyComponent {
+  private readonly translate = inject(TranslateService);
+
+  // Synchronous — returns fallback key if not found
+  getLabel(): string {
+    return this.translate.translate("shared.save");
+  }
+
+  // With params
+  getCountLabel(count: number): string {
+    return this.translate.translate("items.count", { count });
+  }
+
+  // Signal-based — updates automatically on language change
+  readonly pageTitle = this.translate.translateSignal("dashboard.title");
+
+  // Read current language code
+  readonly lang = this.translate.languageCode; // Signal<string>
+}
+```
+
+## 5. Add Admin Routes (Language and Key Management)
+
+```typescript
+// app.routes.ts
+import { LOCALIZATION_ROUTES } from "@flusys/ng-localization";
+
+export const routes: Routes = [
+  {
+    path: "localization",
+    loadChildren: () => LOCALIZATION_ROUTES,
+  },
+];
+```
+
+## RTL Support
+
+When the user switches to an RTL language, `LocalizationStateService` sets `document.documentElement.dir` and `lang` automatically. Tailwind `rtl:` utility classes and component RTL support both activate from this single attribute change — no extra configuration needed.
+
+## License
+
+MIT © FLUSYS