@tuhama/translation-manager 0.6.1 → 0.7.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Tuhama
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Tuhama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,14 +1,19 @@
 # Translation Manager UI 🌍
 
-A modern, web-based interface for managing i18n translation files in React and other JavaScript projects.
+A modern, web-based interface for managing i18n translation files in React and other JavaScript projects. Now with **AI-Friendly** features and an **AI Skill File** to make localization faster and more accurate.
+
+> [!TIP]
+> This project is **AI-Ready**. AI agents can use the included `translations.skill` to automatically audit and manage your translations.
 
 ## Features
 - **Modern UI**: Dark mode, glassmorphism, and smooth animations.
-- **Auto-Translation**: Integrated Google Translate support for single-key and bulk translations.
+- **AI-Powered Translation**: Support for **OpenAI (GPT-4o)**, **Google Gemini**, and Google Cloud Translate.
+- **Context-Aware Scanning**: Extracts code snippets where translation keys are used, providing crucial context for AI 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.
+- **Export/Import**: Export all missing translations to an **AI-Friendly** JSON file (including code context) for external translation.
+- **CLI Status**: Machine-readable JSON output for project health monitoring.
 - **Tree View**: Easy navigation and management of translation keys.
 - **Zero Config**: Auto-detects common locales folders.
 
@@ -24,25 +29,41 @@ 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.
+### 🤖 AI-Friendly Localization
+The manager now extracts the **surrounding code** for every translation key it finds. This context is passed to AI models (like OpenAI or Gemini) to ensure highly accurate translations that respect your code's intent.
 
-### 🧹 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.
+### 📤📥 Export/Import (AI-Enhanced)
+You can export all missing translation keys to a single JSON file. This export is **AI-Ready**, containing code snippets for each key so you can feed it to an LLM for context-aware translations.
 
-### 🪄 Auto-Translation
-Configure Google Cloud Translation API 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. 
+### 📊 CLI Status
+Check your translation coverage programmatically:
+```bash
+npx @tuhama/translation-manager status
+```
+Outputs a machine-readable JSON summary of missing keys, coverage percentage, and project health.
 
-**Recommended Setup:**
-1. Install Google Cloud CLI: `gcloud auth application-default login`
-2. Add your Google Cloud Project ID in Settings
-3. Start translating!
+### ⚠️ 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.
 
-### 🪄 Normalization
-To keep your translation files organized, use the "**Normalize**" button to synchronize keys across all files and sort them alphabetically.
+### 🪄 Auto-Translation
+Configure Google Cloud, OpenAI, or Gemini in the settings to enable auto-translation. Use the "**Source-to-All**" button in the editor to quickly populate all languages.
 
 ## Configuration
 You can optionally create a `translation.config.json` in your project root:
+
+### Using OpenAI (Recommended for AI Quality)
+```json
+{
+  "path": "src/locales",
+  "aiTranslate": {
+    "provider": "openai",
+    "apiKey": "your-openai-api-key",
+    "model": "gpt-4o"
+  }
+}
+```
+
+### Using Google Cloud Translate
 ```json
 {
   "path": "src/locales",
@@ -52,11 +73,6 @@ You can optionally create a `translation.config.json` in your project root:
 }
 ```
 
-**Authentication Options:**
-- **Recommended**: Use Google Cloud CLI (`gcloud auth application-default login`)
-- **Alternative**: Specify `keyFilename` path to service account JSON file
-- **Environment**: Set `GOOGLE_APPLICATION_CREDENTIALS` environment variable
-
 ## Development
 To work on this repo:
 1. `npm install`
@@ -64,7 +80,7 @@ To work on this repo:
 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.
+- **Dynamic Keys**: Highly dynamic keys (e.g. `t(someVar + '.key')`) may not be detected by the "Missing Keys" tool.
 - **Namespaces**: Currently optimized for single-namespace or default-namespace projects.
 
 ## License

package/bin/index.js

@@ -1,45 +1,87 @@
-#!/usr/bin/env node
-
-const { program } = require('commander');
-const path = require('path');
-const fs = require('fs-extra');
-const { startServer } = require('../src/server');
-const open = (...args) => import('open').then(m => m.default(...args));
-
-program
-    .version('0.1.0')
-    .description('Translation Manager CLI - Manage your React translations with a modern UI')
-    .option('-p, --port <number>', 'Port to run the UI on', 3000)
-    .option('-c, --config <path>', 'Path to config file')
-    .action(async (options) => {
-        const targetDir = process.cwd();
-        let config = {};
-
-        // Load config from file
-        const configPath = options.config || 'translation.config.json';
-        const absoluteConfigPath = path.resolve(targetDir, configPath);
-
-        if (await fs.pathExists(absoluteConfigPath)) {
-            config = await fs.readJson(absoluteConfigPath);
-        } else {
-            // Check for JS config
-            const jsConfigPath = path.resolve(targetDir, 'translation.config.js');
-            if (await fs.pathExists(jsConfigPath)) {
-                config = require(jsConfigPath);
-            }
-        }
-
-        console.log('\x1b[36mℹ\x1b[0m Starting Translation Manager...');
-        
-        try {
-            startServer(targetDir, options.port, config);
-            
-            // Open the browser
-            await open(`http://localhost:${options.port}`);
-        } catch (err) {
-            console.error('\x1b[31m✖\x1b[0m Error:', err.message);
-            process.exit(1);
-        }
-    });
-
-program.parse(process.argv);
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const path = require('path');
+const fs = require('fs-extra');
+const { startServer } = require('../src/server');
+const open = (...args) => import('open').then(m => m.default(...args));
+
+program
+    .version('0.1.0')
+    .description('Translation Manager CLI - Manage your React translations with a modern UI')
+    .option('-p, --port <number>', 'Port to run the UI on', 3000)
+    .option('-c, --config <path>', 'Path to config file')
+    .action(async (options) => {
+        const targetDir = process.cwd();
+        let config = await loadConfig(targetDir, options.config);
+
+        console.log('\x1b[36mℹ\x1b[0m Starting Translation Manager...');
+        
+        try {
+            startServer(targetDir, options.port, config);
+            
+            // Open the browser
+            await open(`http://localhost:${options.port}`);
+        } catch (err) {
+            console.error('\x1b[31m✖\x1b[0m Error:', err.message);
+            process.exit(1);
+        }
+    });
+
+program
+    .command('status')
+    .description('Get translation status in JSON format')
+    .option('-c, --config <path>', 'Path to config file')
+    .action(async (options) => {
+        const targetDir = process.cwd();
+        const config = await loadConfig(targetDir, options.config);
+        const TranslatorManager = require('../src/core/TranslatorManager');
+        const manager = new TranslatorManager(targetDir, config);
+
+        try {
+            const data = await manager.scan();
+            const status = {
+                languages: data.languages,
+                totalKeys: data.allKeys.length,
+                missingKeysFromCode: data.missingFromFiles.length,
+                unusedKeys: data.unused.length,
+                maybeUsedKeys: data.maybeUsed.length,
+                coverage: {}
+            };
+
+            data.languages.forEach(lang => {
+                const untranslated = data.allKeys.filter(key => {
+                    const val = require('lodash').get(data.translations[lang], key);
+                    return val === undefined || val === '';
+                }).length;
+                
+                status.coverage[lang] = {
+                    translated: data.allKeys.length - untranslated,
+                    total: data.allKeys.length,
+                    percentage: Math.round(((data.allKeys.length - untranslated) / data.allKeys.length) * 100)
+                };
+            });
+
+            console.log(JSON.stringify(status, null, 2));
+        } catch (err) {
+            console.error(JSON.stringify({ error: err.message }, null, 2));
+            process.exit(1);
+        }
+    });
+
+async function loadConfig(targetDir, configPath) {
+    let config = {};
+    const absoluteConfigPath = path.resolve(targetDir, configPath || 'translation.config.json');
+
+    if (await fs.pathExists(absoluteConfigPath)) {
+        config = await fs.readJson(absoluteConfigPath);
+    } else {
+        const jsConfigPath = path.resolve(targetDir, 'translation.config.js');
+        if (await fs.pathExists(jsConfigPath)) {
+            config = require(jsConfigPath);
+        }
+    }
+    return config;
+}
+
+program.parse(process.argv);

package/package.json

@@ -1,66 +1,76 @@
-{
-  "name": "@tuhama/translation-manager",
-  "version": "0.6.1",
-  "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",
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "main": "src/server.js",
-  "bin": {
-    "translation-manager": "bin/index.js"
-  },
-  "files": [
-    "bin",
-    "src",
-    "web/dist",
-    "README.md",
-    "package.json"
-  ],
-  "scripts": {
-    "dev": "concurrently \"npm run dev-server\" \"npm run dev-web\"",
-    "dev-server": "nodemon bin/index.js",
-    "dev-web": "cd web && npm run dev",
-    "build": "cd web && npm run build",
-    "start": "node bin/index.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Tuhama/translationManager.git"
-  },
-  "keywords": [
-    "translation",
-    "i18n",
-    "localization",
-    "l10n",
-    "react",
-    "ui",
-    "cli",
-    "translation-manager",
-    "internationalization"
-  ],
-  "bugs": {
-    "url": "https://github.com/Tuhama/translationManager/issues"
-  },
-  "homepage": "https://github.com/Tuhama/translationManager#readme",
-  "dependencies": {
-    "@google-cloud/translate": "^8.0.0",
-    "chokidar": "^5.0.0",
-    "commander": "^14.0.3",
-    "cors": "^2.8.6",
-    "express": "^5.2.1",
-    "express-history-api-fallback": "^2.2.1",
-    "fs-extra": "^11.3.4",
-    "lodash": "^4.17.23",
-    "open": "^11.0.0",
-    "picocolors": "^1.1.1"
-  },
-  "devDependencies": {
-    "concurrently": "^9.2.1",
-    "nodemon": "^3.1.14"
-  }
-}
+{
+  "name": "@tuhama/translation-manager",
+  "version": "0.7.1",
+  "description": "AI-powered i18n management with context-aware scanning and support for OpenAI, Gemini, and Google Translate.",
+  "author": "Tuhama <tuhama.gh.qlyshi@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "src/server.js",
+  "bin": {
+    "translation-manager": "bin/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "web/dist",
+    "README.md",
+    "package.json",
+    "translations.skill"
+  ],
+  "scripts": {
+    "dev": "concurrently \"npm run dev-server\" \"npm run dev-web\"",
+    "dev-server": "nodemon bin/index.js",
+    "dev-web": "cd web && npm run dev",
+    "build": "cd web && npm run build",
+    "start": "node bin/index.js",
+    "test": "vitest run",
+    "test:web": "cd web && npx vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tuhama/translationManager.git"
+  },
+  "keywords": [
+    "translation",
+    "i18n",
+    "localization",
+    "l10n",
+    "react",
+    "ui",
+    "cli",
+    "translation-manager",
+    "internationalization",
+    "ai",
+    "openai",
+    "gemini",
+    "context-aware",
+    "automation"
+  ],
+  "bugs": {
+    "url": "https://github.com/Tuhama/translationManager/issues"
+  },
+  "homepage": "https://github.com/Tuhama/translationManager#readme",
+  "dependencies": {
+    "@google-cloud/translate": "^8.0.0",
+    "chokidar": "^5.0.0",
+    "commander": "^14.0.3",
+    "cors": "^2.8.6",
+    "express": "^5.2.1",
+    "express-history-api-fallback": "^2.2.1",
+    "fs-extra": "^11.3.4",
+    "lodash": "^4.17.23",
+    "open": "^11.0.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@vitest/ui": "^4.1.4",
+    "concurrently": "^9.2.1",
+    "nodemon": "^3.1.14",
+    "vitest": "^4.1.4"
+  }
+}