🌍 MCP-Localization-Engine

Global localization data for 174 locales via MCP (Model Context Protocol)

🎯 What is this?

A Model Context Protocol (MCP) server that provides comprehensive localization data for 174 locales worldwide. Perfect for AI agents and applications that need to generate culturally-adapted multilingual content.

✨ Features

• 174 Locales: Complete coverage across Europe, Asia, Americas, Middle East, Africa, and Oceania
• 3 MCP Tools:
  • get_locale_config: Technical metadata (timezone, currency, script, etc.)
  • get_cultural_data: Cultural adaptation data (values, tone, references)
  • get_rules: Global rules (slug generation, SEO, content adaptation)
• Smart Caching: 24-hour TTL with 98% hit rate
• Fast: 2-5ms response time (cached), 50ms (cold)
• Production Ready: Validated schemas, error handling, comprehensive tests

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/supernovae/mcp-localization-engine.git
cd mcp-localization-engine

# Install dependencies
pip install -r requirements.txt

# Verify installation
python src/server.py --version

Running the MCP Server

# Start the server
python src/server.py

# Output:
# 🚀 MCP-Localization-Engine v1.0.0
# 📂 Loaded 174 locales
# 💾 Cache initialized (TTL: 24h)
# ✅ Server ready on stdio

Configure with Claude Desktop

macOS:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Linux:

nano ~/.config/Claude/claude_desktop_config.json

Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "localization": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/mcp-localization-engine/src/server.py"]
    }
  }
}

⚠️ Replace /ABSOLUTE/PATH/TO/ with your actual path!

Restart Claude Desktop to load the configuration.

Test in Claude

Open Claude and try:

"Use the localization MCP to get the configuration for French (France)"

Claude should call get_locale_config("fr-FR") and return technical data!

📚 Documentation

• Complete Documentation - Full guides in docs/ folder
• Architecture - System architecture
• MCP Tools - Detailed tool documentation
• Quick Start - 10-minute setup guide
• Development - Contributing guide

🔧 Usage Example

from src.loader import load_locale_config, load_cultural_data

# Get technical config
config = load_locale_config("ja-JP")
print(config["timezone"])    # "Asia/Tokyo"
print(config["currency"])    # "JPY"
print(config["script"])      # "CJK"

# Get cultural data
cultural = load_cultural_data("ja-JP")
print(cultural["cultural_values"])  # ["Harmony (和)", "Respect for hierarchy", ...]
print(cultural["tone_preferences"]["business"])  # "Formal, polite, humble"

🌍 Supported Locales

174 locales across:

• 🇪🇺 Europe: 75 locales
• 🌏 Asia: 45 locales
• 🌎 Americas: 20 locales
• 🌍 Middle East: 20 locales
• 🌍 Africa: 9 locales
• 🇦🇺 Oceania: 5 locales

View complete list →

🧪 Testing

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src --cov-report=html

# Validate all locale data
python tests/validate_data.py

# Run specific test
pytest tests/test_tools.py -v

🛠️ Development

# Install dev dependencies
pip install -r requirements-dev.txt

# Generate a new locale template
python scripts/generate_locale.py pt-BR

# List all locales
python scripts/list_locales.py

# Benchmark performance
python scripts/benchmark.py

📊 Project Stats

• Code: ~1,000 lines of Python
• Data: ~4.5 MB (174 configs + 174 culturals + 3 rules)
• Tests: 20+ test cases
• Cache Hit Rate: 98%
• Response Time: 2-5ms (cached), 50ms (cold)

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Adding a New Locale

1. Generate template: python scripts/generate_locale.py xx-YY
2. Fill in the data in data/locales/config/xx-YY.json and data/locales/cultural/xx-YY.json
3. Validate: python tests/validate_data.py --locale xx-YY
4. Submit PR

📄 License

MIT License - see LICENSE

🔗 Links

• GitHub Repository
• Documentation
• Issues
• MCP Protocol

💡 Use Cases

• Content Generation: Generate culturally-adapted marketing content
• SEO Optimization: Get locale-specific SEO rules
• URL Generation: Generate proper slugs per locale
• Cultural Adaptation: Avoid cultural faux-pas
• Multi-project: Shared foundation for all your localization needs

🏢 Built by SuperNovae Studio

Made with ❤️ for the global developer community.

---

Questions? Open an issue or check the docs!