Xcode i18n MCP server
npm install xcode-i18n-mcpA 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.
- 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
Install globally using npm:
``bash`Using npm
npm install -g xcode-i18n-mcp
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": []
}
}
}
If you want to contribute or modify the code:
`bashClone the repository
git clone
cd xcode-i18n-mcp
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 fileExample:
`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 valuesExample:
`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 valuesDevelopment
$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 outputError 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 issuesConfiguration
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` filesThe 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.
For issues, questions, or contributions, please visit the project repository or contact the maintainers.
---
Generated with ❤️ by Claude Code