Translations MCP Server
A Model Context Protocol (MCP) server that automatically discovers and searches translation files in your projects.
Features
- Configurable path: Specify exact translation file path via configuration (recommended)
- Auto-discovery: Automatically finds translation files in
enfolders as fallback - Fast search: Indexed search through translation keys and values
- Partial/exact matching: Support for both partial and exact match searches
- File watching: Automatically reloads when translation files change
- Multiple file formats: Supports common translation file names
- TypeScript: Fully typed with proper interfaces and modular architecture
Quick Start
Method 1: Configured Path (Recommended)
Configure your MCP server to use a specific translation file:
{
"mcpServers": {
"translations-mcp": {
"command": "translations-mcp",
"args": ["path/to/your/translation.json"]
}
}
}
Method 2: Environment Variable
{
"mcpServers": {
"translations-mcp": {
"command": "translations-mcp",
"env": {
"TRANSLATION_FILE_PATH": "src/assets/locales/en/translation.json"
}
}
}
}
Method 3: Auto-Discovery (Fallback)
If no path is configured, the server will automatically search for translation files:
{
"mcpServers": {
"translations-mcp": {
"command": "translations-mcp"
}
}
}
Architecture
The project is organized into focused modules for better maintainability:
src/
├── index.ts # Main server entry point with MCP server setup
├── translation-discovery.ts # File discovery and search functionality
└── types.ts # TypeScript interfaces and types
Module Descriptions
index.ts: Main MCP server setup, tool handlers, and entry pointtranslation-discovery.ts: Handles file discovery, indexing, and search functionalitytypes.ts: TypeScript interfaces for type safety across modules
Usage
The server provides two main tools:
1. find_translation
Search for translation keys and values:
{
"name": "find_translation",
"arguments": {
"query": "search term",
"exact": false
}
}
query: String to search for in translation keys or valuesexact: Boolean (optional) - whether to perform exact matching (default: false)
2. refresh_translations
Manually refresh the translation index (useful after file changes):
{
"name": "refresh_translations",
"arguments": {}
}
Returns the current number of indexed entries and refresh status.
Configuration Examples
For React/Next.js Projects
{
"mcpServers": {
"translations-mcp": {
"command": "translations-mcp",
"args": ["public/locales/en/translation.json"]
}
}
}
For ASP.NET Core + React Projects
{
"mcpServers": {
"translations-mcp": {
"command": "translations-mcp",
"args": ["ClientApp/public/locales/en/translation.json"]
}
}
}
Absolute Path
{
"mcpServers": {
"translations-mcp": {
"command": "translations-mcp",
"args": ["C:/projects/my-app/locales/en/translation.json"]
}
}
}
How It Works
- Discovery: On startup, recursively searches for translation files in folders named
en - Indexing: Builds an in-memory search index of all translation keys and values
- Search: Provides fast lookups with support for partial and exact matching
Supported Project Structures
The server can find translation files in various project structures:
./en/translation.json(simple)./locales/en/translation.json(common)./src/assets/locales/en/translation.json(React/Angular)./ClientApp/public/locales/en/translation.json(ASP.NET Core with React)./Project.Name/ClientApp/public/locales/en/translation.json(deep .NET structures)
Installation
Install globally via npm:
npm install -g translations-mcp
Development
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm run test
# Development mode
npm run dev
Testing
The project includes several test scripts:
npm run test:server- Test basic server functionalitynpm run test:find- Test search functionalitynpm run test:quick- Quick integration testnpm run test:all- Run all tests
Supported File Names
The server looks for these translation files in en folders:
- translation.json
- translations.json
- common.json
- messages.json
Adding to Claude Desktop
Recommended: Specify Your Translation File Path
{
"mcpServers": {
"translations": {
"command": "translations-mcp",
"args": ["path/to/your/translation.json"]
}
}
}
Alternative: Auto-Discovery
{
"mcpServers": {
"translations": {
"command": "translations-mcp"
}
}
}
Benefits of Configured Path
✅ Eliminates confusion - No more loading wrong translation files
✅ Faster startup - No need to search directories
✅ Predictable behavior - Always uses the exact file you specify
✅ Works anywhere - Not limited to specific folder structures
✅ Production ready - Points to your actual translation files, not test data
npm run clean- Remove compiled filesnpm test- Run the main server functionality testnpm run test:server- Run comprehensive server tests with response parsingnpm run test:quick- Run quick global installation testnpm run test:all- Run all tests (server + quick)
Development Workflow
- Clone or download this package
- Run
npm installto install dependencies - Make your changes to files in the
src/directory - Test with
npm run devfor development ornpm testto verify functionality - Build for production with
npm run build && npm start
License
MIT
