Xcode i18n MCP Server

A Model Context Protocol (MCP) server for managing iOS/macOS app localization workflows. This server provides tools to extract supported languages from Xcode projects and manage string translations in .xcstrings files.

Features

• Extract Known Regions: Parse .pbxproj files to discover supported languages
• Get Untranslated Strings: Identify strings that need translation for specific languages
• Update Translations: Write translated strings back to .xcstrings files
• Type Safety: Built with TypeScript and Zod schema validation
• Error Handling: Comprehensive error handling for file operations and validation

Installation

For Users

Install globally using npm:

# Using npm
npm install -g xcode-i18n-mcp

Add to Claude Code

After installation, add this MCP server to Claude Code:

Method 1: Using Claude Code CLI

claude mcp add-json xcode-i18n-mcp '{"command":"npx","args":["-y","xcode-i18n-mcp"]}'

Method 2: Manual Configuration

Create or edit the MCP configuration file:

For project-specific configuration: Create .claude/mcp.json in your project root:

{
  "mcpServers": {
    "xcode-i18n-mcp": {
      "command": "npx",
      "args": ["-y", "xcode-i18n-mcp"]
    }
  }
}

For global configuration: Edit ~/.claude/mcp.json:

{
  "mcpServers": {
    "xcode-i18n-mcp": {
      "command": "npx",
      "args": ["-y", "xcode-i18n-mcp"]
    }
  }
}

Alternative (if globally installed):

{
  "mcpServers": {
    "xcode-i18n-mcp": {
      "command": "xcode-i18n-mcp",
      "args": []
    }
  }
}

For Development

If you want to contribute or modify the code:

# Clone the repository
git clone <repository-url>
cd xcode-i18n-mcp

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Test locally
pnpm test

For local development, you can add the local build to Claude Code:

{
  "mcpServers": {
    "xcode-i18n-mcp-dev": {
      "command": "node",
      "args": ["/absolute/path/to/xcode-i18n-mcp/build/index.js"]
    }
  }
}

Usage

This MCP server provides three main tools for managing Xcode internationalization:

1. getKnownRegions

Extracts the list of supported languages from a .pbxproj file.

Parameters:

• pbxprojPath (string): Absolute path to the .pbxproj file

Example:

{
  "name": "getKnownRegions",
  "arguments": {
    "pbxprojPath": "/path/to/project.pbxproj"
  }
}

Returns:

["en", "zh-Hans", "ja", "ko", "fr", "de"]

2. getStringsToTranslate

Identifies strings that need translation for a specific language code.

Parameters:

• xcstringsPath (string): Absolute path to the .xcstrings file
• languageCode (string): Target language code (e.g., "zh-Hans", "ja", "fr")

Example:

{
  "name": "getStringsToTranslate",
  "arguments": {
    "xcstringsPath": "/path/to/Localizable.xcstrings",
    "languageCode": "zh-Hans"
  }
}

Returns:

{
  "Hello": {
    "comment": "Greeting message",
    "value": ""
  },
  "Welcome": {
    "comment": "Welcome screen title",
    "value": ""
  }
}

3. updateTranslations

Updates the .xcstrings file with translated strings for a specific language.

Parameters:

• xcstringsPath (string): Absolute path to the .xcstrings file
• languageCode (string): Target language code
• translations (object): Translation data with keys and translated values

Example:

{
  "name": "updateTranslations",
  "arguments": {
    "xcstringsPath": "/path/to/Localizable.xcstrings",
    "languageCode": "zh-Hans",
    "translations": {
      "Hello": {
        "comment": "Greeting message",
        "value": "你好"
      },
      "Welcome": {
        "comment": "Welcome screen title",
        "value": "欢迎"
      }
    }
  }
}

File Format Support

.pbxproj Files

The server parses Xcode project files to extract the knownRegions array using regex pattern matching. It handles various formatting styles and quoted language codes.

.xcstrings Files

The server works with Xcode 15+ String Catalog files (.xcstrings), which are JSON-formatted files containing:

• Source language information
• String keys with comments
• Localization data for multiple languages
• Translation states and values

Development

Prerequisites

• Node.js 18+
• TypeScript
• Zod for schema validation

Building

pnpm run build

Testing

pnpm test

The project includes comprehensive test coverage for all core functions using Vitest.

Code Structure

• index.ts: Main MCP server implementation
• test/: Test files and sample data
• build/: Compiled JavaScript output

Error Handling

The server provides detailed error messages for common issues:

• File not found errors
• Invalid JSON format in .xcstrings files
• Missing knownRegions in .pbxproj files
• Invalid language codes
• File permission issues

Configuration

This MCP server uses stdio transport for communication with MCP clients. No additional configuration is required.

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

License

MIT License - see LICENSE file for details.

Code Generation

100% of this code was generated by Claude (Anthropic's AI assistant)

MCP Tools Used in Development

During the development of this MCP server, the following MCP tools were utilized:

1. mcp__deepwiki__read_wiki_structure - Used to explore the structure of Model Context Protocol documentation
2. mcp__deepwiki__read_wiki_contents - Used to read detailed MCP documentation pages
3. mcp__deepwiki__ask_question - Used to ask specific questions about MCP implementation best practices
4. mcp__perplexity-ask__perplexity_ask - Used to research Xcode file formats (.pbxproj and .xcstrings) and MCP server implementation patterns

Development Process

The entire codebase was generated through an iterative process involving:

• Research of MCP specifications and TypeScript SDK
• Analysis of Xcode project file formats
• Implementation of regex-based parsing for .pbxproj files
• JSON processing for .xcstrings files
• Comprehensive test suite development
• Error handling and validation implementation
• Code optimization and best practices application

Technical Research

The AI assistant researched:

• Model Context Protocol architecture and implementation patterns
• Xcode project file formats and structures
• String catalog (.xcstrings) JSON schema
• TypeScript MCP SDK usage and best practices
• Testing frameworks and patterns for MCP servers
• Error handling strategies for file operations

This demonstrates the capability of AI-assisted development in creating production-ready software tools with proper documentation, testing, and error handling.

Support

For issues, questions, or contributions, please visit the project repository or contact the maintainers.

---

Generated with ❤️ by Claude Code