Skip to main content
Glama
Sign In
Localizable XStrings MCP Server

Localizable XStrings MCP Server

by iamnotagentleman
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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

Related MCP server: string-catalog-mcp

Setup

Prerequisites

  • Python 3.12+

  • uv (Python package manager)

  • OpenAI API key (for translation features)

Installation

  1. Clone the repository:

git clone git@github.com:iamnotagentleman/localizable-xcstrings-mcp.git
cd localizable-xcstrings-mcp

  1. 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 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:

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

uv sync

2. Add to Claude Code

Use the fastmcp install command:

claude mcp add localizable-xcstrings --scope user -- uv run --with fastmcp fastmcp run server.py

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:

Variable

Required

Default

Description

OPENAI_API_KEY

Yes

-

Your OpenAI API key

OPENAI_MODEL

No

gpt-4o-mini

OpenAI model for translations

OPENAI_BASE_URL

No

-

Custom API base URL

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

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

Available Tools

7 tools
apply_missing_toolA
MCP tool to apply only missing translations for a target language in xcstrings file.
Only translates keys that don't already have translations in the target language.

Args:
    file_path (str): Path to the .xcstrings file
    target_language (str): Target language code
    app_description (str): Optional description of the app for better translation context

Returns:
    str: Application result with newly translated keys or error message

Inputs: file_path (required), target_language (required), app_description. Returns: result

apply_toolC
MCP tool to translate and apply translations to xcstrings file.

Args:
    file_path (str): Path to the .xcstrings file
    target_language (str): Target language code
    app_description (str): Optional description of the app for better translation context

Returns:
    str: Application result with translated keys or error message

Inputs: file_path (required), target_language (required), app_description. Returns: result

get_base_strings_toolB
MCP tool to get base language strings from xcstrings file.

Args:
    file_path (str): Path to the .xcstrings file

Returns:
    str: Base language strings or error message

Inputs: file_path (required). Returns: result

get_keys_toolC
MCP tool to get all localization keys from xcstrings file.

Args:
    file_path (str): Path to the .xcstrings file

Returns:
    str: List of all keys or error message

Inputs: file_path (required). Returns: result

get_languages_toolC
MCP tool to get supported languages from xcstrings file.

Args:
    file_path (str): Path to the .xcstrings file

Returns:
    str: JSON string of supported languages or error message

Inputs: file_path (required). Returns: result

translate_key_toolB
MCP tool to translate a specific key to multiple target languages and apply translations.

Args:
    file_path (str): Path to the .xcstrings file
    key (str): The specific key to translate
    target_languages (str): Comma-separated list of target language codes (e.g., "es,fr,de")
    app_description (str): Optional description of the app for better translation context

Returns:
    str: Translation results or error message

Inputs: file_path (required), key (required), target_languages (required), app_description. Returns: result

translate_toolC
MCP tool to translate strings to target language and return translated keys.

Args:
    file_path (str): Path to the .xcstrings file
    target_language (str): Target language code

Returns:
    str: Translation result with translated keys or error message

Inputs: file_path (required), target_language (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    B3.3/5.0

    Scored across 7 tools

    Disambiguation3/5

    There is significant overlap between translate_tool, apply_tool, and translate_key_tool, as all involve translating strings, which could confuse an agent. However, apply_missing_tool is distinct by focusing only on missing translations, and get_* tools are clearly separate for retrieval purposes.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern (e.g., get_keys_tool, translate_key_tool), but apply_missing_tool and apply_tool deviate slightly by omitting the noun, which is a minor inconsistency. Overall, the naming is readable and predictable.

    Tool Count5/5

    With 7 tools, the count is well-scoped for managing xcstrings files, covering retrieval, translation, and application operations. Each tool serves a distinct role in the localization workflow, making the set appropriately sized.

    Completeness4/5

    The toolset covers key aspects like retrieving base strings, keys, and languages, plus translation and application functions. A minor gap is the lack of tools for updating or deleting translations, but core operations are present, allowing agents to handle most localization tasks.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    Appeared in Searches