i18n-tools-mcp 1.0.2 → 1.0.4

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.
@@ -55,6 +57,14 @@ messages/
 
 In namespace mode, prefix keys with the namespace: `common:Users.name`. Read operations (`query`, `list`, `search`, `missing`) work across all namespaces when no prefix is given. Write operations (`set`, `add`) require a namespace prefix.
 
+## Keys containing dots
+
+Keys may be nested objects, literal keys containing dots (Laravel-style `{"auth.login.title": "..."}`), or a mix of both. A dot-notation key is resolved against what is actually in the file, with the longest literal key winning at each level, so `auth.login.title` finds both `{"auth": {"login": {"title": ...}}}` and `{"auth.login.title": ...}`.
+
+- **Existing keys** are updated in place, in whichever form they already have.
+- **New keys** descend into existing nested objects as far as possible. The remainder is written as one literal dotted key when that object already contains dotted keys, and as nested objects otherwise.
+- **Prefixes** of flat keys act as groups: `query`, `delete`, `rename` and `move` on `datatable` cover `datatable.columns` and `datatable.rows`.
+
 ## Tools
 
 ### `query`

package/dist/translations.js

@@ -62,58 +62,170 @@ function writeJson(filePath, data) {
 export function setIndent(spaces) {
     jsonIndent = spaces;
 }
-function getNestedValue(obj, key) {
-    const parts = key.split('.');
-    let current = obj;
-    for (const part of parts) {
-        if (current == null || typeof current !== 'object') {
-            return undefined;
+function isObject(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+function hasOwn(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+/**
+ * Resolve a dot-notation key to the real chain of object keys. A single object key may itself
+ * contain dots (Laravel-style flat files such as `{"auth.login.title": "..."}`), so at every
+ * level the longest literal key wins, backtracking when a branch does not lead to the full key.
+ */
+function resolvePath(obj, key) {
+    return resolveParts(obj, key.split('.'));
+}
+function resolveParts(obj, parts) {
+    for (let i = parts.length; i > 0; i--) {
+        const segment = parts.slice(0, i).join('.');
+        if (!hasOwn(obj, segment)) {
+            continue;
+        }
+        if (i === parts.length) {
+            return [segment];
+        }
+        const child = obj[segment];
+        if (isObject(child)) {
+            const rest = resolveParts(child, parts.slice(i));
+            if (rest) {
+                return [segment, ...rest];
+            }
         }
-        current = current[part];
     }
-    return current;
+    return undefined;
 }
-function deleteNestedValue(obj, key) {
-    const parts = key.split('.');
+function parentOf(obj, path) {
     let current = obj;
-    for (let i = 0; i < parts.length - 1; i++) {
-        const part = parts[i];
-        if (current[part] == null || typeof current[part] !== 'object') {
-            return false;
+    for (const segment of path.slice(0, -1)) {
+        current = current[segment];
+    }
+    return current;
+}
+function collectEntries(obj, prefix = '', path = []) {
+    const entries = [];
+    for (const [k, v] of Object.entries(obj)) {
+        const key = prefix ? `${prefix}.${k}` : k;
+        if (isObject(v)) {
+            entries.push(...collectEntries(v, key, [...path, k]));
+        }
+        else {
+            entries.push({ key, path: [...path, k], value: v });
         }
-        current = current[part];
     }
-    const lastPart = parts[parts.length - 1];
-    if (!(lastPart in current)) {
-        return false;
+    return entries;
+}
+function collectKeys(obj) {
+    return collectEntries(obj).map((entry) => entry.key);
+}
+/**
+ * Leaf entries whose full key equals `key` or lives under it. Unlike resolvePath this also
+ * finds groups that only exist as a shared prefix of flat keys (`datatable` for
+ * `"datatable.columns"` and `"datatable.rows"`).
+ */
+function matchingEntries(obj, key) {
+    return collectEntries(obj).filter((entry) => entry.key === key || entry.key.startsWith(`${key}.`));
+}
+function getValue(obj, key) {
+    const path = resolvePath(obj, key);
+    if (path) {
+        return parentOf(obj, path)[path[path.length - 1]];
     }
-    delete current[lastPart];
-    return true;
+    const entries = matchingEntries(obj, key);
+    if (entries.length === 0) {
+        return undefined;
+    }
+    return Object.fromEntries(entries.map((entry) => [entry.key.slice(key.length + 1), entry.value]));
+}
+function deleteValue(obj, key) {
+    let deleted = false;
+    const path = resolvePath(obj, key);
+    if (path) {
+        delete parentOf(obj, path)[path[path.length - 1]];
+        deleted = true;
+    }
+    for (const entry of matchingEntries(obj, key)) {
+        delete parentOf(obj, entry.path)[entry.path[entry.path.length - 1]];
+        deleted = true;
+    }
+    return deleted;
 }
-function setNestedValue(obj, key, value) {
-    const parts = key.split('.');
+/**
+ * Set a value, overwriting an existing key wherever it lives. A new key descends into existing
+ * nested objects as far as possible; the remainder is written as one literal dotted key when
+ * that object already uses dotted keys (flat style), and as nested objects otherwise.
+ */
+function setValue(obj, key, value) {
+    const path = resolvePath(obj, key);
+    if (path) {
+        parentOf(obj, path)[path[path.length - 1]] = value;
+        return;
+    }
     let current = obj;
-    for (let i = 0; i < parts.length - 1; i++) {
-        const part = parts[i];
-        if (current[part] == null || typeof current[part] !== 'object') {
+    let parts = key.split('.');
+    descend: while (parts.length > 1) {
+        for (let i = parts.length - 1; i > 0; i--) {
+            const segment = parts.slice(0, i).join('.');
+            const child = current[segment];
+            if (hasOwn(current, segment) && isObject(child)) {
+                current = child;
+                parts = parts.slice(i);
+                continue descend;
+            }
+        }
+        break;
+    }
+    if (Object.keys(current).some((k) => k.includes('.'))) {
+        current[parts.join('.')] = value;
+        return;
+    }
+    for (const part of parts.slice(0, -1)) {
+        if (!isObject(current[part])) {
             current[part] = {};
         }
         current = current[part];
     }
     current[parts[parts.length - 1]] = value;
 }
-function collectKeys(obj, prefix = '') {
-    const keys = [];
-    for (const [k, v] of Object.entries(obj)) {
-        const fk = prefix ? `${prefix}.${k}` : k;
-        if (v != null && typeof v === 'object' && !Array.isArray(v)) {
-            keys.push(...collectKeys(v, fk));
+function valueAt(obj, path) {
+    let current = obj;
+    for (const segment of path) {
+        if (!isObject(current) || !hasOwn(current, segment)) {
+            return undefined;
         }
-        else {
-            keys.push(fk);
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Move every leaf under `oldKey` to `newKey`. New keys are written before the old ones are
+ * removed, so setValue still sees the file's key style (a flat file emptied first would look
+ * nested). Afterwards the old node is dropped if it is an object that is now empty.
+ */
+function renameValue(obj, oldKey, newKey) {
+    const entries = matchingEntries(obj, oldKey);
+    if (entries.length === 0) {
+        return false;
+    }
+    const oldPath = resolvePath(obj, oldKey);
+    const written = new Set();
+    for (const entry of entries) {
+        const target = newKey + entry.key.slice(oldKey.length);
+        setValue(obj, target, entry.value);
+        written.add(JSON.stringify(resolvePath(obj, target)));
+    }
+    for (const entry of entries) {
+        if (!written.has(JSON.stringify(entry.path)) && valueAt(obj, entry.path) !== undefined && !isObject(valueAt(obj, entry.path))) {
+            delete parentOf(obj, entry.path)[entry.path[entry.path.length - 1]];
+        }
+    }
+    if (oldPath) {
+        const node = valueAt(obj, oldPath);
+        if (isObject(node) && Object.keys(node).length === 0) {
+            delete parentOf(obj, oldPath)[oldPath[oldPath.length - 1]];
         }
     }
-    return keys;
+    return true;
 }
 function filterFiles(files, namespace) {
     if (!namespace) {
@@ -135,7 +247,7 @@ export function query(key, dir) {
     const results = [];
     for (const file of filesToSearch) {
         const data = readJson(file.path);
-        const value = getNestedValue(data, dotKey);
+        const value = getValue(data, dotKey);
         if (value !== undefined) {
             const label = !namespace && file.namespace
                 ? `${file.locale} (${file.namespace})`
@@ -166,7 +278,7 @@ export function set(locale, key, value, dir) {
         throw new Error(`Locale "${target}" not found in ${resolvedDir}`);
     }
     const data = readJson(localeFile.path);
-    setNestedValue(data, dotKey, sanitize(value));
+    setValue(data, dotKey, sanitize(value));
     writeJson(localeFile.path, data);
     return `Set ${locale}.${key} = "${value}"`;
 }
@@ -178,7 +290,7 @@ export function remove(key, dir) {
     const deleted = [];
     for (const file of filesToSearch) {
         const data = readJson(file.path);
-        if (deleteNestedValue(data, dotKey)) {
+        if (deleteValue(data, dotKey)) {
             writeJson(file.path, data);
             const label = !namespace && file.namespace
                 ? `${file.locale} (${file.namespace})`
@@ -208,7 +320,7 @@ export function add(key, translations, dir) {
             continue;
         }
         const data = readJson(localeFile.path);
-        setNestedValue(data, dotKey, sanitize(value));
+        setValue(data, dotKey, sanitize(value));
         writeJson(localeFile.path, data);
         updated.push(locale);
     }
@@ -231,21 +343,9 @@ export function rename(oldKey, newKey, dir) {
     const renamed = [];
     for (const file of filesToSearch) {
         const data = readJson(file.path);
-        const value = getNestedValue(data, oldDotKey);
-        if (value === undefined) {
+        if (!renameValue(data, oldDotKey, newDotKey)) {
             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);
-        }
         writeJson(file.path, data);
         const label = !oldNs && file.namespace
             ? `${file.locale} (${file.namespace})`
@@ -317,9 +417,7 @@ export function search(value, page = 1, pageSize = 100, dir) {
     const lowerValue = value.toLowerCase();
     for (const file of localeFiles) {
         const data = readJson(file.path);
-        const keys = collectKeys(data);
-        for (const key of keys) {
-            const v = getNestedValue(data, key);
+        for (const { key, value: v } of collectEntries(data)) {
             if (typeof v === 'string' && v.toLowerCase().includes(lowerValue)) {
                 const fk = fullKey(file, key);
                 results.push(`${file.locale}.${fk} = "${v}"`);
@@ -367,7 +465,7 @@ export function batch(ops, dir) {
                         const target = namespace ? `${op.locale}/${namespace}` : op.locale;
                         throw new Error(`Locale "${target}" not found in ${resolvedDir}`);
                     }
-                    setNestedValue(load(file), dotKey, sanitize(op.value));
+                    setValue(load(file), dotKey, sanitize(op.value));
                     dirty.add(file.path);
                     summary.push(`set ${op.locale}.${op.key}`);
                     break;
@@ -385,7 +483,7 @@ export function batch(ops, dir) {
                             skipped.push(locale);
                             continue;
                         }
-                        setNestedValue(load(file), dotKey, sanitize(value));
+                        setValue(load(file), dotKey, sanitize(value));
                         dirty.add(file.path);
                         updated.push(locale);
                     }
@@ -402,7 +500,7 @@ export function batch(ops, dir) {
                     const deleted = [];
                     for (const file of filesToSearch) {
                         const data = load(file);
-                        if (deleteNestedValue(data, dotKey)) {
+                        if (deleteValue(data, dotKey)) {
                             dirty.add(file.path);
                             deleted.push(file.locale);
                         }
@@ -419,21 +517,8 @@ export function batch(ops, dir) {
                     const filesToSearch = filterFiles(localeFiles, oldNs);
                     const renamed = [];
                     for (const file of filesToSearch) {
-                        const data = load(file);
-                        const value = getNestedValue(data, oldDotKey);
-                        if (value === undefined)
+                        if (!renameValue(load(file), oldDotKey, newDotKey))
                             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);
                     }

package/package.json

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