@nlabs/reaktor 0.10.0 → 0.10.2

package/.env

@@ -0,0 +1 @@
+GOOGLE_API_KEY="AIzaSyB5gXFPS7bkEtqr48yS66C79HZUf1g6sEM"

package/.env.example

@@ -0,0 +1 @@
+GOOGLE_API_KEY=""

package/DATABASE_I18N_GUIDE.md

@@ -0,0 +1,434 @@
+# 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;
+}
+```