i18n-mcp-server 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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

@@ -0,0 +1,63 @@
+# i18n-MCP-Server
+
+面向前端国际化工作流的 MCP Server，提供以下四类能力：
+
+- `extract_replace`：提取硬编码文本并返回源码与语言文件 diff。
+- `doctor_lint`：检查缺失 key、死 key 和硬编码风险点。
+- `refactor_key`：批量重命名 i18n key。
+- `sync_catalog`：预留翻译平台同步适配器接口。
+
+## 设计原则
+
+- 默认不静默写入文件，所有修改都先以 unified diff 返回。
+- JS / TS 使用 Babel AST，Vue 使用 SFC 解析器。
+- 保留 JSON 原始缩进风格，减少 Git 噪音。
+- 默认以 `zh-CN.json` 作为基准语言。
+
+## 快速开始
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+## MCP 工具
+
+### `project_info`
+
+读取项目 `package.json`，自动识别 `vue-i18n`、`react-i18next`、`@angular/localize` 等国际化方案。
+
+### `extract_replace`
+
+输入源码文件与语言目录，扫描静态文本并返回：
+
+- 提议生成的 key
+- 源码 diff
+- 语言 JSON diff
+
+默认只生成补丁，不直接写盘。
+
+### `doctor_lint`
+
+以 `zh-CN.json` 为基准：
+
+- 对比其他语言缺失 key
+- 扫描代码中未引用的死 key
+- 检测剩余的中日韩硬编码文本
+
+### `refactor_key`
+
+对代码中的 `t('oldKey')` 与多语言 JSON 做联动重命名，返回完整影响文件列表和统一 diff。
+
+### `sync_catalog`
+
+MVP 先保留 provider 适配器入口，后续可继续接入 Lokalise / Crowdin / 本地 JSON 导入导出。
+
+## 当前边界
+
+这一版已经具备可编译、可接入的服务骨架，但仍有几项明确的后续增强点：
+
+- Vue 模板替换当前是偏保守的 MVP 方案，复杂模板场景还可以继续细化 AST 级改写。
+- `extract_replace` 目前默认依赖调用侧已有 `t()` 上下文，尚未自动补充 import / hook 注入。
+- `sync_catalog` 目前只保留接口和返回结构，尚未接入真实 provider API。

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { detectFramework } from "./utils/framework.js";
+import { runDoctor } from "./tools/doctor.js";
+import { runExtract } from "./tools/extract.js";
+import { runRefactor } from "./tools/refactor.js";
+import { runSync } from "./tools/sync.js";
+const server = new McpServer({
+    name: "i18n-mcp-server",
+    version: "0.1.0"
+});
+server.tool("project_info", "Inspect the current project and detect which i18n framework is in use.", {
+    cwd: z.string().default(process.cwd())
+}, async ({ cwd }) => ({
+    content: [
+        {
+            type: "text",
+            text: JSON.stringify({
+                cwd,
+                framework: await detectFramework(cwd)
+            }, null, 2)
+        }
+    ]
+}));
+server.tool("extract_replace", "Extract hardcoded i18n text from a source file and propose source + locale diffs.", {
+    cwd: z.string().default(process.cwd()),
+    filePath: z.string(),
+    localesDir: z.string(),
+    baseLocale: z.string().default("zh-CN"),
+    targetLocales: z.array(z.string()).optional(),
+    keyStrategy: z.enum(["semantic", "hash"]).default("semantic"),
+    namespace: z.string().optional()
+}, async (args) => ({
+    content: [
+        {
+            type: "text",
+            text: JSON.stringify(await runExtract({
+                ...args,
+                filePath: path.resolve(args.cwd, args.filePath),
+                localesDir: path.resolve(args.cwd, args.localesDir)
+            }), null, 2)
+        }
+    ]
+}));
+server.tool("doctor_lint", "Check locale health, missing translations, dead keys, and remaining hardcoded text.", {
+    cwd: z.string().default(process.cwd()),
+    srcDir: z.string().default("src"),
+    localesDir: z.string(),
+    baseLocale: z.string().default("zh-CN"),
+    compareLocales: z.array(z.string()).optional()
+}, async (args) => ({
+    content: [
+        {
+            type: "text",
+            text: JSON.stringify(await runDoctor({
+                ...args,
+                localesDir: path.resolve(args.cwd, args.localesDir)
+            }), null, 2)
+        }
+    ]
+}));
+server.tool("refactor_key", "Rename an existing i18n key across source files and locale JSON files, returning a full diff for confirmation.", {
+    cwd: z.string().default(process.cwd()),
+    srcDir: z.string().default("src"),
+    localesDir: z.string(),
+    locales: z.array(z.string()),
+    oldKey: z.string(),
+    newKey: z.string()
+}, async (args) => ({
+    content: [
+        {
+            type: "text",
+            text: JSON.stringify(await runRefactor({
+                ...args,
+                localesDir: path.resolve(args.cwd, args.localesDir)
+            }), null, 2)
+        }
+    ]
+}));
+server.tool("sync_catalog", "Sync locale files with an external provider. MVP currently exposes adapter metadata only.", {
+    provider: z.enum(["lokalise", "json"]).optional(),
+    mode: z.enum(["pull", "push"]).optional(),
+    lang: z.string().optional()
+}, async (args) => ({
+    content: [
+        {
+            type: "text",
+            text: JSON.stringify(await runSync(args), null, 2)
+        }
+    ]
+}));
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/parsers/babel.d.ts

@@ -0,0 +1,2 @@
+import type { File } from "@babel/types";
+export declare function parseCode(source: string, filePath: string): File;

package/dist/parsers/babel.js

@@ -0,0 +1,19 @@
+import { parse } from "@babel/parser";
+export function parseCode(source, filePath) {
+    const isTs = /\.(ts|tsx)$/.test(filePath);
+    const isJsx = /\.(jsx|tsx)$/.test(filePath);
+    return parse(source, {
+        sourceType: "module",
+        plugins: [
+            "decorators-legacy",
+            "importAttributes",
+            "classProperties",
+            "optionalChaining",
+            "nullishCoalescingOperator",
+            "topLevelAwait",
+            "dynamicImport",
+            ...(isTs ? ["typescript"] : []),
+            ...(isJsx ? ["jsx"] : [])
+        ]
+    });
+}

package/dist/parsers/vue.d.ts

@@ -0,0 +1,5 @@
+export declare function parseVueFile(source: string, filePath: string): {
+    descriptor: import("@vue/compiler-sfc").SFCDescriptor;
+    templateAst: import("@vue/compiler-core").RootNode | null;
+    templateContent: string;
+};

package/dist/parsers/vue.js

@@ -0,0 +1,12 @@
+import { parse as parseSfc } from "@vue/compiler-sfc";
+import { parse as parseTemplate } from "@vue/compiler-dom";
+export function parseVueFile(source, filePath) {
+    const sfc = parseSfc(source, { filename: filePath });
+    const templateContent = sfc.descriptor.template?.content ?? "";
+    const templateAst = templateContent ? parseTemplate(templateContent, { comments: true }) : null;
+    return {
+        descriptor: sfc.descriptor,
+        templateAst,
+        templateContent
+    };
+}

package/dist/tools/doctor.d.ts

@@ -0,0 +1,8 @@
+import type { DoctorReport } from "../types.js";
+export declare function runDoctor(params: {
+    cwd: string;
+    srcDir?: string;
+    localesDir: string;
+    baseLocale?: string;
+    compareLocales?: string[];
+}): Promise<DoctorReport>;

package/dist/tools/doctor.js

@@ -0,0 +1,138 @@
+import path from "node:path";
+import traverse from "@babel/traverse";
+import * as t from "@babel/types";
+import { loadLocaleFiles, flattenKeys } from "../utils/json.js";
+import { listCodeFiles, readText } from "../utils/files.js";
+import { parseCode } from "../parsers/babel.js";
+import { parseVueFile } from "../parsers/vue.js";
+const HARD_CODED_TEXT_RE = /[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/;
+export async function runDoctor(params) {
+    const srcDir = params.srcDir ? path.resolve(params.cwd, params.srcDir) : path.join(params.cwd, "src");
+    const baseLocale = params.baseLocale ?? "zh-CN";
+    const compareLocales = params.compareLocales ?? ["en-US", "ja-JP"];
+    const localeFiles = await loadLocaleFiles(params.localesDir, [baseLocale, ...compareLocales]);
+    const baseLocaleFile = localeFiles.find((item) => item.locale === baseLocale);
+    const baseKeys = flattenKeys(baseLocaleFile.data);
+    const missingKeys = compareLocales.flatMap((locale) => {
+        const current = localeFiles.find((item) => item.locale === locale);
+        if (!current) {
+            return [];
+        }
+        const currentKeys = new Set(flattenKeys(current.data));
+        return baseKeys.filter((key) => !currentKeys.has(key)).map((key) => ({ locale, key }));
+    });
+    const files = await listCodeFiles(srcDir);
+    const referencedKeys = new Set();
+    const hardcodedTexts = [];
+    for (const filePath of files) {
+        const source = await readText(filePath);
+        if (filePath.endsWith(".vue")) {
+            collectVueFindings(filePath, source, referencedKeys, hardcodedTexts);
+        }
+        else {
+            collectJsFindings(filePath, source, referencedKeys, hardcodedTexts);
+        }
+    }
+    const deadKeys = baseKeys.filter((key) => !referencedKeys.has(key));
+    return {
+        missingKeys,
+        deadKeys,
+        hardcodedTexts
+    };
+}
+function collectJsFindings(filePath, source, referencedKeys, hardcodedTexts) {
+    const ast = parseCode(source, filePath);
+    traverse(ast, {
+        CallExpression(astPath) {
+            const callee = astPath.node.callee;
+            if (t.isIdentifier(callee, { name: "t" })) {
+                const firstArg = astPath.node.arguments[0];
+                if (t.isStringLiteral(firstArg)) {
+                    referencedKeys.add(firstArg.value);
+                }
+            }
+            if (t.isMemberExpression(callee) && t.isIdentifier(callee.property, { name: "log" })) {
+                astPath.skip();
+            }
+        },
+        JSXText(astPath) {
+            const value = astPath.node.value.trim();
+            if (!value || !HARD_CODED_TEXT_RE.test(value)) {
+                return;
+            }
+            const loc = astPath.node.loc?.start;
+            if (!loc) {
+                return;
+            }
+            hardcodedTexts.push({
+                filePath,
+                text: value,
+                line: loc.line,
+                column: loc.column + 1
+            });
+        },
+        StringLiteral(astPath) {
+            const parent = astPath.parent;
+            if (t.isJSXAttribute(parent) &&
+                t.isJSXIdentifier(parent.name) &&
+                !["className", "data-testid"].includes(parent.name.name) &&
+                HARD_CODED_TEXT_RE.test(astPath.node.value)) {
+                const loc = astPath.node.loc?.start;
+                if (!loc) {
+                    return;
+                }
+                hardcodedTexts.push({
+                    filePath,
+                    text: astPath.node.value,
+                    line: loc.line,
+                    column: loc.column + 1
+                });
+            }
+        }
+    });
+}
+function collectVueFindings(filePath, source, referencedKeys, hardcodedTexts) {
+    const { descriptor, templateAst } = parseVueFile(source, filePath);
+    if (descriptor.script?.content) {
+        collectJsFindings(filePath, descriptor.script.content, referencedKeys, hardcodedTexts);
+    }
+    if (descriptor.scriptSetup?.content) {
+        collectJsFindings(filePath, descriptor.scriptSetup.content, referencedKeys, hardcodedTexts);
+    }
+    if (!templateAst) {
+        return;
+    }
+    const walk = (node) => {
+        if (node.type === 2) {
+            const text = node.content?.trim();
+            if (text && HARD_CODED_TEXT_RE.test(text) && node.loc?.start) {
+                hardcodedTexts.push({
+                    filePath,
+                    text,
+                    line: node.loc.start.line,
+                    column: node.loc.start.column
+                });
+            }
+        }
+        if (Array.isArray(node.props)) {
+            for (const prop of node.props) {
+                if (prop.type === 6 &&
+                    !["class", "data-testid"].includes(prop.name) &&
+                    prop.value?.content &&
+                    HARD_CODED_TEXT_RE.test(prop.value.content) &&
+                    prop.loc?.start) {
+                    hardcodedTexts.push({
+                        filePath,
+                        text: prop.value.content,
+                        line: prop.loc.start.line,
+                        column: prop.loc.start.column
+                    });
+                }
+            }
+        }
+        if (Array.isArray(node.children)) {
+            node.children.forEach(walk);
+        }
+    };
+    walk(templateAst);
+}

package/dist/tools/extract.d.ts

@@ -0,0 +1,14 @@
+import type { ExtractCandidate, KeyStrategy } from "../types.js";
+export declare function runExtract(params: {
+    cwd: string;
+    filePath: string;
+    localesDir: string;
+    baseLocale?: string;
+    targetLocales?: string[];
+    keyStrategy?: KeyStrategy;
+    namespace?: string;
+}): Promise<{
+    diff: string;
+    affectedFiles: string[];
+    candidates: ExtractCandidate[];
+}>;

package/dist/tools/extract.js

@@ -0,0 +1,144 @@
+import generate from "@babel/generator";
+import traverse from "@babel/traverse";
+import * as t from "@babel/types";
+import MagicString from "magic-string";
+import { parseCode } from "../parsers/babel.js";
+import { parseVueFile } from "../parsers/vue.js";
+import { buildKey } from "../utils/keygen.js";
+import { loadLocaleFiles, flattenKeys, getNestedValue, setNestedValue, stringifyLocale } from "../utils/json.js";
+import { buildUnifiedDiff } from "../utils/diff.js";
+import { readText } from "../utils/files.js";
+const IGNORED_JSX_ATTRS = new Set(["className", "data-testid"]);
+const ASIAN_TEXT_RE = /[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/;
+export async function runExtract(params) {
+    const source = await readText(params.filePath);
+    const baseLocale = params.baseLocale ?? "zh-CN";
+    const targetLocales = params.targetLocales ?? [baseLocale];
+    const keyStrategy = params.keyStrategy ?? "semantic";
+    const localeFiles = await loadLocaleFiles(params.localesDir, targetLocales);
+    const existingKeys = new Set(localeFiles.flatMap((file) => flattenKeys(file.data)));
+    const patches = [];
+    const candidates = [];
+    const updatedSource = params.filePath.endsWith(".vue")
+        ? extractFromVue({
+            cwd: params.cwd,
+            filePath: params.filePath,
+            source,
+            namespace: params.namespace,
+            keyStrategy,
+            existingKeys
+        }, candidates)
+        : extractFromJsx({
+            cwd: params.cwd,
+            filePath: params.filePath,
+            source,
+            namespace: params.namespace,
+            keyStrategy,
+            existingKeys
+        }, candidates);
+    if (updatedSource !== source) {
+        patches.push({
+            path: params.filePath,
+            before: source,
+            after: updatedSource
+        });
+    }
+    for (const localeFile of localeFiles) {
+        let nextData = localeFile.data;
+        for (const candidate of candidates) {
+            if (getNestedValue(nextData, candidate.key) === undefined) {
+                const seedValue = localeFile.locale === baseLocale ? candidate.text : "";
+                nextData = setNestedValue(nextData, candidate.key, seedValue);
+            }
+        }
+        const nextRaw = stringifyLocale(nextData, localeFile.indent);
+        if (nextRaw !== localeFile.raw) {
+            patches.push({
+                path: localeFile.path,
+                before: localeFile.raw,
+                after: nextRaw
+            });
+        }
+    }
+    return {
+        diff: buildUnifiedDiff(params.cwd, patches),
+        affectedFiles: patches.map((patch) => patch.path),
+        candidates
+    };
+}
+function extractFromJsx(input, candidates) {
+    const ast = parseCode(input.source, input.filePath);
+    traverse(ast, {
+        JSXText(astPath) {
+            const text = astPath.node.value.trim();
+            if (!text || !ASIAN_TEXT_RE.test(text)) {
+                return;
+            }
+            const key = chooseKey(input, text);
+            candidates.push({ text, key, filePath: input.filePath, kind: "jsx-text" });
+            astPath.replaceWith(t.jsxExpressionContainer(t.callExpression(t.identifier("t"), [t.stringLiteral(key)])));
+        },
+        JSXAttribute(astPath) {
+            const name = t.isJSXIdentifier(astPath.node.name) ? astPath.node.name.name : "";
+            if (IGNORED_JSX_ATTRS.has(name)) {
+                return;
+            }
+            if (t.isStringLiteral(astPath.node.value) && ASIAN_TEXT_RE.test(astPath.node.value.value)) {
+                const text = astPath.node.value.value;
+                const key = chooseKey(input, text);
+                candidates.push({ text, key, filePath: input.filePath, kind: "jsx-attr" });
+                astPath.node.value = t.jsxExpressionContainer(t.callExpression(t.identifier("t"), [t.stringLiteral(key)]));
+            }
+        }
+    });
+    return generate(ast, { retainLines: true }, input.source).code;
+}
+function extractFromVue(input, candidates) {
+    const { descriptor } = parseVueFile(input.source, input.filePath);
+    const templateBlock = descriptor.template;
+    if (!templateBlock || !templateBlock.content) {
+        return input.source;
+    }
+    const templateSource = templateBlock.content;
+    const magic = new MagicString(input.source);
+    let attrPattern = /\b(placeholder|title|alt|label)="([^"]*[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af][^"]*)"/g;
+    let attrMatch;
+    while ((attrMatch = attrPattern.exec(templateSource)) !== null) {
+        const attrName = attrMatch[1];
+        const text = attrMatch[2].trim();
+        if (!text) {
+            continue;
+        }
+        const key = chooseKey(input, text);
+        candidates.push({ text, key, filePath: input.filePath, kind: "vue-attr" });
+        const start = templateBlock.loc.start.offset + attrMatch.index;
+        const end = start + attrMatch[0].length;
+        magic.overwrite(start, end, `:${attrName}="t('${key}')"`);
+    }
+    let textPattern = />([^<>\n]*[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af][^<>]*)</g;
+    let textMatch;
+    while ((textMatch = textPattern.exec(templateSource)) !== null) {
+        const text = textMatch[1].trim();
+        if (!text) {
+            continue;
+        }
+        const key = chooseKey(input, text);
+        candidates.push({ text, key, filePath: input.filePath, kind: "vue-text" });
+        const innerIndex = textMatch[0].indexOf(textMatch[1]);
+        const start = templateBlock.loc.start.offset + textMatch.index + innerIndex;
+        const end = start + textMatch[1].length;
+        magic.overwrite(start, end, `{{ t('${key}') }}`);
+    }
+    return magic.toString();
+}
+function chooseKey(input, text) {
+    const proposed = buildKey({
+        cwd: input.cwd,
+        filePath: input.filePath,
+        text,
+        namespace: input.namespace,
+        strategy: input.keyStrategy
+    });
+    input.existingKeys.add(proposed);
+    return proposed;
+}

package/dist/tools/refactor.d.ts

@@ -0,0 +1,11 @@
+export declare function runRefactor(params: {
+    cwd: string;
+    srcDir?: string;
+    localesDir: string;
+    locales: string[];
+    oldKey: string;
+    newKey: string;
+}): Promise<{
+    affectedFiles: string[];
+    diff: string;
+}>;

package/dist/tools/refactor.js

@@ -0,0 +1,91 @@
+import path from "node:path";
+import generate from "@babel/generator";
+import traverse from "@babel/traverse";
+import * as t from "@babel/types";
+import MagicString from "magic-string";
+import { parseCode } from "../parsers/babel.js";
+import { parseVueFile } from "../parsers/vue.js";
+import { listCodeFiles, readText } from "../utils/files.js";
+import { buildUnifiedDiff } from "../utils/diff.js";
+import { deleteNestedValue, getNestedValue, loadLocaleFiles, setNestedValue, stringifyLocale } from "../utils/json.js";
+export async function runRefactor(params) {
+    const srcDir = params.srcDir ? path.resolve(params.cwd, params.srcDir) : path.join(params.cwd, "src");
+    const patches = [];
+    const codeFiles = await listCodeFiles(srcDir);
+    for (const filePath of codeFiles) {
+        const source = await readText(filePath);
+        const next = filePath.endsWith(".vue")
+            ? renameInVueFile(source, filePath, params.oldKey, params.newKey)
+            : renameInJsFile(source, filePath, params.oldKey, params.newKey);
+        if (next !== source) {
+            patches.push({
+                path: filePath,
+                before: source,
+                after: next
+            });
+        }
+    }
+    const localeFiles = await loadLocaleFiles(params.localesDir, params.locales);
+    for (const localeFile of localeFiles) {
+        const oldValue = getNestedValue(localeFile.data, params.oldKey);
+        if (oldValue === undefined) {
+            continue;
+        }
+        const nextData = setNestedValue(deleteNestedValue(localeFile.data, params.oldKey), params.newKey, oldValue);
+        const nextRaw = stringifyLocale(nextData, localeFile.indent);
+        if (nextRaw !== localeFile.raw) {
+            patches.push({
+                path: localeFile.path,
+                before: localeFile.raw,
+                after: nextRaw
+            });
+        }
+    }
+    return {
+        affectedFiles: patches.map((patch) => patch.path),
+        diff: buildUnifiedDiff(params.cwd, patches)
+    };
+}
+function renameInJsFile(source, filePath, oldKey, newKey) {
+    const ast = parseCode(source, filePath);
+    let touched = false;
+    traverse(ast, {
+        CallExpression(astPath) {
+            const callee = astPath.node.callee;
+            if (!t.isIdentifier(callee, { name: "t" })) {
+                return;
+            }
+            const firstArg = astPath.node.arguments[0];
+            if (t.isStringLiteral(firstArg) && firstArg.value === oldKey) {
+                firstArg.value = newKey;
+                touched = true;
+            }
+        }
+    });
+    return touched ? generate(ast, { retainLines: true }, source).code : source;
+}
+function renameInVueFile(source, filePath, oldKey, newKey) {
+    const { descriptor } = parseVueFile(source, filePath);
+    const magic = new MagicString(source);
+    if (descriptor.script) {
+        const next = renameInJsFile(descriptor.script.content, filePath, oldKey, newKey);
+        if (next !== descriptor.script.content) {
+            magic.overwrite(descriptor.script.loc.start.offset, descriptor.script.loc.end.offset, next);
+        }
+    }
+    if (descriptor.scriptSetup) {
+        const next = renameInJsFile(descriptor.scriptSetup.content, filePath, oldKey, newKey);
+        if (next !== descriptor.scriptSetup.content) {
+            magic.overwrite(descriptor.scriptSetup.loc.start.offset, descriptor.scriptSetup.loc.end.offset, next);
+        }
+    }
+    if (descriptor.template?.content) {
+        const replaced = descriptor.template.content
+            .replaceAll(`t('${oldKey}')`, `t('${newKey}')`)
+            .replaceAll(`t("${oldKey}")`, `t("${newKey}")`);
+        if (replaced !== descriptor.template.content) {
+            magic.overwrite(descriptor.template.loc.start.offset, descriptor.template.loc.end.offset, replaced);
+        }
+    }
+    return magic.toString();
+}

package/dist/tools/sync.d.ts

@@ -0,0 +1,11 @@
+export declare function runSync(params: {
+    provider?: "lokalise" | "json";
+    mode?: "pull" | "push";
+    lang?: string;
+}): Promise<{
+    status: string;
+    provider: "lokalise" | "json";
+    mode: "push" | "pull";
+    lang: string;
+    message: string;
+}>;

package/dist/tools/sync.js

@@ -0,0 +1,9 @@
+export async function runSync(params) {
+    return {
+        status: "planned",
+        provider: params.provider ?? "json",
+        mode: params.mode ?? "pull",
+        lang: params.lang ?? "all",
+        message: "MVP 当前保留 provider 适配层，建议下一步接入 Lokalise API 或本地 JSON 导入导出流水线。"
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+export type KeyStrategy = "semantic" | "hash";
+export interface LocaleFile {
+    locale: string;
+    path: string;
+    indent: string;
+    data: Record<string, unknown>;
+    raw: string;
+}
+export interface FilePatch {
+    path: string;
+    before: string;
+    after: string;
+}
+export interface ExtractCandidate {
+    text: string;
+    key: string;
+    filePath: string;
+    kind: "jsx-text" | "jsx-attr" | "vue-text" | "vue-attr";
+}
+export interface HardcodedTextFinding {
+    filePath: string;
+    text: string;
+    line: number;
+    column: number;
+}
+export interface MissingKeyFinding {
+    locale: string;
+    key: string;
+}
+export interface DoctorReport {
+    missingKeys: MissingKeyFinding[];
+    deadKeys: string[];
+    hardcodedTexts: HardcodedTextFinding[];
+}
+export interface FrameworkInfo {
+    framework: "vue-i18n" | "react-i18next" | "@angular/localize" | "unknown";
+    packageManagerHint: string[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/diff.d.ts

@@ -0,0 +1,2 @@
+import type { FilePatch } from "../types.js";
+export declare function buildUnifiedDiff(cwd: string, patches: FilePatch[]): string;

package/dist/utils/diff.js

@@ -0,0 +1,10 @@
+import path from "node:path";
+import { createTwoFilesPatch } from "diff";
+export function buildUnifiedDiff(cwd, patches) {
+    return patches
+        .map((patch) => {
+        const relativePath = path.relative(cwd, patch.path).split(path.sep).join("/");
+        return createTwoFilesPatch(relativePath, relativePath, patch.before, patch.after, "before", "after");
+    })
+        .join("\n");
+}

package/dist/utils/files.d.ts

@@ -0,0 +1,3 @@
+export declare function readText(filePath: string): Promise<string>;
+export declare function listCodeFiles(rootDir: string): Promise<string[]>;
+export declare function toPosixRelative(rootDir: string, targetPath: string): string;

package/dist/utils/files.js

@@ -0,0 +1,18 @@
+import fg from "fast-glob";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+const CODE_PATTERNS = ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.vue"];
+export async function readText(filePath) {
+    return fs.readFile(filePath, "utf8");
+}
+export async function listCodeFiles(rootDir) {
+    return fg(CODE_PATTERNS, {
+        cwd: rootDir,
+        absolute: true,
+        onlyFiles: true,
+        ignore: ["**/node_modules/**", "**/dist/**", "**/.git/**"]
+    });
+}
+export function toPosixRelative(rootDir, targetPath) {
+    return path.relative(rootDir, targetPath).split(path.sep).join("/");
+}

package/dist/utils/framework.d.ts

@@ -0,0 +1,2 @@
+import type { FrameworkInfo } from "../types.js";
+export declare function detectFramework(cwd: string): Promise<FrameworkInfo>;

package/dist/utils/framework.js

@@ -0,0 +1,23 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+export async function detectFramework(cwd) {
+    const packageJsonPath = path.join(cwd, "package.json");
+    try {
+        const raw = await fs.readFile(packageJsonPath, "utf8");
+        const pkg = JSON.parse(raw);
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if ("vue-i18n" in deps) {
+            return { framework: "vue-i18n", packageManagerHint: ["vue-i18n"] };
+        }
+        if ("react-i18next" in deps || "i18next" in deps) {
+            return { framework: "react-i18next", packageManagerHint: ["react-i18next", "i18next"] };
+        }
+        if ("@angular/localize" in deps) {
+            return { framework: "@angular/localize", packageManagerHint: ["@angular/localize"] };
+        }
+    }
+    catch {
+        return { framework: "unknown", packageManagerHint: [] };
+    }
+    return { framework: "unknown", packageManagerHint: [] };
+}

package/dist/utils/json.d.ts

@@ -0,0 +1,7 @@
+import type { LocaleFile } from "../types.js";
+export declare function loadLocaleFiles(localesDir: string, locales: string[]): Promise<LocaleFile[]>;
+export declare function flattenKeys(input: Record<string, unknown>, prefix?: string): string[];
+export declare function getNestedValue(input: Record<string, unknown>, dottedKey: string): unknown;
+export declare function setNestedValue(input: Record<string, unknown>, dottedKey: string, value: unknown): Record<string, unknown>;
+export declare function deleteNestedValue(input: Record<string, unknown>, dottedKey: string): Record<string, unknown>;
+export declare function stringifyLocale(data: Record<string, unknown>, indent: string): string;

package/dist/utils/json.js

@@ -0,0 +1,73 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import detectIndent from "detect-indent";
+export async function loadLocaleFiles(localesDir, locales) {
+    return Promise.all(locales.map(async (locale) => {
+        const localePath = path.join(localesDir, `${locale}.json`);
+        const raw = await fs.readFile(localePath, "utf8");
+        const indent = detectIndent(raw).indent || "  ";
+        return {
+            locale,
+            path: localePath,
+            indent,
+            data: JSON.parse(raw),
+            raw
+        };
+    }));
+}
+export function flattenKeys(input, prefix = "") {
+    return Object.entries(input).flatMap(([key, value]) => {
+        const nextKey = prefix ? `${prefix}.${key}` : key;
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            return flattenKeys(value, nextKey);
+        }
+        return [nextKey];
+    });
+}
+export function getNestedValue(input, dottedKey) {
+    return dottedKey.split(".").reduce((current, segment) => {
+        if (!current || typeof current !== "object") {
+            return undefined;
+        }
+        return current[segment];
+    }, input);
+}
+export function setNestedValue(input, dottedKey, value) {
+    const clone = structuredClone(input);
+    const segments = dottedKey.split(".");
+    let cursor = clone;
+    for (const segment of segments.slice(0, -1)) {
+        if (!cursor[segment] || typeof cursor[segment] !== "object" || Array.isArray(cursor[segment])) {
+            cursor[segment] = {};
+        }
+        cursor = cursor[segment];
+    }
+    cursor[segments.at(-1)] = value;
+    return clone;
+}
+export function deleteNestedValue(input, dottedKey) {
+    const clone = structuredClone(input);
+    const segments = dottedKey.split(".");
+    const trail = [];
+    let cursor = clone;
+    for (const segment of segments.slice(0, -1)) {
+        const next = cursor[segment];
+        if (!next || typeof next !== "object" || Array.isArray(next)) {
+            return clone;
+        }
+        trail.push({ parent: cursor, key: segment });
+        cursor = next;
+    }
+    delete cursor[segments.at(-1)];
+    for (let index = trail.length - 1; index >= 0; index -= 1) {
+        const { parent, key } = trail[index];
+        const child = parent[key];
+        if (child && typeof child === "object" && !Array.isArray(child) && Object.keys(child).length === 0) {
+            delete parent[key];
+        }
+    }
+    return clone;
+}
+export function stringifyLocale(data, indent) {
+    return `${JSON.stringify(data, null, indent)}\n`;
+}

package/dist/utils/keygen.d.ts

@@ -0,0 +1,9 @@
+import type { KeyStrategy } from "../types.js";
+export declare function buildKey(input: {
+    cwd: string;
+    filePath: string;
+    text: string;
+    componentName?: string;
+    namespace?: string;
+    strategy: KeyStrategy;
+}): string;

package/dist/utils/keygen.js

@@ -0,0 +1,29 @@
+import crypto from "node:crypto";
+import path from "node:path";
+export function buildKey(input) {
+    if (input.strategy === "hash") {
+        const hash = crypto.createHash("sha1").update(input.text).digest("hex").slice(0, 8);
+        return input.namespace ? `${input.namespace}.${hash}` : hash;
+    }
+    const relative = path.relative(input.cwd, input.filePath).replace(/\.[^.]+$/, "");
+    const normalizedPath = relative
+        .split(path.sep)
+        .join(".")
+        .replace(/[^a-zA-Z0-9.]+/g, ".")
+        .replace(/\.+/g, ".")
+        .replace(/^\.|\.$/g, "")
+        .toLowerCase();
+    const semanticTail = input.text
+        .trim()
+        .toLowerCase()
+        .replace(/[\s/]+/g, ".")
+        .replace(/[^a-z0-9.\u4e00-\u9fa5_-]+/g, "")
+        .replace(/\.+/g, ".")
+        .replace(/^\.|\.$/g, "")
+        .slice(0, 48) || "text";
+    return [input.namespace, normalizedPath, input.componentName, semanticTail]
+        .filter(Boolean)
+        .join(".")
+        .replace(/\.+/g, ".")
+        .replace(/^\.|\.$/g, "");
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "i18n-mcp-server",
+  "version": "0.0.1",
+  "description": "MCP server for frontend i18n extraction, linting, refactoring, and sync workflows.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "bin": {
+    "i18n-mcp-server": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/index.js",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "i18n",
+    "typescript",
+    "vue",
+    "react"
+  ],
+  "homepage": "https://github.com/tota92/i18n-mcp-server#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tota92/i18n-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tota92/i18n-mcp-server/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@babel/generator": "^7.28.0",
+    "@babel/parser": "^7.28.0",
+    "@babel/traverse": "^7.28.0",
+    "@babel/types": "^7.28.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@vue/compiler-dom": "^3.5.13",
+    "@vue/compiler-sfc": "^3.5.13",
+    "detect-indent": "^7.0.1",
+    "diff": "^7.0.0",
+    "fast-glob": "^3.3.3",
+    "magic-string": "^0.30.17",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  }
+}