Localizable Xcstrings MCP

🚀 Localizable XStrings MCP Server

このツールは、iOSのLocalizable.xcstringsファイルを扱うためのツールを提供するModel Context Protocol (MCP)サーバーです。Xcode String Catalogsを使用するiOS/macOSプロジェクトの自動翻訳ワークフローとローカライズ管理を可能にします。

✨ 主な機能

• 言語サポートの抽出：.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. platform.openai.com からOpenAI APIキーを取得します。

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呼び出し間の遅延時間を設定します。

💻 使用例

MCPサーバーの起動

以下のコマンドでサーバーを起動します：

uv run src/localizable_xstrings_mcp/server.py 

これにより、FastMCPインターフェースが起動し、以下の操作が可能になります：

• .xcstringsファイルをアップロードする
• 言語情報とキーを抽出する
• 文字列を目的の言語に翻訳する
• 翻訳をファイルに適用する

利用可能なツール

1. 言語の取得：.xcstringsファイルからサポートされている言語コードを抽出します。
2. キーの取得：すべてのローカライズキーを一覧表示します。
3. ベース文字列の取得：ベース言語のキーと値のペアを抽出します。
4. 翻訳：OpenAI APIを使用して翻訳をプレビューします。
5. 翻訳の適用：文字列を翻訳し、.xcstringsファイルに適用します。
6. 欠落翻訳の適用：目的の言語で欠落している翻訳のみを翻訳して適用します。
7. 特定キーの翻訳：特定のキーを複数の言語に翻訳します。

Claude Codeへの追加

このMCPサーバーをClaude Codeで使用するには、以下の手順に従ってください。

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

サンプルワークフロー

1. .xcstringsファイルから情報を抽出する：

get_languages_toolを使用して、Localizable.xcstringsファイルのパスを指定します。

2. すべてのローカライズキーを取得する：

get_keys_toolを使用して、すべての文字列識別子を確認します。

3. 新しい言語に翻訳する：

apply_toolを使用して目的の言語 (例: ドイツ語の場合は "de") を指定します。
.envファイルにOpenAI APIキーが正しく設定されていることを確認します。

4. 特定のキーを翻訳する：

translate_key_toolを使用して個々の文字列の翻訳を行います。

📚 ドキュメント

環境変数

すべての設定は、.envファイル内の環境変数を通じて管理されます。

ファイル形式のサポート

このツールは、Xcode 15以上のString Catalogファイル (.xcstrings) で動作します。これらのファイルは、ローカライズされた文字列とメタデータを格納するためにJSON構造を使用しています。

翻訳機能

• チャンク処理：大規模な翻訳ジョブは50文字列ごとのチャンクに分割されます。
• 非同期並行処理：最大3つのチャンクを同時に処理します。
• トークン制限保護：APIのコンテキスト制限問題を防止します。
• 進捗報告：大規模なジョブの処理状況を表示します。
• コスト効率：翻訳にOpenAI APIを使用します。

テスト

テストスイートを実行するには、以下のコマンドを実行します：

uv run pytest tests/test_xcstrings_tools.py -v

貢献方法

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. 新機能に対するテストを追加します。
5. テストスイートを実行します。
6. プルリクエストを送信します。

サポート

問題や質問がある場合は、以下の方法で対応します：

• テストファイルを確認して使用例を参照してください。
• リポジトリに問題を登録してください。