i18n MCP Server

A MCP server for managing internationalization (i18n) translation files. This server enables LLMs to intelligently manage translations, analyze code for hardcoded strings, and maintain consistency across multiple language files with real-time file watching and advanced search capabilities.

Available Tools

The server provides a comprehensive suite of tools for managing translations, categorized by function.

Translation Search & Exploration

• search_translation: Search for translations by content or key patterns. Supports bulk search and advanced filtering.
• get_translation_suggestions: Get autocomplete suggestions for translation keys.
• get_translation_context: Get hierarchical context for a specific translation key.
• explore_translation_structure: Explore the hierarchical structure of translation files to understand key organization.

Translation Management

• add_translations: Add new translations with key generation and conflict handling.
• add_contextual_translation: Add a translation with a context-aware key.
• update_translation: Update existing translations or perform batch updates.
• delete_translation: Safely delete single or multiple translation keys with dependency checking.

Codebase Analysis

• analyze_codebase: Analyze the codebase for hardcoded strings.
• search_missing_translations: Find translation keys that are used in the code but not defined in translation files (and vice-versa).
• extract_to_translation: Extract a hardcoded string from a file and replace it with a translation key.
• cleanup_unused_translations: Remove unused translation keys that are not referenced in the codebase.

File & Structure Management

• validate_structure: Validate that all translation files have a consistent structure with the base language.
• check_translation_integrity: Check for integrity issues like missing or extra keys and type mismatches across all files.
• reorganize_translation_files: Reorganize and format translation files to match the base language structure, with options for sorting and backups.

Utilities

• generate_types: Generate TypeScript types for all translation keys.
• get_stats: Get server and translation index statistics.

Quick Start

Use via npx (no clone needed):

npx -y i18n-mcp --dir ./locales --project-root /path/to/your/project

Clone and build the project:

git clone https://github.com/dalisys/i18n-mcp.git
cd i18n-mcp
npm install
npm run build

Configuration

Configure for Claude Desktop

Add to your Claude Desktop configuration:

Basic Configuration

{
  "mcpServers": {
    "i18n": {
      "command": "npx", // or "C:\\path\\to\\nvm\\node.exe" or mac "/Users/userName/.volta/bin/npx"
      "args": ["-y", "i18n-mcp", "--dir", "/User/project/locales", "--project-root", "/User/project"]
    }
  }
}

windows

{
  "mcpServers": {
    "i18n": {
      "command": "npx",
      "args": [
        "-y",
        "i18n-mcp",
        "--dir",
        "D:\\path\\to_your_project\\locales",
        "--project-root",
        "D:\\path\\to_your_project"
      ]
    }
  }
}

Advanced Configuration

{
  "mcpServers": {
    "i18n": {
      "command": "npx",
      "args": [
        "-y",
        "i18n-mcp",
        "--dir", "./locales",
        "--base-language", "en",
        "--src-dir", "./src",
        "--project-root", "/path/to/your/project",
        "--exclude", "node_modules,dist",
        "--generate-types", "./src/types/i18n.ts",
        "--frameworks", "react,vue",
        "--key-style", "nested",
        "--debug"
      ]
    }
  }
}

Using Environment Variables

{
  "mcpServers": {
    "i18n": {
      "command": "npx",
      "args": ["-y", "i18n-mcp"],
      "env": {
        "I18N_MCP_DIR": "./locales",
        "I18N_MCP_BASE_LANGUAGE": "en",
        "I18N_MCP_SRC_DIR": "./src",
        "I18N_MCP_PROJECT_ROOT": "/path/to/your/project",
        "I18N_MCP_DEBUG": "true",
        "I18N_MCP_AUTO_SYNC": "true",
        "I18N_MCP_FRAMEWORKS": "react,vue"
      }
    }
  }
}

Configure for IDE

Add the following to your IDE (vscode, cursor):

Node.js Installation

{

      "i18n": {
        "command": "npx",
        "args": ["-y", "i18n-mcp", "--dir", "/User/project/locales", "--project-root", "/User/project"]
      }

}

Configure for Zed

Add to your Zed settings.json:

"context_servers": {
  "i18n": {
    "command": "npx",
    "args": ["-y", "i18n-mcp", "--dir", "./locales", "--project-root", "/path/to/your/project"]
  }
}

Configuration Options

Command Line Arguments

| Argument | Type | Default | Description | |----------|------|---------|-------------| | --dir -d | string | ./locales | Translation files directory | | --base-language -b | string | en | Base language for structure template | | --src-dir | string | - | Source code directory for analysis | | --project-root | string | - | Project root directory for resolving relative paths | | --exclude | string | - | Exclude patterns (comma-separated) | | --auto-sync | boolean | false | Auto-sync changes back to files | | --generate-types | string | - | Generate TypeScript types file path | | --frameworks | string | - | Framework analysis (react,vue,svelte,angular) | | --key-style | string | nested | Key naming style (nested, flat, camelCase, kebab-case) | | --debug | boolean | false | Enable debug logging |

Environment Variables

| Variable | Description | |----------|-------------| | I18N_MCP_DIR | Translation files directory | | I18N_MCP_BASE_LANGUAGE | Base language for structure template | | I18N_MCP_SRC_DIR | Source code directory for analysis | | I18N_MCP_PROJECT_ROOT | Project root directory for resolving relative paths | | I18N_MCP_AUTO_SYNC | Auto-sync mode (true/false) | | I18N_MCP_FRAMEWORKS | Supported frameworks (comma-separated) | | I18N_MCP_DEBUG | Enable debug mode (true/false) |

Path Resolution

The i18n MCP server handles both relative and absolute paths intelligently:

How Path Resolution Works

1. Absolute paths (e.g., /Users/user/project/src) → Used as-is
2. Relative paths (e.g., app, ./src, components) → Resolved relative to --project-root
3. No path specified → Uses configured --src-dir as default

Examples

With configuration:

--project-root /Users/user/project
--src-dir /Users/user/project/src

| Input srcDir | Resolved Path | Description | |----------------|---------------|-------------| | "app" | /Users/user/project/app | Relative to project root | | "./src" | /Users/user/project/src | Relative to project root | | "components" | /Users/user/project/components | Relative to project root | | "/absolute/path" | /absolute/path | Absolute path used as-is | | undefined | /Users/user/project/src | Uses configured --src-dir |

Error Handling

The server provides detailed error messages when paths cannot be resolved:

{
  "error": "Source directory resolution failed",
  "details": "Directory not found: /Users/user/project/nonexistent",
  "providedPath": "nonexistent",
  "resolvedPath": "/Users/user/project/nonexistent",
  "pathDescription": "relative to project root (nonexistent → /Users/user/project/nonexistent)",
  "suggestion": "Check that the path exists and is accessible"
}

Development Workflow Examples

1. Find missing translations: "What translations are missing in Spanish?"
2. Extract hardcoded strings: "Find all hardcoded strings in my React components"
3. Add contextual translation: "Add a translation for 'Save' in the user profile context"
4. Validate consistency: "Check if all language files have the same structure"
5. Generate types: "Generate TypeScript types for my translation keys"

Testing

Run the test suite:

npm test

Build

npm run build