@flusys/nestjs-localization 4.1.1 → 5.0.0

package/README.md

@@ -1,73 +1,9 @@
 # @flusys/nestjs-localization
 
-> Multi-language backend for NestJS — database-driven translations, `{{variable}}` interpolation, RTL support, missing-key detection, verification workflow, and module-scoped partial loading.
+Database-driven multi-language backend for NestJS — manage languages, translation keys (grouped by module), and per-language translation values with verification workflow, missing-key detection, and atomic bulk updates.
 
 [![npm version](https://img.shields.io/npm/v/@flusys/nestjs-localization.svg)](https://www.npmjs.com/package/@flusys/nestjs-localization)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![NestJS](https://img.shields.io/badge/NestJS-11.x-red.svg)](https://nestjs.com/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green.svg)](https://nodejs.org/)
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Features](#features)
-- [Compatibility](#compatibility)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Module Registration](#module-registration)
-  - [forRoot (Sync)](#forroot-sync)
-  - [forRootAsync (Factory)](#forrootasync-factory)
-- [Configuration Reference](#configuration-reference)
-- [Feature Toggles](#feature-toggles)
-- [API Endpoints](#api-endpoints)
-- [Entities](#entities)
-- [Translation Workflow](#translation-workflow)
-- [Variable Interpolation](#variable-interpolation)
-- [Fallback Chain](#fallback-chain)
-- [RTL Support](#rtl-support)
-- [Caching](#caching)
-- [Exported Services](#exported-services)
-- [Integration with API Responses](#integration-with-api-responses)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
-
----
-
-## Overview
-
-`@flusys/nestjs-localization` manages the backend side of multi-language support. Translations are stored in the database and served to the frontend via API. The package provides a full admin workflow: create languages, define translation keys (grouped by module), add translations per language, verify them, and detect missing ones.
-
-All API responses in the FLUSYS ecosystem return a `messageKey` field (e.g., `'auth.login_success'`). The frontend looks up this key in the translations returned by this package.
-
----
-
-## Features
-
-- **Language management** — Create languages with ISO 639-1 codes, native names, and RTL/LTR direction
-- **Translation keys** — Module-scoped key registry with variable declarations and readonly protection
-- **Translations** — Per-language values with a verification workflow (draft → verified)
-- **Variable interpolation** — `{{variableName}}` syntax in messages with `messageVariables` field in API responses
-- **Missing key detection** — Find which keys have no translation for a given language
-- **Bulk operations** — Atomic bulk update of multiple translations in one transaction
-- **Default language** — Configurable fallback language (e.g., `'en'`)
-- **Module scoping** — Keys grouped by module for partial frontend loading
-- **Caching** — Optional HybridCache for translation lookups with configurable TTL
-- **Multi-tenant** — Per-tenant DataSource isolation
-
----
-
-## Compatibility
-
-| Package | Version |
-|---------|---------|
-| `@flusys/nestjs-core` | `^4.0.0` |
-| `@flusys/nestjs-shared` | `^4.0.0` |
-| `@nestjs/core` | `^11.0.0` |
-| `typeorm` | `^0.3.0` |
-| Node.js | `>= 18.x` |
 
 ---
 
@@ -79,457 +15,99 @@ npm install @flusys/nestjs-localization @flusys/nestjs-shared @flusys/nestjs-cor
 
 ---
 
-## Quick Start
+## 1. Module Registration
 
-### Minimal Setup (Single Database)
+### forRoot (sync)
 
 ```typescript
-import { Module } from '@nestjs/common';
 import { LocalizationModule } from '@flusys/nestjs-localization';
 
-@Module({
-  imports: [
-    LocalizationModule.forRoot({
-      global: true,
-      includeController: true,
-      bootstrapAppConfig: {
-        databaseMode: 'single',
-        enableCompanyFeature: false,
-      },
-      config: {
-        defaultDatabaseConfig: {
-          type: 'postgres',
-          host: process.env.DB_HOST,
-          port: Number(process.env.DB_PORT ?? 5432),
-          username: process.env.DB_USER,
-          password: process.env.DB_PASSWORD,
-          database: process.env.DB_NAME,
-        },
-        defaultLanguageCode: 'en',
-        enableCaching: false,
-        cacheTtlSeconds: 300,
-      },
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-After startup, create languages and translation keys via the API. The frontend fetches translations on init and uses the `messageKey` returned by each API response to look up the localized message.
-
----
-
-## Module Registration
-
-### forRoot (Sync)
-
-```typescript
 LocalizationModule.forRoot({
-  global?: boolean;
-  includeController?: boolean;        // Default: true
-  bootstrapAppConfig?: {
-    databaseMode: 'single' | 'multi-tenant';
-    enableCompanyFeature: boolean;    // No company variants — shared data only
-  };
-  config: ILocalizationModuleConfig;
-})
-```
-
-### forRootAsync (Factory)
-
-```typescript
-import { ConfigService } from '@nestjs/config';
-
-LocalizationModule.forRootAsync({
   global: true,
-  includeController: true,
+  includeController: true, // registers Language, TranslationKey, Translation controllers
   bootstrapAppConfig: {
-    databaseMode: 'single',
-    enableCompanyFeature: false,
+    databaseMode: 'single', // 'single' | 'multi-tenant'
+    enableCompanyFeature: false, // localization has no company variants — this is ignored
   },
-  imports: [ConfigModule],
-  useFactory: (configService: ConfigService) => ({
+  config: {
+    defaultLanguageCode: 'en', // fallback language code
+    enableCaching: false, // optional HybridCache for translation lookups
+    cacheTtlSeconds: 300,
     defaultDatabaseConfig: {
-      type: 'postgres',
-      host: configService.get('DB_HOST'),
-      port: configService.get<number>('DB_PORT'),
-      username: configService.get('DB_USER'),
-      password: configService.get('DB_PASSWORD'),
-      database: configService.get('DB_NAME'),
+      type: 'mysql',
+      host: process.env.DB_HOST,
+      port: Number(process.env.DB_PORT),
+      username: process.env.DB_USER,
+      password: process.env.DB_PASSWORD,
+      database: process.env.DB_NAME,
     },
-    defaultLanguageCode: configService.get('DEFAULT_LANGUAGE', 'en'),
-    enableCaching: configService.get<boolean>('LOCALIZATION_CACHE', false),
-    cacheTtlSeconds: 300,
-  }),
-  inject: [ConfigService],
-})
+  },
+});
 ```
 
-### Multi-Tenant Setup
+### forRootAsync (factory — recommended)
 
 ```typescript
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { LocalizationModule } from '@flusys/nestjs-localization';
+
 LocalizationModule.forRootAsync({
   global: true,
   bootstrapAppConfig: {
-    databaseMode: 'multi-tenant',
+    databaseMode: 'single',
     enableCompanyFeature: false,
   },
-  useFactory: (): ILocalizationModuleConfig => ({
-    tenantDefaultDatabaseConfig: {
-      type: 'postgres',
-      host: process.env.DB_HOST,
-      port: Number(process.env.DB_PORT),
-      username: process.env.DB_USER,
-      password: process.env.DB_PASSWORD,
+  imports: [ConfigModule],
+  useFactory: (cfg: ConfigService) => ({
+    defaultLanguageCode: cfg.get('DEFAULT_LANGUAGE', 'en'),
+    enableCaching: cfg.get<boolean>('LOCALIZATION_CACHE_ENABLED', false),
+    cacheTtlSeconds: cfg.get<number>('LOCALIZATION_CACHE_TTL', 300),
+    defaultDatabaseConfig: {
+      type: 'mysql',
+      host: cfg.get('DB_HOST'),
+      port: cfg.get<number>('DB_PORT'),
+      username: cfg.get('DB_USER'),
+      password: cfg.get('DB_PASSWORD'),
+      database: cfg.get('DB_NAME'),
     },
-    tenants: [
-      { id: 'tenant1', database: 'tenant1_db' },
-      { id: 'tenant2', database: 'tenant2_db' },
-    ],
-    defaultLanguageCode: 'en',
   }),
-})
-```
-
-**Exported services:**
-- `LocalizationConfigService`
-- `LocalizationDataSourceProvider`
-- `LanguageService`
-- `TranslationKeyService`
-- `TranslationService`
-
----
-
-## Configuration Reference
-
-```typescript
-interface ILocalizationModuleConfig extends IDataSourceServiceOptions {
-  /** Default language code for fallback (default: 'en') */
-  defaultLanguageCode?: string;
-
-  /** Enable translation caching (default: false) */
-  enableCaching?: boolean;
-
-  /** Cache TTL in seconds (default: 300) */
-  cacheTtlSeconds?: number;
-}
-```
-
----
-
-## Feature Toggles
-
-| Feature | Config | Default | Effect |
-|---------|--------|---------|--------|
-| Caching | `enableCaching: true` | `false` | Translations cached in HybridCache with `cacheTtlSeconds` TTL |
-| Multi-tenant | `databaseMode: 'multi-tenant'` | `'single'` | Per-tenant DataSource connections |
-
-> **Note:** Localization entities do **not** have company variants (`enableCompanyFeature` is ignored). All translation data is shared across companies.
-
----
-
-## API Endpoints
-
-All endpoints use **POST**. Authentication is required unless noted.
-
-### Languages — `POST /localization/language/*`
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /localization/language/insert` | `language.create` | Create a language |
-| `POST /localization/language/get-all` | Public | List all active languages |
-| `POST /localization/language/get/:id` | `language.read` | Get language by ID |
-| `POST /localization/language/update` | `language.update` | Update language |
-| `POST /localization/language/delete` | `language.delete` | Delete language |
-| `POST /localization/language/set-default` | `language.update` | Set as default language |
-
-**Create language:**
-
-```json
-POST /localization/language/insert
-{
-  "name": "English",
-  "nativeName": "English",
-  "code": "en",
-  "direction": "ltr",
-  "isActive": true,
-  "isDefault": true
-}
-```
-
-```json
-POST /localization/language/insert
-{
-  "name": "Arabic",
-  "nativeName": "العربية",
-  "code": "ar",
-  "direction": "rtl",
-  "isActive": true
-}
-```
-
-### Translation Keys — `POST /localization/translation-key/*`
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /localization/translation-key/insert` | `translation-key.create` | Register a new translation key |
-| `POST /localization/translation-key/get-all` | `translation-key.read` | List all keys |
-| `POST /localization/translation-key/get/:id` | `translation-key.read` | Get key by ID |
-| `POST /localization/translation-key/get-by-module` | `translation-key.read` | Get all keys for a module |
-| `POST /localization/translation-key/update` | `translation-key.update` | Update key (not readonly keys) |
-| `POST /localization/translation-key/delete` | `translation-key.delete` | Delete key (not readonly) |
-| `POST /localization/translation-key/get-missing` | `translation-key.read` | Get keys with no translation for a language |
-
-**Register a key:**
-
-```json
-POST /localization/translation-key/insert
-{
-  "key": "auth.login_success",
-  "module": "auth",
-  "description": "Shown after successful login",
-  "defaultValue": "Login successful",
-  "variables": [],
-  "isReadonly": true
-}
-```
-
-**Key with variables:**
-
-```json
-{
-  "key": "user.welcome",
-  "module": "auth",
-  "description": "Welcome message with user name",
-  "defaultValue": "Welcome, {{name}}!",
-  "variables": ["name"],
-  "isReadonly": false
-}
-```
-
-### Translations — `POST /localization/translation/*`
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /localization/translation/insert` | `translation.create` | Add a translation value |
-| `POST /localization/translation/get-all` | `translation.read` | List all translations |
-| `POST /localization/translation/get-by-language` | Public | Get all translations for a language |
-| `POST /localization/translation/get-by-language-module` | Public | Get translations for a language + module |
-| `POST /localization/translation/update` | `translation.update` | Update a translation value |
-| `POST /localization/translation/bulk-update` | `translation.update` | Bulk update translations (atomic) |
-| `POST /localization/translation/delete` | `translation.delete` | Delete a translation |
-| `POST /localization/translation/verify` | `translation.update` | Mark a translation as verified |
-| `POST /localization/translation/unverify` | `translation.update` | Mark a translation as unverified |
-
-**Add a translation:**
-
-```json
-POST /localization/translation/insert
-{
-  "keyId": "uuid-of-translation-key",
-  "languageId": "uuid-of-language",
-  "value": "Connexion réussie"
-}
-```
-
-**Bulk update (atomic transaction):**
-
-```json
-POST /localization/translation/bulk-update
-{
-  "languageId": "uuid-of-french",
-  "translations": [
-    { "keyId": "uuid-1", "value": "Connexion réussie" },
-    { "keyId": "uuid-2", "value": "Bienvenue, {{name}}!" },
-    { "keyId": "uuid-3", "value": "Mot de passe incorrect" }
-  ]
-}
+  inject: [ConfigService],
+});
 ```
 
 ---
 
-## Entities
-
-| Entity | Table | Description |
-|--------|-------|-------------|
-| `Language` | `localization_language` | Language with code, direction, default flag |
-| `TranslationKey` | `localization_translation_key` | Key registry with module, variables, readonly flag |
-| `Translation` | `localization_translation` | Per-language translation values with verification status |
-
-> Localization entities have **no company variants**. All translation data is shared globally.
+## 2. Entities
 
 ```typescript
-import { LocalizationModule } from '@flusys/nestjs-localization';
+import { getLocalizationEntities } from '@flusys/nestjs-localization/entities';
 
 TypeOrmModule.forRoot({
-  entities: [
-    ...LocalizationModule.getEntities(),
-    // other entities
-  ],
-})
+  entities: [...getLocalizationEntities()],
+});
 ```
 
 ---
 
-## Translation Workflow
 
-```
-1. Create Language       → POST /localization/language/insert
-2. Register Key          → POST /localization/translation-key/insert
-3. Add Translation       → POST /localization/translation/insert
-4. Verify Translation    → POST /localization/translation/verify
-5. Detect Missing        → POST /localization/translation-key/get-missing
-6. Bulk Update           → POST /localization/translation/bulk-update
-```
-
-Translation statuses:
-- **Unverified** (default) — Draft translation, may not be production-ready
-- **Verified** — Approved by a translator or admin
-
----
-
-## Variable Interpolation
+## 4. How API responses use messageKey
 
-Translation values use `{{variableName}}` syntax. The `messageVariables` field in API responses carries the variable values that should be interpolated by the frontend:
-
-**Server response:**
-
-```json
-{
-  "success": true,
-  "message": "Welcome, John!",
-  "messageKey": "user.welcome",
-  "messageVariables": { "name": "John" }
-}
-```
-
-**Frontend interpolation:**
+Every FLUSYS API response includes a `messageKey` field. The frontend fetches translations once on init, then uses that key to look up the localized message:
 
 ```typescript
-// Fetch translation for 'user.welcome': "Bienvenue, {{name}}!"
-const template = translations['user.welcome'];
-const message = template.replace(/\{\{(\w+)\}\}/g, (_, key) => variables[key] ?? key);
-// Result: "Bienvenue, John!"
-```
+// Backend throws
+throw new NotFoundException({ message: 'Form not found', messageKey: LANGUAGE_MESSAGES.[key]'form.not.found' });
 
----
-
-## Fallback Chain
-
-When a translation is not found for the requested language, the resolution falls back in this order:
-
-```
-Requested language → Default language (e.g., 'en') → key.defaultValue → key itself
-```
-
----
-
-## RTL Support
-
-Each language has a `direction` field: `'ltr'` (left-to-right) or `'rtl'` (right-to-left).
-
-The frontend uses this to switch layout direction:
-
-```typescript
-// Angular
-const lang = await this.http.post('/localization/language/get-all', {}).toPromise();
-const current = lang.data.find(l => l.code === userLanguageCode);
-document.dir = current.direction; // 'ltr' or 'rtl'
-```
-
----
-
-## Caching
-
-When `enableCaching: true`, translation lookups are cached with the key pattern `loc:{languageCode}:{module}`. Cache is invalidated when translations are updated via the bulk-update or individual update endpoints.
-
-```typescript
-config: {
-  enableCaching: true,
-  cacheTtlSeconds: 600, // 10 minutes
-}
-```
-
-Requires `HybridCache` (Redis or in-memory) to be configured via `CacheModule` from `@flusys/nestjs-shared`.
-
----
-
-## Exported Services
-
-| Service | Description |
-|---------|-------------|
-| `LanguageService` | Language CRUD, default language management |
-| `TranslationKeyService` | Key CRUD, missing-key detection, module filtering |
-| `TranslationService` | Translation CRUD, bulk update, verification |
-| `LocalizationConfigService` | Runtime config (default language, caching settings) |
-| `LocalizationDataSourceProvider` | Dynamic DataSource per request |
-
----
-
-## Integration with API Responses
-
-All FLUSYS response DTOs include `messageKey` and optionally `messageVariables`. The frontend uses these to display localized messages:
-
-**Backend (any service):**
-
-```typescript
+// Backend returns:
 return {
-  success: true,
-  message: 'Welcome, John!',
-  messageKey: 'user.welcome',
-  messageVariables: { name: 'John' },
-  data: userDto,
+      success: true,
+      message: 'Active languages retrieved successfully',
+      messageKey: LANGUAGE_MESSAGES.ACTIVE_SUCCESS,
+      data,
+      meta: { total: data.length, page: 0, pageSize: data.length, count: data.length },
 };
 ```
 
-**Frontend flow:**
-
-1. On app init: `GET /localization/translation/get-by-language` for the user's language
-2. Cache translations in a map: `{ 'user.welcome': 'Bienvenue, {{name}}!' }`
-3. On every API response: look up `messageKey`, interpolate `messageVariables`
-4. Display the localized message
-
----
-
-## Troubleshooting
-
-**`Language not found` for a valid code**
-
-Use the language's UUID (`id`), not the ISO code, in most endpoints. Use `get-by-language` with the code only for the public translation endpoints.
-
----
-
-**Translation not returned for a module**
-
-Check the `module` field on the `TranslationKey`. The `get-by-language-module` endpoint filters strictly by module name. Ensure it matches exactly (case-sensitive).
-
----
-
-**Missing keys not detected**
-
-`get-missing` returns keys that have no `Translation` record for the given language. If you created a translation but left `value` empty, it is still counted as "present" (not missing). Delete or update the empty translation to see it in the missing list.
-
----
-
-**Caching returning stale translations**
-
-When `enableCaching: true`, call `POST /localization/translation/bulk-update` (which invalidates the cache) instead of individual updates if you need immediate cache refresh.
-
----
-
-**`No metadata for entity`**
-
-Register entities:
-```typescript
-entities: [...LocalizationModule.getEntities()]
-```
-
----
-
 ## License
 
 MIT © FLUSYS
-
----
-
-> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.

package/cjs/config/localization.constants.js

@@ -2,19 +2,10 @@
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
-function _export(target, all) {
-    for(var name in all)Object.defineProperty(target, name, {
-        enumerable: true,
-        get: Object.getOwnPropertyDescriptor(all, name).get
-    });
-}
-_export(exports, {
-    get DEFAULT_LANGUAGE_CODE () {
-        return DEFAULT_LANGUAGE_CODE;
-    },
-    get LOCALIZATION_MODULE_OPTIONS () {
+Object.defineProperty(exports, "LOCALIZATION_MODULE_OPTIONS", {
+    enumerable: true,
+    get: function() {
         return LOCALIZATION_MODULE_OPTIONS;
     }
 });
 const LOCALIZATION_MODULE_OPTIONS = 'LOCALIZATION_MODULE_OPTIONS';
-const DEFAULT_LANGUAGE_CODE = 'en';

package/cjs/config/message-keys.js

@@ -13,9 +13,6 @@ _export(exports, {
     get LANGUAGE_MESSAGES () {
         return LANGUAGE_MESSAGES;
     },
-    get LOCALIZATION_MODULE_MESSAGES () {
-        return LOCALIZATION_MODULE_MESSAGES;
-    },
     get TRANSLATION_KEY_MESSAGES () {
         return TRANSLATION_KEY_MESSAGES;
     },
@@ -24,54 +21,18 @@ _export(exports, {
     }
 });
 const LANGUAGE_MESSAGES = {
-    CREATE_SUCCESS: 'language.create.success',
-    CREATE_MANY_SUCCESS: 'language.create.many.success',
-    GET_SUCCESS: 'language.get.success',
-    GET_ALL_SUCCESS: 'language.get.all.success',
-    UPDATE_SUCCESS: 'language.update.success',
-    UPDATE_MANY_SUCCESS: 'language.update.many.success',
-    DELETE_SUCCESS: 'language.delete.success',
-    RESTORE_SUCCESS: 'language.restore.success',
-    NOT_FOUND: 'language.not.found',
     ACTIVE_SUCCESS: 'language.active.success',
     SET_DEFAULT_SUCCESS: 'language.set.default.success',
     GET_DEFAULT_SUCCESS: 'language.get.default.success'
 };
 const TRANSLATION_KEY_MESSAGES = {
-    CREATE_SUCCESS: 'translation.key.create.success',
-    CREATE_MANY_SUCCESS: 'translation.key.create.many.success',
-    GET_SUCCESS: 'translation.key.get.success',
-    GET_ALL_SUCCESS: 'translation.key.get.all.success',
-    UPDATE_SUCCESS: 'translation.key.update.success',
-    UPDATE_MANY_SUCCESS: 'translation.key.update.many.success',
-    DELETE_SUCCESS: 'translation.key.delete.success',
-    RESTORE_SUCCESS: 'translation.key.restore.success',
-    NOT_FOUND: 'translation.key.not.found',
-    IMPORT_SUCCESS: 'translation.key.import.success',
-    EXPORT_SUCCESS: 'translation.key.export.success',
     MODULES_SUCCESS: 'translation.key.modules.success',
     READONLY_DELETE_FORBIDDEN: 'translation.key.readonly.delete.forbidden',
     READONLY_UPDATE_FORBIDDEN: 'translation.key.readonly.update.forbidden',
     DUPLICATE_KEY_IN_MODULE: 'translation.key.duplicate.key.in.module'
 };
 const TRANSLATION_MESSAGES = {
-    CREATE_SUCCESS: 'translation.create.success',
-    CREATE_MANY_SUCCESS: 'translation.create.many.success',
-    GET_SUCCESS: 'translation.get.success',
     GET_ALL_SUCCESS: 'translation.get.all.success',
-    UPDATE_SUCCESS: 'translation.update.success',
     UPDATE_MANY_SUCCESS: 'translation.update.many.success',
-    DELETE_SUCCESS: 'translation.delete.success',
-    RESTORE_SUCCESS: 'translation.restore.success',
-    NOT_FOUND: 'translation.not.found',
-    BY_LANGUAGE_SUCCESS: 'translation.by.language.success',
-    BY_MODULE_SUCCESS: 'translation.by.module.success',
-    MISSING_SUCCESS: 'translation.missing.success',
-    SYNC_SUCCESS: 'translation.sync.success',
-    UPDATE_VALUES_SUCCESS: 'translation.update.values.success'
-};
-const LOCALIZATION_MODULE_MESSAGES = {
-    LANGUAGE: LANGUAGE_MESSAGES,
-    TRANSLATION_KEY: TRANSLATION_KEY_MESSAGES,
-    TRANSLATION: TRANSLATION_MESSAGES
+    BY_LANGUAGE_SUCCESS: 'translation.by.language.success'
 };