tg_tinder_bot/LOCALIZATION.md

# Система локализации Telegram Tinder Bot

## Обзор

Система локализации обеспечивает многоязычную поддержку бота с использованием i18next для интерфейса и DeepSeek AI для перевода анкет пользователей.

## Архитектура

### Компоненты системы

1. **LocalizationService** - основной сервис локализации интерфейса
2. **DeepSeekTranslationService** - сервис для перевода анкет с помощью AI
3. **TranslationController** - контроллер для управления переводами
4. **Файлы переводов** - JSON файлы с переводами для каждого языка

### Поддерживаемые языки

- 🇷🇺 Русский (ru) - по умолчанию
- 🇺🇸 Английский (en)
- 🇪🇸 Испанский (es)
- 🇫🇷 Французский (fr)
- 🇩🇪 Немецкий (de)
- 🇮🇹 Итальянский (it)
- 🇵🇹 Португальский (pt)
- 🇨🇳 Китайский (zh)
- 🇯🇵 Японский (ja)
- 🇰🇷 Корейский (ko)

## Использование

### Локализация интерфейса

```typescript
import { t } from '../services/localizationService';

// Простой перевод
const message = t('welcome.greeting');

// Перевод с параметрами
const message = t('profile.ageRange', { min: 18, max: 65 });

// Установка языка пользователя
localizationService.setLanguage('en');
```

### Структура файлов переводов

```json
{
  "welcome": {
    "greeting": "Добро пожаловать в Telegram Tinder Bot! 💕",
    "description": "Найди свою вторую половинку прямо здесь!"
  },
  "profile": {
    "name": "Имя",
    "age": "Возраст",
    "bio": "О себе"
  }
}
```

### Перевод анкет (Premium функция)

```typescript
import DeepSeekTranslationService from '../services/deepSeekTranslationService';

const translationService = DeepSeekTranslationService.getInstance();

// Перевод текста анкеты
const result = await translationService.translateProfile({
    text: "Привет! Я люблю путешествовать и читать книги.",
    targetLanguage: 'en',
    sourceLanguage: 'ru'
});
```

## Настройка

### Переменные окружения

```env
# DeepSeek API для перевода анкет
DEEPSEEK_API_KEY=your_deepseek_api_key_here
```

### База данных

Таблица `users` содержит поле `language` для хранения предпочитаемого языка пользователя:

```sql
ALTER TABLE users 
ADD COLUMN language VARCHAR(5) DEFAULT 'ru';
```

## Функции

### Автоматическое определение языка

- При регистрации пользователя язык определяется по `language_code` из Telegram
- Пользователь может изменить язык в настройках
- Поддерживается определение языка текста для перевода

### Премиум функции перевода

- **Перевод анкет** - доступен только для премиум пользователей
- **AI-перевод** - используется DeepSeek API для качественного перевода
- **Контекстный перевод** - сохраняется тон и стиль исходного текста

### Клавиатуры и меню

Все кнопки и меню автоматически локализуются на основе языка пользователя:

```typescript
// Пример создания локализованной клавиатуры
public getLanguageSelectionKeyboard() {
    return {
        inline_keyboard: [
            [
                { text: '🇷🇺 Русский', callback_data: 'set_language_ru' },
                { text: '🇺🇸 English', callback_data: 'set_language_en' }
            ]
        ]
    };
}
```

## Расширение

### Добавление нового языка

1. Создать файл перевода `src/locales/{language_code}.json`
2. Добавить язык в массив поддерживаемых языков в `LocalizationService`
3. Обновить ограничение в базе данных
4. Добавить кнопку в меню выбора языка

### Добавление новых переводов

1. Добавить ключи в основной файл перевода (`ru.json`)
2. Перевести на все поддерживаемые языки
3. Использовать в коде через функцию `t()`

## Безопасность

- API ключ DeepSeek хранится в переменных окружения
- Проверка премиум статуса перед доступом к переводу
- Ограничение по количеству запросов к API
- Таймауты для предотвращения зависания

## Мониторинг

- Логирование ошибок перевода
- Отслеживание использования API
- Статистика по языкам пользователей

## Производительность

- Кэширование переводов интерфейса
- Ленивая загрузка файлов переводов
- Асинхронная обработка запросов к DeepSeek API
- Индексы в базе данных для быстрого поиска по языку