@tuhama/translation-manager 0.6.1 → 0.7.0

package/src/core/Scanner.js

@@ -1,128 +1,204 @@
-const fs = require('fs-extra');
-const path = require('path');
-
-/**
- * Scanner class to find translation key usages in source code.
- */
-class Scanner {
-    constructor(targetDir, localesDir, config = {}) {
-        this.targetDir = targetDir;
-        this.localesDir = localesDir;
-        this.config = config;
-        this.extensions = config.extensions || ['.js', '.jsx', '.ts', '.tsx', '.html', '.vue'];
-        this.exclude = config.exclude || ['node_modules', '.git', 'dist', 'build', localesDir];
-    }
-
-    /**
-     * Recursively gets files from the target directory.
-     */
-    async getFiles() {
-        const files = [];
-
-        const walk = async (dir) => {
-            const entries = await fs.readdir(dir, { withFileTypes: true });
-
-            for (const entry of entries) {
-                const fullPath = path.resolve(dir, entry.name);
-
-                if (entry.isDirectory()) {
-                    if (this.exclude.includes(entry.name) || this.exclude.some(ex => fullPath === path.resolve(this.targetDir, ex) || fullPath.startsWith(path.resolve(this.targetDir, ex) + path.sep))) {
-                        continue;
-                    }
-                    await walk(fullPath);
-                } else if (this.extensions.includes(path.extname(fullPath))) {
-                    files.push(fullPath);
-                }
-            }
-        };
-
-        await walk(this.targetDir);
-        return files;
-    }
-
-    /**
-     * Scans source code for key usages.
-     */
-    async findUnusedKeys(allKeys) {
-        const files = await this.getFiles();
-        const contents = await Promise.all(files.map(f => fs.readFile(f, 'utf-8')));
-        const combinedContent = contents.join('\n---\n');
-
-        const used = new Set();
-        const maybeUsed = new Set();
-        const unused = [];
-
-        allKeys.forEach(key => {
-            // 1. Literal usage
-            const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-            const literalRegex = new RegExp(`['"\`]${escapedKey}['"\`]`, 'g');
-
-            if (literalRegex.test(combinedContent)) {
-                used.add(key);
-                return;
-            }
-
-            // 2. Dynamic usage
-            const parts = key.split('.');
-            let isMaybeUsed = false;
-
-            for (let i = 1; i < parts.length; i++) {
-                const prefix = parts.slice(0, i).join('.') + '.';
-                const escapedPrefix = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-                const dynamicRegex = new RegExp(`(['"\`]${escapedPrefix}['"\`].*?[+])|(['"\`]${escapedPrefix}.*?\$\{)`, 'g');
-
-                if (dynamicRegex.test(combinedContent)) {
-                    isMaybeUsed = true;
-                    break;
-                }
-            }
-
-            if (isMaybeUsed) {
-                maybeUsed.add(key);
-            } else {
-                unused.push(key);
-            }
-        });
-
-        return {
-            unused: unused.sort(),
-            maybeUsed: Array.from(maybeUsed).sort()
-        };
-    }
-
-    /**
-     * Finds keys that are used in source code but missing from translation files.
-     */
-    async findMissingKeys(existingKeys) {
-        const files = await this.getFiles();
-        const contents = await Promise.all(files.map(f => fs.readFile(f, 'utf-8')));
-        const combinedContent = contents.join('\n---\n');
-
-        const missingKeys = new Set();
-        const existingKeysSet = new Set(existingKeys);
-
-        // Regex patterns to find potential keys: 
-        // 1. t('key')
-        // 2. i18n.t('key')
-        // 3. i18nKey="key"
-        // 4. <Trans i18nKey="key">
-        const patterns = [
-            /(?:\bt\(|i18n\.t\(|i18nKey=)\s*['"\`]([^'"\`]+)['"\`]/g
-        ];
-
-        patterns.forEach(regex => {
-            let match;
-            while ((match = regex.exec(combinedContent)) !== null) {
-                const key = match[1];
-                // basic validation to avoid random strings
-                if (key && key.includes('.') && !existingKeysSet.has(key)) {
-                    missingKeys.add(key);
-                }
-            }
-        });
-
-        return Array.from(missingKeys).sort();
-    }
-}
-
-module.exports = Scanner;
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Scanner class to find translation key usages in source code.
+ */
+class Scanner {
+    constructor(targetDir, localesDir, config = {}) {
+        this.targetDir = targetDir;
+        this.localesDir = localesDir;
+        this.config = config;
+        this.extensions = config.extensions || ['.js', '.jsx', '.ts', '.tsx', '.html', '.vue'];
+        this.exclude = config.exclude || ['node_modules', '.git', 'dist', 'build', localesDir];
+    }
+
+    /**
+     * Recursively gets files from the target directory.
+     */
+    async getFiles() {
+        const files = [];
+
+        const walk = async (dir) => {
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+
+            for (const entry of entries) {
+                const fullPath = path.resolve(dir, entry.name);
+
+                if (entry.isDirectory()) {
+                    if (this.exclude.includes(entry.name) || this.exclude.some(ex => fullPath === path.resolve(this.targetDir, ex) || fullPath.startsWith(path.resolve(this.targetDir, ex) + path.sep))) {
+                        continue;
+                    }
+                    await walk(fullPath);
+                } else if (this.extensions.includes(path.extname(fullPath))) {
+                    files.push(fullPath);
+                }
+            }
+        };
+
+        await walk(this.targetDir);
+        return files;
+    }
+
+    /**
+     * Scans source code for key usages.
+     */
+    async findUnusedKeys(allKeys) {
+        const files = await this.getFiles();
+        const contents = await Promise.all(files.map(f => fs.readFile(f, 'utf-8')));
+        const combinedContent = contents.join('\n---\n');
+
+        const used = new Set();
+        const maybeUsed = new Set();
+        const unused = [];
+
+        allKeys.forEach(key => {
+            // 1. Literal usage
+            const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const literalRegex = new RegExp(`['"\`]${escapedKey}['"\`]`, 'g');
+
+            if (literalRegex.test(combinedContent)) {
+                used.add(key);
+                return;
+            }
+
+            // 2. Dynamic usage
+            const parts = key.split('.');
+            let isMaybeUsed = false;
+
+            for (let i = 1; i < parts.length; i++) {
+                const prefix = parts.slice(0, i).join('.') + '.';
+                const escapedPrefix = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const dynamicRegex = new RegExp("(['\"`]" + escapedPrefix + "['\"`].*?[+])|(['\"`]" + escapedPrefix + ".*?\\${)", 'g');
+
+                if (dynamicRegex.test(combinedContent)) {
+                    isMaybeUsed = true;
+                    break;
+                }
+            }
+
+            if (isMaybeUsed) {
+                maybeUsed.add(key);
+            } else {
+                unused.push(key);
+            }
+        });
+
+        return {
+            unused: unused.sort(),
+            maybeUsed: Array.from(maybeUsed).sort()
+        };
+    }
+
+    /**
+     * Finds keys that are used in source code but missing from translation files.
+     * Returns an array of keys by default, or an object with context if includeContext is true.
+     */
+    async findMissingKeys(existingKeys, includeContext = false) {
+        const files = await this.getFiles();
+        const missingKeysData = {};
+        const existingKeysSet = new Set(existingKeys);
+
+        // Regex patterns to find potential keys: 
+        // 1. t('key')
+        // 2. i18n.t('key')
+        // 3. i18nKey="key"
+        // 4. <Trans i18nKey="key">
+        // 5. useTranslation(['namespace']) -> t('key')
+        const patterns = [
+            /(?:\bt\(|i18n\.t\(|i18nKey=)\s*['"\`]([^'"\`\s]+)['"\`]/g
+        ];
+
+        for (const file of files) {
+            const content = await fs.readFile(file, 'utf-8');
+            const lines = content.split('\n');
+
+            patterns.forEach(regex => {
+                let match;
+                // Reset regex state for each file
+                regex.lastIndex = 0;
+                while ((match = regex.exec(content)) !== null) {
+                    const key = match[1];
+                    // basic validation to avoid random strings and ensure it's not a translation file path
+                    if (key && !existingKeysSet.has(key) && !key.includes('/') && !key.includes('\\')) {
+                        if (includeContext) {
+                            if (!missingKeysData[key]) {
+                                missingKeysData[key] = {
+                                    key,
+                                    occurrences: []
+                                };
+                            }
+                            
+                            // Find line number
+                            const index = match.index;
+                            const lineNo = content.substring(0, index).split('\n').length;
+                            const contextRange = 2; // lines before and after
+                            const startLine = Math.max(0, lineNo - contextRange - 1);
+                            const endLine = Math.min(lines.length, lineNo + contextRange);
+                            const contextLines = lines.slice(startLine, endLine);
+                            
+                            missingKeysData[key].occurrences.push({
+                                file: path.relative(this.targetDir, file),
+                                line: lineNo,
+                                context: contextLines.join('\n').trim()
+                            });
+                        } else {
+                            missingKeysData[key] = true;
+                        }
+                    }
+                }
+            });
+        }
+
+        if (includeContext) {
+            return missingKeysData;
+        }
+        return Object.keys(missingKeysData).sort();
+    }
+
+    /**
+     * Finds context for a list of existing keys.
+     */
+    async findContextForKeys(keys) {
+        const files = await this.getFiles();
+        const contextData = {};
+        const keysSet = new Set(keys);
+
+        for (const file of files) {
+            const content = await fs.readFile(file, 'utf-8');
+            const lines = content.split('\n');
+
+            keys.forEach(key => {
+                const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const regex = new RegExp(`['"\`]${escapedKey}['"\`]`, 'g');
+                
+                let match;
+                while ((match = regex.exec(content)) !== null) {
+                    if (!contextData[key]) {
+                        contextData[key] = {
+                            key,
+                            occurrences: []
+                        };
+                    }
+
+                    const index = match.index;
+                    const lineNo = content.substring(0, index).split('\n').length;
+                    const contextRange = 2;
+                    const startLine = Math.max(0, lineNo - contextRange - 1);
+                    const endLine = Math.min(lines.length, lineNo + contextRange);
+                    const contextLines = lines.slice(startLine, endLine);
+
+                    contextData[key].occurrences.push({
+                        file: path.relative(this.targetDir, file),
+                        line: lineNo,
+                        context: contextLines.join('\n').trim()
+                    });
+                }
+            });
+        }
+
+        return contextData;
+    }
+}
+
+module.exports = Scanner;

package/src/core/TranslatorManager.js

@@ -5,6 +5,7 @@ const Storage = require('./Storage');
 const Scanner = require('./Scanner');
 const Utilities = require('./Utilities');
 const GoogleTranslator = require('./services/GoogleTranslator');
+const AITranslator = require('./services/AITranslator');
 
 /**
  * Main manager class for translation management.
@@ -45,9 +46,10 @@ class TranslatorManager {
 
         // Scan source for unused and missing keys
         const scanner = new Scanner(this.targetDir, localesDir, this.config);
-        const [analysis, missingFromFiles] = await Promise.all([
+        const [analysis, missingFromFiles, missingKeysContext] = await Promise.all([
             scanner.findUnusedKeys(allKeys),
-            scanner.findMissingKeys(allKeys)
+            scanner.findMissingKeys(allKeys),
+            scanner.findMissingKeys(allKeys, true)
         ]);
 
         return {
@@ -58,7 +60,8 @@ class TranslatorManager {
             results,
             unused: analysis.unused,
             maybeUsed: analysis.maybeUsed,
-            missingFromFiles: missingFromFiles
+            missingFromFiles: missingFromFiles,
+            missingKeysContext: missingKeysContext
         };
     }
 
@@ -112,20 +115,41 @@ class TranslatorManager {
     /**
      * Translates a specific text into target language.
      */
-    async translateSingle(text, targetLang, sourceLang = 'en') {
-        // Support both old and new config formats for backward compatibility
-        let translatorConfig;
+    async translateSingle(text, targetLang, sourceLang = 'en', key = null) {
+        const { translator, type } = await this.getTranslator();
+        
+        if (type === 'ai' && key) {
+            const scanner = new Scanner(this.targetDir, await this.storage.getLocalesDir(), this.config);
+            const context = await scanner.findContextForKeys([key]);
+            return await translator.translate(text, targetLang, sourceLang, context);
+        }
+        
+        return await translator.translate(text, targetLang, sourceLang);
+    }
+
+    /**
+     * Gets the configured translator instance.
+     */
+    async getTranslator() {
+        if (this.config.aiTranslate && this.config.aiTranslate.apiKey) {
+            return {
+                translator: new AITranslator(this.config.aiTranslate),
+                type: 'ai'
+            };
+        }
+
+        if (this.config.googleTranslate && this.config.googleTranslate.projectId) {
+            return {
+                translator: new GoogleTranslator(this.config.googleTranslate),
+                type: 'google'
+            };
+        }
+
         if (this.config.googleTranslateApiKey) {
-            // Legacy v2 config - provide migration guidance
-            throw new Error('Google Translate API v2 is deprecated. Please update your configuration to use v3 with projectId and keyFilename in the googleTranslate object.');
-        } else if (this.config.googleTranslate) {
-            translatorConfig = this.config.googleTranslate;
-        } else {
-            throw new Error('Google Translate configuration is missing. Please add googleTranslate.projectId and googleTranslate.keyFilename in Settings.');
+            throw new Error('Google Translate API v2 is deprecated. Please update your configuration.');
         }
 
-        const translator = new GoogleTranslator(translatorConfig);
-        return await translator.translate(text, targetLang, sourceLang);
+        throw new Error('No translation service configured. Please add Google Translate or AI settings.');
     }
 
     /**
@@ -159,20 +183,16 @@ class TranslatorManager {
     async bulkTranslate(sourceLang) {
         const report = await this.getBulkTranslateReport(sourceLang);
         const translations = await this.storage.readAll();
-
-        // Support both old and new config formats for backward compatibility
-        let translatorConfig;
-        if (this.config.googleTranslateApiKey) {
-            // Legacy v2 config - provide migration guidance
-            throw new Error('Google Translate API v2 is deprecated. Please update your configuration to use v3 with projectId and keyFilename in the googleTranslate object.');
-        } else if (this.config.googleTranslate) {
-            translatorConfig = this.config.googleTranslate;
-        } else {
-            throw new Error('Google Translate configuration is missing. Please add googleTranslate.projectId and googleTranslate.keyFilename in Settings.');
+        const { translator, type } = await this.getTranslator();
+
+        // If AI, get context
+        let context = {};
+        if (type === 'ai') {
+            const scanner = new Scanner(this.targetDir, await this.storage.getLocalesDir(), this.config);
+            const allMissingKeys = Object.values(report).flatMap(r => r.keys);
+            context = await scanner.findContextForKeys([...new Set(allMissingKeys)]);
         }
 
-        const translator = new GoogleTranslator(translatorConfig);
-
         const preview = {};
 
         for (const lang in report) {
@@ -185,7 +205,7 @@ class TranslatorManager {
             const validKeys = validIndices.map(idx => keys[idx]);
 
             if (textsToTranslate.length > 0) {
-                const translatedTexts = await translator.translate(textsToTranslate, lang, sourceLang);
+                const translatedTexts = await translator.translate(textsToTranslate, lang, sourceLang, context);
                 preview[lang] = {};
                 validKeys.forEach((key, idx) => {
                     preview[lang][key] = translatedTexts[idx];
@@ -260,27 +280,68 @@ class TranslatorManager {
     }
 
     /**
-     * Exports keys that are used in code but not in translation files.
+     * Exports all missing translation keys.
+     * Includes:
+     * 1. Keys used in code but missing from all translation files.
+     * 2. Keys existing in translation files but missing values in some languages.
+     * @param {string} sourceLang - The source language to use as reference (default: 'en')
      * @returns {Object} - Export data with missing keys and empty values for each language
      */
-    async exportMissingFromFiles() {
-        const { languages, missingFromFiles } = await this.scan();
+    async exportMissingFromFiles(sourceLang = 'en') {
+        const { languages, translations, allKeys, missingFromFiles, missingKeysContext } = await this.scan();
         const exportData = {};
+        const context = {};
 
-        // Build structure: {"key": {"lang1": "", "lang2": ""}}
+        // 1. Add keys missing from files (found in code)
         missingFromFiles.forEach(key => {
             exportData[key] = {};
             languages.forEach(lang => {
                 exportData[key][lang] = '';
             });
+            
+            // Add context if available
+            if (missingKeysContext[key]) {
+                context[key] = missingKeysContext[key].occurrences.map(occ => ({
+                    file: occ.file,
+                    line: occ.line,
+                    snippet: occ.context
+                }));
+            }
+        });
+
+        // 2. Add existing keys that are missing translations in some languages
+        allKeys.forEach(key => {
+            let isMissingInAny = false;
+            const keyLangs = {};
+
+            languages.forEach(lang => {
+                const val = lodash.get(translations[lang], key);
+                if (val === undefined || val === '') {
+                    isMissingInAny = true;
+                    keyLangs[lang] = '';
+                } else {
+                    keyLangs[lang] = val;
+                }
+            });
+
+            if (isMissingInAny) {
+                // If it's already in exportData (from code), we've already handled it.
+                // Otherwise, add it now.
+                if (!exportData[key]) {
+                    exportData[key] = keyLangs;
+                }
+            }
         });
 
         return {
             exportData,
+            context,
             metadata: {
                 languages,
-                totalKeys: missingFromFiles.length,
-                exportedAt: new Date().toISOString()
+                sourceLang,
+                totalKeys: Object.keys(exportData).length,
+                exportedAt: new Date().toISOString(),
+                aiFriendly: true
             }
         };
     }
@@ -306,6 +367,9 @@ class TranslatorManager {
         };
 
         for (const key in importData) {
+            // Skip metadata if present
+            if (key === 'metadata') continue;
+
             const keyTranslations = importData[key];
 
             for (const lang in keyTranslations) {

package/src/core/Utilities.js

@@ -1,55 +1,59 @@
-const lodash = require('lodash');
-
-/**
- * Utility functions for object manipulation.
- */
-class Utilities {
-    /**
-     * Recursively sorts object keys alphabetically.
-     */
-    static sortObject(obj) {
-        if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
-            return obj;
-        }
-
-        const sorted = {};
-        Object.keys(obj).sort().forEach(key => {
-            sorted[key] = Utilities.sortObject(obj[key]);
-        });
-        return sorted;
-    }
-
-    /**
-     * Flattens a nested object into a set of dot-notated keys.
-     */
-    static flattenKeys(obj, prefix = '', keySet = new Set()) {
-        Object.keys(obj).forEach(key => {
-            const fullKey = prefix ? `${prefix}.${key}` : key;
-            if (typeof obj[key] === 'object' && obj[key] !== null && !Array.isArray(obj[key])) {
-                Utilities.flattenKeys(obj[key], fullKey, keySet);
-            } else {
-                keySet.add(fullKey);
-            }
-        });
-        return keySet;
-    }
-
-    /**
-     * Normalizes translation keys across all languages.
-     */
-    static syncKeys(translations, allKeys) {
-        const languages = Object.keys(translations);
-        languages.forEach(lang => {
-            const content = translations[lang];
-            allKeys.forEach(key => {
-                if (lodash.get(content, key) === undefined) {
-                    lodash.set(content, key, '');
-                }
-            });
-            translations[lang] = Utilities.sortObject(content);
-        });
-        return translations;
-    }
-}
-
-module.exports = Utilities;
+const lodash = require('lodash');
+
+/**
+ * Utility functions for object manipulation.
+ */
+class Utilities {
+    /**
+     * Recursively sorts object keys alphabetically.
+     */
+    static sortObject(obj) {
+        if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
+            return obj;
+        }
+
+        const sorted = {};
+        Object.keys(obj).sort().forEach(key => {
+            sorted[key] = Utilities.sortObject(obj[key]);
+        });
+        return sorted;
+    }
+
+    /**
+     * Flattens a nested object into a set of dot-notated keys.
+     */
+    static flattenKeys(obj, prefix = '', keySet = new Set()) {
+        if (!obj || typeof obj !== 'object') {
+            return keySet;
+        }
+
+        Object.keys(obj).forEach(key => {
+            const fullKey = prefix ? `${prefix}.${key}` : key;
+            if (typeof obj[key] === 'object' && obj[key] !== null && !Array.isArray(obj[key])) {
+                Utilities.flattenKeys(obj[key], fullKey, keySet);
+            } else {
+                keySet.add(fullKey);
+            }
+        });
+        return keySet;
+    }
+
+    /**
+     * Normalizes translation keys across all languages.
+     */
+    static syncKeys(translations, allKeys) {
+        const languages = Object.keys(translations);
+        languages.forEach(lang => {
+            const content = translations[lang];
+            allKeys.forEach(key => {
+                if (lodash.get(content, key) === undefined) {
+                    lodash.set(content, key, '');
+                }
+            });
+            translations[lang] = Utilities.sortObject(content);
+        });
+        return translations;
+    }
+}
+
+module.exports = Utilities;