lokalise-mcp 0.2.0

MCP server for syncing translation keys to Lokalise with AI-powered translations

Lokalise MCP Integration

MCP server for extracting translation keys from code and syncing them to Lokalise with AI-powered translations.

Features

• 🔍 Extract translation keys from git diff and untracked files
• 🤖 Three translation modes: No AI, Lokalise AI, or Claude AI
• 👀 Interactive preview before creating keys
• 🛡️ Content safety guards to prevent harmful translations
• 📦 Batch creation with progress tracking (3 keys at a time)
• ⚠️ Skip existing keys automatically
• 🎯 Supports custom translation functions (t, translate, Translate, etc.)

Installation

Prerequisites

• Lokalise account with API access
• Optional: Anthropic API key (only required for Mode 3 - Claude AI translations)
• One of:
  • Docker (for Option 1 - easiest, no Python required)
  • Python 3.10+ with uv/pip (for Options 2-3)

Option 1: Using uvx (Recommended - Simplest Setup)

No installation needed - just works:

Configure Claude Code MCP in ~/.config/claude/config.json:

{
  "mcpServers": {
    "lokalise": {
      "command": "uvx",
      "args": ["lokalise-mcp"],
      "env": {
        "LOKALISE_API_TOKEN": "your-api-token-here",
        "LOKALISE_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}

Note: Add "ANTHROPIC_API_KEY": "your-anthropic-api-key-here" only if you want Mode 3 (Claude AI translations).

Benefits:

• ✅ Zero configuration - just 2 required environment variables
• ✅ Auto-updates to latest version
• ✅ No volume mounts or file path complexity
• ✅ Works immediately

Option 2: Using Docker (Alternative - No Python Required)

Docker is available but more complex because the container needs access to your local git repository:

docker pull sidzan/lokalise-mcp:latest

Note: Docker setup for this MCP is more complex than API-only MCPs (like mcp-atlassian) because lokalise-mcp needs to read your local git repository files. We recommend using uvx (Option 1) instead for simplicity.

If you still want Docker, the image is available at sidzan/lokalise-mcp:latest.

Option 3: Install Globally with pip/uv

If you prefer to install the package:

# Using pip
pip install lokalise-mcp

# Or using uv
uv tool install lokalise-mcp

Then configure Claude Code:

{
  "mcpServers": {
    "lokalise": {
      "command": "lokalise-mcp",
      "env": {
        "LOKALISE_API_TOKEN": "your-api-token-here",
        "LOKALISE_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}

Note: Add "ANTHROPIC_API_KEY": "your-anthropic-api-key-here" only if you want Mode 3 (Claude AI translations).

Option 4: Install from Source (For Development)

git clone <your-repo-url>
cd lokalise-assist
uv tool install .

Then use the same configuration as Option 2.

Configuration

You can customize extraction patterns in .lokalise-mcp.json in your project directory:

{
  "baseBranch": "main",
  "batchSize": 3,
  "filePatterns": ["**/*.tsx", "**/*.ts", "**/*.jsx", "**/*.js"],
  "excludePatterns": ["**/node_modules/**", "**/dist/**"],
  "translationPatterns": {
    "functions": ["t", "translate", "Translate"],
    "defaultParam": "_"
  },
  "safety": {
    "enabled": true
  }
}

Three Translation Modes

lokalise-mcp now supports three translation modes to fit different workflows and budgets:

Mode 1: No Translation - Just create keys

• No AI translation at all
• Creates keys with base language text only
• Fastest and completely free
• Users translate manually in Lokalise UI
• Use when: You prefer manual translation or have your own workflow

Mode 2: Lokalise Auto-Translation (Recommended)

• Creates keys + Lokalise auto-translation task
• Uses Lokalise's built-in AI (Google Translate, DeepL, or Lokalise AI)
• Integrated with your Lokalise plan
• Reuses translation memory for consistency
• Use when: You want AI translation without extra API costs

Mode 3: Claude AI Translation

• Uses Claude (claude-3-5-haiku) for high-quality translations
• Requires ANTHROPIC_API_KEY
• Includes content safety checks
• Most expensive but highest quality
• Use when: You need premium translation quality

Usage Examples

Mode 1: No Translation

"Create translation keys without AI translation"

Mode 2: Lokalise AI (set use_lokalise_translation=true)

"Create translation keys and use Lokalise auto-translation"

Mode 3: Claude AI (requires ANTHROPIC_API_KEY)

"Create translation keys with AI translation"

Quick Start

1. Install following the steps above
2. Configure your API keys in the MCP server config
3. Use the tools in Claude Code by typing commands like:
   • "Preview translation keys from my changes"
   • "Extract and sync translations to Lokalise"

Documentation

• Installation Guide - Setup and configuration
• Usage Guide - How to use the MCP tools
• Implementation Plan - Technical details

Usage

Available MCP Tools

1. get_lokalise_project_info

Get project details including configured languages.

Example usage in Claude Code:

"Show me my Lokalise project info"

2. preview_new_keys

Preview translation keys that would be extracted without creating them (dry run).

Parameters:

• repo_path (optional): Path to your project repository. Defaults to current working directory.
• base_branch (optional): Branch to compare against (default: "main")

Example usage in Claude Code:

"Preview translation keys"

3. extract_and_sync_translations

Extract keys from changed/untracked files and create them in Lokalise with AI translations.

Parameters:

• repo_path (optional): Path to your project repository. Defaults to current working directory.
• base_branch (optional): Branch to compare against (default: "main")
• batch_size (optional): Number of keys to create per batch (default: 3)
• auto_approve (optional): Skip approval prompts (default: false)
• skip_safety_check (optional): Skip content safety checks (default: false)

Example usage in Claude Code:

"Extract and sync translations to Lokalise"

How It Works

1. Extract: Scans files changed in your branch AND untracked files for translation patterns:

   • t('key', { _: 'Default Text' })
   • translate('key', { _: 'Default Text' })
   • Translate('key', { _: 'Default Text' })
   • Or any custom function you configure

2. Translate: Uses Claude AI (claude-3-5-haiku) to generate natural translations for all project languages

3. Verify: Runs safety checks (regex + AI) to prevent harmful/abusive content

4. Create: Adds keys to Lokalise in batches of 3, skipping duplicates automatically

Supported Translation Patterns

The server detects these patterns by default:

// With default text
t("products.title", { _: "Products" })
translate("users.greeting", { _: "Hello" })
Translate("app.welcome", { _: "Welcome!" })

// Without default (will prompt or skip)
t("products.subtitle")

You can customize the function names and default parameter in .lokalise-mcp.json.

License

MIT