Translations

This MCP server lets you automatically discover and index translation files in your project, then search them quickly by keys or values. It supports auto-discovery, configurable paths, and live reloading so your searches stay up to date as files change.

How to use

You interact with the server through MCP client commands. Use find_translation to search for translation keys or values. You can perform partial matches or require exact matches to narrow results. When translation files change, you can run refresh_translations to rebuild the index so your searches reflect the latest content.

Examples of common usage patterns you’ll perform: search for a term to locate the corresponding translation keys and values, and refresh the index after you update translation files to keep results accurate.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system.

Install the MCP server globally so you can run it from any project directory.

Install globally via npm.

npm install -g translations-mcp

Configuration examples

Configure the translation MCP to use a specific translation file path. The command exposes the file path you want to index and search.

{
  "mcpServers": {
    "translations_mcp_cfg": {
      "command": "translations-mcp",
      "args": ["path/to/your/translation.json"]
    }
  }
}

Environment variable mode

If you prefer to supply the path via an environment variable, set TRANSLATION_FILE_PATH accordingly.

{
  "mcpServers": {
    "translations_mcp_env": {
      "command": "translations-mcp",
      "env": {
        "TRANSLATION_FILE_PATH": "src/assets/locales/en/translation.json"
      }
    }
  }
}

Auto-discovery (fallback)

If you do not specify a path, the server will automatically search for translation files in folders named en as a fallback.

{
  "mcpServers": {
    "translations_mcp_auto": {
      "command": "translations-mcp"
    }
  }
}

Usage of available tools

Two primary tools are exposed for working with translations.

Find a translation by query across keys and values.

Refresh the translation index after file changes to update search results.

Supported file names and discovery

The server searches for common translation file names within en folders, including translation.json, translations.json, common.json, and messages.json. It can locate files in various project structures such as ./en/translation.json, ./locales/en/translation.json, and others.

Installation notes

Install dependencies for development if you are contributing or building locally.

npm install

npm run build

npm run test

Security and maintenance notes

Keep translation files under version control and ensure only authorized updates are indexed. Use the auto-discovery feature cautiously in multi-tenant environments to avoid indexing unrelated locale files.

Troubleshooting tips

If searches return empty results after updates, run refresh_translations to rebuild the index and verify the configured path points to the correct en/translation.json location.

Available tools

find_translation

Search for translation keys and values with support for partial and exact matching.

refresh_translations

Manually refresh the translation index to reflect file changes.