MCP Translation Sync
AI-Powered Translation Sync for i18n Projects
Automatically keep your translation files in perfect sync with GitHub Copilot's intelligence. Edit your source language file (e.g., en.json) once, let AI handle the rest.
✨ Why MCP Translation Sync?
For Product Teams
- Save Time - No more manual translation updates across dozens of files
- Stay Consistent - All translations automatically mirror your source language structure
- Quality AI - GitHub Copilot understands context, not just word-for-word translation
For Developers
- Zero Config - Works instantly with sensible defaults
- Git-Aware - Only translates what changed, saves API calls
- VS Code Native - Seamless integration, right where you code
For Translators
- Smart Detection - Automatically catches missing placeholders like
{name}
- Preview Mode - Dry-run to review changes before applying
- Clear Workflow - Edit source language, everything else updates automatically
🚀 Quick Start
1. Install Extension
Open VS Code → Extensions → Search "MCP Translation Sync" → Install
2. Discover Translation Files
First time setup - Let the extension find your translation files automatically:
Press Ctrl+Shift+P → Type "MCP: Discover Translation Files" → Confirm
Alternatively, use Copilot Chat:
@translate /discover
This auto-detects your translation files and saves them to workspace settings.
3. Sync Translations
Press Ctrl+Shift+P → Type "MCP: Sync Translations" → Done!
Or simply type in Copilot Chat:
@translate sync
All translation files updated automatically with GitHub Copilot.
✨ Key Features
- 🤖 GitHub Copilot Integration - Natural, context-aware translations
- � Universal Language Support - All valid BCP-47 language tags via Intl.Locale (100+ languages)
- �🎯 Smart Reuse - Only translates new or changed content
- 🔍 Placeholder Safe - Preserves
{variables} automatically
- 📝 Git-Aware - Detects source language changes via git history
- ⚡ Fast - Parallel processing, configurable concurrency
- 🎨 Clean Output - Alphabetically sorted keys
- 🔄 Cancellable - Stop long operations anytime
- 📊 Detailed Reports - See what changed and why
- 🎯 Selective Sync - Translate specific languages on demand
- 💬 Chat Integration - Natural language commands via @translate
- 🔍 Auto-Discovery - Finds all translation files automatically
- 📈 Dynamic Progress - Real-time feedback during sync
- ⚙️ Runtime Config Overrides - Temporarily adjust settings from chat
🚀 Usage Examples (Quick Glimpse)
# 1. Discover translation files (first time)
Ctrl+Shift+P → "MCP: Discover Translation Files"
# 2. Edit your source language file (e.g. en.json)
# 3. Sync all translations
Ctrl+Shift+P → "MCP: Sync Translations"
# 4. Result: All non-source language files updated & sorted!
Chat shortcuts (Copilot Chat)
@translate /discover # Auto-find translation files
@translate /settings # View and edit settings
@translate # Sync all translations
@translate sync only fr and de # Sync specific languages
@translate sync except es # Exclude specific languages
@translate sync with temperature 0.8 # Override settings temporarily
@translate sync staged changes # Use git strategy
Language filters, git strategies, and settings are automatically detected from your prompt.
📚 Documentation
Quick Links
📋 Requirements
- VS Code 1.80.0 or later
- GitHub Copilot extension (for AI translations)
- Node.js 16+ (for development/server mode)
- Git (optional, for change detection)
🔄 How It Works
1. First time: Discover translation files → Auto-detected and saved
2. Edit source language file (e.g., en.json) → Add/change/remove keys
3. Run Sync → GitHub Copilot translates intelligently
4. All Done → All language files updated & sorted
Smart Translation Logic
Reuses translations when:
- Translation exists and is valid
- Source language hasn't changed (git-detected)
- Placeholders match perfectly
Translates when:
- Key is new
- Source language value changed
- Marked with
TODO: prefix
- Placeholder mismatch detected
⚙️ Configuration
Basic Setup
Auto-configured by MCP: Discover Translation Files command:
{
"mcpTranslation.translation.projectRoot": ".",
"mcpTranslation.translation.sourceLanguage": "en",
"mcpTranslation.translation.files": [
{ "path": "src/i18n/en.json", "language": "en", "enabled": true },
{ "path": "src/i18n/fr.json", "language": "fr", "enabled": true },
{ "path": "src/i18n/de.json", "language": "de", "enabled": true }
]
}
Manual configuration only needed for custom setups.
Advanced Options
{
// Translation Performance (optimized defaults)
"mcpTranslation.translation.batchingStrategy": "batch-request",
"mcpTranslation.translation.batchRequestSize": 20,
"mcpTranslation.translation.maxConcurrentTranslations": 10,
"mcpTranslation.translation.retryAttempts": 3,
"mcpTranslation.translation.customInstructions": "Use formal tone. Keep brand names in English.",
// Git Detection
"mcpTranslation.sync.detectSourceChanges": true,
"mcpTranslation.sync.gitComparisonStrategy": "head-vs-working",
// Behavior
"mcpTranslation.sync.dryRun": false,
"mcpTranslation.sync.sortKeys": true, // Sort source and translations alphabetically
// Model Preferences
"mcpTranslation.languageModel.preferredVendor": "copilot",
"mcpTranslation.languageModel.rememberLastUsed": true
}
Note: The extension uses batch-request strategy by default for optimal performance (95% fewer API calls). Switch to "concurrent" only for edge cases requiring per-key retry control.
See Configuration Reference for all options.
🎯 Selective Translation
Command Palette:
Ctrl+Shift+P → "MCP: Sync Specific Languages" → Select languages → Sync
File-Level Control:
{
"mcpTranslation.translation.files": [
{ "path": "i18n/fr.json", "language": "fr", "enabled": true },
{ "path": "i18n/de.json", "language": "de", "enabled": true },
{ "path": "i18n/test.json", "language": "test", "enabled": false }
]
}
Preview Mode
// Enable dry-run
{ "mcpTranslation.sync.dryRun": true }
// Run sync → Review translation-sync-preview.md → Apply
⚙️ Runtime Config Overrides (Chat Only)
Temporarily override settings in chat without changing workspace configuration:
Examples:
@translate sync with temperature 0.8 # More creative translations
@translate sync staged changes # Use git strategy
@translate sync with batch size 50 # Larger batches
@translate sync only fr, de with temperature 0.5 # Combine filters + overrides
Supported overrides (11 settings):
- Temperature, batch size, retry attempts
- Git comparison strategy, commit count
- Custom instructions, TODO marker
- Batching strategy, sort keys, continue on error
- Source language
How it works:
- Type natural language in chat:
"sync with temperature 0.8"
- AI parses intent and extracts overrides (confidence > 0.7)
- Settings applied temporarily for that sync only
- Workspace config unchanged
See User Guide - Runtime Overrides for complete examples.
🔍 Supported Placeholders
Automatically validates and preserves:
{name}, {{count}} - Angular, Vue%s, %d - C, PHP, Python%(name)s - Python named${var} - JavaScript template literals[key] - Bracket notation
Mismatch detection: Automatically catches missing or wrong placeholders.
🛠️ For Developers
Development Setup
git clone https://dev.azure.com/noble-wave/mcp-translation-sync
cd mcp-translation-sync
npm install
npm run build
Debug Extension
Press F5 in VS Code → Extension Development Host launches
Run Tests
npm run build
npx ts-node test/test-suite.ts
See Development Guide for contributing.
📋 Available Commands
Command Palette (Ctrl+Shift+P)
MCP: Discover Translation Files - Auto-detect translation files in workspaceMCP: Sync Translations - Sync all enabled translation filesMCP: Sync Specific Languages - Choose specific languages to syncMCP: View Settings - View and edit extension settingsMCP: Clear Remembered Model - Reset AI model selection
Copilot Chat (@translate)
@translate /discover - Find translation files automatically@translate /settings or /config - Open settings panel@translate or /sync - Sync all translations- Natural language: "sync only French and German" or "sync except test languages"
🧭 Dual-Mode Architecture
Works both as VS Code Extension (with GitHub Copilot) and Standalone Server (with mock translations or custom APIs):
Extension Mode: VS Code UI → Command / Chat Handler → Core Sync Engine → Copilot LLM → Natural Translations
Server Mode: MCP Protocol (stdio) → Tool Dispatch → Core Sync Engine → Mock/Custom Provider → Translations
Extension: Real AI translations via GitHub Copilot
Server: Mock translations ([LANG] text) or integrate your own API (DeepL, Google, etc.)
Modular Extension Structure (Post-Refactor)
The extension was refactored from a single large extension.ts into focused modules:
src/extension/
commands/ # One file per command (sync, discover, selective, clear-model)
chat/ # Chat participant handlers (/discover, /sync, help)
services/ # ModelManager (model selection/memory), WorkspaceManager (validation & paths)
ui/ # NotificationManager (centralized user messaging)
extension.ts # Thin activation & wiring only
Benefits:
- Clear separation of concerns
- Easier testing & maintenance
- Faster navigation (feature → single file)
- Reusable services (no duplicate model/workspace logic)
Command names remain the same; their orchestration now lives in src/extension/commands/*.ts. Business logic (diffing, reuse, translation) stays in src/tools/*.ts.
Server Mode Configuration
The standalone server uses stdio transport (not HTTP) and can be configured via environment variables:
# Run with default settings (port config unused in stdio mode)
node dist/server.js
# Configure logging and behavior
LOG_LEVEL=debug LOG_TO_FILE=true node dist/server.js
# Set translation provider (for custom API integration)
TRANSLATION_PROVIDER=custom node dist/server.js
See Architecture for technical details.
-- 📖 Documentation: Browse https://mcp-translation-sync.netlify.app/#/ for comprehensive guides
🤝 Contributing
We welcome contributions! See Development Guide for:
- Setup instructions
- Testing procedures
- Code standards
- Publishing process
Quick start for contributors:
git clone https://dev.azure.com/noble-wave/mcp-translation-sync
cd mcp-translation-sync
npm install
npm run build
# Press F5 to debug
📄 License
MIT License - see LICENSE file for details
Made with ❤️ by Noble Wave
