Localizable XStrings MCP Server

Localizable XStrings MCP Server

A Model Context Protocol (MCP) server that provides tools for working with iOS Localizable.xcstrings files. This tool enables automated translation workflows and localization management for iOS/macOS projects using Xcode String Catalogs.

Features

• Extract Language Support: Get all supported language codes from .xcstrings files
• Key Management: Extract all localization keys and base language strings
• Automated Translation: Translate strings using OpenAI API
• Batch Processing: Chunked translation (50 strings per chunk) with async concurrency
• File Management: Apply translations back to .xcstrings files while preserving structure
• Cost-Effective: Uses OpenAI API for translations

Setup

Prerequisites

• Python 3.12+
• uv (Python package manager)
• OpenAI API key (for translation features)

Installation

1. Clone the repository:

2. Install dependencies with uv:

Configuration

1. Get an OpenAI API key from platform.openai.com
2. Create a .env file and add your OpenAI API key:
   OPENAI_API_KEY=your_openai_api_key_here
3. Optional: Customize other settings in the .env file:
   • OPENAI_MODEL: Choose the translation model (default: gpt-4o-mini)
   • TRANSLATION_CHUNK_SIZE: Adjust batch size for large files
   • TRANSLATION_TEMPERATURE: Control translation creativity (0.0-1.0)
   • TRANSLATION_MAX_CONCURRENT_CHUNKS: Limit concurrent API requests
   • TRANSLATION_RATE_LIMIT_DELAY: Delay between API calls

Usage

Running the MCP Server

Start the server with:

This will launch a FastMCP interface where you can:

• Upload .xcstrings files
• Extract language information and keys
• Translate strings to target languages
• Apply translations back to files

Available Tools

1. Get Languages: Extract supported language codes from .xcstrings files
2. Get Keys: List all localization keys
3. Get Base Strings: Extract base language key-value pairs
4. Translate: Preview translations using OpenAI API
5. Apply Translations: Translate and apply to .xcstrings files
6. Apply Missing: Translate and apply only missing translations for a target language
7. Translate Key: Translate specific keys to multiple languages

Adding to Claude Code

To use this MCP server with Claude Code, follow these steps:

1. Install and Configure

First, ensure the package is installed in your Python environment:

2. Add to Claude Code

Use the fastmcp install command:

3. Restart Claude Code

After installation, restart Claude Code to load the new MCP server.

4. Verify Installation

In Claude Code, you should now have access to these tools:

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

Example Workflow

1. Extract information from your .xcstrings file:
   Use get_languages_tool with path to your Localizable.xcstrings file
2. Get all localization keys:
   Use get_keys_tool to see all string identifiers
3. Translate to a new language:
   Use apply_tool with target language (e.g., "de" for German) Ensure your .env file is properly configured with your OpenAI API key
4. Translate specific keys:
   Use translate_key_tool for individual string translations

Environment Variables

All configuration is managed through environment variables in the .env file:

File Format Support

This tool works with Xcode 15+ String Catalog files (.xcstrings). These files use a JSON structure to store localized strings and metadata.

Translation Features

• Chunked Processing: Large translation jobs are split into 50-string chunks
• Async Concurrency: Up to 3 chunks processed simultaneously
• Token Limit Protection: Prevents API context limit issues
• Progress Reporting: Shows processing status for large jobs
• Cost-Effective: Uses OpenAI API for translations

Testing

Run the test suite:

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

Support

For issues and questions:

• Check the test files for usage examples
• Open an issue on the repository