🌐 Translation Bot

A lightweight, self-hostable CLI tool that translates any open source project into multiple languages using LLMs.

Drop it in any project, run it, answer a few questions, get a PR.

---

Quickstart

# 1. Clone or download this repo
git clone https://github.com/your-username/translation-bot
cd translation-bot

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

# 3. Run it from any project folder
python translate.py --path /path/to/your/project

# Or from inside the project:
cd /path/to/your-project
python /path/to/translation-bot/translate.py

The CLI will guide you through everything interactively.

---

What it detects automatically

Project type	What it finds
Apps with i18n	en.json / en.yaml inside locales/, i18n/, lang/, translations/
Docs repos	All .md files in the project
Mixed (e.g. Hoppscotch)	Both locale files + markdown
Monolingual	English-only project — creates locale structure from scratch
Language registry	languages.json — patched automatically

---

LLM Providers

Provider	Free tier	Quality	Setup
Groq	✅ Yes	Good	console.groq.com
Anthropic Claude	❌ Paid	Excellent	console.anthropic.com
OpenAI GPT-4o	❌ Paid	Excellent	platform.openai.com
Ollama	✅ Local	Varies	ollama.com

API keys are stored securely in your OS keychain (Windows Credential Manager / macOS Keychain / Linux Secret Service) — never in a file on disk.

---

CLI Options

python translate.py                     # interactive mode
python translate.py --path /my/project  # specify project path
python translate.py --review            # enable 2-pass self-review
python translate.py --dry-run           # translate but don't commit/push
python translate.py --clear-keys        # remove stored API keys

---

Supported Languages (v1)

Tier 1 — Spanish, French, German, Portuguese (Brazil), Chinese, Japanese, Korean, Arabic, Hindi, Russian, Italian

Tier 2 — Dutch, Polish, Turkish, Swedish, Czech, Indonesian, Vietnamese, Ukrainian, Thai, Danish, Norwegian

---

Adding a Custom Provider

Create bot/providers/myprovider.py:

from bot.providers.base import BaseProvider
import requests

class MyProvider(BaseProvider):
    name             = "My Custom Model"
    requires_api_key = True

    def __init__(self, api_key):
        self.api_key = api_key

    def translate(self, prompt: str) -> str:
        # call your API here
        ...

    def is_available(self) -> bool:
        # check if your API is reachable
        ...

Then add it to bot/providers/registry.py — it'll appear in the CLI menu automatically.

---

Roadmap

• MCP server mode (use as a tool in Claude Desktop / Cursor)
• .translation-bot.yml config file for non-interactive runs
• Glossary support (save approved corrections, reuse in future runs)
• PO/POT file support (gettext)
• PyInstaller single-file executable
• pip install translation-bot packaging