使用说明

LinguaGuard--i18n MCP服务器

直接从AI编辑器管理您的翻译。
适用于Claude Desktop、Cursor、VS Code、Windsurf、Zed和Cline。

LinguaGuard是当地人模型上下文协议（MCP）服务器，赋予您的AI编辑器超越i18n设置的超能力。问你的人工智能自然问题——它会在幕后自动调用正确的工具。

没有npm发布。没有云。完全在您的机器上运行。

它能做什么？

当你问你的AI…	LinguaGuard运行。..
“缺少哪些翻译键？”	`find_missing_keys`
“是否有未使用的翻译密钥？”	`find_unused_keys`
“添加密钥 `auth.forgot_password` 所有语言”	`sync_key`
“检查我的钥匙是否跟在snake_case后面”	`check_naming_convention`
“给我一份i18n健康报告”	`i18n_health_report`
“为我丢失的密钥提供翻译建议”	`suggest_translations`
“运行CI/CD的i18n检查”	`ci_guard`

需求

Node.js v20或更高版本（建议使用v24）
一个包含JSON语言环境文件（React、Next.js、Vue、Nuxt、Svelte等）的前端项目
支持MCP的AI编辑器（请参阅下面支持的编辑器）

快速开始

步骤1--克隆并构建LinguaGuard

git clone https://github.com/prodip2416/linguaguard.git
cd linguaguard
npm install
npm run build

构建完成后，服务器已准备就绪 dist/index.js.

步骤2——连接到编辑器

从以下部分复制编辑器的配置。替换 path/to/linguaguard 随着 绝对路径 到您克隆此仓库的文件夹。

步骤3--重新启动编辑器并开始提问

打开任何前端项目并询问您的AI：

“我的法语和孟加拉语文件中缺少哪些i18n密钥？”

LinguaGuard将自动查找并检查您的区域设置文件。

环境变量（配置）

所有配置都是通过编辑器MCP配置中的环境变量传递的：

变量	必填	默认	描述
`LOCALES_PATH`	是的	`./src/locales`	区域设置JSON文件文件夹的路径
`LANGUAGES`	是的	`en`	逗号分隔的语言代码（例如。 `en,fr,bn,ar`)
`PRIMARY_LANG`	是的	`en`	将所有其他参考语言进行比较
`FILE_EXTENSION`	没有	`json`	区域设置文件扩展名（目前支持 `json`)
`NAMING_CONVENTION`	没有	`snake_case`	按键样式： `snake_case`, `camelCase`, `kebab-case`, `PascalCase`
`ANTHROPIC_API_KEY`	否	--	只需要 `suggest_translations`.如果不使用AI翻译，请省略。永远不要将此提交给git。
`PROJECT_ROOT`	没有	`.`	用于扫描密钥使用情况的根目录（用于未使用的密钥检测）

区域设置文件夹结构示例

src/
└── locales/
    ├── en.json    ← primary language
    ├── fr.json
    ├── bn.json
    └── ar.json

每个文件都是一个标准的JSON转换文件：

{
  "auth": {
    "login": "Log in",
    "logout": "Log out",
    "forgot_password": "Forgot your password?"
  },
  "common": {
    "submit": "Submit",
    "cancel": "Cancel"
  }
}

编辑器连接配置

替换 path/to/linguaguard 随着 绝对路径 到你克隆这个仓库的地方。
Mac上的示例： /Users/yourname/projects/linguaguard
Windows上的示例： C:\\Users\\yourname\\projects\\linguaguard

1.克劳德桌面

编辑文件： ~/Library/Application Support/Claude/claude_desktop_config.json
（Mac）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）

{
  "mcpServers": {
    "linguaguard": {
      "command": "node",
      "args": ["/absolute/path/to/linguaguard/dist/index.js"],
      "env": {
        "LOCALES_PATH": "/absolute/path/to/your-project/src/locales",
        "LANGUAGES": "en,fr,bn,ar",
        "PRIMARY_LANG": "en",
        "FILE_EXTENSION": "json",
        "NAMING_CONVENTION": "snake_case",
        "ANTHROPIC_API_KEY": "your_api_key_here"  // optional — only needed for suggest_translations
      }
    }
  }
}

保存后重新启动Claude Desktop。您应该在工具列表中看到LinguaGuard。

2.光标

创建或编辑文件： .cursor/mcp.json 在您的主目录或项目根目录中。

{
  "mcpServers": {
    "linguaguard": {
      "command": "node",
      "args": ["/absolute/path/to/linguaguard/dist/index.js"],
      "env": {
        "LOCALES_PATH": "/absolute/path/to/your-project/src/locales",
        "LANGUAGES": "en,fr,bn,ar",
        "PRIMARY_LANG": "en",
        "FILE_EXTENSION": "json",
        "NAMING_CONVENTION": "snake_case",
        "ANTHROPIC_API_KEY": "your_api_key_here"  // optional — only needed for suggest_translations
      }
    }
  }
}

首选 光标设置→ MCP 并验证LinguaGuard是否显示为已连接的服务器。

3.VS代码（克劳德扩展）

创建文件 .vscode/mcp.json 在项目文件夹中：

{
  "servers": {
    "linguaguard": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/linguaguard/dist/index.js"],
      "env": {
        "LOCALES_PATH": "/absolute/path/to/your-project/src/locales",
        "LANGUAGES": "en,fr,bn,ar",
        "PRIMARY_LANG": "en",
        "FILE_EXTENSION": "json",
        "NAMING_CONVENTION": "snake_case",
        "ANTHROPIC_API_KEY": "your_api_key_here"  // optional — only needed for suggest_translations
      }
    }
  }
}

当您打开项目时，Claude VS Code扩展会自动拾取此信息。

4.风浪

编辑文件： ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "linguaguard": {
      "command": "node",
      "args": ["/absolute/path/to/linguaguard/dist/index.js"],
      "env": {
        "LOCALES_PATH": "/absolute/path/to/your-project/src/locales",
        "LANGUAGES": "en,fr,bn,ar",
        "PRIMARY_LANG": "en",
        "FILE_EXTENSION": "json",
        "NAMING_CONVENTION": "snake_case",
        "ANTHROPIC_API_KEY": "your_api_key_here"  // optional — only needed for suggest_translations
      }
    }
  }
}

保存后重新启动Windsurf。

5.Zed

编辑 ~/.config/zed/settings.json 并添加a context_servers 章节：

{
  "context_servers": {
    "linguaguard": {
      "command": {
        "path": "node",
        "args": ["/absolute/path/to/linguaguard/dist/index.js"],
        "env": {
          "LOCALES_PATH": "/absolute/path/to/your-project/src/locales",
          "LANGUAGES": "en,fr,bn,ar",
          "PRIMARY_LANG": "en",
          "FILE_EXTENSION": "json",
          "NAMING_CONVENTION": "snake_case",
          "ANTHROPIC_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

6.Cline（VS代码扩展）

打开VS代码设置 (Cmd+,)，切换到JSON视图，并添加：

{
  "cline.mcpServers": {
    "linguaguard": {
      "command": "node",
      "args": ["/absolute/path/to/linguaguard/dist/index.js"],
      "env": {
        "LOCALES_PATH": "/absolute/path/to/your-project/src/locales",
        "LANGUAGES": "en,fr,bn,ar",
        "PRIMARY_LANG": "en",
        "FILE_EXTENSION": "json",
        "NAMING_CONVENTION": "snake_case",
        "ANTHROPIC_API_KEY": "your_api_key_here"  // optional — only needed for suggest_translations
      }
    }
  }
}

工具参考

`find_missing_keys`

查找主语言文件中存在但其他语言中不存在的键。

示例提示： “我的法语翻译文件中缺少哪些密钥？”

`find_unused_keys`

扫描所有JS/TS/JSX/TSX/Vue/Svelte源文件，查找已定义但从未在代码中调用的翻译键。

示例提示： “我有可以删除的未使用的翻译密钥吗？”

注意：动态键如 t(`prefix.${variable}`) 无法静态检测。手动查看这些。

`sync_key`

向添加新密钥全部语言文件一次。主要语言获得了真正的价值。所有其他语言都获得 [TODO] 占位符。

示例提示： “添加密钥 auth.reset_password 将值“重置密码”设置为所有语言文件。"

参数：

key --点符号键名（例如。 auth.reset_password)
value --主要语言翻译
overwrite （可选） --设置为 true 如果密钥已存在，则覆盖

`check_naming_convention`

根据命名约定检查所有翻译键，并报告任何违规行为。

示例提示： “我的所有翻译密钥都遵循snake_case命名吗？”

支持的约定： snake_case, camelCase, kebab-case, PascalCase

`i18n_health_report`

将所有检查与健康评分（0-100）合并到一个仪表板中。

显示：

每种语言的完整性百分比
缺少密钥计数
未使用的密钥计数
命名违规
可采取行动的建议

示例提示： “为我的项目提供一份完整的i18n健康报告。”

`suggest_translations`

使用 Claude AI API 为所有缺失的密钥提供翻译建议。按语言对结果进行分组，并返回以供查看。

要求： 你自己的 ANTHROPIC_API_KEY 在MCP配置环境中。没有绑定或共享密钥。

示例提示： “为我丢失的钥匙建议法语和孟加拉语翻译。”

翻译仅供参考——使用 sync_key 在审查后应用它们。

`ci_guard`

检查是否缺少密钥，并返回包含完整详细信息的通过/失败状态。设计用于CI/CD管道审查。

示例提示： “运行i18n CI检查——我们准备好合并了吗？”

对于实际的CI管道，您可以直接运行检查：

# In your GitHub Actions / GitLab CI pipeline:
LOCALES_PATH=./src/locales \
LANGUAGES=en,fr,bn,ar \
PRIMARY_LANG=en \
node /path/to/linguaguard/dist/index.js --ci-guard
# Exits with code 0 (pass) or 1 (fail — missing keys found)

示例：完整工作流

您添加了一个需要翻译密钥的新功能
问你的AI： “添加密钥 dashboard.welcome_message with value“欢迎回来！“适用于所有语言”
- LinguaGuard运行 sync_key → 增加 en.json，放 [TODO] 在 fr.json, bn.json, ar.json
问： “建议将缺失的键翻译成法语和孟加拉语”
- LinguaGuard运行 suggest_translations → Claude返回翻译后的值
问： 将法语翻译“Bon retour！”应用于 dashboard.welcome_message"
- LinguaGuard运行 sync_key 和 overwrite: true 法语
合并前： “运行CI保护检查”
- LinguaGuard运行 ci_guard → 确认所有语言都完整✅

故障排除

服务器未连接？

确保你跑了 npm run build 和 dist/index.js 存在
使用 绝对路径 到 dist/index.js 在编辑器配置中（非相对）
检查编辑器的MCP日志，查看LinguaGuard的错误消息

“找不到本地目录”错误？

这 LOCALES_PATH 在您的配置中，与AI编辑器启动服务器的位置有关，而不是与LinguaGuard所在的位置有关。使用绝对路径以确保安全：
"LOCALES_PATH": "/absolute/path/to/your-project/src/locales"

suggest_translations 不工作？

确保 ANTHROPIC_API_KEY 在MCP配置环境中设置
密钥必须有效，并且可以访问 claude-sonnet-4-5

未使用的密钥工具显示太多误报？

如果你使用动态翻译键，比如 t(`nav.${page}`)，这些无法静态检测，将显示为“未使用”。手动添加评论或评论。

支持的语言

LinguaGuard与 任何语言 它使用JSON语言环境文件。这 suggest_translations 该工具内置了对这些语言的AI支持：

代码	语言	代码	语言
`en`	英语	`ko`	朝鲜语
`bn`	孟加拉语（孟加拉语）	`hi`	印地语
`ar`	阿拉伯语	`tr`	土耳其语
`fr`	法语	`pl`	波兰语
`de`	德语	`sv`	瑞典语
`es`	西班牙语	`da`	丹麦语
`pt`	葡萄牙语	`fi`	芬兰语
`it`	意大利语	`no`	挪威语
`nl`	荷兰语	`uk`	乌克兰语
`ru`	俄罗斯人	`vi`	越南语
`zh`	中文（简体）	`th`	泰语
`ja`	日语	`id`	印尼语
`ms`	马来语	`ro`	罗马尼亚语
`cs`	捷克语	`sk`	斯洛伐克语
`hu`	匈牙利语	`el`	希腊语
`he`	希伯来语	`fa`	波斯语（波斯语）

对于不在此列表中的任何其他语言，AI翻译仍将尝试直接使用语言代码进行翻译。

项目结构

linguaguard/
├── src/
│   ├── index.ts                  # MCP server — registers all tools
│   ├── tools/
│   │   ├── missingKeys.ts        # find_missing_keys tool
│   │   ├── unusedKeys.ts         # find_unused_keys tool
│   │   ├── syncKeys.ts           # sync_key tool
│   │   ├── namingChecker.ts      # check_naming_convention tool
│   │   ├── healthReport.ts       # i18n_health_report tool
│   │   ├── aiTranslation.ts      # suggest_translations tool
│   │   └── ciGuard.ts            # ci_guard tool
│   └── utils/
│       ├── fileReader.ts         # reads and flattens locale JSON files
│       └── codeScanner.ts        # scans source files for key usage
├── test-locales/                 # demo locale files for quick testing
│   ├── en.json                   # primary language (complete)
│   ├── fr.json                   # intentionally incomplete — for demo
│   └── bn.json                   # intentionally incomplete — for demo
├── .github/
│   └── workflows/
│       └── ci.yml                # GitHub Actions — build + i18n guard
├── dist/                         # compiled output (run npm run build)
├── mcpize.yaml                   # mcpize marketplace config
├── package.json
├── tsconfig.json
└── README.md

尝试一下（本地演示）

A. test-locales/ 文件夹中包含故意不完整的翻译，因此您可以在安装后立即尝试LinguaGuard：

# Point to the included demo locales
LOCALES_PATH=./test-locales LANGUAGES=en,fr,bn PRIMARY_LANG=en node dist/index.js --ci-guard

fr 和 bn 缺少几个密钥——非常适合测试 find_missing_keys 和 suggest_translations.

构建命令

npm run build    # compile TypeScript → dist/
npm run clean    # delete dist/ folder
npm run dev      # run directly with tsx (dev only, requires tsx)
npm start        # run compiled server: node dist/index.js

许可证

MIT——免费使用、修改和分发。

使用说明

LinguaGuard--i18n MCP服务器

它能做什么？

需求

快速开始

步骤1--克隆并构建LinguaGuard

步骤2——连接到编辑器

步骤3--重新启动编辑器并开始提问

环境变量（配置）

区域设置文件夹结构示例

编辑器连接配置

1.克劳德桌面

2.光标

3.VS代码（克劳德扩展）

4.风浪

5.Zed

6.Cline（VS代码扩展）

工具参考

find_missing_keys

find_unused_keys

sync_key

check_naming_convention

i18n_health_report

suggest_translations

ci_guard

示例：完整工作流

故障排除

支持的语言

项目结构

尝试一下（本地演示）

构建命令

许可证

相关 MCP

AKShare One MCP 股市数据服务

实时网络搜索服务

arXiv 论文检索 MCP 服务器

移动自动化MCP服务器

AI持久记忆服务器

Git仓库管理MCP服务器