JinDaGe - rosetta MCP Details

article

README

🚀 Rosetta

Rosetta 是一款由人工智能驱动的 Excel 翻译命令行工具，它能够在翻译 Excel 文件的同时，完美保留文件的格式、公式和数据完整性。

🚀 快速开始

Rosetta 借助 Claude AI 对 Excel 文件中的所有文本进行翻译，且不会破坏以下内容：

公式和计算
格式（字体、颜色、边框）
合并单元格和布局
图表和图像
下拉菜单
富文本（单元格内的粗体、斜体）

✨ 主要特性

精准翻译：利用 Claude AI 进行文本翻译，保证翻译质量。
格式保留：在翻译过程中，完整保留 Excel 文件的格式、公式、合并单元格等内容。
多语言支持：支持多种目标语言的翻译。
灵活配置：可指定源语言、目标语言、输出文件路径、翻译的工作表等。
实时进度：通过 Server-Sent Events (SSE) 实现实时翻译进度跟踪。
MCP 集成：支持与 Claude Desktop 和 Claude Web 进行 MCP 集成。

📦 安装指南

安装 Rosetta

从 PyPI 安装：

pip install rosetta-xl

设置 API 密钥

你需要从 Anthropic 获取 Claude API 密钥。

访问 console.anthropic.com
创建账户（或登录）
进入 API Keys 并创建新密钥
复制密钥（以 sk-ant- 开头）

设置 API 密钥有以下几种方式：

Linux/macOS

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Windows (Command Prompt)

set ANTHROPIC_API_KEY=sk-ant-your-key-here

Windows (PowerShell)

$env:ANTHROPIC_API_KEY="sk-ant-your-key-here"

或者在工作目录中创建一个 .env 文件：

ANTHROPIC_API_KEY=sk-ant-your-key-here

⚠️ 重要提示

API 使用由 Anthropic 计费。请查看 anthropic.com/pricing 获取当前费率。翻译一个典型的 Excel 文件通常只需几美分。

💻 使用示例

基础用法

# 翻译为法语
rosetta input.xlsx -t french

# 翻译为西班牙语并指定输出文件名
rosetta input.xlsx -t spanish -o translated.xlsx

# 指定源语言（默认自动检测）
rosetta input.xlsx -s english -t german

# 仅翻译特定工作表
rosetta input.xlsx -t french --sheets "Sheet1" --sheets "Data"

# 添加上下文以提高翻译质量（例如特定领域术语）
rosetta input.xlsx -t french -c "Medical terminology document"

高级用法

翻译价格表到多种语言

rosetta prices.xlsx -t french -o prices_fr.xlsx
rosetta prices.xlsx -t german -o prices_de.xlsx
rosetta prices.xlsx -t spanish -o prices_es.xlsx

翻译带有上下文的医疗表格

rosetta patient_form.xlsx -t french -c "Medical intake form with clinical terminology"

仅翻译 "Questions" 工作表

rosetta survey.xlsx -t japanese --sheets "Questions"

📚 详细文档

选项说明

| 选项 | 缩写 | 描述 | |------|------|------| | --target-lang | -t | 目标语言（必需） | | --source-lang | -s | 源语言（省略则自动检测） | | --output | -o | 输出文件路径（默认：input_translated.xlsx） | | --sheets | | 要翻译的工作表（可重复，默认：所有） | | --context | -c | 用于提高准确性的领域上下文 | | --batch-size | -b | 每次 API 调用的单元格数（默认：50） |

故障排除

"ANTHROPIC_API_KEY not set"

确保已导出密钥：export ANTHROPIC_API_KEY=sk-ant-...
或者创建一个包含密钥的 .env 文件

"Invalid API key"

检查密钥是否以 sk-ant- 开头
确保从 console.anthropic.com 复制了完整的密钥

"Rate limit exceeded"

你已达到 Anthropic 的速率限制。等待一分钟后再试
或者减小批量大小：rosetta input.xlsx -t french -b 20

🔧 技术细节

工作原理

从 Excel 文件中提取所有文本单元格
将文本分批发送到 Claude AI 进行翻译
将翻译结果写回文件，同时保留所有格式
保存翻译后的文件

你的原始文件不会被修改。

Web 应用和 API

Rosetta 还包含一个 Web 应用程序和 REST API，用于基于浏览器的翻译。

运行 API 服务器

# 使用 uv 安装（推荐）
uv sync

# 启动服务器
uv run uvicorn rosetta.api:app --reload

# 或者使用 pip
pip install -e .
uvicorn rosetta.api:app --reload

API 默认运行在 http://localhost:8000。

运行前端

cd frontend
npm install
npm run dev

前端运行在 http://localhost:5173 并连接到 API。

API 端点

| 端点 | 方法 | 描述 | |------|------|------| | /translate | POST | 翻译 Excel 文件（返回文件） | | /translate-stream | POST | 通过 SSE 实现实时翻译进度 | | /estimate | POST | 获取单元格数量和成本估算 | | /sheets | POST | 列出文件中的工作表名称 | | /count | POST | 计算可翻译的单元格数量 | | /preview | POST | 预览将被翻译的单元格 | | /health | GET | 健康检查 |

实时进度

/translate-stream 端点使用 Server-Sent Events (SSE) 实时流式传输翻译进度。在不支持 SSE 的网络（例如企业代理）中，前端会自动回退到标准的 /translate 端点。

MCP 集成

Rosetta 包含适用于 Claude Desktop 和 Claude Web 的 MCP（Model Context Protocol）服务器。

对于 Claude Desktop（本地）

将以下内容添加到你的 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "rosetta": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/rosetta", "python", "-m", "rosetta.api.mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}

使用方法：使用本地文件路径以获得最佳效果。

Translate ~/Downloads/report.xlsx to French

对于 Claude Web（浏览器）

注意：截至 2026 年 1 月，Claude.ai 尚不支持在浏览器中使用自定义 MCP 服务器。

当前建议：使用 Web 应用进行基于浏览器的翻译。

详细说明请参阅 MCP_USAGE.md。

📄 许可证

本项目采用 MIT 许可证。

📦 要求

Python 3.11+
Anthropic API 密钥

rosetta