tg_tinder_bot/docs/LOCALIZATION_QUICKSTART.md

Быстрый старт: Система локализации

Что уже работает ✅

1. Выбор языка при первом запуске - новые пользователи видят меню из 10 языков
2. Сохранение языка в БД - колонка users.lang хранит выбор пользователя
3. 10 поддерживаемых языков - ru, en, es, fr, de, it, pt, ko, zh, ja
4. Инфраструктура i18next - готова к использованию

Что нужно сделать ⚠️

ГЛАВНАЯ ЗАДАЧА: Заменить 255 хардкод-текстов

Файлы по приоритету:

1. src/handlers/callbackHandlers.ts - 90 текстов (кнопки, меню)
2. src/handlers/notificationHandlers.ts - 31 текст (уведомления)
3. src/services/notificationService.ts - 22 текста (сервис уведомлений)
4. src/handlers/messageHandlers.ts - 21 текст (создание профиля)
5. Остальные файлы - ~91 текст

Как использовать локализацию в коде

Вариант 1: Через LocalizationService

import LocalizationService from '../services/localizationService';

// В методе класса:
const locService = LocalizationService.getInstance();
const userId = msg.from?.id.toString();
const lang = await this.profileService.getUserLanguage(userId);

locService.setLanguage(lang);
const text = locService.t('profile.namePrompt');

await this.bot.sendMessage(chatId, text);

Вариант 2: Через getUserTranslation (рекомендуется)

import { getUserTranslation } from '../services/localizationService';

const userId = msg.from?.id.toString();
const text = await getUserTranslation(userId, 'profile.namePrompt');

await this.bot.sendMessage(chatId, text);

Вариант 3: С параметрами

// В ru.json:
{
  "welcome": {
    "greeting": "Привет, {{name}}! Добро пожаловать!"
  }
}

// В коде:
const text = await getUserTranslation(userId, 'welcome.greeting', { name: userName });

Процесс замены текста

ШАГ 1: Найти хардкод-текст

# Найти все тексты в файле
grep -n "'[А-Яа-яЁё]\|\"[А-Яа-яЁё]" src/handlers/callbackHandlers.ts

ШАГ 2: Добавить ключ в ru.json

Было в коде:

await bot.sendMessage(chatId, '👤 Введите ваше имя:');

Добавляем в ru.json:

{
  "profile": {
    "prompts": {
      "name": "👤 Введите ваше имя:"
    }
  }
}

ШАГ 3: Заменить в коде

const text = await getUserTranslation(userId, 'profile.prompts.name');
await bot.sendMessage(chatId, text);

ШАГ 4: Добавить перевод в en.json

{
  "profile": {
    "prompts": {
      "name": "👤 Enter your name:"
    }
  }
}

ШАГ 5: Протестировать

# Пересобрать
docker compose up -d --build bot

# Проверить
docker compose logs bot --tail 20

Полезные команды

# Найти все хардкод-тексты
./bin/find_hardcoded_texts.sh

# Посмотреть тексты в конкретном файле
grep -n "'[А-Яа-яЁё]\|\"[А-Яа-яЁё]" src/handlers/callbackHandlers.ts

# Собрать и запустить бота
docker compose up -d --build bot

# Проверить логи
docker compose logs bot --tail 50 -f

# Применить миграцию БД (если еще не применена)
PGPASSWORD='Cl0ud_1985!' psql -h 192.168.0.102 -p 5432 -U trevor \
  -d telegram_tinder_bot -f sql/add_user_language.sql

Структура ключей (рекомендуется)

{
  "language": { ... },      // Управление языком
  "welcome": { ... },       // Приветствия
  "profile": {
    "prompts": { ... },     // Запросы ввода
    "validation": { ... },  // Ошибки валидации
    "labels": { ... }       // Метки полей
  },
  "buttons": { ... },       // Кнопки
  "errors": { ... },        // Общие ошибки
  "commands": { ... },      // Команды бота
  "search": { ... },        // Поиск анкет
  "matches": { ... },       // Матчи
  "notifications": { ... }, // Уведомления
  "settings": { ... },      // Настройки
  "vip": { ... }            // VIP функции
}

Пример: Замена кнопок

Было:

const keyboard = {
    inline_keyboard: [
        [{ text: '❤️ Нравится', callback_data: 'like' }],
        [{ text: '👎 Не нравится', callback_data: 'dislike' }]
    ]
};

Добавили в ru.json:

{
  "buttons": {
    "like": "❤️ Нравится",
    "dislike": "👎 Не нравится"
  }
}

Стало:

const userId = msg.from?.id.toString();
const lang = await this.profileService.getUserLanguage(userId);
this.localizationService.setLanguage(lang);

const keyboard = {
    inline_keyboard: [
        [{ 
            text: this.localizationService.t('buttons.like'), 
            callback_data: 'like' 
        }],
        [{ 
            text: this.localizationService.t('buttons.dislike'), 
            callback_data: 'dislike' 
        }]
    ]
};

Документация

• docs/LOCALIZATION_SYSTEM.md - Полное описание системы
• docs/LOCALIZATION_MIGRATION_PLAN.md - Детальный план замены текстов
• docs/LOCALIZATION_REPORT.md - Отчет о выполненной работе

Следующий шаг

Начните с самого крупного файла:

# Посмотреть все тексты
grep -n "'[А-Яа-яЁё]\|\"[А-Яа-яЁё]" src/handlers/callbackHandlers.ts

# Открыть файл
code src/handlers/callbackHandlers.ts

Заменяйте по 10-20 текстов за раз, тестируйте после каждой замены!

---

Удачи! 🚀