@nlabs/reaktor 0.10.5 → 0.10.7

package/DATABASE_I18N_GUIDE.md

@@ -1,434 +0,0 @@
-# Database-Driven I18N System
-
-This guide explains how to use the new database-driven internationalization (i18n) system for TorchOne API.
-
-## Overview
-
-The database-driven i18n system allows you to:
-- Store translations in the database for dynamic content management
-- Provide fallback content when translations are not found
-- Support interpolation for dynamic values
-- Batch fetch translations for better performance
-- Manage translations through the database without code changes
-
-## Database Schema
-
-### Content Collection
-
-The system uses a `content` collection with the following structure:
-
-```typescript
-interface ContentType {
-  _id?: string;
-  _key?: string;
-  contentId?: string;
-  key: string;           // Translation key (e.g., 'sms.welcome')
-  locale: Locale;        // Language code ('en', 'es', 'fr', 'de', 'pt', 'it')
-  content: string;       // Translated content
-  description?: string;  // Optional description
-  category?: string;     // Optional category for organization
-  isActive?: boolean;    // Whether this translation is active
-  userId?: string;       // User who created the content
-  added?: number;        // Timestamp when created
-  modified?: number;     // Timestamp when last modified
-}
-```
-
-## Locale Support
-
-The system supports both primary languages and regional variants for comprehensive internationalization:
-
-### **Primary Languages**
-- `en` - English
-- `es` - Spanish
-- `fr` - French
-- `de` - German
-- `pt` - Portuguese
-- `it` - Italian
-
-### **Regional Variants**
-- `en-us`, `en-gb`, `en-ca`, `en-au` - English variants
-- `es-mx`, `es-es`, `es-ar` - Spanish variants
-- `fr-fr`, `fr-ca` - French variants
-- `de-de`, `de-at` - German variants
-- `pt-br`, `pt-pt` - Portuguese variants
-- `it-it` - Italian variants
-
-### **Locale Strategy**
-- **Storage**: Full locale with region (e.g., "en-us") for regional formatting
-- **Translation**: Language extraction (e.g., "en-us" → "en") for API calls
-- **Fallback**: Regional → Language → App default hierarchy
-
-### **Locale Utilities**
-
-```typescript
-import {
-  extractLanguage,
-  isRegionalLocale,
-  getFallbackChain,
-  isValidLocale
-} from './src/utils/localeUtils';
-
-// Extract language for translation APIs
-const language = extractLanguage('en-us'); // 'en'
-
-// Check if locale includes region
-const isRegional = isRegionalLocale('es-mx'); // true
-
-// Get fallback chain
-const fallbacks = getFallbackChain('fr-ca'); // ['fr-ca', 'fr']
-
-// Validate locale
-const isValid = isValidLocale('en-us'); // true
-```
-
-## Core Functions
-
-### 1. Basic Translation with Fallback
-
-```typescript
-import { dbI18n } from './src/utils/dbI18n';
-
-const message = await dbI18n(
-  context,
-  'sms.welcome',
-  'Welcome to TorchOne, {{username}}! Thank you for joining our platform.',
-  'en'
-);
-```
-
-**Parameters:**
-- `context`: API context with database connection
-- `key`: Content key to look up in database
-- `fallbackContent`: Content to return if not found in database
-- `locale`: Optional locale (defaults to 'en')
-
-**Returns:** Promise<string> - The translated content or fallback
-
-### 2. Translation with Interpolation
-
-```typescript
-import { dbI18nWithInterpolation } from './src/utils/dbI18n';
-
-const message = await dbI18nWithInterpolation(
-  context,
-  'sms.verificationCode',
-  'Your verification code is: {{code}}',
-  { code: '123456' },
-  'es'
-);
-```
-
-**Parameters:**
-- `context`: API context with database connection
-- `key`: Content key to look up
-- `fallbackContent`: Content to return if not found
-- `interpolation`: Object with values to interpolate
-- `locale`: Optional locale (defaults to 'en')
-
-**Returns:** Promise<string> - The translated content with interpolated values
-
-### 3. Multiple Translations
-
-```typescript
-import { dbI18nMultiple } from './src/utils/dbI18n';
-
-const [welcome, getStarted, signature] = await dbI18nMultiple(context, [
-  {
-    key: 'email.welcome',
-    fallback: 'Welcome to TorchOne!',
-    locale: 'en'
-  },
-  {
-    key: 'email.getStarted',
-    fallback: 'To get started, complete your profile.',
-    locale: 'en'
-  },
-  {
-    key: 'email.teamSignature',
-    fallback: 'The TorchOne Team',
-    locale: 'en'
-  }
-]);
-```
-
-### 4. Batch Translation
-
-```typescript
-import { dbI18nBatch } from './src/utils/dbI18n';
-
-const keys = ['welcome', 'verification', 'passwordReset'];
-const fallbackMap = {
-  'welcome': 'Welcome!',
-  'verification': 'Please verify your account.',
-  'passwordReset': 'Your password has been reset.'
-};
-
-const translations = await dbI18nBatch(context, keys, fallbackMap, 'fr');
-// Returns: { welcome: '...', verification: '...', passwordReset: '...' }
-```
-
-## Database Operations
-
-### Adding Content
-
-```typescript
-import { addContent } from './src/actions/content';
-
-const newContent = await addContent(context, {
-  key: 'sms.welcome',
-  locale: 'es',
-  content: '¡Bienvenido a TorchOne, {{username}}!',
-  description: 'Welcome SMS message in Spanish',
-  category: 'sms',
-  isActive: true
-});
-```
-
-### Updating Content
-
-```typescript
-import { updateContent } from './src/actions/content';
-
-const updatedContent = await updateContent(context, {
-  contentId: 'content-abc123',
-  content: 'Updated welcome message',
-  description: 'Updated description'
-});
-```
-
-### Searching Content
-
-```typescript
-import { searchContent } from './src/actions/content';
-
-// Search by category
-const smsContent = await searchContent(context, { category: 'sms' });
-
-// Search by locale
-const spanishContent = await searchContent(context, { locale: 'es' });
-
-// Search by key
-const welcomeContent = await searchContent(context, { key: 'sms.welcome' });
-```
-
-## Usage Examples
-
-### SMS Notifications
-
-```typescript
-export async function sendWelcomeSMS(context: ApiContext, username: string, phoneNumber: string) {
-  const message = await dbI18nWithInterpolation(
-    context,
-    'sms.welcome',
-    'Welcome to TorchOne, {{username}}! Thank you for joining our platform.',
-    { username },
-    'en'
-  );
-
-  // Send SMS logic here
-  console.log(`Sending SMS to ${phoneNumber}: ${message}`);
-  return message;
-}
-```
-
-### Email Templates
-
-```typescript
-export async function generateWelcomeEmail(context: ApiContext, username: string, locale: Locale = 'en') {
-  const [welcomeMessage, getStartedMessage, teamSignature] = await dbI18nMultiple(context, [
-    {
-      key: 'email.welcome',
-      fallback: 'Welcome to TorchOne, {{username}}!',
-      locale
-    },
-    {
-      key: 'email.getStarted',
-      fallback: 'To get started, please complete your profile and explore our features.',
-      locale
-    },
-    {
-      key: 'email.teamSignature',
-      fallback: 'The TorchOne Team',
-      locale
-    }
-  ]);
-
-  // Apply interpolation
-  const interpolatedWelcome = welcomeMessage.replace(/\{\{username\}\}/g, username);
-
-  return {
-    subject: interpolatedWelcome,
-    body: `${interpolatedWelcome}\n\n${getStartedMessage}\n\n${teamSignature}`
-  };
-}
-```
-
-### Error Messages
-
-```typescript
-export async function getErrorMessage(context: ApiContext, errorCode: string, locale: Locale = 'en') {
-  try {
-    const message = await dbI18n(
-      context,
-      `error.${errorCode}`,
-      `An error occurred: ${errorCode}`,
-      locale
-    );
-    return message;
-  } catch (error) {
-    // If database is unavailable, return fallback
-    console.error('Database error, using fallback:', error);
-    return `An error occurred: ${errorCode}`;
-  }
-}
-```
-
-## Best Practices
-
-### 1. Key Naming Convention
-
-Use hierarchical keys for better organization:
-- `sms.welcome`
-- `email.verification.subject`
-- `error.invalid_email`
-- `notification.profile_updated`
-
-### 2. Fallback Content
-
-Always provide meaningful fallback content:
-```typescript
-// Good
-await dbI18n(context, 'welcome', 'Welcome to our platform!', 'en');
-
-// Bad
-await dbI18n(context, 'welcome', '', 'en');
-```
-
-### 3. Error Handling
-
-Handle database errors gracefully:
-```typescript
-try {
-  const message = await dbI18n(context, key, fallback, locale);
-  return message;
-} catch (error) {
-  console.error('Translation error:', error);
-  return fallback; // Always return fallback on error
-}
-```
-
-### 4. Performance
-
-Use batch operations for multiple translations:
-```typescript
-// Good - Single database query
-const translations = await dbI18nBatch(context, keys, fallbackMap, locale);
-
-// Bad - Multiple database queries
-const translations = await Promise.all(
-  keys.map(key => dbI18n(context, key, fallbackMap[key], locale))
-);
-```
-
-### 5. Caching
-
-Consider implementing caching for frequently accessed translations:
-```typescript
-// Example with simple in-memory cache
-const translationCache = new Map<string, string>();
-
-export async function cachedI18n(context: ApiContext, key: string, fallback: string, locale: Locale = 'en') {
-  const cacheKey = `${key}:${locale}`;
-
-  if (translationCache.has(cacheKey)) {
-    return translationCache.get(cacheKey)!;
-  }
-
-  const content = await dbI18n(context, key, fallback, locale);
-  translationCache.set(cacheKey, content);
-
-  return content;
-}
-```
-
-## Migration from Static Translations
-
-To migrate from the static translation system:
-
-1. **Export existing translations:**
-```typescript
-import { torchoneResources } from './src/translations';
-
-// Convert static translations to database format
-const translations = Object.entries(torchoneResources).flatMap(([locale, data]) =>
-  Object.entries(data.translation).map(([key, content]) => ({
-    key,
-    locale,
-    content: typeof content === 'string' ? content : JSON.stringify(content),
-    category: key.split('.')[0], // Extract category from key
-    isActive: true
-  }))
-);
-```
-
-2. **Bulk insert into database:**
-```typescript
-for (const translation of translations) {
-  await addContent(context, translation);
-}
-```
-
-3. **Update code to use database-driven functions:**
-```typescript
-// Before
-const message = dbI18n('sms.welcome', { username: 'John' });
-
-// After
-const message = await dbI18nWithInterpolation(
-  context,
-  'sms.welcome',
-  'Welcome to TorchOne, {{username}}!',
-  { username: 'John' }
-);
-```
-
-## Benefits
-
-1. **Dynamic Content Management**: Update translations without code changes
-2. **Fallback Support**: Always provide content even if database is unavailable
-3. **Interpolation**: Support for dynamic values in translations
-4. **Performance**: Batch operations for multiple translations
-5. **Organization**: Categorize and manage translations effectively
-6. **Audit Trail**: Track who created/modified translations
-7. **Active/Inactive**: Control which translations are available
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Database Connection Errors**: Always provide fallback content
-2. **Missing Translations**: Check if content exists in database
-3. **Type Errors**: Ensure locale parameter is of type `Locale`
-4. **Performance Issues**: Use batch operations for multiple translations
-
-### Debugging
-
-```typescript
-// Enable debug logging
-const DEBUG_I18N = process.env.DEBUG_I18N === 'true';
-
-export async function debugI18n(context: ApiContext, key: string, fallback: string, locale: Locale = 'en') {
-  if (DEBUG_I18N) {
-    console.log(`[I18N] Looking up key: ${key}, locale: ${locale}`);
-  }
-
-  const content = await dbI18n(context, key, fallback, locale);
-
-  if (DEBUG_I18N) {
-    console.log(`[I18N] Result: ${content}`);
-  }
-
-  return content;
-}
-```