diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7ab2a85
--- /dev/null
+++ b/README.md
@@ -0,0 +1,88 @@
+# Chat Translator
+
+**English** | [Русский](README_RU.md)
+
+A NeoForge mod for Minecraft **1.21.1** that automatically translates chat messages so every player sees them in their own language. Powered by [LibreTranslate](https://libretranslate.com).
+
+## Features
+
+- Per-player translation: each recipient gets the message in their configured language
+- Works with vanilla clients: they simply see the original text (translation requires the mod on the client)
+- Language sources: client locale reported by the mod, vanilla client settings, or automatic detection of the message text (`/detect`)
+- In-game settings GUI (keybind is unbound by default)
+- Translation cache with configurable TTL
+- Optional "show original" line under the translation
+
+## Requirements
+
+| Side | Mod required | Result |
+|------|--------------|--------|
+| Server + Client | yes | Full translation |
+| Server only | server | Players see original messages |
+| Client only | client | Does nothing |
+
+- Minecraft 1.21.1
+- NeoForge 21.1.x
+- A reachable LibreTranslate instance
+
+## Installation
+
+1. Drop `chattranslator-x.y.z.jar` into the `mods/` folder **of your server and/or client**.
+2. Make sure a LibreTranslate instance is reachable (see below).
+3. On the server, edit `config/chattranslator-server.toml`:
+
+```toml
+[server]
+enabled = true
+libretranslate_url = "http://localhost:5000"
+api_key = ""
+show_original = true
+autodetect_language = false
+cache_minutes = 30
+request_timeout_ms = 5000
+```
+
+### Running LibreTranslate
+
+Self-hosted via Docker:
+
+```bash
+docker run -p 5000:5000 libretranslate/libretranslate
+```
+
+Or use a free public instance (no API key):
+
+```
+https://translate.argosopentech.com
+```
+
+`https://libretranslate.com` also works, but requires an API key.
+
+## Usage
+
+Open the settings GUI with a configurable keybind (**Options → Controls → Key Binds → Chat Translator**). From there you can pick your language, test the LibreTranslate connection, and toggle "show original".
+
+> Note: the GUI edits the *server* config, which only takes effect in singleplayer. On dedicated servers use the config file or commands below.
+
+### Commands (operators)
+
+| Command | Description |
+|---------|-------------|
+| `/chattranslate status` | Show status and current URL |
+| `/chattranslate enable` / `disable` | Toggle translation globally |
+| `/chattranslate seturl <url>` | Set the LibreTranslate URL |
+| `/chattranslate setkey <key>` | Set the API key |
+| `/chattranslate showoriginal <true\|false>` | Toggle original messages under translations |
+| `/chattranslate clearcache` | Clear the translation cache |
+
+## Building from source
+
+```bash
+gradlew build
+```
+
+The jar is written to `build/libs/chattranslator-1.0.0.jar`.
+
+## License
+
+[MIT](LICENSE)
diff --git a/README_RU.md b/README_RU.md
new file mode 100644
index 0000000..3d34029
--- /dev/null
+++ b/README_RU.md
@@ -0,0 +1,88 @@
+# Chat Translator
+
+[English](README.md) | **Русский**
+
+Мод для NeoForge (Minecraft **1.21.1**), который автоматически переводит чат так, чтобы каждый игрок видел сообщения на своём языке. Использует [LibreTranslate](https://libretranslate.com).
+
+## Возможности
+
+- Перевод для каждого игрока: каждый получатель видит сообщение на своём языке
+- Поддержка ванильных клиентов: они просто видят оригинальный текст (для перевода нужен мод и на клиенте)
+- Язык игрока: из локали клиента с модом, из настроек ванильного клиента или автодетект текста сообщения (`/detect`)
+- GUI настроек в игре (клавиша по умолчанию не назначена)
+- Кеш переводов с настраиваемым временем жизни
+- Опциональный показ оригинала под переводом
+
+## Требования
+
+| Сторона | Нужен мод | Результат |
+|---------|-----------|-----------|
+| Сервер + Клиент | да | Полный перевод |
+| Только сервер | сервер | Игроки видят оригинал |
+| Только клиент | клиент | Ничего не делает |
+
+- Minecraft 1.21.1
+- NeoForge 21.1.x
+- Доступный инстанс LibreTranslate
+
+## Установка
+
+1. Положите `chattranslator-x.y.z.jar` в папку `mods/` **на сервере и/или клиенте**.
+2. Убедитесь, что доступен LibreTranslate (см. ниже).
+3. На сервере отредактируйте `config/chattranslator-server.toml`:
+
+```toml
+[server]
+enabled = true
+libretranslate_url = "http://localhost:5000"
+api_key = ""
+show_original = true
+autodetect_language = false
+cache_minutes = 30
+request_timeout_ms = 5000
+```
+
+### Запуск LibreTranslate
+
+Локально через Docker:
+
+```bash
+docker run -p 5000:5000 libretranslate/libretranslate
+```
+
+Или используйте бесплатный публичный инстанс (без API-ключа):
+
+```
+https://translate.argosopentech.com
+```
+
+`https://libretranslate.com` тоже подходит, но требует API-ключ.
+
+## Использование
+
+Откройте GUI настроек назначенной клавишей (**Настройки → Управление → Клавиши → Chat Translator**). Там можно выбрать свой язык, проверить соединение с LibreTranslate и включить/выключить показ оригинала.
+
+> Примечание: GUI меняет *серверный* конфиг, поэтому реально работает только в одиночной игре. На выделенном сервере используйте конфиг-файл или команды ниже.
+
+### Команды (для операторов)
+
+| Команда | Описание |
+|---------|----------|
+| `/chattranslate status` | Статус и текущий URL |
+| `/chattranslate enable` / `disable` | Включить / выключить перевод глобально |
+| `/chattranslate seturl <url>` | Задать адрес LibreTranslate |
+| `/chattranslate setkey <key>` | Задать API-ключ |
+| `/chattranslate showoriginal <true\|false>` | Показывать оригинал под переводом |
+| `/chattranslate clearcache` | Очистить кеш переводов |
+
+## Сборка из исходников
+
+```bash
+gradlew build
+```
+
+Готовый jar появится в `build/libs/chattranslator-1.0.0.jar`.
+
+## Лицензия
+
+[MIT](LICENSE)