lokalise-mcp 0.1.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
• 🤖 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

Note: This package is ready for PyPI publication. Once published, installation will be as simple as the commands below. Until then, use Option 3 (Install from Source).

Prerequisites

• Python 3.10+
• Lokalise account with API access
• Anthropic API key (for AI translations)

Option 1: Using uvx (Recommended - No Installation Required)

The easiest way to use lokalise-mcp is with uvx, which runs it without installing:

1. Configure Claude Code MCP:

   Edit ~/.config/claude/config.json:

   {
     "mcpServers": {
       "lokalise": {
         "command": "uvx",
         "args": ["--from", "lokalise-mcp", "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"
         }
       }
     }
   }
   

2. Restart Claude Code - that's it! uvx will automatically download and run the latest version.

Option 2: 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 3: 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