translation-mcp-server

thanhtunguet/translation-mcp-server

3.1

If you are the rightful owner of translation-mcp-server 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.

The Translation MCP Server is a tool designed to assist developers in translating multilingual applications by providing intelligent translation services and maintaining consistency across namespaces.

Tools
8
Resources
0
Prompts
0

Translation MCP Server

A Model Context Protocol (MCP) server that assists developers with translating multilingual applications. This server provides intelligent translation services, maintains consistency across namespaces, and integrates seamlessly with development workflows.

Features

  • Context-aware translation: Uses translation key semantics and English content for better accuracy
  • Workspace integration: Automatically detects VS Code/Cursor workspace settings
  • Multiple file formats: Supports nested and flat JSON structures
  • Batch operations: Efficiently handles multiple keys and files
  • Translation validation: Ensures quality and consistency
  • Missing translation detection: Identifies gaps across locales
  • Flexible configuration: Supports workspace, project, and environment-based settings

Installation

# Clone or download the server code
cd translation-mcp-server

# Install dependencies
npm install

# Build the server
npm run build

# Make the server executable (optional)
chmod +x dist/index.js
chmod +x run-server.js

Quick Start

  1. Test the server locally:
node dist/index.js
  1. Add to your MCP client configuration (replace with absolute paths):
{
  "mcpServers": {
    "translation": {
      "command": "node",
      "args": ["/full/path/to/translation-mcp-server/dist/index.js"],
      "cwd": "/full/path/to/translation-mcp-server"
    }
  }
}

Configuration

The server supports multiple configuration sources in priority order:

  1. VS Code/Cursor Workspace Settings (highest priority)
  2. Project configuration file (translation.config.json)
  3. Environment variables
  4. Default values

Workspace Settings

Add to .vscode/settings.json or .cursor/settings.json:

{
  "translation-mcp": {
    "localesPath": "./src/locales",
    "sourceLocale": "en",
    "supportedLocales": ["en", "vi", "fr", "ja"],
    "fileStructure": "flat",
    "autoDetectNamespaces": true,
    "ai": {
      "provider": "mcp-client",
      "temperature": 0.3
    }
  }
}

Environment Variables

export TRANSLATION_LOCALES_PATH="./locales"
export TRANSLATION_SOURCE_LOCALE="en"
export TRANSLATION_SUPPORTED_LOCALES="en,vi,fr"
export TRANSLATION_FILE_STRUCTURE="flat"  # or "nested"
export TRANSLATION_PROVIDER="mcp-client"

Usage

MCP Client Integration

Add to your MCP client configuration:

{
  "mcpServers": {
    "translation": {
      "command": "node",
      "args": ["/absolute/path/to/translation-mcp-server/dist/index.js"],
      "cwd": "/absolute/path/to/translation-mcp-server"
    }
  }
}

Alternative configuration:

{
  "mcpServers": {
    "translation": {
      "command": "/absolute/path/to/translation-mcp-server/run-server.js"
    }
  }
}

With environment variables:

{
  "mcpServers": {
    "translation": {
      "command": "node",
      "args": ["/absolute/path/to/translation-mcp-server/dist/index.js"],
      "cwd": "/absolute/path/to/translation-mcp-server",
      "env": {
        "TRANSLATION_FILE_STRUCTURE": "flat",
        "TRANSLATION_LOCALES_PATH": "./src/locales",
        "TRANSLATION_SUPPORTED_LOCALES": "en,vi,fr"
      }
    }
  }
}

Available Tools

1. translate_key

Translate a specific translation key to target languages.

// Example usage
{
  "key": "product.name.title",
  "target_locales": ["vi", "fr"],
  "context": "Product listing page title"
}
2. translate_namespace

Translate all keys within a specific namespace/file.

{
  "namespace": "product",
  "target_locales": ["vi", "fr"],
  "mode": "missing_only" // "all", "missing_only", "outdated"
}
3. find_missing_translations

Identify missing translations across locales.

{
  "target_locales": ["vi", "fr"],
  "namespaces": ["product", "user"]
}
4. validate_translations

Validate translation quality and consistency.

{
  "target_locales": ["vi", "fr"],
  "checks": ["consistency", "completeness", "formatting", "placeholders"]
}
5. analyze_translation_context

Analyze translation context and provide suggestions.

{
  "key": "product.name.title",
  "target_locale": "vi"
}
6. get_configuration

Get current configuration and workspace settings.

{
  "source": "all" // "workspace", "project", "env", "all"
}
7. set_workspace_config

Update workspace-specific translation settings.

{
  "config": {
    "localesPath": "./i18n",
    "supportedLocales": ["en", "vi", "fr", "ja"]
  }
}
8. save_translations

Save provided translations to locale files.

{
  "translations": [
    {
      "key": "product.name.title",
      "locale": "vi",
      "translation": "Tiêu Đề Sản Phẩm"
    },
    {
      "key": "product.name.title", 
      "locale": "fr",
      "translation": "Titre du Produit"
    }
  ]
}

Project Structure

locales/
├── en/                    # Base language (English)
│   ├── product.json       # Product-related translations
│   ├── user.json         # User-related translations
│   ├── common.json       # Common UI elements
│   └── ...
├── vi/                   # Vietnamese translations
│   ├── product.json
│   ├── user.json
│   └── ...
└── fr/                   # French translations
    ├── product.json
    ├── user.json
    └── ...

Translation Key Structure

The server supports both full-qualified and namespace-omitted key formats:

Full-Qualified Keys (Flat Structure)

// product.json
{
  "product.name.title": "Product Title",
  "product.name.subtitle": "Product Subtitle", 
  "product.description": "Product Description"
}

Namespace-Omitted Keys (Nested Structure)

// product.json
{
  "name": {
    "title": "Product Title",
    "subtitle": "Product Subtitle"
  },
  "description": "Product Description"
}

Both formats are automatically detected and handled correctly:

  • Reading: The server tries both product.name.title and name.title when reading from product.json
  • Writing: The server maintains the existing format in each file
  • Context-aware: Uses key path semantics for better translation accuracy

Development

# Development mode
npm run dev

# Build
npm run build

# Test (with coverage)
npm run test:coverage

# Test basic functionality only
npm test -- --testNamePattern="Basic functionality"

# Test server startup
npm run test-server

# Start server
npm start

CI/CD

The project includes GitHub Actions workflows for:

  • Simple CI (simple-ci.yml): Basic build, test, and cross-platform compatibility
  • Full CI (ci.yml): Comprehensive testing including security audits and integration tests
  • Integration Tests (integration.yml): Daily integration tests with various project structures
  • Package Publishing (publish.yml): Automated NPM package publishing on release

Running CI Locally

# Run the same checks as CI
npm ci
npx tsc --noEmit
npm run build
npm run test-server
npm test -- --testNamePattern="Basic functionality"

Translation Workflow

The server integrates with Cursor/Claude's built-in AI capabilities. When you request a translation:

  1. The server analyzes the translation context (key semantics, domain, etc.)
  2. It provides you with rich context and guidelines for translation
  3. You provide the translations using Cursor/Claude's AI assistance
  4. The server validates and saves the translations to the appropriate files

This approach gives you full control over the translation quality while leveraging the AI capabilities you already pay for.

Error Handling

The server includes comprehensive error handling for:

  • Missing configuration files
  • Invalid JSON structures
  • API rate limits and failures
  • File system permissions
  • Network connectivity issues

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

MIT License - see LICENSE file for details