Package Exports

@logistically/i18n
@logistically/i18n/decorators
@logistically/i18n/exceptions
@logistically/i18n/graphql
@logistically/i18n/rtl

Readme

@logistically/i18n

Enterprise-grade internationalization (i18n) library for NestJS microservices with RTL support, tree shaking, and performance optimizations.

🚀 Features

Multi-locale support - Support for unlimited locales
RTL language support - Full support for Arabic, Hebrew, Persian, Urdu, and other RTL languages
Parameter interpolation - Dynamic content in translations
Number formatting - Locale-aware number formatting with proper numeral systems
Date formatting - Comprehensive date formatting with locale-specific numerals and calendars
Currency formatting - Native Intl API integration for currency formatting
Caching with TTL - Performance optimization
Statistics tracking - Monitor translation usage
Fallback strategies - Graceful handling of missing translations
Debug logging - Comprehensive logging for troubleshooting
Type safety - Full TypeScript support
Dependency injection - Seamless NestJS integration
Elegant exception handling - Translated exceptions with clean syntax
Enhanced decorators - Multi-source locale extraction (JWT, cookies, headers, query params)
GraphQL integration - Apollo Server plugin with automatic field translation
Performance testing - Comprehensive performance benchmarks
Integration testing - Real NestJS usage validation

📦 Installation

npm install @logistically/i18n

🎯 Quick Start

1. Setup Module

import { Module } from '@nestjs/common';
import { TranslationModule } from '@logistically/i18n';

@Module({
  imports: [
    TranslationModule.forRoot({
      serviceName: 'profile-service',
      defaultLocale: 'en',
      supportedLocales: ['en', 'fr', 'es', 'de', 'ar', 'he', 'fa', 'ur'],
      translationsPath: 'src/translations',
      debug: false,
      fallbackStrategy: 'default',
      cache: { enabled: true, ttl: 3600 },
      pluralization: { enabled: true },
      rtl: { enabled: true }
    })
  ]
})
export class AppModule {}

2. Create Translation Files

// src/translations/en.json
{
  "PROFILE.NOT_FOUND": "Profile not found: ${profileId}",
  "PROFILE.INVALID_TYPE": "Invalid profile type: ${profileType}",
  "VALIDATION.MAX_FILES": "Cannot upload more than ${maxFiles} files",
  "WELCOME.MESSAGE": "Welcome, ${userName}!",
  "ITEMS.COUNT": {
    "one": "1 item",
    "other": "${count} items"
  }
}

// src/translations/fr.json
{
  "PROFILE.NOT_FOUND": "Profil introuvable: ${profileId}",
  "PROFILE.INVALID_TYPE": "Type de profil invalide: ${profileType}",
  "VALIDATION.MAX_FILES": "Impossible de télécharger plus de ${maxFiles} fichiers",
  "WELCOME.MESSAGE": "Bienvenue, ${userName}!",
  "ITEMS.COUNT": {
    "one": "1 élément",
    "other": "${count} éléments"
  }
}

// src/translations/ar.json
{
  "PROFILE.NOT_FOUND": "الملف الشخصي غير موجود: ${profileId}",
  "PROFILE.INVALID_TYPE": "نوع الملف الشخصي غير صحيح: ${profileType}",
  "VALIDATION.MAX_FILES": "لا يمكن رفع أكثر من ${maxFiles} ملف",
  "WELCOME.MESSAGE": "مرحباً، ${userName}!",
  "ITEMS.COUNT": {
    "one": "عنصر واحد",
    "other": "${count} عناصر"
  }
}

3. Use in Services

import { Injectable } from '@nestjs/common';
import { TranslationService, TranslatedExceptions } from '@logistically/i18n';

@Injectable()
export class ProfileService {
  constructor(private translationService: TranslationService) {}

  async getProfile(profileId: string, locale: string = 'en') {
    const profile = await this.profileRepository.findById(profileId);
    
    if (!profile) {
      // 🎯 Elegant translated exception
      throw TranslatedExceptions.notFound('PROFILE.NOT_FOUND', {
        locale,
        params: { profileId }
      });
    }
    
    return profile;
  }

  // Basic translation
  getWelcomeMessage(locale: string, userName: string) {
    return this.translationService.translate('WELCOME.MESSAGE', locale, {
      userName
    });
  }

  // Pluralization
  getItemCount(locale: string, count: number) {
    return this.translationService.translatePlural('ITEMS.COUNT', count, locale, {
      count
    });
  }

  // Date formatting
  getFormattedDate(locale: string, date: Date) {
    return this.translationService.formatDateForLocale(date, locale, {
      format: 'full'
    });
  }

  // Number formatting
  getFormattedNumber(locale: string, number: number) {
    return this.translationService.formatNumberForLocale(number, locale);
  }

  // RTL text detection
  getTextDirection(text: string) {
    return this.translationService.getTextDirection(text);
  }
}

4. Use Enhanced Decorators

The library provides powerful decorators for extracting locale from multiple sources:

import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { 
  Locale, 
  LocaleFromJWT, 
  LocaleFromCookies, 
  LocaleFromHeaders, 
  LocaleFromQuery,
  TranslationParams 
} from '@logistically/i18n';

@Controller('profiles')
export class ProfileController {
  @Get(':id')
  async getProfile(
    @Param('id') id: string,
    @Locale() locale: string,                    // Multi-source (JWT > Cookies > Headers > Query)
    @LocaleFromJWT() jwtLocale: string | null,  // JWT token only
    @LocaleFromCookies() cookieLocale: string | null,  // Cookies only
    @LocaleFromHeaders() headerLocale: string | null,  // Headers only
    @LocaleFromQuery() queryLocale: string | null,     // Query params only
    @TranslationParams() params: any
  ) {
    return { 
      message: 'Profile loaded', 
      detectedLocale: locale,
      sources: { jwtLocale, cookieLocale, headerLocale, queryLocale },
      params 
    };
  }

  @Post('upload')
  async uploadFiles(
    @Body() body: any,
    @Locale() locale: string,
    @TranslationParams() params: any
  ) {
    const maxFiles = 10;
    if (body.files.length > maxFiles) {
      throw TranslatedExceptions.badRequest('VALIDATION.MAX_FILES', {
        locale,
        params: { maxFiles }
      });
    }
    return { success: true };
  }
}

Locale Sources Priority (for `@Locale()` decorator):

JWT Token - Authorization: Bearer <token> (highest priority)
Cookies - locale, language, lang cookies
Headers - Accept-Language, X-Locale, Accept-Locale
Query Parameters - ?locale=, ?language=, ?lang=
Default - Falls back to configured default locale

5. GraphQL Integration

The library provides seamless GraphQL integration with Apollo Server:

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { ApolloI18nPlugin, i18nSchemaExtensions } from '@logistically/i18n/graphql';
import { TranslationService } from '@logistically/i18n';

// Create translation service
const translationService = new TranslationService({
  serviceName: 'graphql-service',
  defaultLocale: 'en',
  supportedLocales: ['en', 'fr', 'es', 'ar'],
  translationsPath: 'src/translations'
});

// Create Apollo server with i18n plugin
const server = new ApolloServer({
  typeDefs: [yourSchema, i18nSchemaExtensions],
  resolvers: [yourResolvers],
  plugins: [
    new ApolloI18nPlugin({
      translationService,
      defaultLocale: 'en',
      supportedLocales: ['en', 'fr', 'es', 'ar']
    })
  ]
});

Use @i18n Directive

type User {
  id: ID!
  name: String! @i18n(key: "USER.NAME")
  bio: String @i18n(key: "USER.BIO")
  status: String! @i18n(key: "USER.STATUS")
}

type Product {
  id: ID!
  name: String! @i18n(key: "PRODUCT.NAME")
  description: String! @i18n(key: "PRODUCT.DESCRIPTION")
  status: String! @i18n(key: "PRODUCT.STATUS", params: { status: "status" })
}

Query with Automatic Translation

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name  # Automatically translated based on Accept-Language header
    bio   # Automatically translated
    status # Automatically translated
  }
}

For detailed GraphQL integration guide, see GRAPHQL_GUIDE.md.

JWT Token Format:

{
  "sub": "user123",
  "locale": "fr",        // Preferred field name
  "language": "es",      // Alternative field name
  "lang": "de"          // Alternative field name
}

🎨 Advanced Usage

Exception Handling

import { TranslatedExceptions } from '@logistically/i18n';

// Different exception types
throw TranslatedExceptions.notFound('PROFILE.NOT_FOUND', {
  locale: 'fr',
  params: { profileId: '123' }
});

throw TranslatedExceptions.badRequest('VALIDATION.ERROR', {
  locale: 'en',
  params: { field: 'email' }
});

throw TranslatedExceptions.internalServerError('SYSTEM.ERROR', {
  locale: 'en',
  params: { service: 'database' }
});

// Custom HTTP status
throw TranslatedExceptions.http('CUSTOM.ERROR', 422, {
  locale: 'en',
  params: { reason: 'validation_failed' }
});

RTL Language Support

// Check if locale is RTL
const isRTL = translationService.isRTLLocale('ar'); // true
const isRTL = translationService.isRTLLocale('he'); // true
const isRTL = translationService.isRTLLocale('en'); // false

// Get RTL information
const rtlInfo = translationService.getRTLInfo('ar');
// {
//   isRTL: true,
//   direction: "rtl",
//   script: "Arab",
//   name: "Arabic"
// }

// Get text direction for mixed content
const direction = translationService.getTextDirection('Hello مرحبا'); // "auto"
const direction = translationService.getTextDirection('مرحبا'); // "rtl"
const direction = translationService.getTextDirection('Hello'); // "ltr"

// Translation with RTL support
const result = translationService.translateWithRTL('PROFILE.NOT_FOUND', 'ar', { profileId: '123' });
// {
//   text: "الملف الشخصي غير موجود: 123",
//   rtl: { isRTL: true, direction: "rtl" }
// }

Number and Date Formatting

// Number formatting with locale-specific numerals
const formattedNumber = translationService.formatNumberForLocale(1234.56, 'ar');
// Output: "١٬٢٣٤٫٥٦" (Arabic numerals)

const formattedNumber = translationService.formatNumberForLocale(1234.56, 'he');
// Output: "קכד״קנו" (Hebrew numerals)

// Date formatting
const formattedDate = translationService.formatDateForLocale(new Date(), 'ar', {
  format: 'full'
});
// Output: "١٥ يناير ٢٠٢٤" (Arabic numerals)

// Date range formatting
const formattedRange = translationService.formatDateRangeForLocale(
  new Date('2024-01-15'), 
  new Date('2024-01-20'), 
  'he'
);
// Output: "15 ינואר 2024 - 20 ינואר 2024" (Hebrew numerals)

// Relative date formatting
const relativeDate = translationService.formatRelativeDate(new Date(), 'en');
// Output: "today", "yesterday", "in 2 days", etc.

Statistics and Monitoring

// Get translation statistics
const stats = translationService.getStats();
console.log(stats);
// {
//   totalRequests: 1000,
//   successfulTranslations: 950,
//   failedTranslations: 50,
//   cacheHits: 800,
//   cacheMisses: 200,
//   localeUsage: { en: 600, fr: 400 },
//   keyUsage: { 'PROFILE.NOT_FOUND': 100 }
// }

// Clear cache
translationService.clearCache();

// Reload translations
translationService.reloadTranslations();

Custom Configuration

TranslationModule.forRoot({
  serviceName: 'my-service',
  defaultLocale: 'en',
  supportedLocales: ['en', 'fr', 'es', 'ar'],
  translationsPath: 'src/translations',
  
  // Interpolation settings
  interpolation: {
    prefix: '{{',
    suffix: '}}'
  },
  
  // Fallback strategy
  fallbackStrategy: 'key', // 'key' | 'default' | 'throw'
  
  // Caching
  cache: {
    enabled: true,
    ttl: 3600 // 1 hour
  },
  
  // Statistics
  statistics: {
    enabled: true,
    trackKeyUsage: true,
    trackLocaleUsage: true
  },
  
  // RTL support
  rtl: {
    enabled: true,
    autoDetect: true,
    wrapWithMarkers: false,
    includeDirectionalInfo: true
  },
  
  // Pluralization
  pluralization: {
    enabled: true,
    formatNumbers: true,
    useDirectionalMarkers: true,
    validatePluralRules: true,
    trackPluralizationStats: true,
    ordinal: false,
    customRules: {}
  },
  
  // Debug mode
  debug: false
});

🧪 Testing

Unit Testing

import { Test } from '@nestjs/testing';
import { TranslationModule } from '@logistically/i18n';

describe('ProfileService', () => {
  let translationService: TranslationService;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      imports: [
        TranslationModule.forRoot({
          serviceName: 'test-service',
          debug: true
        })
      ]
    }).compile();

    translationService = module.get<TranslationService>(TranslationService);
  });

  it('should translate correctly', () => {
    const result = translationService.translate('TEST.KEY', 'en', { name: 'John' });
    expect(result).toBe('Hello John!');
  });

  it('should handle RTL text', () => {
    const isRTL = translationService.isRTLLocale('ar');
    expect(isRTL).toBe(true);
  });
});

Integration Testing

import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import { TranslationModule } from '@logistically/i18n';
import { TranslationService } from '@logistically/i18n';
import * as request from 'supertest';

describe('Translation Integration Tests', () => {
  let app: INestApplication;
  let translationService: TranslationService;

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [TranslationModule.forRoot({
        serviceName: 'integration-test',
        translationsPath: './test-translations',
        defaultLocale: 'en',
        supportedLocales: ['en', 'fr', 'es'],
        pluralization: { enabled: true },
        rtl: { enabled: true },
        cache: { enabled: true, ttl: 3600 },
        debug: true
      })],
    }).compile();

    app = moduleFixture.createNestApplication();
    translationService = moduleFixture.get<TranslationService>(TranslationService);
    await app.init();
  });

  afterAll(async () => {
    await app.close();
  });

  it('should handle HTTP requests with locale detection', async () => {
    const response = await request(app.getHttpServer())
      .get('/test/translate/test-key')
      .set('accept-language', 'fr')
      .expect(200);

    expect(response.body).toBeDefined();
  });
});

Performance Testing

import { Test, TestingModule } from '@nestjs/testing';
import { TranslationModule } from '@logistically/i18n';

describe('Translation Performance Tests', () => {
  let translationService: TranslationService;

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [TranslationModule.forRoot({
        serviceName: 'performance-test',
        translationsPath: './test-translations',
        defaultLocale: 'en',
        supportedLocales: ['en', 'fr', 'es'],
        pluralization: { enabled: true },
        rtl: { enabled: true },
        cache: { enabled: true, ttl: 3600 },
        debug: false
      })],
    }).compile();

    translationService = moduleFixture.get<TranslationService>(TranslationService);
  });

  it('should handle 1000 translations within 100ms', () => {
    const startTime = performance.now();
    
    for (let i = 0; i < 1000; i++) {
      translationService.translate('welcome', 'en', { name: `User${i}` });
    }
    
    const endTime = performance.now();
    const duration = endTime - startTime;
    
    expect(duration).toBeLessThan(100);
  });
});

📊 Performance

The library has been extensively performance tested and optimized:

Performance Benchmarks

Operation	Volume	Time	Performance
Mixed Text Detection	1,000	0.09ms	12,500,000 ops/sec
Cache Hits	1,000	0.26ms	4,347,826 ops/sec
Basic Translations	10,000	3.50ms	2,857,143 ops/sec
RTL Text Detection	1,000	0.26ms	3,846,154 ops/sec
Concurrent Translations	100	0.14ms	714,286 ops/sec

Production-Ready Features

✅ High load handling - 4,000 operations in 50ms
✅ Sustained performance - Consistent under stress
✅ Memory efficient - 23.5MB for 40k operations
✅ Cache effective - 1MB cache for 1,000 entries
✅ Zero memory leaks - Stable memory usage

🔧 Configuration Options

Option	Type	Default	Description
`serviceName`	`string`	-	Service name for key prefixing
`defaultLocale`	`string`	`'en'`	Default locale
`supportedLocales`	`string[]`	`['en', 'fr', 'es', 'de', 'ar']`	Supported locales
`translationsPath`	`string`	`'src/translations'`	Path to translation files
`debug`	`boolean`	`false`	Enable debug logging
`interpolation.prefix`	`string`	`'${'`	Interpolation prefix
`interpolation.suffix`	`string`	`'}'`	Interpolation suffix
`fallbackStrategy`	`'key' \| 'default' \| 'throw'`	`'default'`	Fallback strategy
`cache.enabled`	`boolean`	`true`	Enable caching
`cache.ttl`	`number`	`3600`	Cache TTL in seconds
`statistics.enabled`	`boolean`	`true`	Enable statistics tracking
`statistics.trackKeyUsage`	`boolean`	`true`	Track key usage statistics
`statistics.trackLocaleUsage`	`boolean`	`true`	Track locale usage statistics
`rtl.enabled`	`boolean`	`true`	Enable RTL language support
`rtl.autoDetect`	`boolean`	`true`	Auto-detect RTL text content
`rtl.wrapWithMarkers`	`boolean`	`false`	Wrap text with directional markers
`rtl.includeDirectionalInfo`	`boolean`	`true`	Include RTL info in metadata
`pluralization.enabled`	`boolean`	`true`	Enable pluralization
`pluralization.formatNumbers`	`boolean`	`true`	Enable number formatting
`pluralization.useDirectionalMarkers`	`boolean`	`true`	Use RTL directional markers
`pluralization.validatePluralRules`	`boolean`	`true`	Validate plural rule structure
`pluralization.trackPluralizationStats`	`boolean`	`true`	Track pluralization statistics
`pluralization.ordinal`	`boolean`	`false`	Enable ordinal pluralization
`pluralization.customRules`	`Record<string, (count: number) => string>`	`{}`	Custom plural rules

📚 Documentation

GitHub Repository: https://github.com/onwello/i18n
NPM Package: @logistically/i18n

📖 Guides

RTL Language Support - Complete guide for Right-to-Left languages
Performance Optimization - Tree shaking, caching, and best practices
Enhanced Decorators - Multi-source locale extraction
Performance Summary - Comprehensive performance benchmarks
Testing Summary - Complete testing coverage

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

@logistically/i18n

Package Exports

Readme

@logistically/i18n

🚀 Features

📦 Installation

🎯 Quick Start

1. Setup Module

2. Create Translation Files

3. Use in Services

4. Use Enhanced Decorators

Locale Sources Priority (for @Locale() decorator):

5. GraphQL Integration

Use @i18n Directive

Query with Automatic Translation

JWT Token Format:

🎨 Advanced Usage

Exception Handling

RTL Language Support

Number and Date Formatting

Statistics and Monitoring

Custom Configuration

🧪 Testing

Unit Testing

Integration Testing

Performance Testing

📊 Performance

Performance Benchmarks

Production-Ready Features

🔧 Configuration Options

📚 Documentation

📖 Guides

🤝 Contributing

📄 License

Locale Sources Priority (for `@Locale()` decorator):