@flusys/nestjs-localization 4.0.0-lts

package/README.md

@@ -0,0 +1,870 @@
+# Localization Package Guide
+
+> **Package:** `@flusys/nestjs-localization`
+> **Version:** 3.0.1
+> **Type:** Multi-language backend support with TypeORM entities, caching, and translation management
+
+---
+
+## Overview
+
+`@flusys/nestjs-localization` provides a complete localization backend system:
+
+- **Language Management** - CRUD operations for languages with RTL support
+- **Translation Keys** - Module-based key organization with variables
+- **Translations** - Per-language translations with verification status
+- **Caching** - Optional hybrid caching for performance
+- **Dynamic DataSource** - Request-scoped repository pattern
+- **Variable Interpolation** - `{{variable}}` syntax support
+- **Bulk Operations** - Batch update translations
+- **Missing Translation Detection** - Find untranslated keys
+
+### Package Hierarchy
+
+```
+@flusys/nestjs-core           <- Foundation (IDataSourceServiceOptions)
+        |
+@flusys/nestjs-shared         <- Base classes (RequestScopedApiService)
+        |
+@flusys/nestjs-localization   <- Localization system (THIS PACKAGE)
+```
+
+---
+
+## Package Architecture
+
+```
+nestjs-localization/
+├── config/
+│   ├── localization.constants.ts      # LOCALIZATION_MODULE_OPTIONS
+│   └── index.ts
+├── interfaces/
+│   ├── language.interface.ts          # ILanguage
+│   ├── translation-key.interface.ts   # ITranslationKey
+│   ├── translation.interface.ts       # ITranslation, ITranslationsMap
+│   ├── localization-module-options.interface.ts # Module config
+│   └── index.ts
+├── entities/
+│   ├── language.entity.ts             # Language entity
+│   ├── translation-key.entity.ts      # TranslationKey entity
+│   ├── translation.entity.ts          # Translation entity
+│   └── index.ts
+├── dtos/
+│   ├── language.dto.ts                # Language DTOs
+│   ├── translation-key.dto.ts         # TranslationKey DTOs
+│   ├── translation.dto.ts             # Translation DTOs
+│   └── index.ts
+├── services/
+│   ├── localization-config.service.ts # Config management
+│   ├── localization-datasource.provider.ts # DataSource provider
+│   ├── localization-helper.service.ts # Interpolation utilities
+│   ├── language.service.ts            # Language CRUD
+│   ├── translation-key.service.ts     # TranslationKey CRUD
+│   ├── translation.service.ts         # Translation CRUD + queries
+│   └── index.ts
+├── controllers/
+│   ├── language.controller.ts         # Language endpoints
+│   ├── translation-key.controller.ts  # TranslationKey endpoints
+│   ├── translation.controller.ts      # Translation endpoints
+│   └── index.ts
+├── modules/
+│   └── localization.module.ts         # Module definition
+└── index.ts
+```
+
+---
+
+## Database Schema
+
+### Language Table
+
+| Column | Type | Nullable | Description |
+|--------|------|----------|-------------|
+| `id` | uuid | No | Primary key |
+| `code` | varchar(10) | No | ISO 639-1 code (e.g., 'en', 'ar') |
+| `name` | varchar(100) | No | English name |
+| `native_name` | varchar(100) | Yes | Native name (e.g., 'العربية') |
+| `direction` | varchar(3) | Yes | 'ltr' or 'rtl' |
+| `is_active` | boolean | No | Active status (default: true) |
+| `is_default` | boolean | No | Default language flag |
+| `serial` | int | Yes | Sort order |
+| `created_at` | timestamp | No | Creation timestamp |
+| `updated_at` | timestamp | No | Update timestamp |
+| `deleted_at` | timestamp | Yes | Soft delete timestamp |
+
+**Indexes:**
+- `UNIQUE (code)`
+- `INDEX (is_active)`
+- `INDEX (is_default)`
+
+### TranslationKey Table
+
+| Column | Type | Nullable | Description |
+|--------|------|----------|-------------|
+| `id` | uuid | No | Primary key |
+| `module` | varchar(100) | No | Module grouping (e.g., 'auth') |
+| `key` | varchar(255) | No | Translation key |
+| `default_message` | varchar(500) | No | Default/fallback message |
+| `description` | text | Yes | Description for translators |
+| `variables` | simple-array | Yes | Required variables |
+| `is_active` | boolean | No | Active status |
+| `serial` | int | Yes | Sort order |
+| `created_at` | timestamp | No | Creation timestamp |
+| `updated_at` | timestamp | No | Update timestamp |
+| `deleted_at` | timestamp | Yes | Soft delete timestamp |
+
+**Indexes:**
+- `UNIQUE (key)`
+- `INDEX (module)`
+- `INDEX (module, key)`
+- `INDEX (is_active)`
+
+### Translation Table
+
+| Column | Type | Nullable | Description |
+|--------|------|----------|-------------|
+| `id` | uuid | No | Primary key |
+| `language_id` | uuid | No | FK to language |
+| `translation_key_id` | uuid | No | FK to translation_key |
+| `value` | text | No | Translated value |
+| `is_verified` | boolean | No | Verified by translator |
+| `is_active` | boolean | No | Active status |
+| `created_at` | timestamp | No | Creation timestamp |
+| `updated_at` | timestamp | No | Update timestamp |
+| `deleted_at` | timestamp | Yes | Soft delete timestamp |
+
+**Indexes:**
+- `UNIQUE (language_id, translation_key_id)`
+- `INDEX (language_id)`
+- `INDEX (translation_key_id)`
+- `INDEX (is_active)`
+
+---
+
+## Module Setup
+
+### Basic Setup
+
+```typescript
+// app.module.ts
+import { LocalizationModule } from '@flusys/nestjs-localization';
+
+@Module({
+  imports: [
+    LocalizationModule.forRoot({
+      global: true,
+      includeController: true,
+      bootstrapAppConfig: {
+        dataSource: AppDataSource,
+      },
+      config: {
+        defaultLanguageCode: 'en',
+        enableCaching: true,
+        cacheTtlSeconds: 300,
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Async Setup
+
+```typescript
+// app.module.ts
+import { LocalizationModule } from '@flusys/nestjs-localization';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+
+@Module({
+  imports: [
+    LocalizationModule.forRootAsync({
+      global: true,
+      includeController: true,
+      imports: [ConfigModule],
+      bootstrapAppConfig: {
+        dataSource: AppDataSource,
+      },
+      useFactory: (configService: ConfigService) => ({
+        defaultLanguageCode: configService.get('DEFAULT_LANGUAGE', 'en'),
+        enableCaching: configService.get('ENABLE_CACHE', true),
+        cacheTtlSeconds: configService.get('CACHE_TTL', 300),
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Module Options
+
+```typescript
+interface ILocalizationModuleConfig {
+  defaultLanguageCode?: string;  // Default: 'en'
+  enableCaching?: boolean;       // Enable hybrid cache
+  cacheTtlSeconds?: number;      // Cache TTL in seconds
+}
+
+interface LocalizationModuleOptions {
+  global?: boolean;              // Register as global module
+  includeController?: boolean;   // Include controllers (default: true)
+  bootstrapAppConfig: IBootstrapAppConfig;
+  config?: ILocalizationModuleConfig;
+}
+```
+
+---
+
+## Entities
+
+### Language Entity
+
+```typescript
+@Entity({ name: 'language' })
+export class Language extends Identity {
+  @Column({ type: 'varchar', length: 10 })
+  code!: string;
+
+  @Column({ type: 'varchar', length: 100 })
+  name!: string;
+
+  @Column({ type: 'varchar', length: 100, nullable: true, name: 'native_name' })
+  nativeName!: string | null;
+
+  @Column({ type: 'varchar', length: 3, nullable: true })
+  direction!: 'ltr' | 'rtl' | null;
+
+  @Column({ type: 'boolean', default: true, name: 'is_active' })
+  isActive!: boolean;
+
+  @Column({ type: 'boolean', default: false, name: 'is_default' })
+  isDefault!: boolean;
+
+  @Column({ type: 'int', nullable: true })
+  serial!: number | null;
+
+  @OneToMany('Translation', 'language')
+  translations?: Translation[];
+}
+```
+
+### TranslationKey Entity
+
+```typescript
+@Entity({ name: 'translation_key' })
+export class TranslationKey extends Identity {
+  @Column({ type: 'varchar', length: 100 })
+  module!: string;
+
+  @Column({ type: 'varchar', length: 255 })
+  key!: string;
+
+  @Column({ type: 'varchar', length: 500, name: 'default_message' })
+  defaultMessage!: string;
+
+  @Column({ type: 'text', nullable: true })
+  description!: string | null;
+
+  @Column({ type: 'simple-array', nullable: true })
+  variables!: string[] | null;
+
+  @Column({ type: 'boolean', default: true, name: 'is_active' })
+  isActive!: boolean;
+
+  @Column({ type: 'int', nullable: true })
+  serial!: number | null;
+
+  @OneToMany('Translation', 'translationKey')
+  translations?: Translation[];
+}
+```
+
+### Translation Entity
+
+```typescript
+@Entity({ name: 'translation' })
+export class Translation extends Identity {
+  @Column({ type: 'uuid', name: 'language_id' })
+  languageId!: string;
+
+  @Column({ type: 'uuid', name: 'translation_key_id' })
+  translationKeyId!: string;
+
+  @Column({ type: 'text' })
+  value!: string;
+
+  @Column({ type: 'boolean', default: false, name: 'is_verified' })
+  isVerified!: boolean;
+
+  @Column({ type: 'boolean', default: true, name: 'is_active' })
+  isActive!: boolean;
+
+  @ManyToOne(() => Language)
+  @JoinColumn({ name: 'language_id' })
+  language?: Language;
+
+  @ManyToOne(() => TranslationKey)
+  @JoinColumn({ name: 'translation_key_id' })
+  translationKey?: TranslationKey;
+}
+```
+
+---
+
+## Services
+
+### LanguageService
+
+CRUD operations for languages:
+
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class LanguageService extends RequestScopedApiService<...> {
+  // Inherited CRUD from RequestScopedApiService
+  // insert(), update(), delete(), findById(), findAll()
+
+  // Get active languages (public, no auth)
+  async getActiveLanguages(): Promise<Language[]>;
+
+  // Get default language
+  async getDefaultLanguage(): Promise<Language | null>;
+
+  // Set default language (unsets previous default)
+  async setDefaultLanguage(id: string): Promise<Language>;
+}
+```
+
+### TranslationKeyService
+
+CRUD operations for translation keys:
+
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class TranslationKeyService extends RequestScopedApiService<...> {
+  // Inherited CRUD from RequestScopedApiService
+
+  // Get keys by module
+  async getByModule(module: string): Promise<TranslationKey[]>;
+
+  // Get all unique modules
+  async getModules(): Promise<string[]>;
+}
+```
+
+### TranslationService
+
+Translation operations with queries:
+
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class TranslationService extends RequestScopedApiService<...> {
+  // Inherited CRUD from RequestScopedApiService
+
+  // Get all translations for a language (public, no auth)
+  async getByLanguageCode(languageCode: string): Promise<ITranslationsMap>;
+
+  // Get translations by module and language (public, no auth)
+  async getByModuleAndLanguage(module: string, languageCode: string): Promise<ITranslationsMap>;
+
+  // Bulk update translation values
+  async bulkUpdate(updates: BulkUpdateTranslationDto[]): Promise<Translation[]>;
+
+  // Get translation keys missing translations for a language
+  async getMissingTranslations(languageCode: string): Promise<TranslationKey[]>;
+}
+```
+
+### LocalizationHelperService
+
+Variable interpolation utilities:
+
+```typescript
+@Injectable()
+export class LocalizationHelperService {
+  // Replace {{variable}} placeholders with values
+  interpolate(template: string, variables?: Record<string, string | number>): string;
+
+  // Extract variable names from template
+  extractVariables(template: string): string[];
+}
+```
+
+**Example:**
+
+```typescript
+const helper = inject(LocalizationHelperService);
+
+const result = helper.interpolate('Hello, {{name}}!', { name: 'John' });
+// Output: "Hello, John!"
+
+const vars = helper.extractVariables('Welcome {{user}}, you have {{count}} items');
+// Output: ['user', 'count']
+```
+
+---
+
+## Controllers
+
+All endpoints follow **POST-only RPC** style (not REST).
+
+### Language Controller
+
+| Endpoint | Auth | Permission | Description |
+|----------|------|------------|-------------|
+| `POST /localization/language/insert` | JWT | `language.create` | Create language |
+| `POST /localization/language/update` | JWT | `language.update` | Update language |
+| `POST /localization/language/delete` | JWT | `language.delete` | Delete language |
+| `POST /localization/language/get-by-id` | JWT | `language.read` | Get by ID |
+| `POST /localization/language/get-all` | JWT | `language.read` | Get all with pagination |
+| `POST /localization/language/get-active` | None | - | Get active languages |
+| `POST /localization/language/get-default` | None | - | Get default language |
+| `POST /localization/language/set-default` | JWT | `language.update` | Set default language |
+
+### TranslationKey Controller
+
+| Endpoint | Auth | Permission | Description |
+|----------|------|------------|-------------|
+| `POST /localization/translation-key/insert` | JWT | `translation-key.create` | Create key |
+| `POST /localization/translation-key/update` | JWT | `translation-key.update` | Update key |
+| `POST /localization/translation-key/delete` | JWT | `translation-key.delete` | Delete key |
+| `POST /localization/translation-key/get-by-id` | JWT | `translation-key.read` | Get by ID |
+| `POST /localization/translation-key/get-all` | JWT | `translation-key.read` | Get all with pagination |
+| `POST /localization/translation-key/get-by-module` | JWT | `translation-key.read` | Get keys by module |
+| `POST /localization/translation-key/get-modules` | JWT | `translation-key.read` | Get all unique module names |
+
+### Translation Controller
+
+| Endpoint | Auth | Permission | Description |
+|----------|------|------------|-------------|
+| `POST /localization/translation/insert` | JWT | `translation.create` | Create translation |
+| `POST /localization/translation/update` | JWT | `translation.update` | Update translation |
+| `POST /localization/translation/delete` | JWT | `translation.delete` | Delete translation |
+| `POST /localization/translation/get-by-id` | JWT | `translation.read` | Get by ID |
+| `POST /localization/translation/get-all` | JWT | `translation.read` | Get all with pagination |
+| `POST /localization/translation/get-by-language` | None | - | Get translations by language code |
+| `POST /localization/translation/get-by-module` | None | - | Get translations by module + language |
+| `POST /localization/translation/update-many-values` | JWT | `translation.update` | Bulk update translations |
+| `POST /localization/translation/get-missing` | JWT | `translation.read` | Get missing translations |
+
+---
+
+## DTOs
+
+### Language DTOs
+
+```typescript
+// Create
+interface CreateLanguageDto {
+  code: string;         // Required, ISO 639-1
+  name: string;         // Required
+  nativeName?: string;
+  direction?: 'ltr' | 'rtl';
+  isActive?: boolean;
+  isDefault?: boolean;
+  serial?: number;
+}
+
+// Update
+interface UpdateLanguageDto extends Partial<CreateLanguageDto> {
+  id: string;  // Required
+}
+
+// Response
+interface LanguageResponseDto {
+  id: string;
+  code: string;
+  name: string;
+  nativeName: string | null;
+  direction: 'ltr' | 'rtl' | null;
+  isActive: boolean;
+  isDefault: boolean;
+  serial: number | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+### TranslationKey DTOs
+
+```typescript
+// Create
+interface CreateTranslationKeyDto {
+  module: string;        // Required
+  key: string;           // Required
+  defaultMessage: string; // Required
+  description?: string;
+  variables?: string[];
+  isActive?: boolean;
+  serial?: number;
+}
+
+// Update
+interface UpdateTranslationKeyDto extends Partial<CreateTranslationKeyDto> {
+  id: string;  // Required
+}
+```
+
+### Translation DTOs
+
+```typescript
+// Create
+interface CreateTranslationDto {
+  languageId: string;      // Required
+  translationKeyId: string; // Required
+  value: string;           // Required
+  isVerified?: boolean;
+  isActive?: boolean;
+}
+
+// Update
+interface UpdateTranslationDto extends Partial<CreateTranslationDto> {
+  id: string;  // Required
+}
+
+// Bulk Update
+interface BulkUpdateTranslationDto {
+  id: string;
+  value: string;
+  isVerified?: boolean;
+}
+
+interface BulkUpdateTranslationsDto {
+  translations: BulkUpdateTranslationDto[];
+}
+
+// Query DTOs
+interface GetTranslationsByLanguageDto {
+  languageCode: string;
+}
+
+interface GetTranslationsByModuleDto {
+  module: string;
+  languageCode: string;
+}
+```
+
+---
+
+## Interfaces
+
+### ILanguage
+
+```typescript
+interface ILanguage {
+  id: string;
+  code: string;
+  name: string;
+  nativeName: string | null;
+  direction: 'ltr' | 'rtl' | null;
+  isActive: boolean;
+  isDefault: boolean;
+  serial: number | null;
+}
+```
+
+### ITranslationKey
+
+```typescript
+interface ITranslationKey {
+  id: string;
+  module: string;
+  key: string;
+  defaultMessage: string;
+  description: string | null;
+  variables: string[] | null;
+  isActive: boolean;
+  serial: number | null;
+}
+```
+
+### ITranslation
+
+```typescript
+interface ITranslation {
+  id: string;
+  languageId: string;
+  translationKeyId: string;
+  value: string;
+  isVerified: boolean;
+  isActive: boolean;
+}
+```
+
+### ITranslationsMap
+
+```typescript
+type ITranslationsMap = Record<string, string>;
+
+// Example
+{
+  'shared.save': 'Save',
+  'shared.cancel': 'Cancel',
+  'auth.login.title': 'Login',
+}
+```
+
+---
+
+## Permissions
+
+| Resource | Permission | Description |
+|----------|------------|-------------|
+| Language | `language.create` | Create languages |
+| Language | `language.read` | Read languages |
+| Language | `language.update` | Update languages |
+| Language | `language.delete` | Delete languages |
+| TranslationKey | `translation-key.create` | Create keys |
+| TranslationKey | `translation-key.read` | Read keys |
+| TranslationKey | `translation-key.update` | Update keys |
+| TranslationKey | `translation-key.delete` | Delete keys |
+| Translation | `translation.create` | Create translations |
+| Translation | `translation.read` | Read translations |
+| Translation | `translation.update` | Update translations |
+| Translation | `translation.delete` | Delete translations |
+
+---
+
+## Data Flow
+
+### Public Translation Request
+
+```
+Frontend requests translations
+        ↓
+POST /localization/translation/get-by-language
+{ languageCode: 'en' }
+        ↓
+TranslationController.getByLanguage()
+        ↓
+TranslationService.getByLanguageCode('en')
+        ↓
+Find language by code (active only)
+        ↓
+Query translations with JOIN on translation_key
+        ↓
+Build ITranslationsMap { key: value }
+        ↓
+Return SingleResponseDto<ITranslationsMap>
+```
+
+### Admin Translation Update
+
+```
+Admin updates translations
+        ↓
+POST /localization/translation/update-many-values
+{ translations: [{ id, value, isVerified }] }
+        ↓
+JWT Auth + permission check (translation.update)
+        ↓
+TranslationController.updateManyValues()
+        ↓
+TranslationService.bulkUpdate(translations)
+        ↓
+Update each translation in database
+        ↓
+Return BulkResponseDto with updated count
+```
+
+---
+
+## Usage Examples
+
+### Inject Services
+
+```typescript
+import { TranslationService, LanguageService } from '@flusys/nestjs-localization';
+
+@Injectable()
+export class MyService {
+  constructor(
+    private readonly translationService: TranslationService,
+    private readonly languageService: LanguageService,
+  ) {}
+
+  async getTranslationsForUser(languageCode: string) {
+    return this.translationService.getByLanguageCode(languageCode);
+  }
+
+  async getActiveLanguages() {
+    return this.languageService.getActiveLanguages();
+  }
+}
+```
+
+### Variable Interpolation
+
+```typescript
+import { LocalizationHelperService } from '@flusys/nestjs-localization';
+
+@Injectable()
+export class NotificationService {
+  constructor(private readonly helper: LocalizationHelperService) {}
+
+  formatMessage(template: string, user: User) {
+    return this.helper.interpolate(template, {
+      name: user.name,
+      count: user.notifications.length,
+    });
+  }
+}
+```
+
+### Seeding Languages
+
+```typescript
+// seed/languages.seed.ts
+const languages = [
+  { code: 'en', name: 'English', nativeName: 'English', direction: 'ltr', isDefault: true, isActive: true },
+  { code: 'ar', name: 'Arabic', nativeName: 'العربية', direction: 'rtl', isActive: true },
+  { code: 'fr', name: 'French', nativeName: 'Français', direction: 'ltr', isActive: true },
+];
+
+// Use LanguageService to seed
+for (const lang of languages) {
+  await languageService.insert(lang);
+}
+```
+
+### Seeding Translation Keys
+
+```typescript
+const keys = [
+  { module: 'shared', key: 'shared.save', defaultMessage: 'Save' },
+  { module: 'shared', key: 'shared.cancel', defaultMessage: 'Cancel' },
+  { module: 'auth', key: 'auth.login.title', defaultMessage: 'Login' },
+  { module: 'auth', key: 'auth.welcome', defaultMessage: 'Welcome, {{name}}!', variables: ['name'] },
+];
+```
+
+---
+
+## Caching
+
+When `enableCaching: true`:
+
+- Translations are cached using HybridCache
+- Cache key format: `localization:translations:{languageCode}`
+- TTL configured via `cacheTtlSeconds`
+- Cache invalidated on translation updates
+
+---
+
+## Frontend Integration
+
+The backend serves translations to the frontend using **module-wise loading**:
+
+### Module-Wise Loading Pattern
+
+Frontend loads translations **per-module** as users navigate, NOT all at once:
+
+```
+App Init
+        ↓
+POST /localization/language/get-active → Load available languages
+        ↓
+User navigates to protected route
+        ↓
+POST /localization/translation/get-by-module
+{ module: 'shared', languageCode: 'en' }
+        ↓
+POST /localization/translation/get-by-module
+{ module: 'layout', languageCode: 'en' }
+        ↓
+User navigates to /storage
+        ↓
+POST /localization/translation/get-by-module
+{ module: 'storage', languageCode: 'en' }
+```
+
+### 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.event.create.success
+> ❌ eventManager.eventCreateSuccess
+> ```
+
+| Module | Keys Prefix | Description |
+|--------|-------------|-------------|
+| `shared` | `shared.*` | Common UI labels, actions, validation messages |
+| `layout` | `layout.*` | Layout, navigation, topbar labels |
+| `auth` | `auth.*` | Login, register, password, user management |
+| `iam` | `iam.*` | Roles, permissions, actions |
+| `storage` | `storage.*` | File upload, folders, storage config |
+| `formBuilder` | `formBuilder.*` | Form builder UI |
+| `email` | `email.*` | Email templates, config |
+| `notification` | `notification.*` | Notifications |
+| `eventManager` | `event.manager.*` | Calendar, events |
+| `localization` | `localization.*` | Language & translation admin UI |
+
+### When Frontend Localization is ENABLED
+
+1. **App Init:** Frontend calls `POST /localization/language/get-active`
+2. **Route Navigation:** Frontend calls `POST /localization/translation/get-by-module` for each feature
+3. **Language Switch:** Frontend reloads translations for already-loaded modules
+
+### When Frontend Localization is DISABLED
+
+1. Frontend skips all API calls to localization endpoints
+2. Frontend uses hardcoded fallback messages only
+3. Backend localization module is not utilized (can still be included for admin use)
+
+### Response Format
+
+All public endpoints return consistent format:
+
+```typescript
+// GET Active Languages
+{
+  success: true,
+  data: [
+    { id: '...', code: 'en', name: 'English', nativeName: 'English', direction: 'ltr', isDefault: true },
+    { id: '...', code: 'ar', name: 'Arabic', nativeName: 'العربية', direction: 'rtl', isDefault: false }
+  ]
+}
+
+// GET Translations by Module
+{
+  success: true,
+  data: {
+    'storage.folders.title': 'Folders',
+    'storage.upload.success': 'File uploaded successfully',
+    'storage.delete.confirm': 'Are you sure you want to delete this file?'
+  }
+}
+```
+
+---
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| **Module Organization** | Group keys by module (auth, shared, storage) |
+| **Key Naming** | Use full dot-case: `module.feature.action` — all lowercase, dots only, no camelCase |
+| **Default Messages** | Always provide meaningful defaults |
+| **Document Variables** | Use `variables` array to document required placeholders |
+| **Description Field** | Add context for translators |
+| **Soft Delete** | Use soft delete for translations (recoverable) |
+| **Bulk Operations** | Use bulk update for efficiency |
+
+---
+
+## Public API Exports
+
+| Category | Exports |
+|----------|---------|
+| **Entities** | `Language`, `TranslationKey`, `Translation` |
+| **Interfaces** | `ILanguage`, `ITranslationKey`, `ITranslation`, `ITranslationsMap`, `ILocalizationModuleConfig`, `LocalizationModuleOptions` |
+| **DTOs** | `CreateLanguageDto`, `UpdateLanguageDto`, `LanguageResponseDto`, `CreateTranslationKeyDto`, `UpdateTranslationKeyDto`, `TranslationKeyResponseDto`, `CreateTranslationDto`, `UpdateTranslationDto`, `TranslationResponseDto`, `BulkUpdateTranslationsDto`, `GetTranslationsByLanguageDto`, `GetTranslationsByModuleDto` |
+| **Services** | `LanguageService`, `TranslationKeyService`, `TranslationService`, `LocalizationHelperService`, `LocalizationConfigService`, `LocalizationDataSourceProvider` |
+| **Controllers** | `LanguageController`, `TranslationKeyController`, `TranslationController` |
+| **Module** | `LocalizationModule` |
+| **Constants** | `LOCALIZATION_MODULE_OPTIONS` |
+
+---
+
+**Last Updated:** 2026-03-01
+**Version:** 3.0.2
+**NestJS Version:** 11