@umituz/react-native-localization 1.0.0 → 1.1.0

package/README.md

@@ -7,6 +7,7 @@ Universal localization system for React Native apps with i18n support. Built wit
 - **29+ Language Support**: Pre-configured support for 29 languages including RTL languages (Arabic)
 - **Automatic Device Locale Detection**: Automatically detects and applies device language on first launch
 - **Persistent Language Preferences**: Saves user's language choice using AsyncStorage
+- **Translation Management Scripts**: Built-in scripts for setup, translation, and validation
 - **Type-Safe**: Full TypeScript support with type definitions
 - **Zero Configuration**: Works out of the box with sensible defaults
 - **Production Ready**: Battle-tested in production apps
@@ -231,26 +232,65 @@ function MyComponent() {
 }
 ```
 
-### Custom Translations
+### Project-Specific Translations
+
+The package includes common translations. For project-specific translations:
+
+1. **Create your translation files** in your project:
+   ```
+   src/domains/localization/infrastructure/locales/
+     en-US/
+       myFeature.json
+       auth.json
+     tr-TR/
+       myFeature.json
+       auth.json
+   ```
+
+2. **Load project translations** in your app initialization:
+   ```tsx
+   import { i18n } from '@umituz/react-native-localization';
+   import myFeatureEnUS from './locales/en-US/myFeature.json';
+   import myFeatureTrTR from './locales/tr-TR/myFeature.json';
+   
+   // Add project translations
+   i18n.addResources('en-US', 'translation', myFeatureEnUS);
+   i18n.addResources('tr-TR', 'translation', myFeatureTrTR);
+   ```
+
+3. **Use in components**:
+   ```tsx
+   const { t } = useLocalization();
+   console.log(t('myFeature.title')); // 'My Feature'
+   ```
+
+### Translation Management Scripts
+
+The package includes scripts for managing translations:
 
-You can extend the translations by adding your own:
+```bash
+# Setup language directories (creates all language folders from en-US)
+npm run i18n:setup
 
-```tsx
-import { i18n } from '@umituz/react-native-localization';
-
-// Add custom translations
-i18n.addResources('en-US', 'translation', {
-  myFeature: {
-    title: 'My Feature',
-    description: 'Feature description'
-  }
-});
-
-// Use in components
-const { t } = useLocalization();
-console.log(t('myFeature.title')); // 'My Feature'
+# Translate missing keys using Google Translate
+npm run i18n:translate
+
+# Check translation completeness
+npm run i18n:check <language-code>
+npm run i18n:check all  # Check all languages
+
+# Remove unused translation keys
+npm run i18n:remove-unused <language-code>
+npm run i18n:remove-unused --all  # Remove from all languages
 ```
 
+**Workflow:**
+1. Add new keys to `en-US/*.json` files
+2. Run `npm run i18n:setup` to create language directories
+3. Run `npm run i18n:translate` to auto-translate missing keys
+4. Run `npm run i18n:check all` to verify completeness
+5. Review and refine translations manually if needed
+
 ## TypeScript Support
 
 The package is written in TypeScript and includes full type definitions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-localization",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Universal localization system for React Native apps with i18n support",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,7 +13,11 @@
     "prepublishOnly": "npm run build",
     "version:patch": "npm version patch -m 'chore: release v%s'",
     "version:minor": "npm version minor -m 'chore: release v%s'",
-    "version:major": "npm version major -m 'chore: release v%s'"
+    "version:major": "npm version major -m 'chore: release v%s'",
+    "i18n:setup": "node scripts/setup-languages.js",
+    "i18n:translate": "node scripts/translate-missing.js",
+    "i18n:check": "node scripts/check-translations.js",
+    "i18n:remove-unused": "node scripts/remove-unused-keys.js"
   },
   "keywords": [
     "react-native",
@@ -58,6 +62,7 @@
   "files": [
     "lib",
     "src",
+    "scripts",
     "README.md",
     "LICENSE"
   ]

package/scripts/check-translations.js

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const fs = require('fs');
+const path = require('path');
+const { getLocalesDir } = require('./utils/findLocalesDir');
+
+// Function to get all keys from an object recursively
+function getAllKeys(obj, prefix = '') {
+  let keys = [];
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+      if (
+        typeof obj[key] === 'object' &&
+        obj[key] !== null &&
+        !Array.isArray(obj[key])
+      ) {
+        keys = keys.concat(getAllKeys(obj[key], fullKey));
+      } else {
+        keys.push(fullKey);
+      }
+    }
+  }
+  return keys;
+}
+
+// Function to get value by key path
+function getValueByPath(obj, path) {
+  return path.split('.').reduce((current, key) => current && current[key], obj);
+}
+
+// Function to compare two translation objects
+function compareTranslations(enUS, targetLang, filePath, langCode) {
+  const enKeys = getAllKeys(enUS);
+  const targetKeys = getAllKeys(targetLang);
+
+  const missingInTarget = enKeys.filter(key => !targetKeys.includes(key));
+  const extraInTarget = targetKeys.filter(key => !enKeys.includes(key));
+
+  const issues = [];
+
+  // Check for missing keys in target language
+  if (missingInTarget.length > 0) {
+    issues.push({
+      type: 'missing',
+      message: `Missing keys in ${langCode}: ${missingInTarget.join(', ')}`,
+      keys: missingInTarget,
+    });
+  }
+
+  // Check for extra keys in target language
+  if (extraInTarget.length > 0) {
+    issues.push({
+      type: 'extra',
+      message: `Extra keys in ${langCode}: ${extraInTarget.join(', ')}`,
+      keys: extraInTarget,
+    });
+  }
+
+  // Check for empty or placeholder values in target language
+  enKeys.forEach(key => {
+    if (targetKeys.includes(key)) {
+      const enValue = getValueByPath(enUS, key);
+      const targetValue = getValueByPath(targetLang, key);
+
+      // Skip checking if the value is the same and it's a common English word that doesn't need translation
+      const commonEnglishWords = [
+        'Premium',
+        'EULA',
+        'Plan',
+        'OK',
+        'API',
+        'URL',
+        'iOS',
+        'Android',
+        'minute',
+        'min',
+        'Sessions',
+        'Points',
+        'Nature',
+        'Instrumental',
+        'Piano',
+        'Silence',
+        'Pause',
+        'Gratitude',
+        'Notes',
+        '5 min',
+        '10 min',
+        '15 min',
+        '20 min',
+        '30 min',
+        '{{count}} min',
+        '{{duration}} min',
+        '{{duration}} • {{cycles}} cycles',
+        'No',
+        'Error',
+        'Try Again',
+        'Back',
+        'Oops! Something went wrong',
+        "We encountered an unexpected error. Don't worry, your meditation data is safe.",
+        "This screen doesn't exist.",
+        'Go to home screen!',
+        'No meditation cards available',
+        "Thank you for reporting this bug! We'll investigate and fix it as soon as possible.",
+        "Thank you for your feature request! We'll consider it for future updates.",
+        'Thank you for your suggestion! We appreciate your input and will review it carefully.',
+        'Your feedback has been submitted successfully. We appreciate your input!',
+        'Continue',
+        'Go Home',
+        'Start Meditating',
+        'Begin Your Journey',
+        'Detailed statistics',
+        'Achievement badges',
+        'Weekly/monthly reports',
+        'Sign Up',
+        'Sign In',
+        'Breathe In',
+        'Hold',
+        'Breathe Out',
+        'Rest',
+        'Find a comfortable seated position',
+        'Focus on slow, controlled movements',
+        "Don't force the breath, let it flow naturally",
+        'Cycle {{current}} of {{total}}',
+        '{{inhale}}s in • {{hold}}s hold • {{exhale}}s out',
+        'Total elapsed: {{time}}',
+        'Cancel',
+        'End Session',
+        'Reset',
+        "Today's Progress",
+        'See All',
+        'Total Time',
+        'Streak',
+        'Last Session',
+        'minutes completed',
+        'Find a quiet, comfortable space',
+        'Focus on your breath naturally',
+        'Let thoughts come and go without judgment',
+        'Start with shorter sessions and build up',
+        'Legal',
+        'Loading sounds...',
+      ];
+      const shouldSkip =
+        commonEnglishWords.includes(enValue) && targetValue === enValue;
+
+      // Check if value needs translation
+      // Skip if already translated (different from English) - protects manual translations
+      const isAlreadyTranslated = targetValue !== enValue;
+      
+      if (
+        !shouldSkip &&
+        !isAlreadyTranslated &&
+        (!targetValue ||
+          (typeof targetValue === 'string' && targetValue.trim() === '') ||
+          targetValue === enValue ||
+          targetValue.includes('[NEEDS TRANSLATION]') ||
+          targetValue.includes('[MISSING:') ||
+          targetValue.includes('[ÇEVİRİ GEREKLİ:') ||
+          targetValue.includes('[TRANSLATE:'))
+      ) {
+        issues.push({
+          type: 'translation',
+          message: `Key "${key}" has empty, missing, or untranslated value`,
+          key: key,
+          enValue: enValue,
+          targetValue: targetValue,
+        });
+      }
+    }
+  });
+
+  return {
+    file: filePath,
+    issues: issues,
+    totalEnKeys: enKeys.length,
+    totalTargetKeys: targetKeys.length,
+    missingCount: missingInTarget.length,
+    extraCount: extraInTarget.length,
+  };
+}
+
+// Main function
+function main() {
+  const args = process.argv.slice(2);
+  const targetLanguage = args.find(arg => !arg.startsWith('--'));
+
+  if (!targetLanguage) {
+    console.log('Kullanım: npm run i18n:check <dil-kodu>');
+    console.log('Örnek: npm run i18n:check de-DE');
+    console.log('Örnek: npm run i18n:check fr-FR');
+    console.log('Örnek: npm run i18n:check tr-TR');
+    console.log(
+      'Örnek: npm run i18n:check spanish (tüm İspanyolca varyantları)'
+    );
+    console.log(
+      '\nTüm dilleri kontrol etmek için: npm run i18n:check all'
+    );
+    process.exit(1);
+  }
+
+  // Find project's locales directory
+  const localesDir = getLocalesDir();
+  const enUSDir = path.join(localesDir, 'en-US');
+
+  // 🔥 CRITICAL FIX: Auto-discover all JSON files (NO HARDCODED LIST!)
+  // This ensures check-translations works with ANY en-US file structure
+  const files = fs
+    .readdirSync(enUSDir)
+    .filter(file => file.endsWith('.json'))
+    .sort();
+
+  if (files.length === 0) {
+    console.error('❌ No JSON files found in en-US directory!');
+    process.exit(1);
+  }
+
+  console.log(`🔍 Discovered ${files.length} translation files in en-US:\n   ${files.join(', ')}\n`);
+
+  // Get all language directories
+  const allLanguageDirs = fs
+    .readdirSync(localesDir)
+    .filter(dir => {
+      const fullPath = path.join(localesDir, dir);
+      return fs.statSync(fullPath).isDirectory() && dir !== 'en-US';
+    })
+    .sort();
+
+  // Determine which languages to process
+  let languageDirs = allLanguageDirs;
+  if (targetLanguage !== 'all') {
+    if (targetLanguage === 'spanish' || targetLanguage === 'es') {
+      // Check all Spanish variants
+      languageDirs = allLanguageDirs.filter(dir => dir.startsWith('es-'));
+      if (languageDirs.length === 0) {
+        console.log('❌ No Spanish variants found.');
+        process.exit(1);
+      }
+    } else if (allLanguageDirs.includes(targetLanguage)) {
+      languageDirs = [targetLanguage];
+    } else {
+      console.log(
+        `❌ Language ${targetLanguage} not found. Available languages: ${allLanguageDirs.join(', ')}`
+      );
+      process.exit(1);
+    }
+  }
+
+  let totalIssues = 0;
+  let totalMissing = 0;
+  let totalExtra = 0;
+  let totalTranslationIssues = 0;
+  let languagesWithIssues = 0;
+
+  console.log(
+    `🔍 Checking ${languageDirs.length} language(s) against English (en-US)...\n`
+  );
+
+  // Check each language
+  languageDirs.forEach(langCode => {
+    const langDir = path.join(localesDir, langCode);
+    let langIssues = 0;
+    let langMissing = 0;
+    let langExtra = 0;
+    let langTranslationIssues = 0;
+
+    console.log(`\n🌍 Checking ${langCode}...`);
+
+    files.forEach(file => {
+      const enUSPath = path.join(enUSDir, file);
+      const langPath = path.join(langDir, file);
+
+      if (!fs.existsSync(enUSPath)) {
+        console.log(`   ❌ English file not found: ${file}`);
+        return;
+      }
+
+      if (!fs.existsSync(langPath)) {
+        console.log(`   ❌ ${langCode} file not found: ${file}`);
+        return;
+      }
+
+      try {
+        const enUS = JSON.parse(fs.readFileSync(enUSPath, 'utf8'));
+        const langData = JSON.parse(fs.readFileSync(langPath, 'utf8'));
+
+        const comparison = compareTranslations(enUS, langData, file, langCode);
+
+        if (comparison.issues.length === 0) {
+          console.log(`   ✅ ${file}: Complete`);
+        } else {
+          console.log(
+            `   📄 ${file}: ${comparison.missingCount} missing, ${comparison.extraCount} extra, ${comparison.issues.filter(i => i.type === 'translation').length} untranslated`
+          );
+
+          // Show detailed issues for debugging
+          comparison.issues.forEach(issue => {
+            if (issue.type === 'translation') {
+              console.log(
+                `     🔍 ${issue.key}: "${issue.enValue}" → "${issue.targetValue || '[EMPTY]'}"`
+              );
+            } else if (issue.type === 'extra') {
+              console.log(`     ➕ Extra keys: ${issue.keys.join(', ')}`);
+            } else if (issue.type === 'missing') {
+              console.log(`     ➖ Missing keys: ${issue.keys.join(', ')}`);
+            }
+            langIssues++;
+            totalIssues++;
+            if (issue.type === 'missing') {
+              langMissing += issue.keys.length;
+              totalMissing += issue.keys.length;
+            } else if (issue.type === 'extra') {
+              langExtra += issue.keys.length;
+              totalExtra += issue.keys.length;
+            } else if (issue.type === 'translation') {
+              langTranslationIssues++;
+              totalTranslationIssues++;
+            }
+          });
+        }
+      } catch (error) {
+        console.log(`   ❌ Error processing ${file}: ${error.message}`);
+      }
+    });
+
+    // Summary for this language
+    if (langIssues === 0) {
+      console.log(`   🎉 ${langCode}: All translations complete!`);
+    } else {
+      languagesWithIssues++;
+      console.log(
+        `   ⚠️  ${langCode}: ${langIssues} issues (${langMissing} missing, ${langExtra} extra, ${langTranslationIssues} translation issues)`
+      );
+    }
+  });
+
+  console.log('\n📊 Summary:');
+  console.log(`   Languages checked: ${languageDirs.length}`);
+  console.log(`   Languages with issues: ${languagesWithIssues}`);
+  console.log(`   Total issues found: ${totalIssues}`);
+  console.log(`   Missing keys: ${totalMissing}`);
+  console.log(`   Extra keys: ${totalExtra}`);
+  console.log(`   Translation issues: ${totalTranslationIssues}`);
+
+  if (totalIssues === 0) {
+    console.log('\n🎉 All translations are complete and correct!');
+    process.exit(0);
+  } else {
+    console.log(`\n⚠️  ${languagesWithIssues} language(s) need attention.`);
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/remove-unused-keys.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const fs = require('fs');
+const path = require('path');
+const { getLocalesDir } = require('./utils/findLocalesDir');
+
+// Function to get all keys from an object recursively
+function getAllKeys(obj, prefix = '') {
+  let keys = [];
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+      if (
+        typeof obj[key] === 'object' &&
+        obj[key] !== null &&
+        !Array.isArray(obj[key])
+      ) {
+        keys = keys.concat(getAllKeys(obj[key], fullKey));
+      } else {
+        keys.push(fullKey);
+      }
+    }
+  }
+  return keys;
+}
+
+// Function to remove a key from an object by path
+function removeKeyByPath(obj, keyPath) {
+  const keys = keyPath.split('.');
+  let current = obj;
+  
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (!current[keys[i]] || typeof current[keys[i]] !== 'object') {
+      return false; // Path doesn't exist
+    }
+    current = current[keys[i]];
+  }
+  
+  const lastKey = keys[keys.length - 1];
+  if (current.hasOwnProperty(lastKey)) {
+    delete current[keys[keys.length - 1]];
+    
+    // Clean up empty parent objects
+    if (keys.length > 1) {
+      let parent = obj;
+      for (let i = 0; i < keys.length - 2; i++) {
+        parent = parent[keys[i]];
+      }
+      const parentKey = keys[keys.length - 2];
+      if (Object.keys(parent[parentKey]).length === 0) {
+        delete parent[parentKey];
+      }
+    }
+    
+    return true;
+  }
+  return false;
+}
+
+// Function to remove unused keys from a translation file
+function removeUnusedKeys(enUS, targetLang, filePath, langCode, dryRun = false) {
+  const enKeys = getAllKeys(enUS);
+  const targetKeys = getAllKeys(targetLang);
+  
+  const extraKeys = targetKeys.filter(key => !enKeys.includes(key));
+  
+  if (extraKeys.length === 0) {
+    return { removed: 0, keys: [] };
+  }
+  
+  // Create a deep copy to modify
+  const cleanedLang = JSON.parse(JSON.stringify(targetLang));
+  
+  let removedCount = 0;
+  for (const key of extraKeys) {
+    if (removeKeyByPath(cleanedLang, key)) {
+      removedCount++;
+    }
+  }
+  
+  if (!dryRun && removedCount > 0) {
+    // Write cleaned file
+    const targetFile = filePath;
+    fs.writeFileSync(targetFile, JSON.stringify(cleanedLang, null, 2) + '\n', 'utf8');
+  }
+  
+  return { removed: removedCount, keys: extraKeys };
+}
+
+// Main function
+function main() {
+  const args = process.argv.slice(2);
+  const targetLanguage = args.find(arg => !arg.startsWith('--'));
+  const dryRun = args.includes('--dry-run') || args.includes('-d');
+  const allLanguages = args.includes('--all') || args.includes('-a');
+  
+  if (!targetLanguage && !allLanguages) {
+    console.log('Usage: npm run i18n:remove-unused <language-code> [--dry-run]');
+    console.log('Example: npm run i18n:remove-unused tr-TR');
+    console.log('Example: npm run i18n:remove-unused tr-TR --dry-run (preview only, no removal)');
+    console.log('Example: npm run i18n:remove-unused --all (all languages)');
+    process.exit(1);
+  }
+  
+  // Find project's locales directory
+  const localesDir = getLocalesDir();
+  const enUSDir = path.join(localesDir, 'en-US');
+  
+  // Auto-discover all JSON files
+  const files = fs
+    .readdirSync(enUSDir)
+    .filter(file => file.endsWith('.json'))
+    .sort();
+  
+  if (files.length === 0) {
+    console.error('❌ No JSON files found in en-US directory!');
+    process.exit(1);
+  }
+  
+  // Get language directories
+  const allLanguageDirs = fs
+    .readdirSync(localesDir)
+    .filter(dir => {
+      const fullPath = path.join(localesDir, dir);
+      return fs.statSync(fullPath).isDirectory() && dir !== 'en-US';
+    })
+    .sort();
+  
+  // Determine which languages to process
+  let languageDirs = allLanguageDirs;
+  if (!allLanguages) {
+    if (targetLanguage === 'spanish' || targetLanguage === 'es') {
+      languageDirs = allLanguageDirs.filter(dir => dir.startsWith('es-'));
+    } else if (allLanguageDirs.includes(targetLanguage)) {
+      languageDirs = [targetLanguage];
+    } else {
+      console.log(`❌ Language ${targetLanguage} not found. Available: ${allLanguageDirs.join(', ')}`);
+      process.exit(1);
+    }
+  }
+  
+  if (dryRun) {
+    console.log('🔍 DRY RUN MODE - No files will be modified\n');
+  }
+  
+  let totalRemoved = 0;
+  let totalFiles = 0;
+  
+  console.log(`🧹 Removing unused keys from ${languageDirs.length} language(s)...\n`);
+  
+  languageDirs.forEach(langCode => {
+    const langDir = path.join(localesDir, langCode);
+    let langRemoved = 0;
+    let langFiles = 0;
+    
+    console.log(`\n🌍 Processing ${langCode}...`);
+    
+    files.forEach(file => {
+      const enUSPath = path.join(enUSDir, file);
+      const langPath = path.join(langDir, file);
+      
+      if (!fs.existsSync(enUSPath)) {
+        return;
+      }
+      
+      if (!fs.existsSync(langPath)) {
+        return;
+      }
+      
+      try {
+        const enUS = JSON.parse(fs.readFileSync(enUSPath, 'utf8'));
+        const langData = JSON.parse(fs.readFileSync(langPath, 'utf8'));
+        
+        const result = removeUnusedKeys(enUS, langData, langPath, langCode, dryRun);
+        
+        if (result.removed > 0) {
+          langRemoved += result.removed;
+          langFiles++;
+          totalRemoved += result.removed;
+          totalFiles++;
+          
+          if (dryRun) {
+            console.log(`   🔍 ${file}: Would remove ${result.removed} key(s): ${result.keys.slice(0, 5).join(', ')}${result.keys.length > 5 ? '...' : ''}`);
+          } else {
+            console.log(`   ✅ ${file}: Removed ${result.removed} unused key(s): ${result.keys.slice(0, 5).join(', ')}${result.keys.length > 5 ? '...' : ''}`);
+          }
+        }
+      } catch (error) {
+        console.log(`   ❌ Error processing ${file}: ${error.message}`);
+      }
+    });
+    
+    if (langRemoved === 0) {
+      console.log(`   ✅ ${langCode}: No unused keys found`);
+    } else {
+      console.log(`   📊 ${langCode}: Removed ${langRemoved} unused key(s) from ${langFiles} file(s)`);
+    }
+  });
+  
+  console.log('\n📊 Summary:');
+  console.log(`   Languages processed: ${languageDirs.length}`);
+  console.log(`   Files modified: ${totalFiles}`);
+  console.log(`   Total keys removed: ${totalRemoved}`);
+  
+  if (dryRun) {
+    console.log('\n💡 Run without --dry-run to actually remove the keys.');
+  } else if (totalRemoved > 0) {
+    console.log('\n✅ Unused keys removed successfully!');
+  } else {
+    console.log('\n✅ No unused keys found!');
+  }
+}
+
+main();
+

package/scripts/setup-languages.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const fs = require("fs");
+const path = require("path");
+const { getLocalesDir } = require('./utils/findLocalesDir');
+
+// All 38 languages (excluding en-US)
+const LANGUAGES = [
+  "ar-SA", // Arabic
+  "bg-BG", // Bulgarian
+  "cs-CZ", // Czech
+  "da-DK", // Danish
+  "de-DE", // German
+  "el-GR", // Greek
+  "en-AU", // English (Australia)
+  "en-CA", // English (Canada)
+  "en-GB", // English (UK)
+  "es-ES", // Spanish (Spain)
+  "es-MX", // Spanish (Mexico)
+  "fi-FI", // Finnish
+  "fr-CA", // French (Canada)
+  "fr-FR", // French (France)
+  "hi-IN", // Hindi
+  "hr-HR", // Croatian
+  "hu-HU", // Hungarian
+  "id-ID", // Indonesian
+  "it-IT", // Italian
+  "ja-JP", // Japanese
+  "ko-KR", // Korean
+  "ms-MY", // Malay
+  "nl-NL", // Dutch
+  "no-NO", // Norwegian
+  "pl-PL", // Polish
+  "pt-BR", // Portuguese (Brazil)
+  "pt-PT", // Portuguese (Portugal)
+  "ro-RO", // Romanian
+  "ru-RU", // Russian
+  "sk-SK", // Slovak
+  "sv-SE", // Swedish
+  "th-TH", // Thai
+  "tl-PH", // Tagalog
+  "tr-TR", // Turkish
+  "uk-UA", // Ukrainian
+  "vi-VN", // Vietnamese
+  "zh-CN", // Chinese Simplified
+  "zh-TW", // Chinese Traditional
+];
+
+async function setupLanguages() {
+  // Find or create project's locales directory
+  const localesDir = getLocalesDir(true); // Create if not exists
+  const enUSDir = path.join(localesDir, "en-US");
+
+  console.log("🚀 Setting up language directories and files...\n");
+
+  // Check if en-US directory exists
+  if (!fs.existsSync(enUSDir)) {
+    console.error("❌ en-US directory not found!");
+    console.error("   Expected path:", enUSDir);
+    process.exit(1);
+  }
+
+  // Automatically discover all JSON files in en-US directory
+  const files = fs
+    .readdirSync(enUSDir)
+    .filter((file) => file.endsWith(".json"))
+    .sort();
+
+  if (files.length === 0) {
+    console.error("❌ No JSON files found in en-US directory!");
+    process.exit(1);
+  }
+
+  console.log(`📄 Found ${files.length} translation files in en-US:`);
+  files.forEach((file) => console.log(`   - ${file}`));
+  console.log("");
+
+  let createdDirs = 0;
+  let createdFiles = 0;
+
+  for (const langCode of LANGUAGES) {
+    const langDir = path.join(localesDir, langCode);
+
+    // Create language directory if it doesn't exist
+    if (!fs.existsSync(langDir)) {
+      fs.mkdirSync(langDir, { recursive: true });
+      console.log(`📁 Created directory: ${langCode}/`);
+      createdDirs++;
+    }
+
+    // Copy each file from en-US
+    for (const file of files) {
+      const enUSFile = path.join(enUSDir, file);
+      const targetFile = path.join(langDir, file);
+
+      if (!fs.existsSync(targetFile)) {
+        // Copy the en-US file as a starting point
+        const content = fs.readFileSync(enUSFile, "utf8");
+        fs.writeFileSync(targetFile, content);
+        console.log(`   📄 Created: ${langCode}/${file}`);
+        createdFiles++;
+      }
+    }
+  }
+
+  console.log(`\n✅ Setup completed!`);
+  console.log(`   Directories created: ${createdDirs}`);
+  console.log(`   Files created: ${createdFiles}`);
+  console.log(`   Total languages: ${LANGUAGES.length + 1} (including en-US)`);
+  console.log(
+    `\n📝 Next steps:`,
+  );
+  console.log(`   1. Add your translation keys to en-US/*.json files`);
+  console.log(`   2. Run 'npm run i18n:translate' to auto-translate all languages`);
+  console.log(`   3. Run 'npm run i18n:check all' to verify completeness`);
+}
+
+setupLanguages().catch((error) => {
+  console.error("❌ Setup failed:", error);
+  process.exit(1);
+});

package/scripts/translate-missing.js

@@ -0,0 +1,500 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const { getLocalesDir } = require('./utils/findLocalesDir');
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const options = {
+  verbose: args.includes('--verbose') || args.includes('-v'),
+  force: args.includes('--force') || args.includes('-f'),
+  keysFilter: args.find(a => a.startsWith('--keys='))?.split('=')[1]?.split(','),
+  report: args.includes('--report') || args.includes('-r'),
+};
+
+// Statistics tracking
+const stats = {
+  totalLanguages: 0,
+  totalFiles: 0,
+  totalKeys: 0,
+  translated: 0,
+  skipped: 0,
+  errors: 0,
+};
+
+// Language codes mapping for Google Translate API
+const LANGUAGE_MAP = {
+  'ar-SA': 'ar', // Arabic
+  'bg-BG': 'bg', // Bulgarian
+  'cs-CZ': 'cs', // Czech
+  'da-DK': 'da', // Danish
+  'de-DE': 'de', // German (already complete)
+  'el-GR': 'el', // Greek
+  'en-AU': 'en', // English (skip)
+  'en-CA': 'en', // English (skip)
+  'en-GB': 'en', // English (skip)
+  'es-ES': 'es', // Spanish (already complete)
+  'es-MX': 'es', // Spanish (already complete)
+  'fi-FI': 'fi', // Finnish
+  'fr-CA': 'fr', // French
+  'fr-FR': 'fr', // French (already complete)
+  'hi-IN': 'hi', // Hindi
+  'hr-HR': 'hr', // Croatian
+  'hu-HU': 'hu', // Hungarian
+  'id-ID': 'id', // Indonesian
+  'it-IT': 'it', // Italian
+  'ja-JP': 'ja', // Japanese
+  'ko-KR': 'ko', // Korean
+  'ms-MY': 'ms', // Malay
+  'nl-NL': 'nl', // Dutch
+  'no-NO': 'no', // Norwegian
+  'pl-PL': 'pl', // Polish
+  'pt-BR': 'pt', // Portuguese
+  'pt-PT': 'pt', // Portuguese
+  'ro-RO': 'ro', // Romanian
+  'ru-RU': 'ru', // Russian
+  'sk-SK': 'sk', // Slovak
+  'sv-SE': 'sv', // Swedish
+  'th-TH': 'th', // Thai
+  'tl-PH': 'tl', // Tagalog
+  'tr-TR': 'tr', // Turkish (already complete)
+  'uk-UA': 'uk', // Ukrainian
+  'vi-VN': 'vi', // Vietnamese
+  'zh-CN': 'zh-CN', // Chinese Simplified
+  'zh-TW': 'zh-TW', // Chinese Traditional
+};
+
+// Only skip actual brand names - everything else should be translated
+// Note: Even common words like "Email", "OK", "Premium" should be localized
+const SKIP_WORDS = new Set([
+  'Google',
+  'Apple',
+  'Facebook',
+  'Instagram',
+  'Twitter',
+  'WhatsApp',
+]);
+
+/**
+ * Simple Google Translate API call using free endpoint
+ * Note: This uses Google's unofficial API. For production, use official API with key.
+ */
+async function translateText(text, targetLang) {
+  return new Promise((resolve, _reject) => {
+    if (SKIP_WORDS.has(text)) {
+      resolve(text);
+      return;
+    }
+
+    const encodedText = encodeURIComponent(text);
+    const url = `https://translate.googleapis.com/translate_a/single?client=gtx&sl=en&tl=${targetLang}&dt=t&q=${encodedText}`;
+
+    https
+      .get(url, res => {
+        let data = '';
+        res.on('data', chunk => {
+          data += chunk;
+        });
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(data);
+            const translated = parsed[0]
+              .map(item => item[0])
+              .join('')
+              .trim();
+            resolve(translated || text);
+          } catch (error) {
+            console.warn(
+              `⚠️ Translation failed for "${text}" to ${targetLang}:`,
+              error.message
+            );
+            resolve(text); // Fallback to original
+          }
+        });
+      })
+      .on('error', err => {
+        console.warn(
+          `⚠️ Network error translating "${text}" to ${targetLang}:`,
+          err.message
+        );
+        resolve(text); // Fallback to original
+      });
+  });
+}
+
+/**
+ * Add delay between API calls to avoid rate limiting
+ */
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Check if a value needs translation (is missing or undefined)
+ *
+ * IMPROVED DETECTION:
+ * - Respects --force flag to retranslate everything
+ * - Respects --keys filter for selective retranslation
+ * - Shows skip reasons in --verbose mode
+ * - Protects manual translations by default
+ */
+function needsTranslation(key, value, enValue) {
+  // --force mode: Always translate
+  if (options.force) {
+    if (options.verbose) {
+      console.log(`   🔄 Force mode: translating "${key}"`);
+    }
+    return true;
+  }
+
+  // --keys filter: Only translate specified keys
+  if (options.keysFilter && !options.keysFilter.includes(key)) {
+    if (options.verbose) {
+      console.log(`   ⏭️  Skipping "${key}": not in --keys filter`);
+    }
+    stats.skipped++;
+    return false;
+  }
+
+  // Translate if value is missing/undefined
+  if (value === undefined || value === null) {
+    if (options.verbose) {
+      console.log(`   ✅ Translating "${key}": missing value`);
+    }
+    return true;
+  }
+
+  if (typeof value !== 'string') {
+    if (options.verbose) {
+      console.log(`   ⏭️  Skipping "${key}": non-string value`);
+    }
+    stats.skipped++;
+    return false;
+  }
+
+  // Skip brand names only
+  if (SKIP_WORDS.has(value)) {
+    if (options.verbose) {
+      console.log(`   ⏭️  Skipping "${key}": brand name`);
+    }
+    stats.skipped++;
+    return false;
+  }
+
+  // Skip numeric values and placeholders (0.00, phone numbers, etc.)
+  if (/^[\d\s.+()-]+$/.test(value)) {
+    if (options.verbose) {
+      console.log(`   ⏭️  Skipping "${key}": numeric value`);
+    }
+    stats.skipped++;
+    return false;
+  }
+
+  // Skip email addresses
+  if (/^[\w.-]+@[\w.-]+\.\w+$/.test(value)) {
+    if (options.verbose) {
+      console.log(`   ⏭️  Skipping "${key}": email address`);
+    }
+    stats.skipped++;
+    return false;
+  }
+
+  // Skip URLs
+  if (value.startsWith('http://') || value.startsWith('https://')) {
+    if (options.verbose) {
+      console.log(`   ⏭️  Skipping "${key}": URL`);
+    }
+    stats.skipped++;
+    return false;
+  }
+
+  // Skip if already translated (value is different from English)
+  // This protects manual translations!
+  if (value !== enValue) {
+    if (options.verbose) {
+      console.log(`   ⏭️  Skipping "${key}": already translated (manual or previous auto)`);
+    }
+    stats.skipped++;
+    return false;
+  }
+
+  // If we get here, value exists and equals enValue
+  // This means it hasn't been translated yet - TRANSLATE IT!
+  if (options.verbose) {
+    console.log(`   ✅ Translating "${key}": equals English source`);
+  }
+  return true;
+}
+
+/**
+ * Recursively find and translate missing values
+ */
+async function translateObject(enObj, targetObj, targetLang, path = '') {
+  let translatedCount = 0;
+
+  for (const key in enObj) {
+    const currentPath = path ? `${path}.${key}` : key;
+    stats.totalKeys++;
+
+    if (typeof enObj[key] === 'object' && enObj[key] !== null) {
+      if (!targetObj[key] || typeof targetObj[key] !== 'object') {
+        targetObj[key] = {};
+      }
+      translatedCount += await translateObject(
+        enObj[key],
+        targetObj[key],
+        targetLang,
+        currentPath
+      );
+    } else if (typeof enObj[key] === 'string') {
+      const originalValue = enObj[key];
+
+      // Skip placeholders like {{count}}, {{mood}}, etc.
+      if (originalValue.includes('{{') && originalValue.includes('}}')) {
+        if (options.verbose) {
+          console.log(
+            `   ⏭️  Skipping placeholder: ${currentPath} = "${originalValue}"`
+          );
+        }
+        stats.skipped++;
+        continue;
+      }
+
+      // Check if needs translation
+      if (needsTranslation(key, targetObj[key], originalValue)) {
+        if (!options.verbose) {
+          // Only show in non-verbose mode (verbose already shows in needsTranslation)
+          console.log(`   🔄 Translating: ${currentPath} = "${originalValue}"`);
+        }
+
+        try {
+          const translated = await translateText(originalValue, targetLang);
+          targetObj[key] = translated;
+          translatedCount++;
+          stats.translated++;
+
+          // Add delay to avoid rate limiting (200ms between requests)
+          await delay(200);
+        } catch (error) {
+          console.error(`   ❌ Failed to translate "${currentPath}":`, error.message);
+          stats.errors++;
+        }
+      }
+    }
+  }
+
+  return translatedCount;
+}
+
+/**
+ * Translate missing strings for a single file
+ */
+async function translateFile(enUSFile, targetFile, langCode) {
+  const enUS = JSON.parse(fs.readFileSync(enUSFile, 'utf8'));
+  const target = JSON.parse(fs.readFileSync(targetFile, 'utf8'));
+
+  const targetLang = LANGUAGE_MAP[langCode];
+  if (!targetLang) {
+    console.log(`   ⚠️ No language mapping for ${langCode}, skipping`);
+    return 0;
+  }
+
+  // Note: English variants (en-AU, en-CA, en-GB) will also be translated
+  // Google Translate may use regional variations and accents
+
+  const translatedCount = await translateObject(enUS, target, targetLang);
+
+  if (translatedCount > 0) {
+    // Ensure parent directory exists before writing
+    const targetDir = path.dirname(targetFile);
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+    fs.writeFileSync(targetFile, JSON.stringify(target, null, 2) + '\n');
+  }
+
+  return translatedCount;
+}
+
+/**
+ * Show usage information
+ */
+function showUsage() {
+  console.log(`
+📖 Google Translate Auto-Translation Script
+
+USAGE:
+  npm run i18n:translate [options]
+
+OPTIONS:
+  --verbose, -v     Show detailed translation decisions
+  --force, -f       Force retranslate all keys (overwrite manual translations)
+  --keys=key1,key2  Only translate specific keys (comma-separated)
+  --report, -r      Show detailed statistics report
+
+EXAMPLES:
+  npm run i18n:translate
+    → Translate only missing keys, skip manual translations
+
+  npm run i18n:translate --verbose
+    → Show why each key is translated or skipped
+
+  npm run i18n:translate --force
+    → Retranslate ALL keys, overwriting manual translations
+
+  npm run i18n:translate --keys=save,cancel,delete
+    → Only retranslate these specific keys
+
+  npm run i18n:translate --verbose --keys=title
+    → Verbose mode for specific key translation
+
+BEHAVIOR:
+  ✅ Protects manual translations by default
+  ✅ Only translates missing keys or keys that equal English
+  ✅ Use --force to override protection
+  ✅ Use --keys to selectively retranslate specific keys
+
+NOTE:
+  Scripts automatically find your project's locales directory.
+  Supported paths:
+    - src/domains/localization/infrastructure/locales
+    - src/locales
+    - locales
+`);
+  process.exit(0);
+}
+
+// Show usage if --help
+if (args.includes('--help') || args.includes('-h')) {
+  showUsage();
+}
+
+/**
+ * Main function to translate all missing strings
+ */
+async function translateAllLanguages() {
+  // Find project's locales directory
+  const localesDir = getLocalesDir();
+  const enUSDir = path.join(localesDir, 'en-US');
+
+  // Automatically discover all JSON files in en-US directory
+  const files = fs
+    .readdirSync(enUSDir)
+    .filter(file => file.endsWith('.json'))
+    .sort();
+
+  // Get languages that need translation (skip complete ones)
+  const skipLanguages = new Set([
+    'en-US', // Base language - skip translation
+    'en-AU', // English variant - copy from en-US
+    'en-CA', // English variant - copy from en-US
+    'en-GB', // English variant - copy from en-US
+  ]);
+
+  const allLanguages = fs
+    .readdirSync(localesDir)
+    .filter(
+      dir =>
+        !skipLanguages.has(dir) &&
+        fs.statSync(path.join(localesDir, dir)).isDirectory()
+    )
+    .sort();
+
+  console.log('🚀 Starting automatic translation...\n');
+
+  // Show options if any are active
+  if (options.verbose || options.force || options.keysFilter || options.report) {
+    console.log('⚙️  Active options:');
+    if (options.verbose) console.log('   • Verbose mode: ON');
+    if (options.force) console.log('   • Force retranslate: ON (⚠️  will overwrite manual translations)');
+    if (options.keysFilter) console.log(`   • Keys filter: ${options.keysFilter.join(', ')}`);
+    if (options.report) console.log('   • Detailed report: ON');
+    console.log('');
+  }
+
+  console.log(`📊 Languages to translate: ${allLanguages.length}`);
+  console.log(`📄 Files per language: ${files.length}`);
+  console.log(
+    `⏱️ Estimated time: ~${Math.ceil((allLanguages.length * files.length * 50 * 0.2) / 60)} minutes\n`
+  );
+  console.log(
+    '⚡ Running with optimized speed (200ms delay between translations)\n'
+  );
+
+  stats.totalLanguages = allLanguages.length;
+  stats.totalFiles = files.length;
+
+  let totalTranslated = 0;
+  let totalLanguages = 0;
+
+  for (const langCode of allLanguages) {
+    console.log(`\n🌍 Translating ${langCode}...`);
+    totalLanguages++;
+
+    let langTranslated = 0;
+
+    for (const file of files) {
+      const enUSFile = path.join(enUSDir, file);
+      const targetDir = path.join(localesDir, langCode);
+      const targetFile = path.join(targetDir, file);
+
+      // Ensure target directory exists
+      if (!fs.existsSync(targetDir)) {
+        fs.mkdirSync(targetDir, { recursive: true });
+      }
+
+      // Create target file if it doesn't exist (create empty structure)
+      if (!fs.existsSync(targetFile)) {
+        console.log(`   📝 Creating ${file} (new file)`);
+        // Create empty object - translation will populate it
+        fs.writeFileSync(targetFile, JSON.stringify({}, null, 2) + '\n');
+      }
+
+      const count = await translateFile(enUSFile, targetFile, langCode);
+      langTranslated += count;
+      totalTranslated += count;
+
+      // Only log files that were actually translated
+      if (count > 0) {
+        console.log(`   ✅ ${file}: ${count} strings translated`);
+      }
+    }
+
+    console.log(
+      `   📊 ${langCode} summary: ${langTranslated} strings translated`
+    );
+  }
+
+  console.log(`\n✅ Translation completed!`);
+  console.log(`   Languages processed: ${totalLanguages}`);
+  console.log(`   Total strings translated: ${totalTranslated}`);
+
+  // Show detailed statistics if --report or --verbose
+  if (options.report || options.verbose) {
+    console.log(`\n📊 DETAILED STATISTICS:`);
+    console.log(`   Total keys processed: ${stats.totalKeys}`);
+    console.log(`   Translated: ${stats.translated} (${((stats.translated / stats.totalKeys) * 100).toFixed(1)}%)`);
+    console.log(`   Skipped: ${stats.skipped} (${((stats.skipped / stats.totalKeys) * 100).toFixed(1)}%)`);
+    if (stats.errors > 0) {
+      console.log(`   Errors: ${stats.errors} ❌`);
+    }
+
+    console.log(`\n💡 TIPS:`);
+    console.log(`   • Manual translations are protected (skipped) by default`);
+    console.log(`   • Use --force to retranslate everything`);
+    console.log(`   • Use --keys=key1,key2 to retranslate specific keys`);
+    console.log(`   • Use --verbose to see why keys are skipped`);
+  }
+
+  console.log(
+    `\n📝 Next step: Run 'npm run i18n:check' to verify translations.`
+  );
+}
+
+translateAllLanguages().catch(error => {
+  console.error('❌ Translation failed:', error);
+  process.exit(1);
+});

package/scripts/utils/findLocalesDir.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * Utility to find project's locales directory
+ * Searches common paths for localization files
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Find locales directory in project
+ * @returns {string|null} Path to locales directory or null if not found
+ */
+function findLocalesDir() {
+  const projectRoot = process.cwd();
+  
+  // Common paths to search
+  const possiblePaths = [
+    // DDD structure
+    path.join(projectRoot, 'src/domains/localization/infrastructure/locales'),
+    path.join(projectRoot, 'src/domains/i18n/infrastructure/locales'),
+    path.join(projectRoot, 'src/infrastructure/localization/locales'),
+    // Simple structure
+    path.join(projectRoot, 'src/locales'),
+    path.join(projectRoot, 'locales'),
+    path.join(projectRoot, 'translations'),
+    // Alternative DDD
+    path.join(projectRoot, 'src/features/localization/locales'),
+  ];
+  
+  // Find first existing path with en-US directory
+  for (const possiblePath of possiblePaths) {
+    const enUSPath = path.join(possiblePath, 'en-US');
+    if (fs.existsSync(possiblePath) && fs.existsSync(enUSPath)) {
+      return possiblePath;
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Get or create locales directory
+ * @param {boolean} createIfNotExists - Create directory if it doesn't exist (for setup script)
+ * @returns {string} Path to locales directory
+ */
+function getLocalesDir(createIfNotExists = false) {
+  let localesDir = findLocalesDir();
+  
+  if (!localesDir) {
+    if (createIfNotExists) {
+      // Try to create in most common location
+      const projectRoot = process.cwd();
+      localesDir = path.join(projectRoot, 'src/domains/localization/infrastructure/locales');
+      const enUSDir = path.join(localesDir, 'en-US');
+      
+      if (!fs.existsSync(localesDir)) {
+        fs.mkdirSync(localesDir, { recursive: true });
+        fs.mkdirSync(enUSDir, { recursive: true });
+        console.log(`✅ Created locales directory: ${localesDir}`);
+      }
+      
+      return localesDir;
+    }
+    
+    console.error('❌ Locales directory not found!');
+    console.error('\nPlease create a locales directory in one of these locations:');
+    console.error('  - src/domains/localization/infrastructure/locales');
+    console.error('  - src/locales');
+    console.error('  - locales');
+    console.error('\nOr run: npm run i18n:setup');
+    process.exit(1);
+  }
+  
+  return localesDir;
+}
+
+module.exports = { findLocalesDir, getLocalesDir };
+