i18n-MCP-Server

i18n-mcp-server 是一个面向前端国际化工作流的 MCP Server，帮助你在 Vue / React / TS 项目里完成文案提取、翻译健康检查、Key 重构和同步扩展。

Features

• 提取代码中的硬编码中日韩文本，替换为 t('key')
• 自动生成 i18n key，并更新本地语言 JSON
• 检查缺失翻译、死 key、残留硬编码文本
• 批量重命名 i18n key，并同步更新代码与 JSON
• 预留 Lokalise / 通用 JSON 同步能力

Installation

方式 1：通过 npx 直接运行

这是最推荐的方式，不需要全局安装：

npx -y i18n-mcp-server

方式 2：全局安装

npm install -g i18n-mcp-server

安装后可以直接运行：

i18n-mcp-server

MCP Client 配置

这个包是一个标准的 stdio MCP Server，适用于 Claude Desktop、Cherry Studio、Cline、Cursor MCP 插件等支持 MCP 的客户端。

通用配置示例

使用 npx：

{
  "mcpServers": {
    "i18n": {
      "command": "npx",
      "args": ["-y", "i18n-mcp-server"]
    }
  }
}

使用全局安装命令：

{
  "mcpServers": {
    "i18n": {
      "command": "i18n-mcp-server"
    }
  }
}

Windows 兼容写法

如果你的 MCP 客户端在 Windows 下对命令解析比较严格，可以这样配置：

{
  "mcpServers": {
    "i18n": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "i18n-mcp-server"]
    }
  }
}

Quick Start

把 MCP Server 接入客户端后，你可以直接让 AI 调用这些工具。

示例指令：

• “调用 project_info，检查当前项目的 i18n 框架”
• “调用 doctor_lint，扫描 src 和 src/locales”
• “调用 extract_replace，处理 src/pages/UserProfile.tsx”
• “调用 refactor_key，把 common.btn.save 改成 common.actions.save”

Tools

project_info

读取项目 package.json，自动识别当前项目使用的国际化方案：

• vue-i18n
• react-i18next
• @angular/localize

示例参数：

{
  "cwd": "C:\\your-project"
}

extract_replace

从源码文件中提取静态文本，生成 key，并返回源码与语言文件的 unified diff。

支持文件类型：

• .vue
• .tsx
• .jsx
• .ts
• .js

示例参数：

{
  "cwd": "C:\\your-project",
  "filePath": "src/pages/UserProfile.tsx",
  "localesDir": "src/locales",
  "baseLocale": "zh-CN",
  "targetLocales": ["zh-CN", "en-US", "ja-JP"],
  "keyStrategy": "semantic",
  "namespace": "userProfile"
}

说明：

• 默认只返回 diff，不静默写盘
• keyStrategy 支持 semantic 和 hash
• 当前版本默认假设源码上下文中已经可以使用 t()

doctor_lint

检查翻译文件健康状况，包括：

• 缺失翻译 key
• 死 key
• 未国际化的中日韩硬编码文本

示例参数：

{
  "cwd": "C:\\your-project",
  "srcDir": "src",
  "localesDir": "src/locales",
  "baseLocale": "zh-CN",
  "compareLocales": ["en-US", "ja-JP"]
}

refactor_key

批量重命名 i18n key，并联动更新代码引用和语言文件。

示例参数：

{
  "cwd": "C:\\your-project",
  "srcDir": "src",
  "localesDir": "src/locales",
  "locales": ["zh-CN", "en-US", "ja-JP"],
  "oldKey": "common.btn.save",
  "newKey": "common.actions.save"
}

sync_catalog

当前是 MVP 预留接口，用于未来对接：

• Lokalise
• Crowdin
• 本地 JSON 导入导出

示例参数：

{
  "provider": "json",
  "mode": "pull",
  "lang": "de"
}

Output Behavior

为了降低误改代码和误写翻译文件的风险，当前版本默认采用“建议变更”模式：

• 返回结构化 JSON 结果
• 返回受影响文件列表
• 返回 unified diff
• 不默认直接改写文件

这让 MCP Client 可以在应用补丁前先做确认。

Recommended Project Structure

推荐项目目录类似这样：

src/
  pages/
  components/
  locales/
    zh-CN.json
    en-US.json
    ja-JP.json

Local Development

如果你要在本地开发这个 MCP Server：

npm install
npm run check
npm run build
npm start

Current Limitations

• Vue 模板替换目前是偏保守的 MVP 实现
• extract_replace 还不会自动补 t() 的 import 或 hook 注入
• sync_catalog 目前还没有接入真实 provider API

License

MIT