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文件中的環境變量進行管理：

文件格式支持

此工具支持Xcode 15+的字符串目錄文件（.xcstrings）。這些文件使用JSON結構存儲本地化字符串和元數據。

翻譯特性

• 分塊處理：大型翻譯任務會被拆分為50個字符串的塊
• 異步併發：最多可同時處理3個塊
• 令牌限制保護：防止API上下文限制問題
• 進度報告：顯示大型任務的處理狀態
• 經濟高效：使用OpenAI API進行翻譯

🔧 技術細節

測試

運行測試套件：

uv run pytest tests/test_xcstrings_tools.py -v

🤝 貢獻指南

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 為新功能添加測試
5. 運行測試套件
6. 提交拉取請求

🛠️ 支持與反饋

若遇到問題或有疑問：

• 查看測試文件以獲取使用示例
• 在倉庫中創建問題報告