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

$3

Install globally using npm:

``bash


Using npm


npm install -g xcode-i18n-mcp
`

$3

After installation, add this MCP server to Claude Code:

#### Method 1: Using Claude Code CLI

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

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

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

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

Alternative (if globally installed):
`json
{
"mcpServers": {
"xcode-i18n-mcp": {
"command": "xcode-i18n-mcp",
"args": []
}
}
}
`

$3

If you want to contribute or modify the code:

`bash


Clone the repository

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

`json
{
"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:

$3

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

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

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

Returns:
`json
["en", "zh-Hans", "ja", "ko", "fr", "de"]
`

$3

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:
`json
{
"name": "getStringsToTranslate",
"arguments": {
"xcstringsPath": "/path/to/Localizable.xcstrings",
"languageCode": "zh-Hans"
}
}
`

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

$3

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:
`json
{
"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

$3

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

$3

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

$3

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

$3

`bash
pnpm run build
`

$3

`bash
pnpm test
`

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

$3

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

$3

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

$3

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

$3

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