@scoutello/i18n-magic 0.53.0 → 0.55.0

package/README.md

@@ -2,7 +2,7 @@
 
 **The intelligent CLI toolkit that automates your internationalization workflow with AI-powered translations.**
 
-i18n Magic streamlines the entire translation management process for your JavaScript/TypeScript projects. Say goodbye to manually maintaining translation files and hello to automated, context-aware translations that keep your international users happy.
+Stop context switching. Let AI handle your translations while you stay in your code editor.
 
 ## 🚀 What it does
 
@@ -19,373 +19,343 @@ i18n Magic streamlines the entire translation management process for your JavaSc
 - Node.js 16+
 - An OpenAI or Google Gemini API key
 
-## 🛠️ Quick Setup
+## Why This Matters
 
-### 1. Install the package
+**Traditional workflow**: 40+ minutes and 13 context switches to add 10 keys across 4 languages.
 
-```bash
-npm install -g @scoutello/i18n-magic
-# or use directly with npx
-npx @scoutello/i18n-magic
-```
+**With i18n-magic + AI agents**: 2.5 minutes, zero context switches. Stay in flow.
 
-### 2. Set up your API key
+---
 
-Create a `.env` file in your project root:
+## CLI Commands
 
 ```bash
-# Choose one:
-OPENAI_API_KEY=your_openai_api_key_here
-# OR
-GEMINI_API_KEY=your_gemini_api_key_here
+npx @scoutello/i18n-magic scan          # Find & add missing translations
+npx @scoutello/i18n-magic sync          # Translate to all languages
+npx @scoutello/i18n-magic replace [key] # Update existing translation
+npx @scoutello/i18n-magic clean         # Remove unused keys
+npx @scoutello/i18n-magic check-missing # CI/CD validation
 ```
 
-### 3. Create your configuration
+**`scan`** - Scans your codebase for missing keys, prompts you for values, auto-translates to all locales.
 
-Create an `i18n-magic.js` file in your project root with your project-specific settings:
+**`sync`** - Takes your default locale translations and translates missing keys to other locales. Perfect for CI/CD.
 
-```js
-module.exports = {
-  globPatterns: [
-    './components/**/*.tsx',
-    './pages/**/*.tsx',
-    './lib/**/*.ts',
-    // Namespace-specific patterns for automatic namespace assignment
-    {
-      pattern: './apps/dashboard/**/*.tsx',
-      namespaces: ['dashboard'],
-    },
-    {
-      pattern: './apps/dashboard/**/*.ts',
-      namespaces: ['dashboard'],
-    },
-    {
-      pattern: './apps/mobile/**/*.tsx',
-      namespaces: ['mobile'],
-    },
-    {
-      pattern: './apps/mobile/**/*.ts',
-      namespaces: ['mobile'],
-    },
-  ],
-  loadPath: 'locales/{{lng}}/{{ns}}.json',
-  savePath: 'locales/{{lng}}/{{ns}}.json',
-  locales: ['en', 'de'],
-  defaultLocale: 'de',
-  defaultNamespace: 'common',
-  namespaces: ['common', 'forms', 'dashboard', 'mobile'],
-  context:
-    'This is a context which increases the quality of the translations by giving context to the LLM',
-  // Optional configurations
-  model: 'gemini-2.0-flash-lite', // or any OpenAI/Gemini model like 'gpt-4.1-mini'
-  OPENAI_API_KEY: '.', // Alternative to using .env file
-  GEMINI_API_KEY: '', // Alternative to using .env file
-  disableTranslationDuringScan: false, // Set to true to skip automatic translations during the scan step. Useful if you want to sync the other languages during CI/CD using sync.
-  autoClear: true, // When using the scan command, always run the clean before
-};
+**`replace`** - Update an existing translation key across all locales. Detects which namespaces use the key automatically.
+
+**`clean`** - Removes unused translation keys from all locales. Great for keeping files lean.
+
+**`check-missing`** - Dry-run check. Exits with error code if translations are missing. Perfect for CI pipelines.
+
+### Namespace Organization (for large apps)
+
+```javascript
+// i18n-magic.js
+globPatterns: [
+  './src/shared/**/*.tsx',              // → common.json
+  { pattern: './src/dashboard/**/*.tsx', namespaces: ['dashboard'] },
+  { pattern: './src/mobile/**/*.tsx', namespaces: ['mobile'] }
+]
 ```
 
-#### Glob Patterns Configuration
+Result: Separate files per feature (`common.json`, `dashboard.json`, `mobile.json`) across all locales.
 
-The `globPatterns` array supports two formats:
+---
 
-1. **String patterns**: Simple glob patterns that apply to all namespaces
+## The MCP Server: AI Superpowers
 
-   ```js
-   './components/**/*.tsx';
-   ```
+**MCP (Model Context Protocol)** = API for AI agents.
 
-2. **Object patterns**: Patterns with namespace-specific configuration for automatic namespace assignment
-   ```js
-   {
-     pattern: './apps/dashboard/**/*.tsx',
-     namespaces: ['dashboard']
-   }
-   ```
+Install the i18n-magic MCP server in Cursor, and your AI gets 5 new tools:
 
-When using object patterns, translation keys found in files matching that pattern will be automatically saved to the specified namespaces. This enables automatic creation of namespace-specific translation files based on where the keys are used in your codebase.
+### 1. `search_translations` - Prevent Duplicates
+Fuzzy search across all translations. AI searches before adding anything.
 
-### 4. Start using i18n Magic
+### 2. `add_translation_key` - Add New Keys  
+Adds key to English (`en`) locale. Run `sync` afterward to translate to other languages.
 
-```bash
-# Scan for missing translations and add them
-npx @scoutello/i18n-magic scan
+### 3. `get_translation_key` - Check What Exists
+Retrieve current value for any key.
 
-# Check what's missing without making changes
-npx @scoutello/i18n-magic check-missing
+### 4. `update_translation_key` - Fix & Auto-Translate
+Update a key and **instantly translate to all languages**. No sync needed!
 
-# Sync all locales from your default language
-npx @scoutello/i18n-magic sync
-```
+### 5. `list_untranslated_keys` - Batch Check
+Show all missing keys across your codebase.
 
-## 🔧 Advanced Configuration
+---
 
-### Custom Storage Solutions
+## Quick Setup (5 Minutes)
 
-You can provide custom functions for `loadPath` and `savePath` to store translations in other systems like S3, databases, or CDNs:
+### 1. Install
 
-```js
-const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3")
+```bash
+npm install @scoutello/i18n-magic
+```
 
-const s3Client = new S3Client({
-  region: process.env.S3_REGION,
-  credentials: {
-    accessKeyId: process.env.S3_ACCESS_KEY,
-    secretAccessKey: process.env.S3_SECRET_KEY,
-  },
-})
+### 2. Create `i18n-magic.js` in project root
 
+```javascript
 module.exports = {
-  ...
-  // Custom load function
-  loadPath: async (locale, namespace) => {
-    // Example: Load from S3
-    const response = await s3Client.send(
-      new GetObjectCommand({
-        Bucket: 'my-translations-bucket',
-        Key: `locales/${locale}/${namespace}.json`,
-      })
-    );
-    const data = await response.Body.transformToString();
-    return JSON.parse(data);
-  },
-
-  // Custom save function
-  savePath: async (locale, namespace, data) => {
-    // Example: Save to S3
-    await s3Client.send(
-      new PutObjectCommand({
-        Bucket: 'my-translations-bucket',
-        Key: `locales/${locale}/${namespace}.json`,
-        Body: JSON.stringify(data, null, 2),
-        ContentType: 'application/json',
-      })
-    );
-  },
-};
+  globPatterns: ['./src/**/*.{ts,tsx,js,jsx}'],
+  loadPath: 'locales/{{lng}}/{{ns}}.json',
+  savePath: 'locales/{{lng}}/{{ns}}.json',
+  locales: ['en', 'de', 'es', 'fr'],
+  defaultLocale: 'en',
+  namespaces: ['common'],
+  defaultNamespace: 'common',
+  context: 'Your app description here',
+  model: 'gpt-4o-mini', // or 'gemini-2.0-flash-lite'
+  
+  // Optional: Auto-clean before scanning
+  autoClear: true,
+  
+  // Optional: Skip translation during scan (translate later with sync)
+  disableTranslationDuringScan: false,
+}
 ```
 
-## 📚 Available Commands
+**Key options**:
+- `context`: Describe your app/domain. Better context = better translations.
+- `autoClear`: Auto-remove unused keys before scanning.
+- `disableTranslationDuringScan`: Set `true` to only add English during scan, then use `sync` command for translations.
 
-All commands can be run with:
+### 3. Add API key to `.env`
 
 ```bash
-npx @scoutello/i18n-magic [command]
+OPENAI_API_KEY=sk-your-key-here
 ```
 
-### `scan`
+### 4. Configure MCP in Cursor
+
+Settings → Features → Model Context Protocol:
 
-Scan your codebase for missing translations and automatically generate them. This command analyzes your code to find translation keys that don't exist in your translation files yet.
+```json
+{
+  "i18n-magic": {
+    "command": "node",
+    "args": ["./node_modules/@scoutello/i18n-magic/dist/mcp-server.js"]
+  }
+}
+```
 
-The command will:
+### 5. Restart Cursor
 
-1. Scan all files matching your glob patterns for translation usage
-2. Automatically determine which namespaces each key belongs to based on the file location
-3. Identify missing translation keys in your default locale
-4. Prompt you to provide translations for each missing key
-5. Automatically translate to all other configured locales using AI
-6. Save the new translations to the appropriate namespace files
+Done! Test by asking: *"Search for translations with 'password'"*
 
-This is useful for:
+---
 
-- Adding new translations during development
-- Ensuring all translation keys have corresponding values
-- Maintaining translation consistency across locales
-- Automatically organizing translations into the correct namespaces
+## How to Use It
 
-### `replace`
+### Pattern 1: Adding Translations (Search First!)
 
-Update an existing translation key with a new value and automatically translate it to all other locales. This command allows you to modify existing translations while maintaining consistency across all languages.
+**You**: "Add a submit button"
 
-The command will:
+**AI**:
+1. Searches existing translations for "submit"
+2. Finds `submitButton: "Submit"` already exists
+3. Suggests reusing it
+4. Generates: `<Button>{t('submitButton')}</Button>`
 
-1. Automatically detect which namespaces the key is used in based on your codebase
-2. Prompt you to select or specify the translation key to replace
-3. Ask for the new translation value in your default locale
-4. Automatically translate the new value to all other configured locales using AI
-5. Update all relevant namespace files with the new values
+**Result**: No duplicate keys, instant code.
 
-You can specify the key in two ways:
+If nothing exists:
+- AI adds key to English: `add_translation_key`
+- You run: `npx @scoutello/i18n-magic sync`
+- Translated to all languages!
 
-- As a positional argument: `npx @scoutello/i18n-magic replace your.translation.key`
-- Using the option flag: `npx @scoutello/i18n-magic replace --key your.translation.key`
+### Pattern 2: Updating Translations
 
-If no key is provided, you will be prompted to enter one.
+**You**: "Change welcome message to 'Welcome back!'"
 
-This is useful for:
+**AI**:
+1. Finds the key via search
+2. Calls `update_translation_key`
+3. **Auto-translates to ALL languages instantly**
 
-- Updating existing translations that need changes
-- Fixing translation errors across all locales
-- Maintaining consistency when modifying content
-- Automatically updating translations in all relevant namespaces
+No sync needed!
 
-### `check-missing`
+### Pattern 3: Batch Check
 
-Check if there are any missing translations without making any changes. This command performs a dry-run analysis to identify translation gaps in your project.
+**You**: "What translations are missing?"
 
-The command will:
+**AI**: Calls `list_untranslated_keys`, shows you the list.
 
-1. Scan all files matching your glob patterns for translation usage
-2. Check if all found translation keys exist in your translation files
-3. Report any missing translations without prompting for input
-4. Exit with an error code if missing translations are found
+Add them now or during development. Your choice.
 
-This is useful for:
+---
 
-- CI/CD pipelines to ensure translation completeness
-- Pre-commit hooks to catch missing translations early
-- Quality assurance checks before deployment
-- Automated testing of translation coverage
+## Real Example
 
-### `sync`
+Building a UserProfile component:
 
-Synchronize translations from your default locale to all other configured locales using AI translation. This command takes existing translations in your default language and generates corresponding translations for all other locales.
+**You**: "Replace 'User Profile' with translation"
 
-The command will:
+**AI**:
+- Searches for "user profile"
+- Nothing found
+- Adds: `profile.title: "User Profile"` to en/dashboard.json
+- Updates code: `<h1>{t('profile.title')}</h1>`
 
-1. Load all translation keys from your default locale
-2. Identify keys that are missing in other locales
-3. Automatically translate missing keys using AI
-4. Update translation files for all non-default locales
-5. Preserve existing translations (only adds missing ones)
+**You**: "Add translations for labels"
 
-This is useful for:
+**AI**:
+- Searches "email" → finds `emailLabel` in common
+- Reuses existing key (no duplicate!)
+- Searches "full name" → nothing found
+- Adds new: `profile.fullNameLabel: "Full Name"`
 
-- CI/CD pipelines to ensure all locales are up-to-date
-- Batch translation of new content
-- Maintaining translation parity across languages
-- Automated deployment workflows
+**You run**:
+```bash
+npx @scoutello/i18n-magic sync
+```
 
-**Note**: This command works best when used with `disableTranslationDuringScan: true` in your config to separate the scanning and translation phases. The sync command will always translate regardless of this setting.
+**Result**: All keys now in EN, DE, ES, FR. Took 2 minutes.
 
-### `clean`
+Later: **"Change title to 'Your Profile'"**
 
-Remove unused translation keys from all locales. This command scans your codebase to find which translation keys are actually being used and removes any keys that are no longer referenced in your code.
+**AI**: Calls `update_translation_key` → instantly updated in all 4 languages. No sync needed!
 
-The command will:
+---
 
-1. Scan all files matching your glob patterns for translation usage
-2. Compare found keys with existing translation files
-3. Remove unused keys from all locale files
-4. Report how many keys were removed
+## Pro Tips
 
-This is useful for:
+### Better Translations with Context
 
-- Keeping translation files clean and maintainable
-- Reducing bundle size by removing dead translations
-- Regular maintenance in CI/CD pipelines
+```javascript
+// Generic → Okay
+context: 'Web application'
 
-## 🔌 MCP Server Integration
+// Specific → Much better!
+context: 'E-commerce for outdoor gear. Friendly tone. Target: adventurers.'
+```
 
-i18n Magic includes an MCP (Model Context Protocol) server that allows LLMs like Cursor to add missing translation keys directly to your translation files. This enables a seamless workflow where your AI assistant can identify and add missing translations while you code.
+More context = better AI translations.
 
-### Setting up the MCP Server
+### CI/CD: Auto-translate on PR
 
-1. **Install i18n-magic** (if not already installed):
+```yaml
+# .github/workflows/auto-translate.yml
+on:
+  pull_request:
+    paths: ['locales/en/**/*.json']
 
-```bash
-npm install -g @scoutello/i18n-magic
-# or locally in your project
-npm install @scoutello/i18n-magic
+jobs:
+  translate:
+    steps:
+      - run: npx @scoutello/i18n-magic sync
+      - run: git commit -am "chore: auto-translate"
 ```
 
-2. **Configure Cursor** (or other MCP-compatible tools):
+English changes → auto-translated → committed. Zero manual work.
 
-Open Cursor settings and add this to your MCP configuration:
+### Namespace Strategy
 
-**For global installation:**
-```json
-{
-  "i18n-magic": {
-    "command": "i18n-magic-mcp",
-    "cwd": "/absolute/path/to/your/project"
+- **<100 keys**: Single `common.json`
+- **100-500 keys**: Split by feature (`auth`, `dashboard`)  
+- **500+ keys**: Feature-based with auto-assignment (see setup section)
+
+### Custom Storage Solutions
+
+Store translations anywhere (S3, databases, CDNs):
+
+```javascript
+// Example: S3 storage
+const { S3Client, GetObjectCommand, PutObjectCommand } = require('@aws-sdk/client-s3')
+
+const s3Client = new S3Client({
+  region: process.env.S3_REGION,
+  credentials: {
+    accessKeyId: process.env.S3_ACCESS_KEY,
+    secretAccessKey: process.env.S3_SECRET_KEY,
   }
+})
+
+module.exports = {
+  loadPath: async (locale, namespace) => {
+    const response = await s3Client.send(
+      new GetObjectCommand({
+        Bucket: 'my-translations-bucket',
+        Key: `locales/${locale}/${namespace}.json`,
+      })
+    )
+    const data = await response.Body.transformToString()
+    return JSON.parse(data)
+  },
+  
+  savePath: async (locale, namespace, data) => {
+    await s3Client.send(
+      new PutObjectCommand({
+        Bucket: 'my-translations-bucket',
+        Key: `locales/${locale}/${namespace}.json`,
+        Body: JSON.stringify(data, null, 2),
+        ContentType: 'application/json',
+      })
+    )
+  },
+  // ... other config
 }
 ```
 
-**For local installation:**
+---
+
+## Troubleshooting
+
+### MCP Connection Error
+
+**Error**: `MCP error -32000: Connection closed`
+
+**Fix**: Use auto-detection (no `cwd` needed):
 ```json
 {
   "i18n-magic": {
     "command": "node",
-    "args": ["./node_modules/@scoutello/i18n-magic/dist/mcp-server.js"],
-    "cwd": "/absolute/path/to/your/project"
+    "args": ["./node_modules/@scoutello/i18n-magic/dist/mcp-server.js"]
   }
 }
 ```
 
-**⚠️ CRITICAL Configuration**: 
-- Replace `/absolute/path/to/your/project` with **YOUR PROJECT DIRECTORY** containing `i18n-magic.js`
-- **DO NOT** use the i18n-magic package directory - use where YOU use translations
-- The `cwd` parameter must be an absolute path
-- If you get "Connection closed" error, verify your `cwd` points to the correct directory
-
-### Troubleshooting MCP Setup
-
-**Error: "MCP error -32000: Connection closed"**
-
-This means the server couldn't find your configuration. Check:
-
-1. ✅ `cwd` points to YOUR project directory (not the i18n-magic package)
-2. ✅ `i18n-magic.js` exists in that directory
-3. ✅ Paths are absolute
-
-Test your setup:
+**Still broken?** Check `i18n-magic.js` exists in project root:
 ```bash
-# Navigate to your project
-cd /your/project/path
-
-# Verify config exists
 ls -la i18n-magic.js
-
-# Test the MCP server manually
-node ./node_modules/@scoutello/i18n-magic/dist/mcp-server.js
 ```
 
-You should see: `[i18n-magic MCP] Server started and ready to accept connections`
+### Translations Not Working
 
-### How it works
+**Problem**: Keys added but not translated.
+
+**Fix**: Run sync!
+```bash
+npx @scoutello/i18n-magic sync
+```
 
-**Workflow 1: Adding individual keys**
-1. While coding, the LLM identifies a missing translation key
-2. The LLM calls the `add_translation_key` tool to add it with an English value
-3. The key is automatically added to the `en` locale (regardless of your `defaultLocale`)
-4. Run `i18n-magic sync` to translate the key to all other configured locales
+`add_translation_key` only adds English. `sync` translates to other languages.
 
-**Workflow 2: Batch checking missing keys**
-1. The LLM calls `list_untranslated_keys` to get a complete overview
-2. Review all missing keys grouped by namespace
-3. Add keys using `add_translation_key` or run `i18n-magic scan` for batch processing
-4. Run `i18n-magic sync` to translate all new keys
+### MCP Tools Not Appearing
 
-### Available MCP Tools
+1. Restart Cursor after adding MCP config
+2. Check Settings → Features → MCP shows "i18n-magic" as Connected
+3. Test: Ask AI to *"search translations for 'password'"*
 
-**add_translation_key**: Add a new translation key with an English value
+---
 
-Parameters:
-- `key` (required): The translation key (e.g., "welcomeMessage")
-- `value` (required): The English text value
-- `namespace` (optional): Target namespace (defaults to your defaultNamespace)
+## Get Started Now
 
-Example:
-```json
-{
-  "key": "user.profileUpdated",
-  "value": "Your profile has been updated successfully",
-  "namespace": "common"
-}
-```
+1. `npm install @scoutello/i18n-magic`
+2. Create `i18n-magic.js` config (see setup section)
+3. Add `OPENAI_API_KEY` to `.env`
+4. Configure MCP in Cursor
+5. Start coding. AI handles translations.
 
-**list_untranslated_keys**: List all translation keys used in the codebase that are not yet defined
+**5 minutes to set up. Hours saved every week.**
 
-Parameters:
-- `namespace` (optional): Check a specific namespace only (defaults to all namespaces)
+### Links
 
-Example:
-```json
-{}
-```
+- **MCP Details**: [MCP-SERVER.md](./MCP-SERVER.md)
+- **Example App**: [example-app/](./example-app/)
+- **GitHub**: [github.com/BjoernRave/i18n-magic](https://github.com/BjoernRave/i18n-magic)
+- **NPM**: [@scoutello/i18n-magic](https://www.npmjs.com/package/@scoutello/i18n-magic)
 
-Response shows all missing keys grouped by namespace with counts and next steps.
+---
 
-For detailed setup instructions and troubleshooting, see [MCP-SERVER.md](./MCP-SERVER.md).
+*Never context switch for translations again. 🌍*

package/dist/lib/utils.d.ts

@@ -59,13 +59,41 @@ export declare class TranslationError extends Error {
     constructor(message: string, locale?: string, namespace?: string, cause?: Error);
 }
 /**
- * Add a translation key with an English value to the locale files.
- * This function always adds to the "en" locale, and if the defaultLocale is different,
- * it will also translate and save to the defaultLocale right away.
+ * Add a translation key with a value in a specific language to the locale files.
+ * This function adds to the specified language locale, and will also translate
+ * and save to other locales if OpenAI is configured.
  */
-export declare const addTranslationKey: ({ key, value, config, }: {
+/**
+ * Add multiple translation keys in batch. This is optimized for performance:
+ * - Single codebase scan for all keys
+ * - Batched file I/O operations
+ * - Batched translations per locale
+ */
+export declare const addTranslationKeys: ({ keys, config, }: {
+    keys: Array<{
+        key: string;
+        value: string;
+        language?: string;
+    }>;
+    config: Configuration;
+}) => Promise<{
+    results: {
+        key: string;
+        value: string;
+        namespace: string;
+        locale: string;
+    }[];
+    performance: {
+        totalTime: number;
+        scanTime: number;
+        translationTime: number;
+        fileIOTime: number;
+    };
+}>;
+export declare const addTranslationKey: ({ key, value, language, config, }: {
     key: string;
     value: string;
+    language?: string;
     config: Configuration;
 }) => Promise<{
     key: string;