MCP server for LangAPI - AI-powered translation management for i18n projects
npm install @langapi/mcp-serverMCP (Model Context Protocol) server for LangAPI - AI-powered translation management for i18n projects.
This package enables AI assistants like Claude, Cursor, and VS Code extensions to manage translations in your project programmatically.
``bash1. Get your API key at https://langapi.io (1,000 free credits)
Features
- Locale Detection: Automatically detect i18n framework (next-intl, i18next, react-intl, iOS/macOS) and locale files
- Translation Status: Compare source and target locales to find missing translations
- Sync Translations: Translate missing keys via LangAPI with credit-based billing
- Dry Run Mode: Preview changes and costs before syncing (enabled by default)
- Format Preservation: Maintains JSON formatting when writing translated files
- Delta Detection: Only translate new/changed keys, saving up to 90% on costs
- Apple Localization: Support for iOS/macOS
, .xcstrings, and .stringsdict filesInstallation
`bash
npm install @langapi/mcp-server
`Or use directly with npx (recommended):
bash
npx @langapi/mcp-server
`---
Setup by Tool
$3
Config file locations:
- macOS:
- Windows:
- Linux: Configuration:
json
{
"mcpServers": {
"langapi": {
"command": "npx",
"args": ["@langapi/mcp-server"],
"env": {
"LANGAPI_API_KEY": "your-api-key-here"
}
}
}
}
`After editing, restart Claude Desktop for changes to take effect.
---
$3
Option 1: CLI command (quickest)
bash
Add to current project (stored in .mcp.json)
claude mcp add langapi \
--env LANGAPI_API_KEY=your-api-key-here \
-- npx -y @langapi/mcp-server`Option 2: Project-level config (recommended for teams)
Create
in your project root:`json
{
"mcpServers": {
"langapi": {
"command": "npx",
"args": ["@langapi/mcp-server"],
"env": {
"LANGAPI_API_KEY": "your-api-key-here"
}
}
}
}
`Option 3: User-level config
Add to
:`json
{
"mcpServers": {
"langapi": {
"command": "npx",
"args": ["@langapi/mcp-server"],
"env": {
"LANGAPI_API_KEY": "your-api-key-here"
}
}
}
}
`Option 4: Environment variable
bash
export LANGAPI_API_KEY="your-api-key-here"
`Then the MCP server will pick it up automatically.
Verify connection:
bash
List configured servers
claude mcp listCheck server status inside Claude Code
/mcp
`Remove server:
bash
claude mcp remove langapi
`---
$3
Config file locations:
- Project-level:
in your project root
- Global: ~/.cursor/mcp.jsonConfiguration:
json
{
"mcpServers": {
"langapi": {
"command": "npx",
"args": ["@langapi/mcp-server"],
"env": {
"LANGAPI_API_KEY": "your-api-key-here"
}
}
}
}
`Alternative: Via UI
1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Search for "MCP"
3. Click "Edit in settings.json"
4. Add the configuration above
---
$3
1. Install the Cline extension
2. Create
in your project:`json
{
"mcpServers": {
"langapi": {
"command": "npx",
"args": ["@langapi/mcp-server"],
"env": {
"LANGAPI_API_KEY": "your-api-key-here"
}
}
}
}
`3. Reload VS Code window (Cmd/Ctrl + Shift + P > "Reload Window")
---
$3
1. Install the Roo Code extension
2. Create
in your project:`json
{
"mcpServers": {
"langapi": {
"command": "npx",
"args": ["@langapi/mcp-server"],
"env": {
"LANGAPI_API_KEY": "your-api-key-here"
}
}
}
}
`3. Reload VS Code window
---
$3
Config file:
json
{
"mcpServers": {
"langapi": {
"command": "npx",
"args": ["@langapi/mcp-server"],
"env": {
"LANGAPI_API_KEY": "your-api-key-here"
}
}
}
}
`Restart Windsurf after editing.
---
Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
|
| Yes | Your LangAPI API key (get one at langapi.io) |
| LANGAPI_API_URL | No | Custom API URL (default: https://api.langapi.io) |---
MCP Tools
$3
Scan your project for locale JSON files and detect the i18n framework.
Input:
`json
{
"project_path": "/path/to/project", // optional, defaults to cwd
"include_key_count": true // optional, default: true
}
`Output:
json
{
"framework": "next-intl",
"confidence": "high",
"source_lang": "en",
"locales_path": "messages",
"locales": [
{
"lang": "en",
"files": [{ "path": "messages/en.json", "namespace": null, "key_count": 150 }],
"total_keys": 150
},
{
"lang": "de",
"files": [{ "path": "messages/de.json", "namespace": null, "key_count": 120 }],
"total_keys": 120
}
],
"config_file": "i18n.ts"
}
`$3
Compare source locale against targets to identify missing keys and estimate costs.
Input:
json
{
"source_lang": "en",
"target_langs": ["de", "fr"], // optional, all non-source by default
"project_path": "/path/to/project" // optional
}
`Output:
json
{
"source_lang": "en",
"source_keys": 150,
"targets": [
{
"lang": "de",
"status": "outdated",
"keys": { "total": 120, "missing": ["new.key1", "new.key2"], "extra": [] }
}
],
"cost_estimate": {
"words_to_translate": 45,
"credits_required": 90,
"current_balance": 1000,
"balance_after_sync": 910
}
}
`$3
Sync translations via the LangAPI API. Default is dry_run=true for safety.
Input:
json
{
"source_lang": "en",
"target_langs": ["de", "fr"],
"dry_run": true, // default: true (preview mode)
"project_path": "/path/to/project", // optional
"write_to_files": true, // optional, default: true
"skip_keys": ["key.to.skip"] // optional, keys to exclude
}
`Output (dry_run=true):
json
{
"success": true,
"dry_run": true,
"delta": {
"new_keys": ["new.key1", "new.key2"],
"changed_keys": [],
"total_keys_to_sync": 2
},
"cost": {
"words_to_translate": 45,
"credits_required": 90,
"current_balance": 1000,
"balance_after_sync": 910
},
"message": "Preview: 2 keys to sync, 90 credits required. Run with dry_run=false to execute."
}
`Output (dry_run=false):
json
{
"success": true,
"dry_run": false,
"results": [
{ "language": "de", "translated_count": 2, "file_written": "messages/de.json" },
{ "language": "fr", "translated_count": 2, "file_written": "messages/fr.json" }
],
"cost": {
"credits_used": 90,
"balance_after_sync": 1910
},
"message": "Sync complete. 4 keys translated across 2 languages. 90 credits used."
}
`---
Prompt Examples
$3
"Scan my project for translations"
"What i18n framework am I using?"
"List all my locale files"
"How many translation keys do I have?"
"What languages are configured in my project?"
$3
"What translations are missing?"
"Compare English to all other languages"
"How many keys need to be translated for French?"
"Which languages are out of sync?"
"Show me the missing keys for German"
"How much will it cost to sync all languages?"
$3
"Preview what would happen if I sync all languages"
"Do a dry run for French translations"
"Show me what keys will be translated"
"What's the cost estimate for syncing German?"
"Preview the sync without making changes"
$3
"Sync all missing translations"
"Translate to German and French"
"Update all locale files with missing keys"
"Sync translations and write to files"
"Execute the translation sync"
$3
"Are there any extra keys in German that aren't in English?"
"Skip the settings.* keys when syncing"
"Only sync the home. and nav. keys"
"Sync to Japanese but skip experimental features"
$3
You: List the translations in my projectClaude: [Calls list_local_locales]
I found a next-intl project with English (150 keys) and German (120 keys) translations.
You: What translations are missing for German?
Claude: [Calls get_translation_status]
German is missing 30 keys. The sync would cost 85 credits (you have 1000 credits).
You: Sync the German translations
Claude: [Calls sync_translations with dry_run=true]
Preview: 30 keys will be translated, costing 85 credits. Should I proceed?
You: Yes, go ahead
Claude: [Calls sync_translations with dry_run=false]
Done! 30 keys translated. German file updated at messages/de.json.
---
Supported Frameworks
The server automatically detects these i18n frameworks:
| Framework | Locale Patterns | Config Files |
|-----------|-----------------|--------------|
| next-intl |
, locales/.json | i18n.ts, next.config.js |
| i18next | public/locales//.json, locales//.json | i18next.config.js, i18n.js |
| react-intl | src/lang/.json, lang/.json | src/i18n.ts |
| iOS/macOS | .strings, .xcstrings, .stringsdict | Info.plist |
| generic | Various common patterns | - |---
Troubleshooting
$3
- Ensure npx is in your PATH
- Try running npx @langapi/mcp-server manually to test
- On Windows, you may need to use the full path to npx$3
- Verify your API key at langapi.io/dashboard
- Check for extra spaces or quotes in your config
- Ensure the key is set in the env section, not args$3
- Check that your locale files match supported patterns (see Frameworks above)
- Verify files are valid JSON
- Try specifying explicitly$3
- Check file/directory write permissions
- On macOS, ensure your terminal has disk access$3
1. Restart your IDE/tool completely (not just reload)
2. Check the config file syntax (valid JSON?)
3. Look for error messages in your tool's developer console$3
- Check your credit balance at langapi.io
- Verify network connectivity to api.langapi.io---
Advanced Configuration
$3
Use project-level config files (
.mcp.json, .cursor/mcp.json) with different API keys per project.$3
For self-hosted or enterprise deployments:
`json
{
"mcpServers": {
"langapi": {
"command": "npx",
"args": ["@langapi/mcp-server"],
"env": {
"LANGAPI_API_KEY": "your-api-key",
"LANGAPI_API_URL": "https://your-api-server.com"
}
}
}
}
``---
LangAPI uses a credit-based billing system:
- 1 credit = 1 word to translate
- New users get 1,000 free credits
- Top up with 100,000 credits for $15 (no subscription, no expiry)
Get your API key at langapi.io.
---
MIT