Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/romkravets/telegram-bot-googletrans

Telegram Translation Bot A public Telegram bot that translates text, forwarded posts, and photos โ€” right where you are.
https://github.com/romkravets/telegram-bot-googletrans

deepl google-translate inline-bot ocr poll ptb python python-telegram-bot sqlite telegram-bot-ai-assistant tesseract translation

Last synced: 17 days ago
JSON representation

Telegram Translation Bot A public Telegram bot that translates text, forwarded posts, and photos โ€” right where you are.

Awesome Lists containing this project

README 

          
# Telegram Translation Bot



A public Telegram bot that translates text, forwarded posts, and photos โ€” right where you are.



**Developer:** [Roman Kravets](https://github.com/romkravets)



---



## Features



| Feature | Description |

|---------|-------------|

| ๐Ÿ’ฌ Text translation | Send any text โ€” get an instant translation |

| ๐Ÿ“จ Forwarded posts | Forward a channel post or message โ€” bot translates it automatically |

| ๐Ÿ“ท Photo OCR | Send a photo with text โ€” bot extracts and translates it via Tesseract |

| โœ๏ธ Inline mode | Type `@botname text` in **any** chat โ€” see translation without leaving |

| ๐Ÿ‘ฅ Group support | Mention the bot `@botname your text` in any group |

| ๐ŸŒ 30+ languages | DeepL (primary) + Google Translate (fallback) |

| ๐Ÿ’พ Preferences | Per-user language saved in SQLite โ€” remembered across sessions |



---



## How to use



### Private chat

Just send any text, forward a post, or send a photo with text.



### Groups

Mention the bot with your text:

```

@YourBotName ะŸั€ะธะฒั–ั‚, ัะบ ัะฟั€ะฐะฒะธ?

```

For forwarded posts in groups โ€” mention must appear in the caption.



### Inline mode (translate anywhere)

Type `@YourBotName` followed by a space and your text **in any chat**:

```

@YourBotName The quick brown fox jumps over the lazy dog

```

A translation result will appear as a popup โ€” tap it to send.

This is the fastest way to translate without switching chats.



### Commands

| Command | Description |

|---------|-------------|

| `/start` | Welcome message + choose target language |

| `/lang` | Open language picker |

| `/lang Polish` | Set language directly by name |

| `/help` | Show this usage guide |



---



## Supported languages



DeepL (high quality) + Google Translate (fallback for all languages):



๐Ÿ‡บ๐Ÿ‡ฆ Ukrainian ยท ๐Ÿ‡ฌ๐Ÿ‡ง English ยท ๐Ÿ‡ฉ๐Ÿ‡ช German ยท ๐Ÿ‡ซ๐Ÿ‡ท French ยท ๐Ÿ‡ช๐Ÿ‡ธ Spanish ยท ๐Ÿ‡ฎ๐Ÿ‡น Italian ยท ๐Ÿ‡ต๐Ÿ‡ฑ Polish ยท ๐Ÿ‡ต๐Ÿ‡น Portuguese ยท ๐Ÿ‡จ๐Ÿ‡ณ Chinese ยท ๐Ÿ‡ฏ๐Ÿ‡ต Japanese ยท ๐Ÿ‡ฐ๐Ÿ‡ท Korean ยท ๐Ÿ‡ท๐Ÿ‡บ Russian ยท ๐Ÿ‡ธ๐Ÿ‡ฆ Arabic ยท ๐Ÿ‡ณ๐Ÿ‡ฑ Dutch ยท ๐Ÿ‡ธ๐Ÿ‡ช Swedish ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ Danish ยท ๐Ÿ‡ซ๐Ÿ‡ฎ Finnish ยท ๐Ÿ‡จ๐Ÿ‡ฟ Czech ยท ๐Ÿ‡ธ๐Ÿ‡ฐ Slovak ยท ๐Ÿ‡ท๐Ÿ‡ด Romanian ยท ๐Ÿ‡ญ๐Ÿ‡บ Hungarian ยท ๐Ÿ‡ง๐Ÿ‡ฌ Bulgarian ยท ๐Ÿ‡ฌ๐Ÿ‡ท Greek ยท ๐Ÿ‡น๐Ÿ‡ท Turkish ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ Indonesian ยท ๐Ÿ‡ณ๐Ÿ‡ด Norwegian ยท ๐Ÿ‡ฎ๐Ÿ‡ณ Hindi ยท ๐Ÿ‡ป๐Ÿ‡ณ Vietnamese ยท ๐Ÿ‡น๐Ÿ‡ญ Thai ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ Hebrew ยท ๐Ÿ‡ฎ๐Ÿ‡ท Persian



---



## Architecture



```

telegram-bot-googletrans/

โ”œโ”€โ”€ bot.py                  # Entry point: registers all handlers, starts polling

โ”œโ”€โ”€ config.py               # Centralised env var loading (BOT_TOKEN, DEEPL_API_KEY, DB_PATH)

โ”œโ”€โ”€ languages.py            # Language registry (31 languages, DeepL + Google codes)

โ”œโ”€โ”€ handlers/

โ”‚   โ”œโ”€โ”€ start.py            # /start, /lang, /help commands + language keyboard callback

โ”‚   โ”œโ”€โ”€ translate.py        # Text and forwarded message handlers

โ”‚   โ”œโ”€โ”€ photo.py            # Photo handler: download โ†’ OCR โ†’ translate

โ”‚   โ””โ”€โ”€ inline.py           # Inline query handler (@botname text in any chat)

โ”œโ”€โ”€ services/

โ”‚   โ”œโ”€โ”€ translator.py       # DeepL (thread-local singleton) + Google fallback

โ”‚   โ””โ”€โ”€ ocr.py              # Tesseract OCR via pytesseract + Pillow

โ”œโ”€โ”€ db/

โ”‚   โ””โ”€โ”€ storage.py          # SQLite: init, get_language, set_language

โ”œโ”€โ”€ tests/                  # 20 unit tests (languages, storage, OCR, translator)

โ”œโ”€โ”€ ecosystem.config.js     # PM2 process config for VPS deployment

โ”œโ”€โ”€ requirements.txt        # Production dependencies

โ””โ”€โ”€ requirements-dev.txt    # Dev dependencies (adds pytest)

```



All blocking I/O (SQLite, HTTP translation requests, Tesseract OCR) runs via `asyncio.to_thread` so the event loop is never blocked.



---



## Local development



### Prerequisites

- Python 3.10+

- Tesseract OCR installed



Install Tesseract (macOS):

```bash

brew install tesseract

```



Install Tesseract (Ubuntu/Debian):

```bash

sudo apt install tesseract-ocr tesseract-ocr-ukr tesseract-ocr-deu \

  tesseract-ocr-fra tesseract-ocr-spa tesseract-ocr-pol tesseract-ocr-chi-sim

```



### Setup



```bash

git clone https://github.com/romkravets/telegram-bot-googletrans

cd telegram-bot-googletrans



python3 -m venv .venv

source .venv/bin/activate



pip install -r requirements-dev.txt   # includes pytest

cp .env.example .env

# edit .env: fill in BOT_TOKEN and optionally DEEPL_API_KEY

```



### Run tests



```bash

pytest

```



### Start the bot



```bash

python3 bot.py

```



---



## Enable inline mode (required for @botname in any chat)



1. Open [@BotFather](https://t.me/BotFather) in Telegram

2. Send `/setinline`

3. Choose your bot

4. Enter a placeholder hint, e.g. `Enter text to translate...`



That's it. No code changes needed โ€” the bot already handles inline queries.



---



## VPS deployment (Ubuntu/Debian + PM2)



### 1. Install Node.js + PM2



```bash

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

sudo apt-get install -y nodejs

sudo npm install -g pm2

```



### 2. Install Tesseract



```bash

sudo apt install tesseract-ocr tesseract-ocr-ukr tesseract-ocr-deu \

  tesseract-ocr-fra tesseract-ocr-spa tesseract-ocr-pol tesseract-ocr-chi-sim

```



Add more packs as needed: `tesseract-ocr-jpn`, `tesseract-ocr-chi-sim`, etc.



### 3. Clone and configure



```bash

git clone https://github.com/romkravets/telegram-bot-googletrans /opt/translate-bot

cd /opt/translate-bot



python3 -m venv .venv

source .venv/bin/activate

pip install -r requirements.txt



cp .env.example .env

nano .env   # fill in BOT_TOKEN and DEEPL_API_KEY

```



### 4. Start with PM2 and enable auto-start on reboot



```bash

pm2 start ecosystem.config.js

pm2 startup systemd

pm2 save

```



### PM2 commands



```bash

pm2 logs translate-bot      # live logs

pm2 restart translate-bot   # restart

pm2 stop translate-bot      # stop

pm2 list                    # all running processes

```



---



## Environment variables



| Variable | Required | Description |

|----------|----------|-------------|

| `BOT_TOKEN` | โœ… | From [@BotFather](https://t.me/BotFather) |

| `DEEPL_API_KEY` | optional | [DeepL free tier](https://www.deepl.com/pro-api): 500k chars/month. If not set, falls back to Google Translate for all requests |

| `DB_PATH` | optional | SQLite file path (default: `./data/translate_bot.db`) |



---



## Tech stack



- [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) v22 โ€” async bot framework

- [DeepL Python SDK](https://github.com/DeepLcom/deepl-python) โ€” primary translation engine

- [deep-translator](https://github.com/nidhaloff/deep-translator) โ€” Google Translate fallback

- [pytesseract](https://github.com/madmaze/pytesseract) + [Pillow](https://python-pillow.org/) โ€” OCR

- SQLite (stdlib) โ€” user language preferences

- [PM2](https://pm2.keymetrics.io/) โ€” process manager for VPS