i18n-mcp

dalisys/i18n-mcp

3.3

If you are the rightful owner of i18n-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A MCP server for managing internationalization (i18n) translation files, enabling LLMs to intelligently manage translations and maintain consistency across multiple language files.

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

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": "node",
        "args": ["/path/to/i18n-mcp/dist/index.js", "--dir", "/User/project/locales"]
      }
  }
}
windows
{
  "mcpServers": {
    "i18n": {
      "command": "C:\\path\\to\\node.exe", // or "C:\\path\\to\\nvm\\node.exe"
      "args": [
        "D:\\i18n-mcp\\dist\\index.js",
        "--dir",
        "D:\\path\\to_your_project\\locales"
      ]
    }
}
Advanced Configuration
{
  "mcpServers": {
    "i18n": {
      "command": "node",
      "args": [
        "/path/to/i18n-mcp/dist/index.js",
        "--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": "node",
      "args": ["/path/to/i18n-mcp/dist/index.js"],
      "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": "node",
        "args": ["/path/to/i18n-mcp/dist/index.js", "--dir", "/User/project/locales"]
      }

}

Configure for Zed

Add to your Zed settings.json:

"context_servers": {
  "i18n": {
    "command": "node",
    "args": ["/path/to/i18n-mcp/dist/index.js", "--dir", "./locales"]
  }
}

Configuration Options

Command Line Arguments

ArgumentTypeDefaultDescription
--dir -dstring./localesTranslation files directory
--base-language -bstringenBase language for structure template
--src-dirstring-Source code directory for analysis
--project-rootstring-Project root directory for resolving relative paths
--excludestring-Exclude patterns (comma-separated)
--auto-syncbooleanfalseAuto-sync changes back to files
--generate-typesstring-Generate TypeScript types file path
--frameworksstring-Framework analysis (react,vue,svelte,angular)
--key-stylestringnestedKey naming style (nested, flat, camelCase, kebab-case)
--debugbooleanfalseEnable debug logging

Environment Variables

VariableDescription
I18N_MCP_DIRTranslation files directory
I18N_MCP_BASE_LANGUAGEBase language for structure template
I18N_MCP_SRC_DIRSource code directory for analysis
I18N_MCP_PROJECT_ROOTProject root directory for resolving relative paths
I18N_MCP_AUTO_SYNCAuto-sync mode (true/false)
I18N_MCP_FRAMEWORKSSupported frameworks (comma-separated)
I18N_MCP_DEBUGEnable 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 srcDirResolved PathDescription
"app"/Users/user/project/appRelative to project root
"./src"/Users/user/project/srcRelative to project root
"components"/Users/user/project/componentsRelative to project root
"/absolute/path"/absolute/pathAbsolute path used as-is
undefined/Users/user/project/srcUses 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