Localizable Xcstrings MCP

🚀 Localizable XStrings MCP Server

A Model Context Protocol (MCP) server offering tools for handling iOS Localizable.xcstrings files. It enables automated translation workflows and localization management for iOS/macOS projects using Xcode String Catalogs.

🚀 Quick Start

This Localizable XStrings MCP Server provides a set of tools for working with iOS Localizable.xcstrings files. To get started, follow the setup and usage instructions below.

✨ Features

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

📦 Installation

Prerequisites

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

Steps

1. Clone the repository:

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

2. Install dependencies with uv:

uv sync

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 the 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 Examples

Running the MCP Server

Start the server with:

uv run src/localizable_xstrings_mcp/server.py 

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 the 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

1. Install and Configure

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

uv sync

2. Add to Claude Code

Use the fastmcp install command:

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

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 the 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 the 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

📚 Documentation

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 are processed simultaneously.
• Token Limit Protection: Prevents API context limit issues.
• Progress Reporting: Shows the processing status for large jobs.
• Cost - Effective: Uses the OpenAI API for translations.

🧪 Testing

Run the test suite:

uv run pytest tests/test_xcstrings_tools.py -v

🤝 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.