i18n-tools-mcp 1.0.1 → 1.0.3

package/README.md

@@ -1,3 +1,5 @@
+![i18n-tools-mcp by Trivle — Translation files. Agent-ready.](./i18n-tools-mcp-og.png)
+
 # i18n-tools-mcp
 
 MCP server for querying and managing JSON translation files. Designed for AI agents (Claude Code, Cursor, etc.) to read and write i18n, i18next, react-i18next, and next-i18next translations directly through the Model Context Protocol.
@@ -130,6 +132,26 @@ Search translations by value (case-insensitive).
 
 Find translation keys that exist in some locales but are missing in others. Takes no parameters.
 
+### `batch`
+
+Apply multiple mutations in a single call. Each affected locale file is read once, mutated in memory, and written exactly once — regardless of how many ops touch it. Per-file atomic: if any op fails, no files are written.
+
+Prefer this over repeated `set`/`add`/`delete`/`rename`/`move` calls for bulk changes. It minimizes file-watcher churn (Next.js dev, Vite HMR) and avoids partial writes.
+
+| Parameter | Type      | Required | Description                                  |
+|-----------|-----------|----------|----------------------------------------------|
+| `ops`     | `BatchOp[]` | yes    | Ordered list of operations (see below)       |
+
+Each op is one of:
+
+```jsonc
+{ "op": "set",    "locale": "en", "key": "Users.name", "value": "Name" }
+{ "op": "add",    "key": "Users.email", "translations": { "nl": "E-mail", "en": "Email" } }
+{ "op": "delete", "key": "Users.legacy" }
+{ "op": "rename", "oldKey": "Users.name", "newKey": "Users.fullName" }
+{ "op": "move",   "oldKey": "Users.name", "newKey": "Profile.name" }
+```
+
 ## Development
 
 ```bash

package/dist/index.js

@@ -2,7 +2,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { query, set, add, remove, rename, missing, list, search, move, setIndent } from './translations.js';
+import { query, set, add, remove, rename, missing, list, search, move, batch, setIndent } from './translations.js';
 const baseDir = process.argv[2];
 if (!baseDir) {
     console.error('Usage: i18n-tools-mcp <translations-directory> [base-locale] [indent]');
@@ -148,6 +148,47 @@ server.registerTool('move', {
         return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
     }
 });
+const batchOpSchema = z.discriminatedUnion('op', [
+    z.object({
+        op: z.literal('set'),
+        locale: z.string(),
+        key: z.string(),
+        value: z.string(),
+    }),
+    z.object({
+        op: z.literal('add'),
+        key: z.string(),
+        translations: z.record(z.string(), z.string()),
+    }),
+    z.object({
+        op: z.literal('delete'),
+        key: z.string(),
+    }),
+    z.object({
+        op: z.literal('rename'),
+        oldKey: z.string(),
+        newKey: z.string(),
+    }),
+    z.object({
+        op: z.literal('move'),
+        oldKey: z.string(),
+        newKey: z.string(),
+    }),
+]);
+server.registerTool('batch', {
+    description: `Apply multiple translation mutations in a single call. Each affected locale file is written exactly once, regardless of how many ops touch it. Prefer this over repeated set/add/delete/rename/move calls when making bulk changes — it minimizes file-watcher churn (Next.js dev, etc.) and is atomic per-file: if any op fails, no files are written. Always include the base locale "${baseLocale}" in add ops.`,
+    inputSchema: {
+        ops: z.array(batchOpSchema).describe('Ordered list of operations. Each op is one of: {op:"set", locale, key, value}, {op:"add", key, translations}, {op:"delete", key}, {op:"rename", oldKey, newKey}, {op:"move", oldKey, newKey}.'),
+    },
+}, async ({ ops }) => {
+    try {
+        const result = batch(ops, baseDir);
+        return { content: [{ type: 'text', text: result }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
+    }
+});
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/translations.d.ts

@@ -8,3 +8,25 @@ export declare function missing(dir?: string): string;
 export declare function list(prefix?: string, page?: number, pageSize?: number, dir?: string): string;
 export declare function search(value: string, page?: number, pageSize?: number, dir?: string): string;
 export declare function move(oldKey: string, newKey: string, dir?: string): string;
+export type BatchOp = {
+    op: 'set';
+    locale: string;
+    key: string;
+    value: string;
+} | {
+    op: 'add';
+    key: string;
+    translations: Record<string, string>;
+} | {
+    op: 'delete';
+    key: string;
+} | {
+    op: 'rename';
+    oldKey: string;
+    newKey: string;
+} | {
+    op: 'move';
+    oldKey: string;
+    newKey: string;
+};
+export declare function batch(ops: BatchOp[], dir?: string): string;

package/dist/translations.js

@@ -341,3 +341,116 @@ export function search(value, page = 1, pageSize = 100, dir) {
 export function move(oldKey, newKey, dir) {
     return rename(oldKey, newKey, dir).replace('Renamed', 'Moved');
 }
+export function batch(ops, dir) {
+    const resolvedDir = dir || DEFAULT_DIR;
+    const localeFiles = discoverLocaleFiles(resolvedDir);
+    const cache = new Map();
+    const dirty = new Set();
+    const load = (file) => {
+        if (!cache.has(file.path)) {
+            cache.set(file.path, readJson(file.path));
+        }
+        return cache.get(file.path);
+    };
+    const summary = [];
+    for (let i = 0; i < ops.length; i++) {
+        const op = ops[i];
+        try {
+            switch (op.op) {
+                case 'set': {
+                    const { namespace, dotKey } = parseKey(op.key);
+                    if (isNamespaced(localeFiles) && !namespace) {
+                        throw new Error(`Namespace required in namespace mode. Use "namespace:${op.key}" format.`);
+                    }
+                    const file = findLocaleFile(localeFiles, op.locale, namespace);
+                    if (!file) {
+                        const target = namespace ? `${op.locale}/${namespace}` : op.locale;
+                        throw new Error(`Locale "${target}" not found in ${resolvedDir}`);
+                    }
+                    setNestedValue(load(file), dotKey, sanitize(op.value));
+                    dirty.add(file.path);
+                    summary.push(`set ${op.locale}.${op.key}`);
+                    break;
+                }
+                case 'add': {
+                    const { namespace, dotKey } = parseKey(op.key);
+                    if (isNamespaced(localeFiles) && !namespace) {
+                        throw new Error(`Namespace required in namespace mode. Use "namespace:${op.key}" format.`);
+                    }
+                    const updated = [];
+                    const skipped = [];
+                    for (const [locale, value] of Object.entries(op.translations)) {
+                        const file = findLocaleFile(localeFiles, locale, namespace);
+                        if (!file) {
+                            skipped.push(locale);
+                            continue;
+                        }
+                        setNestedValue(load(file), dotKey, sanitize(value));
+                        dirty.add(file.path);
+                        updated.push(locale);
+                    }
+                    if (updated.length === 0) {
+                        throw new Error(`No locales updated for "${op.key}"`);
+                    }
+                    const skipNote = skipped.length > 0 ? ` (skipped: ${skipped.join(', ')})` : '';
+                    summary.push(`add ${op.key} → ${updated.join(', ')}${skipNote}`);
+                    break;
+                }
+                case 'delete': {
+                    const { namespace, dotKey } = parseKey(op.key);
+                    const filesToSearch = filterFiles(localeFiles, namespace);
+                    const deleted = [];
+                    for (const file of filesToSearch) {
+                        const data = load(file);
+                        if (deleteNestedValue(data, dotKey)) {
+                            dirty.add(file.path);
+                            deleted.push(file.locale);
+                        }
+                    }
+                    summary.push(deleted.length > 0
+                        ? `delete ${op.key} → ${deleted.join(', ')}`
+                        : `delete ${op.key} → not found`);
+                    break;
+                }
+                case 'rename':
+                case 'move': {
+                    const { namespace: oldNs, dotKey: oldDotKey } = parseKey(op.oldKey);
+                    const { dotKey: newDotKey } = parseKey(op.newKey);
+                    const filesToSearch = filterFiles(localeFiles, oldNs);
+                    const renamed = [];
+                    for (const file of filesToSearch) {
+                        const data = load(file);
+                        const value = getNestedValue(data, oldDotKey);
+                        if (value === undefined)
+                            continue;
+                        deleteNestedValue(data, oldDotKey);
+                        if (typeof value === 'object' && value !== null) {
+                            const subKeys = collectKeys(value);
+                            for (const subKey of subKeys) {
+                                const subValue = getNestedValue(value, subKey);
+                                setNestedValue(data, `${newDotKey}.${subKey}`, subValue);
+                            }
+                        }
+                        else {
+                            setNestedValue(data, newDotKey, value);
+                        }
+                        dirty.add(file.path);
+                        renamed.push(file.locale);
+                    }
+                    summary.push(renamed.length > 0
+                        ? `${op.op} ${op.oldKey} → ${op.newKey} (${renamed.join(', ')})`
+                        : `${op.op} ${op.oldKey} → not found`);
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            throw new Error(`Op #${i + 1} (${op.op}) failed: ${error.message}. No files written.`);
+        }
+    }
+    for (const path of dirty) {
+        writeJson(path, cache.get(path));
+    }
+    const header = `Batch: ${ops.length} op(s), ${dirty.size} file(s) written`;
+    return [header, ...summary].join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18n-tools-mcp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "MCP server for managing JSON translation files",
   "type": "module",
   "bin": {