localizable-xcstrings-mcp

🚀 可本地化XStrings MCP服务器

这是一个模型上下文协议（MCP）服务器，为处理iOS的Localizable.xcstrings文件提供工具。该工具借助Xcode字符串目录，实现了iOS/macOS项目的自动翻译工作流和本地化管理。

🚀 快速开始

运行MCP服务器

使用以下命令启动服务器：

uv run src/localizable_xstrings_mcp/server.py 

这将启动一个FastMCP界面，你可以在其中：

• 上传.xcstrings文件
• 提取语言信息和键
• 将字符串翻译成目标语言
• 将翻译应用回文件

添加到Claude Code

若要在Claude Code中使用此MCP服务器，请按以下步骤操作：

1. 安装和配置：首先，确保该软件包已安装在你的Python环境中：

uv sync

2. 添加到Claude Code：使用fastmcp install命令：

fastmcp install claude-code server.py --name "localizable-xcstrings" \
  --env OPENAI_API_KEY=your_api_key \
  --env OPENAI_MODEL=gpt-4o-mini

3. 重启Claude Code：安装完成后，重启Claude Code以加载新的MCP服务器。
4. 验证安装：在Claude Code中，你现在应该可以使用以下工具：

• get_languages_tool
• get_keys_tool
• get_base_strings_tool
• translate_tool
• apply_tool
• apply_missing_tool
• translate_key_tool

✨ 主要特性

• 提取语言支持：从.xcstrings文件中获取所有支持的语言代码
• 键管理：提取所有本地化键和基础语言字符串
• 自动翻译：使用OpenAI API翻译字符串
• 批量处理：分块翻译（每块50个字符串），支持异步并发
• 文件管理：将翻译应用回.xcstrings文件，同时保留文件结构
• 经济高效：使用OpenAI API进行翻译

📦 安装指南

前提条件

• Python 3.12+
• uv（Python包管理器）
• OpenAI API密钥（用于翻译功能）

安装步骤

1. 克隆仓库：

git clone <repository-url>
cd localizable-xcstrings-mcp

2. 使用uv安装依赖项：

uv sync

配置

1. 获取OpenAI API密钥：从 platform.openai.com 获取。
2. 创建.env文件：并添加你的OpenAI API密钥：

OPENAI_API_KEY=your_openai_api_key_here

3. 可选：在.env文件中自定义其他设置：

• OPENAI_MODEL：选择翻译模型（默认：gpt-4o-mini）
• TRANSLATION_CHUNK_SIZE：调整大文件的批量大小
• TRANSLATION_TEMPERATURE：控制翻译的创造性（0.0 - 1.0）
• TRANSLATION_MAX_CONCURRENT_CHUNKS：限制并发API请求
• TRANSLATION_RATE_LIMIT_DELAY：API调用之间的延迟

💻 使用示例

示例工作流

1. 从.xcstrings文件中提取信息：

使用get_languages_tool并指定Localizable.xcstrings文件的路径

2. 获取所有本地化键：

使用get_keys_tool列出所有本地化键

3. 翻译成新语言：

使用apply_tool并指定目标语言（例如，"de" 代表德语）
确保你的.env文件中已正确配置OpenAI API密钥

4. 翻译特定键：

使用translate_key_tool翻译单个字符串

📚 详细文档

可用工具

1. 获取语言：从.xcstrings文件中提取支持的语言代码
2. 获取键：列出所有本地化键
3. 获取基础字符串：提取基础语言的键值对
4. 翻译：使用OpenAI API预览翻译结果
5. 应用翻译：将翻译应用到.xcstrings文件
6. 应用缺失翻译：仅翻译并应用目标语言中缺失的翻译
7. 翻译键：将特定键翻译成多种语言

环境变量

所有配置都通过.env文件中的环境变量进行管理： | 属性 | 详情 | |------|------| | OPENAI_API_KEY | 必需，你的OpenAI API密钥 | | OPENAI_MODEL | 可选，翻译模型（默认：gpt-4o-mini） | | OPENAI_BASE_URL | 可选，自定义API基础URL | | TRANSLATION_CHUNK_SIZE | 可选，每个API请求的字符串数量（默认：50） | | TRANSLATION_TEMPERATURE | 可选，模型创造性（0.0 - 1.0，默认：0.3） | | TRANSLATION_MAX_CONCURRENT_CHUNKS | 可选，最大并发请求数（默认：2） | | TRANSLATION_RATE_LIMIT_DELAY | 可选，请求之间的延迟（秒，默认：1.0） |

文件格式支持

此工具支持Xcode 15+的字符串目录文件（.xcstrings）。这些文件使用JSON结构存储本地化字符串和元数据。

翻译特性

• 分块处理：大型翻译任务会被拆分为50个字符串的块
• 异步并发：最多可同时处理3个块
• 令牌限制保护：防止API上下文限制问题
• 进度报告：显示大型任务的处理状态
• 经济高效：使用OpenAI API进行翻译

🔧 技术细节

测试

运行测试套件：

uv run pytest tests/test_xcstrings_tools.py -v

🤝 贡献指南

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 运行测试套件
6. 提交拉取请求

🛠️ 支持与反馈

若遇到问题或有疑问：

• 查看测试文件以获取使用示例
• 在仓库中创建问题报告