Telegram Translation Bot

A self-hosted Telegram bot that silently translates messages between Spanish, English, and Swedish in real time — no cloud AI APIs required.

Spanish  →  🇬🇧 English  +  🇸🇪 Swedish
English  →  🇪🇸 Spanish  +  🇸🇪 Swedish
Swedish  →  🇪🇸 Spanish  +  🇬🇧 English

---

Features

• Offline language detection — uses lingua locally; no external API calls for detection
• LLM-powered translation — any model served by Ollama (local or remote)
• Smart filtering — ignores emoji-only messages, photos, videos, and stickers automatically
• Per-chat toggle — each chat can independently enable or disable the bot
• Docker support — single command to deploy on any server

---

How it works

Telegram message
      │
      ▼
lingua (local, offline)
  detects language
      │
      ▼
Ollama  ──────────────────────────────────────────────────
  translate to language A  │  translate to language B
         (parallel)        │        (parallel)
      │                    │              │
      └────────────────────┘──────────────┘
                           │
                           ▼
                  reply with both translations

File	Responsibility
bot.py	Telegram commands, per-chat state, message flow
translator.py	Language detection and Ollama calls
prompts.py	Translation prompt builders
config.py	Settings loaded from environment variables

---

Prerequisites

• A Telegram bot token — create one via @BotFather
• Ollama running locally or on a reachable server with a model pulled:

ollama pull translategemma:4b   # recommended — purpose-built for translation
# or any other model, e.g.:
ollama pull qwen2.5:3b

---

Deployment

Docker (recommended)

# 1. Clone the repo
git clone https://github.com/Manuel0516/telegram-translation-bot
cd telegram-translation-bot

# 2. Configure
cp .env.example .env
# Edit .env and set at least TELEGRAM_BOT_TOKEN and OLLAMA_URL

# 3. Build and run
docker build -t telegram-translation-bot .
docker run -d --restart unless-stopped --env-file .env telegram-translation-bot

Local / manual

# 1. Create a virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

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

# 3. Configure
cp .env.example .env
# Edit .env and set at least TELEGRAM_BOT_TOKEN and OLLAMA_URL

# 4. Run
python bot.py

---

Configuration

All settings are read from the .env file (see .env.example):

Variable	Default	Description
TELEGRAM_BOT_TOKEN	required	Token from @BotFather
OLLAMA_URL	http://localhost:11434/api/chat	Ollama API endpoint
OLLAMA_MODEL	qwen2.5:3b	Model used for translation
MAX_CONTEXT_MESSAGES	6	Recent messages kept for context
REQUEST_TIMEOUT	60	Ollama request timeout in seconds

To point the bot at a remote Ollama instance, set:

OLLAMA_URL=http://192.168.1.100:11434/api/chat

---

Commands

Command	Description
/on	Enable automatic translation
/off	Disable automatic translation
/status	Show whether translation is on/off
/help	Show usage instructions

---

License

MIT