@tuhama/translation-manager 0.1.0 → 0.3.0

package/README.md

@@ -4,9 +4,12 @@ A modern, web-based interface for managing i18n translation files in React and o
 
 ## Features
 - **Modern UI**: Dark mode, glassmorphism, and smooth animations.
+- **Auto-Translation**: Integrated Google Translate support for single-key and bulk translations.
+- **Missing Keys Detection**: Identifies translation keys used in source code but missing from files.
+- **Cleanup Tool**: Detects and batch-removes unused translation keys.
+- **Normalization**: Synchronizes keys across all languages and sorts them alphabetically with one click.
 - **Nested Keys**: Supports dot-notation for nested JSON structures.
-- **Tree View**: Easy navigation and deletion of translation keys.
-- **Auto-population**: Automatically populates existing values when entering an existing key.
+- **Tree View**: Easy navigation and management of translation keys.
 - **Zero Config**: Auto-detects common locales folders.
 
 ## Installation
@@ -19,6 +22,20 @@ Or run directly with npx:
 npx @tuhama/translation-manager
 ```
 
+## Usage
+
+### ⚠️ Missing Keys Detection
+The application automatically scans your source code for translation keys used (e.g., `t('key.name')`) but missing from your translation files. Click the "**Missing**" button in the sidebar to review and create them instantly.
+
+### 🧹 Cleaning Unused Keys
+Over time, some translation keys might become obsolete. Use the "**Clean**" button to identify and batch-delete keys that are no longer referenced in your source code.
+
+### 🪄 Auto-Translation
+Specify a Google Translate API Key in the settings to enable auto-translation. Use the "**Source-to-All**" button in the editor to quickly populate all languages from a single source translation.
+
+### 🪄 Normalization
+To keep your translation files organized, use the "**Normalize**" button to synchronize keys across all files and sort them alphabetically.
+
 ## Configuration
 You can optionally create a `translation.config.json` in your project root:
 ```json
@@ -34,5 +51,9 @@ To work on this repo:
 2. `cd web && npm install`
 3. `npm run dev` (starts both the API and the Vite UI)
 
+## Limitations
+- **Dynamic Keys**: The scanner uses regex to find translation keys. Highly dynamic keys (e.g. `t(someVar + '.key')` or `t(dynamicValue)`) may not be detected by the "Missing Keys" or "Unused Keys" tools.
+- **Namespaces**: Currently optimized for single-namespace or default-namespace projects.
+
 ## License
 MIT © [Tuhama](mailto:tuhama.gh.qlyshi@gmail.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuhama/translation-manager",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A modern, web-based UI for managing i18n translation files in React and other JavaScript projects.",
   "author": "Tuhama <tuhama.gh.qlyshi@gmail.com>",
   "license": "MIT",
@@ -15,7 +15,6 @@
     "translation-manager": "bin/index.js"
   },
   "files": [
-    "dist",
     "bin",
     "src",
     "web/dist",
@@ -49,6 +48,7 @@
   },
   "homepage": "https://github.com/Tuhama/translationManager#readme",
   "dependencies": {
+    "axios": "^1.14.0",
     "chokidar": "^5.0.0",
     "commander": "^14.0.3",
     "cors": "^2.8.6",

package/src/core/Scanner.js

@@ -0,0 +1,128 @@
+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;

package/src/core/Storage.js

@@ -0,0 +1,82 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Interface-like class for managing translation file storage.
+ * Defaults to JSON files on local filesystem.
+ */
+class Storage {
+    constructor(targetDir, config = {}) {
+        this.targetDir = targetDir;
+        this.config = config;
+        this.defaultPaths = [
+            'public/locales',
+            'src/locales',
+            'src/i18n',
+            'locales'
+        ];
+    }
+
+    /**
+     * Finds and returns the path to the locales directory.
+     */
+    async getLocalesDir() {
+        let localesDir = this.config.path;
+
+        if (!localesDir) {
+            for (const p of this.defaultPaths) {
+                const fullPath = path.resolve(this.targetDir, p);
+                if (await fs.pathExists(fullPath) && (await fs.stat(fullPath)).isDirectory()) {
+                    return fullPath;
+                }
+            }
+        } else {
+            localesDir = path.resolve(this.targetDir, localesDir);
+        }
+
+        if (!localesDir || !(await fs.pathExists(localesDir))) {
+            throw new Error('Could not find translation directory. Please specify it in the config or ensure it exists.');
+        }
+
+        return localesDir;
+    }
+
+    /**
+     * Reads all translation files from the locales directory.
+     */
+    async readAll() {
+        const localesDir = await this.getLocalesDir();
+        const files = await fs.readdir(localesDir);
+        const jsonFiles = files.filter(f => f.endsWith('.json'));
+
+        const translations = {};
+        for (const file of jsonFiles) {
+            const lang = path.basename(file, '.json');
+            const content = await fs.readJson(path.join(localesDir, file));
+            translations[lang] = content;
+        }
+
+        return translations;
+    }
+
+    /**
+     * Writes a single translation file (or all of them).
+     */
+    async write(lang, content) {
+        const localesDir = await this.getLocalesDir();
+        const filePath = path.join(localesDir, `${lang}.json`);
+        await fs.writeJson(filePath, content, { spaces: 2 });
+    }
+
+    /**
+     * Writes all translations.
+     */
+    async writeAll(translations) {
+        const languages = Object.keys(translations);
+        for (const lang of languages) {
+            await this.write(lang, translations[lang]);
+        }
+    }
+}
+
+module.exports = Storage;

package/src/core/TranslatorManager.js

@@ -0,0 +1,206 @@
+const lodash = require('lodash');
+const fs = require('fs-extra');
+const path = require('path');
+const Storage = require('./Storage');
+const Scanner = require('./Scanner');
+const Utilities = require('./Utilities');
+const GoogleTranslator = require('./services/GoogleTranslator');
+
+/**
+ * Main manager class for translation management.
+ * Acts as an orchestrator.
+ */
+class TranslatorManager {
+    constructor(targetDir, config = {}) {
+        this.targetDir = targetDir;
+        this.config = config;
+        this.storage = new Storage(targetDir, config);
+    }
+
+    /**
+     * Re-scans translations and sources to build a complete picture.
+     */
+    async scan() {
+        const localesDir = await this.storage.getLocalesDir();
+        const translations = await this.storage.readAll();
+        const languages = Object.keys(translations);
+
+        // Flatten all keys across all languages
+        const allKeysSet = new Set();
+        languages.forEach(lang => Utilities.flattenKeys(translations[lang], '', allKeysSet));
+        const allKeys = Array.from(allKeysSet).sort();
+
+        // Calculate results
+        const results = {};
+        allKeys.forEach(key => {
+            const missing = [];
+            languages.forEach(lang => {
+                const val = lodash.get(translations[lang], key);
+                if (val === undefined || val === '') {
+                    missing.push(lang);
+                }
+            });
+            results[key] = { missing };
+        });
+
+        // Scan source for unused and missing keys
+        const scanner = new Scanner(this.targetDir, localesDir, this.config);
+        const [analysis, missingFromFiles] = await Promise.all([
+            scanner.findUnusedKeys(allKeys),
+            scanner.findMissingKeys(allKeys)
+        ]);
+
+        return {
+            localesDir,
+            languages,
+            translations,
+            allKeys,
+            results,
+            unused: analysis.unused,
+            maybeUsed: analysis.maybeUsed,
+            missingFromFiles: missingFromFiles
+        };
+    }
+
+    /**
+     * Saves a translation key across all language files.
+     */
+    async saveTranslation(key, values) {
+        const translations = await this.storage.readAll();
+        const languages = Object.keys(translations);
+
+        for (const lang of languages) {
+            if (values[lang] !== undefined) {
+                lodash.set(translations[lang], key, values[lang]);
+                await this.storage.write(lang, translations[lang]);
+            }
+        }
+    }
+
+    /**
+     * Deletes one or more translation keys across all language files.
+     */
+    async deleteTranslations(keys) {
+        const keysToDelete = Array.isArray(keys) ? keys : [keys];
+        const translations = await this.storage.readAll();
+        const languages = Object.keys(translations);
+
+        for (const lang of languages) {
+            keysToDelete.forEach(key => lodash.unset(translations[lang], key));
+            await this.storage.write(lang, translations[lang]);
+        }
+    }
+
+    /**
+     * Normalizes and sorts everything.
+     */
+    async normalize() {
+        let translations = await this.storage.readAll();
+        const languages = Object.keys(translations);
+
+        const allKeysSet = new Set();
+        languages.forEach(lang => Utilities.flattenKeys(translations[lang], '', allKeysSet));
+        const allKeys = Array.from(allKeysSet);
+
+        // Sync and sort
+        translations = Utilities.syncKeys(translations, allKeys);
+
+        // Save back
+        await this.storage.writeAll(translations);
+    }
+
+    /**
+     * Translates a specific text into target language.
+     */
+    async translateSingle(text, targetLang, sourceLang = 'en') {
+        const translator = new GoogleTranslator(this.config.googleTranslateApiKey);
+        return await translator.translate(text, targetLang, sourceLang);
+    }
+
+    /**
+     * Gets a report of missing translations.
+     */
+    async getBulkTranslateReport(sourceLang) {
+        const { languages, translations, allKeys } = await this.scan();
+        const report = {};
+        
+        languages.forEach(lang => {
+            if (lang === sourceLang) return;
+            const missing = allKeys.filter(key => {
+                const val = lodash.get(translations[lang], key);
+                return val === undefined || val === '';
+            });
+            if (missing.length > 0) {
+                report[lang] = {
+                    count: missing.length,
+                    keys: missing
+                };
+            }
+        });
+
+        return report;
+    }
+
+    /**
+     * Performs bulk translation for all missing keys.
+     * Returns an object mapping language to key-value pairs for review.
+     */
+    async bulkTranslate(sourceLang) {
+        const report = await this.getBulkTranslateReport(sourceLang);
+        const translations = await this.storage.readAll();
+        const translator = new GoogleTranslator(this.config.googleTranslateApiKey);
+        
+        const preview = {};
+
+        for (const lang in report) {
+            const keys = report[lang].keys;
+            const sourceTexts = keys.map(key => lodash.get(translations[sourceLang], key));
+            
+            // Filter out keys that don't have source text
+            const validIndices = sourceTexts.map((text, idx) => text ? idx : null).filter(idx => idx !== null);
+            const textsToTranslate = validIndices.map(idx => sourceTexts[idx]);
+            const validKeys = validIndices.map(idx => keys[idx]);
+
+            if (textsToTranslate.length > 0) {
+                const translatedTexts = await translator.translate(textsToTranslate, lang, sourceLang);
+                preview[lang] = {};
+                validKeys.forEach((key, idx) => {
+                    preview[lang][key] = translatedTexts[idx];
+                });
+            }
+        }
+
+        return preview;
+    }
+
+    /**
+     * Saves multiple translation keys across languages.
+     * @param {Object} data - { lang: { key: value } }
+     */
+    async saveBulkTranslations(data) {
+        const translations = await this.storage.readAll();
+        const languages = Object.keys(translations);
+
+        for (const lang in data) {
+            if (languages.includes(lang)) {
+                for (const key in data[lang]) {
+                    lodash.set(translations[lang], key, data[lang][key]);
+                }
+                await this.storage.write(lang, translations[lang]);
+            }
+        }
+    }
+
+    /**
+     * Saves the current configuration to the config file.
+     */
+    async saveConfig(newConfig) {
+        this.config = { ...this.config, ...newConfig };
+        // Sync storage config if path changed
+        this.storage.config = this.config;
+        const configPath = path.resolve(this.targetDir, 'translation.config.json');
+        await fs.writeJson(configPath, this.config, { spaces: 2 });
+    }
+}
+
+module.exports = TranslatorManager;

package/src/core/Utilities.js

@@ -0,0 +1,55 @@
+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;

package/src/core/services/GoogleTranslator.js

@@ -0,0 +1,51 @@
+const axios = require('axios');
+
+/**
+ * Service for interacting with Google Cloud Translation API.
+ */
+class GoogleTranslator {
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+        this.baseUrl = 'https://translation.googleapis.com/language/translate/v2';
+    }
+
+    /**
+     * Translates text or an array of texts.
+     * @param {string|string[]} text - Text(s) to translate
+     * @param {string} targetLang - Target language code (e.g. 'fr')
+     * @param {string} sourceLang - Source language code (e.g. 'en')
+     */
+    async translate(text, targetLang, sourceLang = 'en') {
+        if (!this.apiKey) {
+            throw new Error('Google Translate API Key is missing. Please add it in Settings.');
+        }
+
+        if (!text || (Array.isArray(text) && text.length === 0)) {
+            return text;
+        }
+
+        try {
+            const response = await axios.post(
+                `${this.baseUrl}?key=${this.apiKey}`,
+                {
+                    q: text,
+                    target: targetLang,
+                    source: sourceLang,
+                    format: 'text'
+                }
+            );
+
+            const translations = response.data.data.translations;
+            
+            if (Array.isArray(text)) {
+                return translations.map(t => t.translatedText);
+            }
+            return translations[0].translatedText;
+        } catch (error) {
+            const message = error.response?.data?.error?.message || error.message;
+            throw new Error(`Google Translate Error: ${message}`);
+        }
+    }
+}
+
+module.exports = GoogleTranslator;