lokalise-mcp 0.1.1

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
• 🤖 AI-powered translation to multiple languages using Claude
• 👀 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
• Anthropic API key (for 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",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key-here"
      }
    }
  }
}

Benefits:

• ✅ Zero configuration - just 3 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",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key-here"
      }
    }
  }
}

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
  }
}

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