Merge pull request #256 from SimpleX-T/issue-254

feat(localization): add backend i18n module with translations API and caching

Author: RUKAYAT-CODER

.gitignore

@@ -58,4 +58,7 @@ pids
 report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 
 # Husky internal bootstrap directory (auto-generated, not hand-edited)
-.husky/_/
+.husky/_/
+
+# Local PR / commit message drafts (not tracked)
+pr.md

package-lock.json

@@ -49,6 +49,7 @@ import { TenancyModule } from './tenancy/tenancy.module';
 import { CdnModule } from './cdn/cdn.module';
 import { AuthModule } from './auth/auth.module';
 import { PaymentsModule } from './payments/payments.module';
+import { LocalizationModule } from './localization/localization.module';
 
 @Module({})
 export class AppModule {
@@ -355,6 +356,15 @@ export class AppModule {
       startupLogger.recordModuleSkipped('CDNModule', 'ENABLE_CDN=false');
     }
 
+    // Localization Module
+    if (flags.ENABLE_LOCALIZATION) {
+      const startTime = Date.now();
+      featureModules.push(LocalizationModule);
+      startupLogger.recordModuleLoaded('LocalizationModule', startTime);
+    } else {
+      startupLogger.recordModuleSkipped('LocalizationModule', 'ENABLE_LOCALIZATION=false');
+    }
+
     // Queue Module (always loaded for Bull)
     featureModules.push(QueueModule);
 

src/app.module.ts

@@ -0,0 +1,14 @@
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+import { RequestWithLocale } from '../types/request-with-locale';
+
+/**
+ * Resolved request locale when LanguageMiddleware runs (Accept-Language / ?lang=).
+ * Falls back to I18N_DEFAULT_LOCALE or the decorator argument when unset.
+ */
+export const CurrentLocale = createParamDecorator(
+  (fallbackLocale: string | undefined, ctx: ExecutionContext): string => {
+    const req = ctx.switchToHttp().getRequest<RequestWithLocale>();
+    const envDefault = (process.env.I18N_DEFAULT_LOCALE || 'en').trim().toLowerCase();
+    return req.resolvedLocale ?? fallbackLocale ?? envDefault;
+  },
+);

src/common/decorators/translate.decorator.ts

@@ -0,0 +1,3 @@
+import { Request } from 'express';
+
+export type RequestWithLocale = Request & { resolvedLocale?: string };

src/common/types/request-with-locale.ts

@@ -110,6 +110,12 @@ export const envValidationSchema = Joi.object({
   ENABLE_SECURITY: Joi.boolean().default(true),
   ENABLE_TENANCY: Joi.boolean().default(true),
   ENABLE_CDN: Joi.boolean().default(true),
+  ENABLE_LOCALIZATION: Joi.boolean().default(true),
+
+  // i18n / localization
+  I18N_DEFAULT_LOCALE: Joi.string().default('en'),
+  I18N_SUPPORTED_LOCALES: Joi.string().default('en'),
+  I18N_CACHE_TTL_SECONDS: Joi.number().integer().min(0).default(300),
 
   // Cluster Mode
   CLUSTER_MODE: Joi.boolean().default(false),

src/config/env.validation.ts

@@ -33,6 +33,7 @@ export interface FeatureFlagsConfig {
   ENABLE_SECURITY: boolean;
   ENABLE_TENANCY: boolean;
   ENABLE_CDN: boolean;
+  ENABLE_LOCALIZATION: boolean;
 }
 
 /**
@@ -65,6 +66,7 @@ export const defaultFeatureFlags: FeatureFlagsConfig = {
   ENABLE_SECURITY: true,
   ENABLE_TENANCY: true,
   ENABLE_CDN: true,
+  ENABLE_LOCALIZATION: true,
 };
 
 /**
@@ -134,6 +136,10 @@ export function loadFeatureFlags(): FeatureFlagsConfig {
     ENABLE_SECURITY: getBooleanEnv('ENABLE_SECURITY', defaultFeatureFlags.ENABLE_SECURITY),
     ENABLE_TENANCY: getBooleanEnv('ENABLE_TENANCY', defaultFeatureFlags.ENABLE_TENANCY),
     ENABLE_CDN: getBooleanEnv('ENABLE_CDN', defaultFeatureFlags.ENABLE_CDN),
+    ENABLE_LOCALIZATION: getBooleanEnv(
+      'ENABLE_LOCALIZATION',
+      defaultFeatureFlags.ENABLE_LOCALIZATION,
+    ),
   };
 }
 
@@ -179,6 +185,7 @@ export function getEnabledModules(flags: FeatureFlagsConfig): string[] {
   if (flags.ENABLE_SECURITY) modules.push('SecurityModule');
   if (flags.ENABLE_TENANCY) modules.push('TenancyModule');
   if (flags.ENABLE_CDN) modules.push('CDNModule');
+  if (flags.ENABLE_LOCALIZATION) modules.push('LocalizationModule');
 
   return modules;
 }

src/config/feature-flags.config.ts

@@ -0,0 +1,19 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsNotEmpty, IsOptional, IsString, MaxLength } from 'class-validator';
+
+export class BundleQueryDto {
+  @ApiProperty({ example: 'errors' })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(128)
+  namespace: string;
+
+  @ApiPropertyOptional({
+    example: 'en',
+    description: 'If omitted, uses detected language from middleware / Accept-Language',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(32)
+  locale?: string;
+}

src/localization/dto/bundle-query.dto.ts

@@ -0,0 +1,27 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsNotEmpty, IsString, MaxLength } from 'class-validator';
+
+export class CreateTranslationDto {
+  @ApiProperty({ example: 'errors' })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(128)
+  namespace: string;
+
+  @ApiProperty({ example: 'not_found' })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(512)
+  key: string;
+
+  @ApiProperty({ example: 'en' })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(32)
+  locale: string;
+
+  @ApiProperty({ example: 'Resource was not found.' })
+  @IsString()
+  @IsNotEmpty()
+  value: string;
+}

src/localization/dto/create-translation.dto.ts

@@ -0,0 +1,22 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsIn, IsNotEmpty, IsOptional, IsString, MaxLength } from 'class-validator';
+
+export class ExportQueryDto {
+  @ApiProperty({ example: 'errors' })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(128)
+  namespace: string;
+
+  @ApiPropertyOptional({ example: 'en' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(32)
+  locale?: string;
+
+  @ApiPropertyOptional({ enum: ['json', 'csv'], default: 'json' })
+  @IsOptional()
+  @IsString()
+  @IsIn(['json', 'csv'])
+  format?: 'json' | 'csv' = 'json';
+}