Localizable XStrings

Translation Mcp For Localizable.xcstrings file

python

5

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "iamnotagentleman-localizable-xcstrings-mcp": {
      "command": "uv",
      "args": [
        "run",
        "src/localizable_xstrings_mcp/server.py"
      ],
      "env": {
        "OPENAI_MODEL": "gpt-4o-mini",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
        "OPENAI_BASE_URL": "https://api.openai.com"
      }
    }
  }
}

You run a local MCP server that helps you manage iOS Localizable.xcstrings files. It lets you extract languages and keys, translate strings with OpenAI, and apply translations back to your .xcstrings files, all while preserving structure and workflow efficiency.

How to use

Use an MCP client to connect to the Localizable XStrings MCP Server. You will upload your .xcstrings files, inspect available languages and keys, preview translations, and then apply translations back to your files. The workflow centers on extracting source data, sending translation requests in manageable chunks, and writing the results back without losing the file layout.

How to install

Prerequisites include Python 3.12 or newer and the uv tool to run MCP servers. An OpenAI API key is required for translation features.

# Prerequisites
python3 --version
uv --version

# Install and run the MCP server (local stdio variant)
# 1) Clone the project
git clone git@github.com:iamnotagentleman/localizable-xcstrings-mcp.git
cd localizable-xcstrings-mcp

# 2) Run the server directly using uv as described in usage
uv run src/localizable_xstrings_mcp/server.py

Configuration and environment

Configure your environment to enable translations and keep credentials secure.

OPENAI_API_KEY=your_openai_api_key_here
# Optional customization
OPENAI_MODEL=gpt-4o-mini
TRANSLATION_CHUNK_SIZE=50
TRANSLATION_TEMPERATURE=0.0
TRANSLATION_MAX_CONCURRENT_CHUNKS=3
TRANSLATION_RATE_LIMIT_DELAY=0.5

Files and formats

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

Handling translations

Translations are processed in chunks of up to 50 strings, with asynchronous concurrency to speed up large jobs. You can preview translations before applying them to ensure accuracy and consistency.

Starting tips

When starting the server, use the exact start command shown in the usage instructions to ensure the MCP client can connect and send requests.

Available tools

get_languages_tool

Extract supported language codes from .xcstrings files

get_keys_tool

List all localization keys from the base strings file

get_base_strings_tool

Extract base language key-value pairs for reference

translate_tool

Preview translations using OpenAI API before applying them

apply_tool

Translate and apply translations to .xcstrings files for a target language

apply_missing_tool

Translate and apply only missing translations for a target language

translate_key_tool

Translate specific keys to multiple languages