@flusys/ng-localization 4.0.0-rc

package/README.md

@@ -0,0 +1,975 @@
+# Localization Package Guide
+
+> **Package:** `@flusys/ng-localization`
+> **Version:** 4.0.0-rc
+> **Type:** Multi-language support with signal-based state management, RTL support, and dynamic translation loading
+
+---
+
+## Overview
+
+`@flusys/ng-localization` provides a complete localization system:
+
+- **Multi-Language Support** - Dynamic language switching at runtime
+- **RTL Support** - Automatic right-to-left direction handling
+- **Signal-Based State** - Reactive state management with Angular signals
+- **Fallback Messages** - Static fallback messages when localization is disabled
+- **Variable Interpolation** - `{{variable}}` syntax in translations
+- **Lazy Loading** - Load translations per module or language
+- **Language Selector** - Dropdown component for topbar integration
+- **Admin Pages** - Language and translation management UI
+- **Provider Pattern** - Independent via injection tokens
+
+### Package Hierarchy
+
+```
+@flusys/ng-core           <- Foundation (APP_CONFIG, TRANSLATE_ADAPTER token)
+        |
+@flusys/ng-shared         <- TranslatePipe (uses TRANSLATE_ADAPTER)
+        |
+@flusys/ng-layout         <- Layout (LAYOUT_LANGUAGE_SELECTOR token)
+        |
+@flusys/ng-localization   <- Localization system (THIS PACKAGE)
+```
+
+### Layout Integration
+
+Language selector integrates with ng-layout via Provider Interface Pattern:
+
+```typescript
+import { LAYOUT_LANGUAGE_SELECTOR } from '@flusys/ng-layout';
+
+// ng-localization provides the selector component
+{ provide: LAYOUT_LANGUAGE_SELECTOR, useValue: LanguageSelectorComponent }
+
+// ng-layout renders it dynamically
+@if (languageSelectorComponent) {
+  <ng-container *ngComponentOutlet="languageSelectorComponent" />
+}
+```
+
+---
+
+## Package Architecture
+
+```
+ng-localization/
+├── constants/
+│   ├── localization.constants.ts      # STORAGE_KEYS, DEFAULT_LANGUAGE_CODE
+│   └── index.ts
+├── interfaces/
+│   ├── language.interface.ts          # ILanguage, ITranslationsMap
+│   ├── localization-config.interface.ts # ILocalizationConfig, tokens
+│   ├── translation-key.interface.ts   # ITranslationKey
+│   ├── translation.interface.ts       # ITranslation
+│   └── index.ts
+├── services/
+│   ├── localization-state.service.ts  # Signal-based state management
+│   ├── localization-api.service.ts    # API calls to backend
+│   ├── localization-initializer.service.ts # APP_INITIALIZER bootstrap
+│   ├── translate.service.ts           # Translation service
+│   ├── language-api.service.ts        # Language CRUD API
+│   ├── translation-key-api.service.ts # Translation key CRUD API
+│   ├── translation-api.service.ts     # Translation CRUD API
+│   └── index.ts
+├── pipes/
+│   └── translate.pipe.ts              # Optimized pipe with signal tracking
+├── components/
+│   └── language-selector/
+│       └── language-selector.component.ts # Topbar language dropdown
+├── providers/
+│   └── localization.providers.ts      # provideLocalization(), etc.
+├── pages/
+│   ├── routes.ts                      # LOCALIZATION_ROUTES
+│   ├── language-list/                 # Language management list
+│   ├── language-form/                 # Language create/edit form
+│   └── translation-list/              # Translation management
+└── public-api.ts
+```
+
+---
+
+## Storage
+
+### localStorage
+
+| Key | Purpose |
+|-----|---------|
+| `flusys.language` | Persists selected language code |
+
+### Signal State
+
+| Signal | Type | Purpose |
+|--------|------|---------|
+| `currentLanguage` | `ILanguage \| null` | Current selected language |
+| `availableLanguages` | `ILanguage[]` | List of available languages |
+| `translations` | `ITranslationsMap` | Key-value translation map |
+| `isLoading` | `boolean` | Loading state |
+| `isInitialized` | `boolean` | Initialization complete |
+
+---
+
+## Route Integration
+
+### Adding Localization Routes
+
+```typescript
+// app.routes.ts
+import { LOCALIZATION_ROUTES } from '@flusys/ng-localization';
+
+export const routes: Routes = [
+  {
+    path: '',
+    component: AppLayout,
+    children: [
+      {
+        path: 'localization',
+        children: LOCALIZATION_ROUTES,
+      },
+    ],
+  },
+];
+```
+
+### Route Structure
+
+| Path | Component | Purpose |
+|------|-----------|---------|
+| `/localization/languages` | LanguageListPage | Language management |
+| `/localization/languages/new` | LanguageFormPage | Create language |
+| `/localization/languages/:id` | LanguageFormPage | Edit language |
+| `/localization/translations` | TranslationListPage | Translation management |
+
+---
+
+## Enabled vs Disabled Behavior
+
+The localization system has two modes controlled by provider presence:
+
+### When Localization is ENABLED (`provideLocalization()` provided)
+
+| Aspect | Behavior |
+|--------|----------|
+| **Initialization** | Fetches active languages and translations from backend API |
+| **Translation Resolution** | API translations → Fallback messages → Key |
+| **API Calls** | Yes (on app init and language switch) |
+| **Language Switching** | Fully functional via `LanguageSelectorComponent` |
+| **RTL Support** | Dynamic based on selected language direction |
+| **Error Messages** | Translated using API-loaded translations |
+
+### When Localization is DISABLED (only `provideFallbackLocalization()` or no provider)
+
+| Aspect | Behavior |
+|--------|----------|
+| **Initialization** | Skips all API calls, immediately marks as initialized |
+| **Translation Resolution** | Fallback messages → Key (no API lookup) |
+| **API Calls** | None (better performance, no network dependency) |
+| **Language Switching** | Not functional (no languages loaded) |
+| **RTL Support** | No effect (defaults to LTR) |
+| **Error Messages** | Uses hardcoded fallback messages from route resolvers |
+
+### Use Cases
+
+| Scenario | Configuration |
+|----------|---------------|
+| **Multi-language app** | `provideLocalization(config)` with backend translations |
+| **Single-language app** | `provideFallbackLocalization()` with fallback messages only |
+| **Development/Testing** | `provideFallbackLocalization()` for faster startup |
+| **Offline-first apps** | `provideFallbackLocalization()` with embedded messages |
+
+### Translation Resolution Flow
+
+```
+TranslatePipe receives key
+        ↓
+Check if LOCALIZATION_CONFIG exists (provider was provided)
+        ↓
+If not → Look up in fallbackMessages (from route resolver) → Return value or key
+        ↓
+If yes → Look up in LocalizationStateService.translations()
+        ↓
+If not found → Look up in LocalizationStateService.fallbackMessages()
+        ↓
+If still not found → Return original key
+```
+
+**Note:** Fallback messages are populated per-module via route resolvers. Each module's fallbacks are merged into the state service when the route loads.
+
+---
+
+## Provider Setup
+
+### Basic Setup (Localization Enabled with API)
+
+```typescript
+// app.config.ts
+import { provideLocalization } from '@flusys/ng-localization';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // Enable full localization with API support
+    ...provideLocalization({
+      defaultLanguageCode: 'en',
+      loadStrategy: 'modules',
+      initialModules: ['shared', 'layout'],
+      enableLayoutSelector: true,
+    }),
+  ],
+};
+```
+
+### Fallback-Only Setup (Localization Disabled)
+
+```typescript
+// app.config.ts
+import { provideFallbackLocalization } from '@flusys/ng-shared';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // Use fallback messages only (no API calls)
+    ...provideFallbackLocalization(),
+  ],
+};
+```
+
+### What Providers Register
+
+```typescript
+// provideLocalization(config)
+{ provide: LOCALIZATION_CONFIG, useValue: config },
+LocalizationStateService,
+LocalizationApiService,
+LocalizationInitializerService,
+TranslateService,
+{ provide: TRANSLATE_ADAPTER, useExisting: TranslateService },
+{ provide: APP_INITIALIZER, useFactory: initializeLocalization, multi: true },
+
+// if enableLayoutSelector: true
+{ provide: LAYOUT_LANGUAGE_SELECTOR, useValue: LanguageSelectorComponent }
+```
+
+### Module-Wise Translation Loading (Mandatory)
+
+Translations are loaded **per-module via route resolvers**, NOT at app initialization. This provides:
+
+- **Faster initial load** - Only load translations needed for current route
+- **Smaller memory footprint** - Each route loads only its module's translations
+- **On-demand loading** - Translations fetched when navigating to a feature
+
+### How It Works
+
+1. **App initialization** - Only loads available languages from API (no translations)
+2. **Route navigation** - Route resolver loads that module's translations
+3. **Translations merge** - New module translations merge with existing ones
+
+### Setup Pattern
+
+**Step 1: Configure main app layout with shared/layout modules and their fallback messages**
+
+```typescript
+// app.routes.ts
+import { resolveTranslationModule, SHARED_MESSAGES, LAYOUT_MESSAGES } from '@flusys/ng-shared';
+
+export const routes: Routes = [
+  {
+    path: '',
+    component: AppLayout,
+    canActivate: [appInitGuard],
+    // Load shared + layout translations with fallback messages
+    resolve: {
+      translations: resolveTranslationModule({
+        modules: ['shared', 'layout'],
+        fallbackMessages: { ...SHARED_MESSAGES, ...LAYOUT_MESSAGES }
+      })
+    },
+    children: [
+      { path: 'storage', children: STORAGE_ROUTES },
+      { path: 'iam', children: IAM_ROUTES },
+      // ...
+    ],
+  },
+];
+```
+
+**Step 2: Each feature module loads its own translations with its fallback messages**
+
+```typescript
+// storage.routes.ts
+import { resolveTranslationModule, SHARED_MESSAGES } from '@flusys/ng-shared';
+import { STORAGE_MESSAGES } from '@flusys/ng-storage';
+
+export const STORAGE_ROUTES: Routes = [
+  {
+    path: '',
+    resolve: {
+      translations: resolveTranslationModule({
+        modules: ['storage'],
+        fallbackMessages: STORAGE_MESSAGES
+      })
+    },
+    children: [
+      // Storage pages...
+    ],
+  },
+];
+```
+
+### Route Resolver Interface
+
+```typescript
+interface IResolverModuleConfig {
+  modules: string[];                    // Module names to load
+  fallbackMessages?: ITranslationsMap;  // Fallback messages for these modules
+}
+```
+
+### Route Resolver Function
+
+| Function | Usage | Example |
+|----------|-------|---------|
+| `resolveTranslationModule(config)` | Load modules with fallback messages | `resolveTranslationModule({ modules: ['auth'], fallbackMessages: AUTH_MESSAGES })` |
+
+### Available Modules
+
+> **Key Format:** All translation keys use **full dot-case** — every word separated by a dot, all lowercase. No camelCase anywhere in keys.
+> ```
+> ✅ event.manager.form.title.required
+> ❌ eventManager.formTitleRequired
+> ```
+
+| Module | Keys Prefix | Package | Route |
+|--------|-------------|---------|-------|
+| `shared` | `shared.*` | ng-shared | Main layout (always loaded) |
+| `layout` | `layout.*` | ng-layout | Main layout (always loaded) |
+| `auth` | `auth.*` | ng-auth | `/auth/*`, `/administration/*` |
+| `iam` | `iam.*` | ng-iam | `/iam/*` |
+| `storage` | `storage.*` | ng-storage | `/storage/*` |
+| `formBuilder` | `formBuilder.*` | ng-form-builder | `/forms/*` |
+| `email` | `email.*` | ng-email | `/email/*` |
+| `notification` | `notification.*` | ng-notification | `/notifications/*` |
+| `eventManager` | `event.manager.*` | ng-event-manager | `/event-manager/*` |
+| `localization` | `localization.*` | ng-localization | `/localization/*` |
+
+### Module Loading Flow
+
+```
+User navigates to /storage/folders
+        ↓
+Router activates STORAGE_ROUTES
+        ↓
+Route resolver resolveTranslationModule(config) executes
+        ↓
+Register fallback messages for the module
+        ↓
+Check if LOCALIZATION_CONFIG exists (provider was used)
+        ↓
+If not → Return immediately (use fallback messages)
+        ↓
+POST /localization/translation/get-by-language
+{ languageCode: currentLanguage, modules: ['storage'] }
+        ↓
+LocalizationStateService.mergeTranslations(newTranslations)
+        ↓
+Component renders with storage translations available
+```
+
+### Best Practice: Hierarchical Module Loading with Per-Module Fallbacks
+
+Parent routes should load common modules, child routes load specific ones. Each route provides its own fallback messages:
+
+```typescript
+// Main layout loads shared + layout (needed everywhere)
+{
+  path: '',
+  component: AppLayout,
+  resolve: {
+    translations: resolveTranslationModule({
+      modules: ['shared', 'layout'],
+      fallbackMessages: { ...SHARED_MESSAGES, ...LAYOUT_MESSAGES }
+    })
+  },
+  children: [
+    // Feature routes load their own modules with their fallbacks
+    {
+      path: 'auth',
+      resolve: { translations: resolveTranslationModule({ modules: ['auth'], fallbackMessages: AUTH_MESSAGES }) },
+      ...
+    },
+    {
+      path: 'storage',
+      resolve: { translations: resolveTranslationModule({ modules: ['storage'], fallbackMessages: STORAGE_MESSAGES }) },
+      ...
+    },
+  ],
+}
+```
+
+This ensures:
+- `shared` and `layout` translations are available immediately after login
+- Feature-specific translations load only when needed
+- Each module has its own fallback messages that load with the module
+- No need to load ALL_MESSAGES at app startup
+
+---
+
+## Interfaces
+
+### ILanguage
+
+```typescript
+interface ILanguage {
+  id: string;
+  code: string;           // ISO 639-1 code (e.g., 'en', 'ar')
+  name: string;           // English name
+  nativeName: string | null; // Native name (e.g., 'العربية')
+  direction: 'ltr' | 'rtl' | null;
+  isActive: boolean;
+  isDefault: boolean;
+  serial: number | null;
+}
+```
+
+### ITranslationsMap
+
+```typescript
+type ITranslationsMap = Record<string, string>;
+
+// Example
+{
+  'shared.save': 'Save',
+  'shared.cancel': 'Cancel',
+  'auth.login.title': 'Login',
+}
+```
+
+### ILocalizationConfig
+
+```typescript
+interface ILocalizationConfig {
+  defaultLanguageCode: string; // Default language code (e.g., 'en')
+  loadStrategy?: 'all' | 'modules'; // 'all' = load all translations, 'modules' = load per-module (default: 'modules')
+  initialModules?: string[];   // Modules to load on app initialization (default: ['shared', 'layout'])
+  enableLayoutSelector?: boolean; // Enable language selector in layout (default: false)
+}
+```
+
+**Note:** Translations are always loaded per-module via route resolvers. The config only affects initialization behavior.
+
+### ITranslationKey
+
+```typescript
+interface ITranslationKey {
+  id: string;
+  module: string;          // Module grouping (e.g., 'auth', 'shared')
+  key: string;             // Translation key (e.g., 'auth.login.title')
+  defaultMessage: string;  // Default message (fallback)
+  description: string | null;
+  variables: string[] | null; // Required variables ['name', 'count']
+  isActive: boolean;
+  isReadonly: boolean;     // System keys cannot be deleted
+  serial: number | null;
+}
+```
+
+**Note:** Keys with `isReadonly: true` are system keys that cannot be deleted by users. The `module + key` combination must be unique (you cannot have duplicate keys within the same module).
+
+### ITranslation
+
+```typescript
+interface ITranslation {
+  id: string;
+  languageId: string;
+  translationKeyId: string;
+  value: string;
+  isVerified: boolean;
+  isActive: boolean;
+}
+```
+
+---
+
+## Tokens
+
+### LOCALIZATION_CONFIG
+
+Configuration for localization behavior:
+
+```typescript
+export const LOCALIZATION_CONFIG = new InjectionToken<ILocalizationConfig>('LOCALIZATION_CONFIG');
+```
+
+### LOCALIZATION_MODULE_FALLBACKS
+
+Module-specific fallback messages (populated via route resolvers):
+
+```typescript
+export const LOCALIZATION_MODULE_FALLBACKS = new InjectionToken<Map<string, ITranslationsMap>>('LOCALIZATION_MODULE_FALLBACKS');
+```
+
+**Note:** Fallback messages are now loaded per-module via route resolvers instead of globally at app startup. Use `resolveTranslationModule({ modules: [...], fallbackMessages: ... })` to register fallbacks for each module.
+
+### TRANSLATE_ADAPTER (from ng-core)
+
+Adapter interface for translation service:
+
+```typescript
+interface ITranslateAdapter {
+  translate(key: string, variables?: Record<string, string | number>): string;
+}
+
+export const TRANSLATE_ADAPTER = new InjectionToken<ITranslateAdapter>('TRANSLATE_ADAPTER');
+```
+
+---
+
+## Services
+
+### LocalizationStateService
+
+Central state management with signals:
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class LocalizationStateService {
+  // Public readonly signals
+  readonly currentLanguage: Signal<ILanguage | null>;
+  readonly availableLanguages: Signal<ILanguage[]>;
+  readonly translations: Signal<ITranslationsMap>;
+  readonly isLoading: Signal<boolean>;
+  readonly isInitialized: Signal<boolean>;
+
+  // Computed signals
+  readonly currentLanguageCode: Signal<string>;  // Defaults to 'en'
+  readonly isRtl: Signal<boolean>;
+
+  // Methods
+  setCurrentLanguage(language: ILanguage): void;
+  setAvailableLanguages(languages: ILanguage[]): void;
+  setTranslations(translations: ITranslationsMap): void;
+  mergeTranslations(translations: ITranslationsMap): void;
+  clearTranslations(): void;
+  setLoading(loading: boolean): void;
+  setInitialized(initialized: boolean): void;
+  getSavedLanguageCode(): string | null;
+}
+```
+
+**Automatic Features:**
+- Updates `document.dir` on language change (ltr/rtl)
+- Updates `document.lang` attribute
+- Persists language code to localStorage
+
+### TranslateService
+
+Translation with variable interpolation:
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class TranslateService {
+  // Synchronous translation
+  translate(key: string, variables?: Record<string, string | number>): string;
+
+  // Signal-based translation (reactive)
+  translateSignal(key: string, variables?: Record<string, string | number>): Signal<string>;
+
+  // Alias for translate()
+  instant(key: string, variables?: Record<string, string | number>): string;
+}
+```
+
+**Translation Resolution Order:**
+1. If `isActive: false`, use fallback messages
+2. Look up key in current language translations
+3. Fall back to `LOCALIZATION_FALLBACK_MESSAGES`
+4. Return key if not found anywhere
+
+### LocalizationApiService
+
+API calls to backend:
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class LocalizationApiService {
+  // Get active languages (no auth required)
+  getActiveLanguages(): Observable<IListResponse<ILanguage>>;
+
+  // Get translations for one or more modules in a language (no auth required)
+  getTranslationsByLanguage(languageCode: string, modules?: string[]): Observable<ISingleResponse<ITranslationsMap>>;
+}
+```
+
+### LocalizationInitializerService
+
+APP_INITIALIZER bootstrap (languages only, NOT translations):
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class LocalizationInitializerService {
+  async initialize(): Promise<void>;
+}
+```
+
+**Initialization Flow:**
+1. Check if `LOCALIZATION_CONFIG` is provided (if not, mark initialized and return)
+2. Load available languages from API
+3. Determine language: saved → default → first available
+4. Set current language
+5. Mark as initialized
+
+**Important:** Translations are NOT loaded during initialization. They are loaded per-module via route resolvers (`resolveTranslationModule`). This ensures faster app startup and on-demand translation loading
+
+---
+
+## Pipes
+
+### TranslatePipe
+
+Optimized pipe with signal-based language change detection:
+
+```typescript
+@Pipe({
+  name: 'translate',
+  pure: false,  // Reacts to language changes
+})
+export class TranslatePipe implements PipeTransform {
+  transform(key: string, variables?: Record<string, string | number>): string;
+}
+```
+
+**Note:** `standalone: true` is implicit in Angular 21 and not required in decorators.
+
+**Usage:**
+
+```html
+<!-- Simple translation -->
+<span>{{ 'shared.save' | translate }}</span>
+
+<!-- With variables -->
+<span>{{ 'shared.welcome' | translate: { name: userName } }}</span>
+```
+
+---
+
+## Components
+
+### LanguageSelectorComponent
+
+Topbar language dropdown:
+
+```typescript
+@Component({
+  selector: 'lib-language-selector',
+  standalone: true,
+})
+export class LanguageSelectorComponent {
+  readonly languages: Signal<ILanguage[]>;
+  selectedLanguageCode: WritableSignal<string>;
+
+  onLanguageChange(code: string): void;
+}
+```
+
+**Features:**
+- PrimeNG p-select dropdown
+- Shows language code in selected item (uppercase)
+- Shows native name in dropdown options
+- Automatically loads translations on change
+
+---
+
+## Backend Integration
+
+All endpoints use **POST-only RPC** style (not REST).
+
+### API Endpoints
+
+| Endpoint | Auth | Description |
+|----------|------|-------------|
+| `POST /localization/language/get-active` | None | Get active languages |
+| `POST /localization/language/get-default` | None | Get default language |
+| `POST /localization/translation/get-by-language` | None | Get translations by language code |
+| `POST /localization/translation/get-by-module` | None | Get translations by module + language |
+
+### Admin Endpoints
+
+| Endpoint | Permission | Description |
+|----------|------------|-------------|
+| `POST /localization/language/insert` | `language.create` | Create language |
+| `POST /localization/language/update` | `language.update` | Update language |
+| `POST /localization/language/delete` | `language.delete` | Delete language |
+| `POST /localization/language/set-default` | `language.update` | Set default language |
+| `POST /localization/translation/update-many-values` | `translation.update` | Bulk update translations |
+| `POST /localization/translation/get-missing` | `translation.read` | Get missing translations |
+
+---
+
+## Data Flow
+
+### Initialization Flow (Languages Only)
+
+```
+App bootstraps
+        ↓
+APP_INITIALIZER runs LocalizationInitializerService.initialize()
+        ↓
+Check if LOCALIZATION_CONFIG was provided
+        ↓
+If not provided → setInitialized(true) and return (use fallback only)
+        ↓
+POST /localization/language/get-active
+        ↓
+Set available languages
+        ↓
+Determine language (localStorage → default → first)
+        ↓
+Set current language, mark initialized
+        ↓
+App ready (NO translations loaded yet)
+        ↓
+User navigates to protected route
+        ↓
+Route resolver loads shared + layout translations + fallback messages
+        ↓
+User navigates to feature route
+        ↓
+Route resolver loads feature-specific translations + fallback messages
+```
+
+**Key Point:** Translations are NOT loaded during app initialization. They are loaded on-demand via route resolvers when navigating to each feature. Fallback messages are always available regardless of whether localization is enabled.
+
+### Language Switch Flow
+
+```
+User selects language in dropdown
+        ↓
+LanguageSelectorComponent.onLanguageChange(code)
+        ↓
+LocalizationStateService.setCurrentLanguage(language)
+        ↓
+Effect updates document.dir, document.lang, localStorage
+        ↓
+POST /localization/translation/get-by-language
+        ↓
+LocalizationStateService.setTranslations(translations)
+        ↓
+TranslatePipe re-evaluates (pure: false)
+        ↓
+UI updates with new translations
+```
+
+### Translation Resolution Flow
+
+```
+{{ 'some.key' | translate: { var: value } }}
+        ↓
+TranslatePipe.transform(key, variables)
+        ↓
+TRANSLATE_ADAPTER.translate(key, variables)
+        ↓
+TranslateService.translate(key, variables)
+        ↓
+Check if LOCALIZATION_CONFIG exists
+        ↓
+If not provided → Look up in fallback messages (from route resolver)
+        ↓
+If provided → Look up in LocalizationStateService.translations()
+        ↓
+If found → Interpolate variables and return
+        ↓
+If not found → Look up in LocalizationStateService.fallbackMessages()
+        ↓
+If not found → Return original key
+```
+
+---
+
+## Usage Examples
+
+### Basic Translation
+
+```typescript
+import { TranslateService, TranslatePipe } from '@flusys/ng-localization';
+
+@Component({
+  imports: [TranslatePipe],
+  template: `
+    <h1>{{ 'auth.login.title' | translate }}</h1>
+    <button>{{ saveLabel() }}</button>
+  `,
+})
+export class MyComponent {
+  private readonly translateService = inject(TranslateService);
+
+  // Reactive signal-based translation
+  readonly saveLabel = this.translateService.translateSignal('shared.save');
+
+  // Imperative translation
+  showMessage() {
+    const message = this.translateService.translate('shared.success');
+    console.log(message);
+  }
+}
+```
+
+### With Variables
+
+```typescript
+// Translation key: "shared.welcome": "Welcome, {{name}}!"
+const greeting = translateService.translate('shared.welcome', { name: 'John' });
+// Output: "Welcome, John!"
+
+// Template
+{{ 'shared.itemCount' | translate: { count: items.length } }}
+```
+
+### Checking Current Language
+
+```typescript
+import { LocalizationStateService } from '@flusys/ng-localization';
+
+@Component({})
+export class MyComponent {
+  private readonly localizationState = inject(LocalizationStateService);
+
+  readonly currentLang = this.localizationState.currentLanguageCode;
+  readonly isRtl = this.localizationState.isRtl;
+
+  // Use in template
+  // [dir]="isRtl() ? 'rtl' : 'ltr'"
+}
+```
+
+### Manual Language Switch
+
+```typescript
+import { LocalizationStateService, LocalizationApiService } from '@flusys/ng-localization';
+
+@Component({})
+export class MyComponent {
+  private readonly localizationState = inject(LocalizationStateService);
+  private readonly localizationApi = inject(LocalizationApiService);
+
+  async switchToArabic() {
+    const language = this.localizationState.availableLanguages()
+      .find(l => l.code === 'ar');
+
+    if (language) {
+      this.localizationState.setCurrentLanguage(language);
+
+      const response = await firstValueFrom(
+        this.localizationApi.getTranslationsByLanguage('ar')
+      );
+
+      if (response.success && response.data) {
+        this.localizationState.setTranslations(response.data);
+      }
+    }
+  }
+}
+```
+
+---
+
+## Fallback Messages
+
+### Available Message Sets
+
+| File | Export | Module |
+|------|--------|--------|
+| `shared.messages.ts` | `SHARED_MESSAGES` | Common actions, labels, validation |
+| `auth.messages.ts` | `AUTH_MESSAGES` | Login, logout, password |
+| `iam.messages.ts` | `IAM_MESSAGES` | Roles, permissions, companies |
+| `storage.messages.ts` | `STORAGE_MESSAGES` | File upload/download |
+| `form-builder.messages.ts` | `FORM_BUILDER_MESSAGES` | Form builder |
+| `email.messages.ts` | `EMAIL_MESSAGES` | Email |
+| `notification.messages.ts` | `NOTIFICATION_MESSAGES` | Notifications |
+| `event-manager.messages.ts` | `EVENT_MANAGER_MESSAGES` | Calendar, events |
+| `localization.messages.ts` | `LOCALIZATION_MESSAGES` | Language & translation management |
+| `index.ts` | `ALL_MESSAGES` | Combined export of all messages |
+
+### Using Fallback Messages
+
+```typescript
+import { ALL_MESSAGES, SHARED_MESSAGES, AUTH_MESSAGES } from '@flusys/ng-shared';
+
+// All messages combined
+provideLocalizationFallback(ALL_MESSAGES)
+
+// Or specific modules only
+provideLocalizationFallback({
+  ...SHARED_MESSAGES,
+  ...AUTH_MESSAGES,
+})
+```
+
+---
+
+## RTL Support
+
+When a language with `direction: 'rtl'` is selected:
+
+1. `document.documentElement.dir` is set to `'rtl'`
+2. `document.documentElement.lang` is set to the language code
+3. `LocalizationStateService.isRtl()` returns `true`
+
+**Usage in Components:**
+
+```typescript
+@Component({
+  host: {
+    '[class.rtl]': 'localizationState.isRtl()',
+  },
+})
+export class MyComponent {
+  readonly localizationState = inject(LocalizationStateService);
+}
+```
+
+---
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| **Use TranslatePipe** | Prefer pipe over service for template translations |
+| **Signal-Based Translations** | Use `translateSignal()` for computed values that need to react to language changes |
+| **Organize Keys by Module** | Use `module.feature.action` naming (e.g., `auth.login.title`) |
+| **Provide Fallbacks** | Always provide `LOCALIZATION_FALLBACK_MESSAGES` |
+| **Handle Loading State** | Check `isInitialized()` before rendering translated content |
+| **RTL-Aware Styles** | Use logical CSS properties (margin-inline-start vs margin-left) |
+
+---
+
+## Public API Exports
+
+| Category | Exports |
+|----------|---------|
+| **Interfaces** | `ILanguage`, `ITranslationsMap`, `ILocalizationConfig`, `LocalizationLoadStrategy`, `ITranslationKey`, `ITranslation`, `IResolverModuleConfig` |
+| **Tokens** | `LOCALIZATION_CONFIG`, `LOCALIZATION_MODULE_FALLBACKS` |
+| **Constants** | `STORAGE_KEYS`, `DEFAULT_LANGUAGE_CODE` |
+| **Services** | `LocalizationStateService`, `LocalizationApiService`, `LocalizationInitializerService`, `TranslateService`, `LanguageApiService`, `TranslationKeyApiService`, `TranslationApiService` |
+| **Pipes** | `TranslatePipe` (optimized with signal tracking) |
+| **Components** | `LanguageSelectorComponent` |
+| **Providers** | `provideLocalization` |
+| **Routes** | `LOCALIZATION_ROUTES` |
+| **Pages** | `LanguageListPage`, `LanguageFormPage`, `TranslationListPage` |
+
+**Note:** `resolveTranslationModule` is now exported from `@flusys/ng-shared` for use across all packages. The ng-localization package uses it internally but consumers should import from ng-shared.
+
+---
+
+**Last Updated:** 2026-03-03
+**Version:** 3.0.3
+**Angular Version:** 21
+
+---
+
+## Latest Changes (v3.0.3)
+
+- **Removed deprecated `resolveTranslationModules()` function** - Use `resolveTranslationModule()` with config object
+- **Removed unused `getDefaultLanguage()` and `getTranslationsByModule()` from LocalizationApiService**
+- **Consolidated translation loading logic** in `TranslationLoaderService` for better maintainability
+- **Moved `resolveTranslationModule` to ng-shared** - Now part of base package, not ng-localization
+- **Simplified ILocalizationConfig** - Removed `isActive` and `cacheTimeout` properties
+- **Behavior change** - Localization presence is determined by provider existence, not `isActive` property
+- **Removed `standalone: true`** from TranslatePipe (implicit in Angular 21)