From f2d4d6d3b176d09e40a4a424a276fd235ced2ddc Mon Sep 17 00:00:00 2001
From: NW <nw@softuniq.eu>
Date: Thu, 25 Jun 2026 23:54:59 +0100
Subject: [PATCH] docs: update README with i18n section, language support, and
 project structure

---
 README.md | 43 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 90f23c8..989cd04 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,8 @@
 - Управление криптокошельками (создание, пополнение, баланс)
 - История транзакций и покупок
 - SaaS-система с автоматическим расчётом комиссий
-- Админ-панель на порту 3001
+- **Мультиязычность (i18n)** — английский, испанский, немецкий с переключением в боте
+- Админ-панель на порту 3001 с вкладкой локализации
 - Tor-прокси с двумя onion-сервисами (SSH + админка)
 - WireGuard VPN для безопасных транзакций
 
@@ -67,6 +68,7 @@ curl http://localhost:3001/health
 | `ADMIN_URL` | — | Полный URL админ-панели (для фото товаров) |
 | `SUPER_ADMIN_IDS` | — | ID супер-админов |
 | `SUPPORT_LINK` | — | Ссылка на поддержку |
+| `DEFAULT_LANGUAGE` | — | Язык по умолчанию (`en`, `es`, `de`; по умолчанию `en`) |
 | `SSH_HOST_IP` | — | Куда Tor перенаправляет SSH (по умолчанию host.docker.internal) |
 | `SHOP_CONTAINER` | — | Имя контейнера магазина (по умолчанию telegram_shop_prod) |
 | `WG_ENABLED` | — | `true` / `false` (по умолчанию `false`) |
@@ -221,6 +223,40 @@ WireGuard по умолчанию отключен (`WG_ENABLED=false`). Для
 
 Контейнер требует `NET_ADMIN` и `sysctl net.ipv4.conf.all.src_valid_mark=1` для WireGuard. Эти привилегии заданы в `docker-compose.yml`.
 
+## Мультиязычность (i18n)
+
+Бот поддерживает 3 языка: **🇬🇧 English**, **🇪🇸 Español**, **🇩🇪 Deutsch**.
+
+### Как это работает
+
+- **`/start`** — всегда показывает выбор языка с флагами
+- **`/language`** — команда для смены языка в любой момент
+- **Профиль** — кнопка «🌐 Change Language» рядом с «Set Location»
+- Выбранный язык сохраняется в БД (`users.language`) и используется во всех сообщениях
+- Интерполяция: `t('key', { param: value })` → `{{param}}` в строках
+- Fallback: запрошенный язык → English → ключ
+
+### Структура i18n
+
+```
+src/i18n/
+├── index.js              # tForUser(), tForLang(), LANGUAGE_NAMES, AVAILABLE_LANGUAGES
+└── locales/
+    ├── en.json           # 201 ключ, английский
+    ├── es.json           # 201 ключ, испанский
+    └── de.json           # 201 ключ, немецкий
+```
+
+### Админ-панель локализации
+
+Вкладка «Локализация» в админ-панели (`/locales`) позволяет просматривать и редактировать все ключи перевода в таблице с сохранением в JSON-файлы.
+
+### Добавление нового языка
+
+1. Создать `src/i18n/locales/<code>.json` по шаблону `en.json`
+2. Добавить код в `AVAILABLE_LANGUAGES` и `LANGUAGE_NAMES` в `src/i18n/index.js`
+3. Язык автоматически появится в выборе при `/start` и `/language`
+
 ## Безопасность
 
 - `.env` монтируется только для чтения (`:ro`)
@@ -243,7 +279,7 @@ WireGuard по умолчанию отключен (`WG_ENABLED=false`). Для
 ```
 ├── src/
 │   ├── admin/            # Админ-панель (Express)
-│   │   ├── routes/       # Роуты админ-панели
+│   │   ├── routes/       # Роуты админ-панели (вкл. /locales для i18n)
 │   │   ├── views/        # Шаблоны HTML
 │   │   ├── public/       # Статические файлы (CSS)
 │   │   ├── auth.js       # Авторизация
@@ -253,6 +289,9 @@ WireGuard по умолчанию отключен (`WG_ENABLED=false`). Для
 │   ├── handlers/         # Обработчики команд
 │   │   ├── adminHandlers/  # Обработчики админа
 │   │   └── userHandlers/    # Обработчики пользователя
+│   ├── i18n/              # Интернационализация
+│   │   ├── index.js         # tForUser(), tForLang(), LANGUAGE_NAMES
+│   │   └── locales/         # en.json, es.json, de.json (201 ключ)
 │   ├── middleware/        # Промежуточные обработчики
 │   ├── migrations/        # Миграции БД
 │   ├── models/            # Модели данных