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