i18n-agent

🌍 i18n-agent MCP 客户端

适用于 Claude、Cursor、VS Code、Antigravity 及其他 AI IDE 的专业翻译服务客户端，使用 Model Context Protocol（MCP）。

✨ 功能

• 🎯 智能翻译：结合上下文进行翻译，并适应文化差异
• 📁 文件翻译：支持 JSON、YAML、CSV、XML、Markdown 等格式
• ⚡ 大文件支持：异步处理大于 50KB 的文件，并跟踪进度
• 🔄 超时优化：为大型翻译任务延长超时时间（5–10 分钟）
• 📊 进度跟踪：实时查看任务状态和完成情况
• 💰 额度跟踪：实时查看额度余额和预估字数
• 🌐 支持 48 种语言：全面支持多种语言及地区变体
• 🔧 轻松配置：为主流 AI IDE 提供一键安装

🚀 快速安装

npx @i18n-agent/mcp-client install

安装程序将检测所有可用的 AI IDE 并自动完成配置。

从 Claude Code Marketplace 安装

Claude Code 用户可以直接从 Marketplace 安装：

步骤 1：获取 API 密钥

• 访问 app.i18nagent.ai
• 注册或登录
• 复制 API 密钥（以 "i18n_" 开头）

步骤 2：设置环境变量

echo 'export I18N_AGENT_API_KEY=your-api-key-here' >> ~/.zshrc
source ~/.zshrc

将 your-api-key-here 替换为你的实际 API 密钥。

步骤 3：从 Marketplace 安装

/plugin marketplace add i18n-agent/mcp-client
/plugin install i18n-agent@i18n-agent

步骤 4：重启 Claude Code

完成！插件将自动使用环境变量中的 API 密钥。

🔑 设置 API 密钥

1. 获取 API 密钥，请访问 app.i18nagent.ai

2. 设置环境变量：

   export I18N_AGENT_API_KEY=your-api-key-here
   

3. 将设置永久保存（添加到 ~/.bashrc 或 ~/.zshrc）：

   echo 'export I18N_AGENT_API_KEY=your-api-key-here' >> ~/.zshrc
   

4. 重启 AI IDE，以加载新配置

🎮 使用示例

文本翻译

Translate "Hello, how are you?" to Spanish for a casual audience

文件翻译

Translate this JSON file to French, preserving the structure

查看额度

Check my translation credits

语言支持

List supported languages with quality ratings

内容分析

Analyze "Hello world! This is a test." for translation to Spanish

🛠 支持的 AI IDE

IDE	状态	macOS	Windows	Linux
Claude Desktop	✅ 自动配置	~/Library/Application Support/Claude/	%APPDATA%\Claude\	~/.config/Claude/
Claude Code CLI	✅ 自动配置	~/.claude.json	~/.claude.json	~/.claude.json
Cursor	✅ 自动配置	~/.cursor/mcp_settings.json	~/.cursor/mcp_settings.json	~/.cursor/mcp_settings.json
VS Code	✅ 自动配置	~/.vscode/mcp_settings.json	~/.vscode/mcp_settings.json	~/.vscode/mcp_settings.json
Codex (OpenAI)	✅ 自动配置	~/.codex/mcp_settings.json	~/.codex/mcp_settings.json	~/.codex/mcp_settings.json
Antigravity (Google)	✅ 自动配置	~/.gemini/antigravity/mcp_config.json	%USERPROFILE%\.gemini\antigravity\mcp_config.json	~/.config/antigravity/mcp_config.json

注意： 安装程序会自动检测你的平台并使用相应的配置路径。

🌐 语言支持（48 种语言）

• bg：保加利亚语
• ca：加泰罗尼亚语
• cs：捷克语
• da：丹麦语
• de：德语
• el：希腊语
• en：英语
• en-AU：英语（澳大利亚）
• en-CA：英语（加拿大）
• en-GB：英语（英国）
• en-US：英语（美国）
• es：西班牙语
• es-MX：西班牙语（墨西哥）
• et：爱沙尼亚语
• fi：芬兰语
• fr：法语
• fr-CA：法语（加拿大）
• hi：印地语
• hr：克罗地亚语
• hu：匈牙利语
• id：印度尼西亚语
• is：冰岛语
• it：意大利语
• ja：日语
• ko：韩语
• lt：立陶宛语
• lv：拉脱维亚语
• ms：马来语
• nl：荷兰语
• no：挪威语
• pl：波兰语
• pt：葡萄牙语
• pt-BR：葡萄牙语（巴西）
• ro：罗马尼亚语
• ru：俄语
• sk：斯洛伐克语
• sl：斯洛文尼亚语
• sr：塞尔维亚语
• sv：瑞典语
• th：泰语
• tl：菲律宾语
• tr：土耳其语
• uk：乌克兰语
• vi：越南语
• zh-Hans：中文（简体）
• zh-Hant-HK：中文（繁体，香港）
• zh-Hant-TW：中文（繁体，台湾）

📁 支持的文件格式

格式	扩展名	特性
JSON	.json	保留结构和嵌套对象
YAML	.yaml、.yml	保留格式和注释
CSV	.csv	支持带引号的字段和逗号
XML/HTML	.xml、.html	提取文本内容
Markdown	.md	保留格式，跳过代码
属性文件	.properties	Java 属性键值对
纯文本	.txt	直接翻译
PDF	.pdf	提取并翻译文本
Word	.docx、.doc	文档翻译
Gettext	.po、.pot、.mo	本地化文件格式

🔧 手动设置

如果自动安装失败，你可以手动配置 IDE：

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "i18n-agent": {
      "command": "node",
      "args": ["/path/to/i18n-agent.js"],
      "env": {
        "MCP_SERVER_URL": "https://mcp.i18nagent.ai",
        "I18N_AGENT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor / VS Code

创建 .cursor/mcp_settings.json 或 .vscode/mcp_settings.json：

{
  "mcpServers": {
    "i18n-agent": {
      "command": "node", 
      "args": ["/path/to/i18n-agent.js"],
      "env": {
        "MCP_SERVER_URL": "https://mcp.i18nagent.ai",
        "I18N_AGENT_API_KEY": "your-api-key-here"
      }
    }
  }
}

💡 使用技巧

翻译上下文

• 目标受众：指定“技术”“随意”“正式”或“通用”
• 行业背景：使用“科技”“医疗保健”“金融”“教育”
• 地区差异：添加“西班牙”“墨西哥”“巴西”等地区

文件翻译

• 保留结构：保留原始文件格式和结构
• 输出格式：在不同格式间转换（JSON ↔ YAML ↔ CSV）
• 大文件：自动分块处理大文件
• 异步处理：异步处理大于 50 KB 的文件，并跟踪任务
• 进度监控：为耗时较长的翻译实时更新状态
• 超时弹性：大型翻译任务的超时时间最长可达 10 分钟

大型翻译处理

• 异步处理：超过 100 条文本或大于 50 KB 的文件将异步处理
• 任务跟踪：使用唯一任务 ID 监控耗时较长的翻译
• 进度更新：实时显示完成百分比和状态
• 延长超时：5–10 分钟的超时时间可避免中断
• 自动轮询：客户端自动轮询任务完成状态

额度管理

• 费用：每个词消耗 1 个额度（每词 $0.01）
• 监控：大型翻译前检查余额
• 估算：翻译前估算词数

质量警告

• 源内容分析：默认情况下，翻译前会分析源内容是否存在质量问题
• 跳过警告：在自动化工作流中使用 skipWarnings: true 跳过警告
• 权衡：跳过警告可能会降低翻译质量，因为潜在问题不会得到处理
• 最佳实践：生产环境中的翻译应保持警告启用（默认设置）

🚨 故障排除

安装问题

权限被拒绝：

sudo npm install -g @i18n-agent/mcp-client

未检测到 IDE：

# Check if IDE directory exists
ls ~/Library/Application\ Support/Claude/
ls ~/.cursor/
ls ~/.vscode/

MCP 连接问题

Claude Code 中显示“Failed”状态：

这通常是由 Node 版本管理器（nvm、fnm、n）导致的。安装程序现在会自动检测 nvm 并创建包装脚本。如果仍有问题：

1. 检查 Node 安装：

   which node
   # If output contains .nvm, you're using nvm
   

2. 手动创建包装脚本（如果自动检测失败）： 创建 ~/.claude/run-mcp.sh：

   #!/bin/bash
   export PATH="$(dirname $(which node)):$PATH"
   cd ~/.claude
   exec node node_modules/@i18n-agent/mcp-client/i18n-agent.js
   

   将其设为可执行文件：

   chmod +x ~/.claude/run-mcp.sh
   

3. 更新 Claude 配置： 编辑 ~/.claude.json：

   {
     "mcpServers": {
       "i18n-agent": {
         "command": "/Users/YOUR_USERNAME/.claude/run-mcp.sh",
         "env": {
           "MCP_SERVER_URL": "https://mcp.i18nagent.ai",
           "I18N_AGENT_API_KEY": "your-api-key"
         }
       }
     }
   }
   

4. 完全重启 Claude Code（不要只关闭窗口，要退出应用）

运行时问题

找不到 API 密钥：

echo $I18N_AGENT_API_KEY  # Should show your key
export I18N_AGENT_API_KEY=your-key-here

连接错误：

• 检查网络连接
• 确认 API 密钥有效
• 几秒后重试

翻译质量：

• 生产环境请使用 Tier 1 语言
• 使用行业／受众参数添加上下文
• 手动检查 Tier 2／3 翻译

📊 定价

• 按使用量付费：每个单词 1 个积分（每个单词 $0.01）
• 无订阅：只为翻译的内容付费
• 批量折扣：企业用户可享
• 免费套餐：新账户可获得入门积分

🔐 隐私与安全

• 不存储数据：翻译内容会实时处理
• 加密传输：所有数据均通过 HTTPS 发送
• API 密钥安全：密钥存储在本地，不会传输到日志中
• 符合 GDPR：遵循欧盟隐私标准

🏗️ 架构

MCP 客户端安装程序采用模块化架构，确保安装可靠无误：

lib/
├── config-manager.js      # Config file operations with atomic writes
├── installer-core.js      # Installation orchestration
├── transport-detector.js  # Auto-detect SSE vs stdio transport
└── validator.js          # Input validation and sanitization

主要功能

• 原子化配置写入：使用临时文件和重命名，确保崩溃安全
• 自动备份：修改前创建带时间戳的备份
• 传输方式检测：根据配置自动检测 SSE 或 stdio
• 全面验证：在模块边界验证所有输入
• 零外部依赖：仅使用 Node.js 内置功能

架构详情

查看详细文档：

• 模块架构 - 模块职责与设计
• 完整架构指南 - 完整的系统设计

🤝 参与贡献

欢迎贡献！请参阅我们的贡献指南。

开发环境设置

git clone https://github.com/i18n-agent/mcp-client.git
cd mcp-client
npm install
npm test

发布

使用内置测试门禁的发布脚本：

./scripts/publish-mcp-client.sh --dry-run  # Preview package
./scripts/publish-mcp-client.sh            # Run pre-publish checks
npm publish                                 # Publish to npm

📝 许可证

MIT 许可证——详情请参阅 LICENSE 文件。

版权所有 (c) 2025 FatCouple OÜ

🔗 链接

• 网站：i18nagent.ai
• 控制面板：app.i18nagent.ai
• 文档：docs.i18nagent.ai
• GitHub：github.com/i18n-agent/mcp-client
• 问题反馈：github.com/i18n-agent/mcp-client/issues

🆘 支持

• 电子邮件：[email protected]
• 文档：docs.i18nagent.ai

🔧 可用的 MCP 工具

translate_text

翻译文本内容，并进行文化适配和上下文感知。

参数：

• texts（array）：要翻译的字符串数组
• targetLanguage（string）：目标语言代码
• targetAudience（string）：目标受众背景
• industry（string）：行业背景
• namespace（string，可选）：可选的命名空间标识符，用于后端跟踪和项目组织
• sourceLanguage（string，可选）：源语言（如果未提供，则自动检测）
• region（string，可选）：用于本地化的特定地区
• skipWarnings（boolean，可选）：跳过源文本质量警告（默认值：false）。⚠️ WARNING：绕过源文本分析可能会降低翻译质量。仅在确信内容质量良好或用于自动化工作流时使用。

translate_file

翻译文件，同时保留结构和格式。

参数：

• filePath 或 fileContent（string）：要翻译的文件路径或内容
• fileType（string）：文件格式（json、yaml、xml、csv、txt、md 等）
• targetLanguage（string）：目标语言代码
• namespace（string，必填）：用于后端跟踪和项目组织的唯一命名空间标识符
• preserveKeys（boolean）：是否保留对象键/结构
• outputFormat（string）：输出格式（same、json、yaml、txt）
• skipWarnings（boolean，可选）：跳过源文本质量警告（默认值：false）。⚠️ 警告：跳过源文本分析可能会降低翻译质量。只有在确信内容质量良好或用于自动化工作流时才使用。

analyze_content

分析内容是否已准备好进行翻译，并在翻译前获取改进建议。这有助于在花费翻译额度前发现潜在问题并优化内容。

参数：

• content（string/array/object）：要分析的内容
• targetLanguage（string）：翻译目标语言
• fileType（string，可选）：如果内容来自文件，则填写文件类型
• sourceLanguage（string，可选）：源语言（自动检测）
• industry（string）：行业背景
• targetAudience（string）：目标受众
• region（string，可选）：本地化的特定地区

返回内容：

• 源语言检测及置信度评分
• 内容类型和语气分析
• 翻译准备度评分（0-100）
• 具体改进建议
• 质量指标和问题
• 潜在问题警告
• 预估所需额度

list_supported_languages

获取所有支持语言的列表及其质量评级。

参数：

• includeQuality（boolean）：是否包含质量评级（默认值：true）

get_credits

查看剩余翻译额度和字数估算。

参数：

• apiKey（string）：你的 API 密钥

check_translation_status

查看异步翻译任务的状态（适用于大型文件）。

参数：

• jobId（string）：异步翻译返回的任务 ID

---

由 FatCouple OÜ 倾情打造 ❤️