@flusys/nestjs-localization 4.1.0 → 5.0.0

package/fesm/controllers/translation-key.controller.js

@@ -27,15 +27,15 @@ function _ts_param(paramIndex, decorator) {
 }
 import { createApiController, TRANSLATION_KEY_PERMISSIONS } from '@flusys/nestjs-shared/classes';
 import { CurrentUser, RequirePermission } from '@flusys/nestjs-shared/decorators';
-import { TRANSLATION_KEY_MESSAGES } from '../config';
 import { JwtAuthGuard } from '@flusys/nestjs-shared/guards';
 import { ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
-import { Body, Controller, Inject, Post, UseGuards } from '@nestjs/common';
+import { Controller, Inject, Post, UseGuards } from '@nestjs/common';
 import { ApiBearerAuth, ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
-import { CreateTranslationKeyDto, GetByModuleDto, TranslationKeyResponseDto, UpdateTranslationKeyDto } from '../dtos';
+import { TRANSLATION_KEY_MESSAGES } from '../config';
+import { CreateTranslationKeyDto, TranslationKeyResponseDto, UpdateTranslationKeyDto } from '../dtos';
 import { TranslationKeyService } from '../services';
 export class TranslationKeyController extends createApiController(CreateTranslationKeyDto, UpdateTranslationKeyDto, TranslationKeyResponseDto, {
-    entityName: 'translationKey',
+    entityName: 'translation.key',
     security: {
         insert: {
             level: 'permission',
@@ -90,21 +90,6 @@ export class TranslationKeyController extends createApiController(CreateTranslat
             data
         };
     }
-    async getByModule(body, _user) {
-        const data = await this.service.findByModule(body.module);
-        return {
-            success: true,
-            message: 'Translation keys retrieved successfully',
-            messageKey: TRANSLATION_KEY_MESSAGES.GET_ALL_SUCCESS,
-            data,
-            meta: {
-                total: data.length,
-                page: 0,
-                pageSize: data.length,
-                count: data.length
-            }
-        };
-    }
     constructor(service){
         super(service), _define_property(this, "service", void 0), this.service = service;
     }
@@ -130,29 +115,6 @@ _ts_decorate([
     ]),
     _ts_metadata("design:returntype", Promise)
 ], TranslationKeyController.prototype, "getModules", null);
-_ts_decorate([
-    Post('get-by-module'),
-    UseGuards(JwtAuthGuard),
-    ApiBearerAuth(),
-    RequirePermission(TRANSLATION_KEY_PERMISSIONS.READ),
-    ApiOperation({
-        summary: 'Get translation keys by module'
-    }),
-    ApiResponse({
-        status: 200,
-        type: [
-            TranslationKeyResponseDto
-        ]
-    }),
-    _ts_param(0, Body()),
-    _ts_param(1, CurrentUser()),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        typeof GetByModuleDto === "undefined" ? Object : GetByModuleDto,
-        typeof ILoggedUserInfo === "undefined" ? Object : ILoggedUserInfo
-    ]),
-    _ts_metadata("design:returntype", Promise)
-], TranslationKeyController.prototype, "getByModule", null);
 TranslationKeyController = _ts_decorate([
     ApiTags('Localization - Translation Key'),
     Controller('localization/translation-key'),

package/fesm/controllers/translation.controller.js

@@ -32,7 +32,7 @@ import { JwtAuthGuard } from '@flusys/nestjs-shared/guards';
 import { ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
 import { Body, Controller, Inject, Post, UseGuards } from '@nestjs/common';
 import { ApiBearerAuth, ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
-import { BulkUpdateTranslationsDto, CreateTranslationDto, GetTranslationsByLanguageDto, GetTranslationsByModuleDto, TranslationResponseDto, UpdateTranslationDto } from '../dtos';
+import { BulkUpdateTranslationsDto, CreateTranslationDto, GetTranslationsByLanguageDto, TranslationResponseDto, UpdateTranslationDto } from '../dtos';
 import { TranslationService } from '../services';
 export class TranslationController extends createApiController(CreateTranslationDto, UpdateTranslationDto, TranslationResponseDto, {
     entityName: 'translation',
@@ -90,15 +90,6 @@ export class TranslationController extends createApiController(CreateTranslation
             data
         };
     }
-    async getByModule(body) {
-        const data = await this.service.getByModuleAndLanguage(body.module, body.languageCode);
-        return {
-            success: true,
-            message: 'Translations by module retrieved successfully',
-            messageKey: TRANSLATION_MESSAGES.BY_MODULE_SUCCESS,
-            data
-        };
-    }
     async updateManyValues(body, _user) {
         const data = await this.service.bulkUpdate(body.translations);
         return {
@@ -114,21 +105,6 @@ export class TranslationController extends createApiController(CreateTranslation
             }
         };
     }
-    async getMissing(body, _user) {
-        const data = await this.service.getMissingTranslations(body.languageCode);
-        return {
-            success: true,
-            message: 'Missing translations retrieved successfully',
-            messageKey: TRANSLATION_MESSAGES.MISSING_SUCCESS,
-            data,
-            meta: {
-                total: data.length,
-                page: 0,
-                pageSize: data.length,
-                count: data.length
-            }
-        };
-    }
     async getCounts(_user) {
         const data = await this.service.getTranslationCounts();
         return {
@@ -157,21 +133,6 @@ _ts_decorate([
     ]),
     _ts_metadata("design:returntype", Promise)
 ], TranslationController.prototype, "getByLanguage", null);
-_ts_decorate([
-    Post('get-by-module'),
-    ApiOperation({
-        summary: 'Get translations by module and language'
-    }),
-    ApiResponse({
-        status: 200
-    }),
-    _ts_param(0, Body()),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        typeof GetTranslationsByModuleDto === "undefined" ? Object : GetTranslationsByModuleDto
-    ]),
-    _ts_metadata("design:returntype", Promise)
-], TranslationController.prototype, "getByModule", null);
 _ts_decorate([
     Post('update-many-values'),
     UseGuards(JwtAuthGuard),
@@ -195,26 +156,6 @@ _ts_decorate([
     ]),
     _ts_metadata("design:returntype", Promise)
 ], TranslationController.prototype, "updateManyValues", null);
-_ts_decorate([
-    Post('get-missing'),
-    UseGuards(JwtAuthGuard),
-    ApiBearerAuth(),
-    RequirePermission(TRANSLATION_PERMISSIONS.READ),
-    ApiOperation({
-        summary: 'Get translation keys missing translations for a language'
-    }),
-    ApiResponse({
-        status: 200
-    }),
-    _ts_param(0, Body()),
-    _ts_param(1, CurrentUser()),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        typeof GetTranslationsByLanguageDto === "undefined" ? Object : GetTranslationsByLanguageDto,
-        typeof ILoggedUserInfo === "undefined" ? Object : ILoggedUserInfo
-    ]),
-    _ts_metadata("design:returntype", Promise)
-], TranslationController.prototype, "getMissing", null);
 _ts_decorate([
     Post('get-counts'),
     UseGuards(JwtAuthGuard),

package/fesm/docs/index.js

@@ -0,0 +1 @@
+export { localizationSwaggerConfig } from './localization-swagger.config';

package/fesm/docs/localization-swagger.config.js

@@ -0,0 +1,101 @@
+export function localizationSwaggerConfig(bootstrapConfig) {
+    const isMultiTenant = bootstrapConfig?.databaseMode === 'multi-tenant';
+    const multiTenantNote = isMultiTenant ? `\n> **Multi-Tenant Mode**: Include \`x-tenant-id\` header to target a specific tenant database.\n` : '';
+    return {
+        title: 'Localization API',
+        description: `
+## Localization API
+${multiTenantNote}
+
+Database-driven internationalization system. Manage languages, translation keys, and translations — all stored in the database and served via API.
+
+## Features
+
+### 🌐 Language Management
+- Create and manage languages with LTR/RTL direction support
+- Set a default language
+- Mark languages as readonly to protect seeded entries
+
+### 🔑 Translation Keys
+- Organize keys by module for lazy loading (e.g. \`auth\`, \`iam\`, \`common\`)
+- Dot-case naming convention: \`auth.login.title\`, \`common.button.save\`
+- Support for interpolation variables: \`['count', 'name']\`
+- Readonly protection — system keys cannot be deleted or have their key/module changed
+
+### 📝 Translations
+- Store translated values per language per key
+- Mark translations as verified
+- Bulk upsert in a single transaction — create or update in one call
+- Detect missing translations for a given language
+- Track translation counts per key
+
+### 🚀 Angular Lazy Loading
+- Public endpoints return flat key-value maps: \`{ "auth.login.title": "Sign In" }\`
+- Filter by one or multiple modules to load only what is needed
+- No authentication required for translation retrieval endpoints
+
+## Key Naming Convention
+
+Translation keys use dot-case and must be unique per module:
+
+\`\`\`
+auth.login.title
+auth.login.submit
+auth.register.email.placeholder
+common.button.save
+common.button.cancel
+iam.role.create.success
+\`\`\`
+
+## Module-Based Lazy Loading
+
+Keys are grouped by \`module\` so the frontend loads translations on demand:
+
+| Module | Purpose |
+|--------|---------|
+| auth | Login, register, profile pages |
+| iam | Roles, permissions management |
+| storage | Files and folders |
+| event-manager | Calendar events |
+| form-builder | Dynamic form fields |
+| notification | Notification titles and messages |
+| email | Email template content |
+| common | Shared labels used across modules |
+
+## Public vs Authenticated Endpoints
+
+**Public** (no auth required — used by Angular to load translations):
+- POST /localization/language/get-active
+- POST /localization/language/get-default
+- POST /localization/translation/get-by-language
+- POST /localization/translation/get-by-module
+
+**Authenticated** (require JWT + permission):
+- All create, update, delete operations
+- get-missing, get-counts, update-many-values
+
+## Bulk Update
+
+POST /localization/translation/update-many-values accepts an array of translation objects. Each item is either an upsert (provide **id** to update, omit to create). The entire batch runs in a single database transaction.
+
+## Readonly Protection
+
+Languages and translation keys with \`isReadonly: true\` are protected at the service layer:
+- Cannot be deleted
+- Key and module fields cannot be modified
+
+Use \`isReadonly\` to protect entries that are seeded at startup and should not be changed by users.
+
+## Getting Started
+
+1. **Authenticate**: Obtain JWT token from POST /auth/login
+2. **Create languages**: Add languages via POST /localization/language/insert
+3. **Seed translation keys**: Bulk insert keys via POST /localization/translation-key/insert-many
+4. **Add translations**: Use POST /localization/translation/update-many-values for bulk upsert
+5. **Load in Angular**: Call POST /localization/translation/get-by-language with { languageCode: "en", modules: ["auth"] }
+    `,
+        version: '1.0',
+        path: 'api/docs/localization',
+        bearerAuth: true
+    };
+}

package/fesm/dtos/translation-key.dto.js

@@ -192,18 +192,3 @@ _ts_decorate([
 TranslationKeyResponseDto = _ts_decorate([
     Exclude()
 ], TranslationKeyResponseDto);
-export class GetByModuleDto {
-    constructor(){
-        _define_property(this, "module", void 0);
-    }
-}
-_ts_decorate([
-    IsString(),
-    MaxLength(100),
-    Transform(({ value })=>value?.trim()?.toLowerCase()),
-    ApiProperty({
-        example: 'auth',
-        description: 'Module name'
-    }),
-    _ts_metadata("design:type", String)
-], GetByModuleDto.prototype, "module", void 0);

package/fesm/dtos/translation.dto.js

@@ -237,29 +237,3 @@ _ts_decorate([
     }),
     _ts_metadata("design:type", Array)
 ], GetTranslationsByLanguageDto.prototype, "modules", void 0);
-export class GetTranslationsByModuleDto {
-    constructor(){
-        _define_property(this, "module", void 0);
-        _define_property(this, "languageCode", void 0);
-    }
-}
-_ts_decorate([
-    IsString(),
-    MaxLength(100),
-    Transform(({ value })=>value?.trim()?.toLowerCase()),
-    ApiProperty({
-        example: 'auth',
-        description: 'Module name'
-    }),
-    _ts_metadata("design:type", String)
-], GetTranslationsByModuleDto.prototype, "module", void 0);
-_ts_decorate([
-    IsString(),
-    MaxLength(10),
-    Transform(({ value })=>value?.trim()?.toLowerCase()),
-    ApiProperty({
-        example: 'en',
-        description: 'Language code'
-    }),
-    _ts_metadata("design:type", String)
-], GetTranslationsByModuleDto.prototype, "languageCode", void 0);

package/fesm/entities/translation-key.entity.js

@@ -61,7 +61,7 @@ _ts_decorate([
 ], TranslationKey.prototype, "description", void 0);
 _ts_decorate([
     Column({
-        type: 'simple-array',
+        type: 'json',
         nullable: true
     }),
     _ts_metadata("design:type", Object)

package/fesm/services/translation-key.service.js

@@ -67,7 +67,7 @@ export class TranslationKeyService extends RequestScopedApiService {
                 throw new ForbiddenException({
                     message: `Cannot modify key or module of readonly translation key "${existing.key}"`,
                     messageKey: TRANSLATION_KEY_MESSAGES.READONLY_UPDATE_FORBIDDEN,
-                    messageParams: {
+                    messageVariables: {
                         key: existing.key
                     }
                 });
@@ -103,7 +103,7 @@ export class TranslationKeyService extends RequestScopedApiService {
             throw new ForbiddenException({
                 message: `Cannot delete readonly translation keys: ${keys}`,
                 messageKey: TRANSLATION_KEY_MESSAGES.READONLY_DELETE_FORBIDDEN,
-                messageParams: {
+                messageVariables: {
                     keys
                 }
             });
@@ -146,7 +146,7 @@ export class TranslationKeyService extends RequestScopedApiService {
                 throw new BadRequestException({
                     message: `Translation key "${key}" already exists in module "${module}"`,
                     messageKey: TRANSLATION_KEY_MESSAGES.DUPLICATE_KEY_IN_MODULE,
-                    messageParams: {
+                    messageVariables: {
                         key,
                         module
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/nestjs-localization",
-  "version": "4.1.0",
+  "version": "5.0.0",
   "description": "Localization module for multi-language support",
   "main": "cjs/index.js",
   "module": "fesm/index.js",
@@ -31,6 +31,11 @@
       "import": "./fesm/controllers/index.js",
       "require": "./cjs/controllers/index.js"
     },
+    "./docs": {
+      "types": "./docs/index.d.ts",
+      "import": "./fesm/docs/index.js",
+      "require": "./cjs/docs/index.js"
+    },
     "./dtos": {
       "types": "./dtos/index.d.ts",
       "import": "./fesm/dtos/index.js",
@@ -75,7 +80,7 @@
     "express": "^4.18.0"
   },
   "dependencies": {
-    "@flusys/nestjs-core": "4.1.0",
-    "@flusys/nestjs-shared": "4.1.0"
+    "@flusys/nestjs-core": "5.0.0",
+    "@flusys/nestjs-shared": "5.0.0"
   }
 }