refactor: translate comments and documentation to improve clarity for Russian-speaking developers

Author: 4RH1T3CT0R7

README.md

@@ -294,11 +294,14 @@ TJudge/
 | Документ | Описание |
 |----------|----------|
 | [docs/USER_GUIDE.md](docs/USER_GUIDE.md) | Руководство пользователя и администратора |
-| [docs/SETUP.md](docs/SETUP.md) | Настройка окружения, разработка, деплой |
+| [docs/SETUP.md](docs/SETUP.md) | Настройка окружения и локальная разработка |
 | [docs/SELF_HOSTED.md](docs/SELF_HOSTED.md) | Развёртывание на собственном сервере |
+| [docs/OPERATIONS.md](docs/OPERATIONS.md) | Production деплой, runbook, бэкапы, мониторинг |
+| [docs/SLO.md](docs/SLO.md) | Service Level Objectives и алерты |
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Детальная архитектура системы |
 | [docs/API_GUIDE.md](docs/API_GUIDE.md) | REST API и WebSocket эндпоинты |
 | [docs/DATABASE_SCHEMA.md](docs/DATABASE_SCHEMA.md) | Схема базы данных |
+| [docs/ADDING_GAMES.md](docs/ADDING_GAMES.md) | Добавление новых игр |
 | [docs/PERFORMANCE_TESTING.md](docs/PERFORMANCE_TESTING.md) | Тестирование производительности |
 
 ---

cmd/api/main.go

@@ -80,7 +80,7 @@ func main() {
 		zap.String("env", "production"),
 	)
 
-	// P2.6: OpenTelemetry tracing (опционально, если задан OTEL_EXPORTER_OTLP_ENDPOINT).
+	// OpenTelemetry tracing (опционально, если задан OTEL_EXPORTER_OTLP_ENDPOINT).
 	otelShutdown, err := observability.InitTracerProvider(context.Background(), "tjudge-api", "dev", log)
 	if err != nil {
 		log.Warn("Failed to init OTel tracing (continuing without)", zap.Error(err))
@@ -179,9 +179,9 @@ func main() {
 		events.MatchesCreated{}, events.MatchResultProcessed{},
 	)
 
-	// Redis Pub/Sub bridge: receive events from worker process for WebSocket broadcast.
-	// Uses a dedicated bus so that worker-originated events only trigger broadcast,
-	// avoiding double cache updates (worker already updated its own cache).
+	// Мост Redis Pub/Sub: принимает события из процесса воркера для рассылки по WebSocket.
+	// Используется отдельная шина, чтобы события от воркера триггерили только рассылку
+	// и не приводили к повторному обновлению кэша (воркер уже обновил свой кэш).
 	wsBus := events.NewSyncBus(log)
 	wsBus.Subscribe(
 		eventhandlers.NewBroadcastHandler(wsHub, log),
@@ -261,7 +261,7 @@ func main() {
 	// Создаём API сервер
 	adminChecker := middleware.NewVerifiedAdminChecker(userRepo, 5*time.Minute)
 
-	// P1.12: audit log (async). Буфер 2048 — при нагрузке 10 admin-запросов/сек
+	// Audit log (async). Буфер 2048: при нагрузке 10 admin-запросов/сек
 	// даёт ~200 сек запаса перед drop'ом.
 	auditRepo := db.NewAuditLogRepository(database)
 	auditLogger := middleware.NewAuditLogger(auditRepo, 2048, log)
@@ -346,7 +346,7 @@ func main() {
 	if err := srv.Shutdown(shutdownCtx); err != nil {
 		log.Error("API server forced to shutdown", zap.Error(err))
 	}
-	// UR bug_015: останавливаем background-горутины (rate-limiter cleanup).
+	// Останавливаем background-горутины (rate-limiter cleanup).
 	apiServer.Close()
 
 	// Останавливаем metrics сервер

cmd/benchmark/main.go

@@ -13,7 +13,7 @@ import (
 	"time"
 )
 
-// BenchmarkResult holds parsed benchmark result
+// BenchmarkResult хранит распарсенный результат бенчмарка.
 type BenchmarkResult struct {
 	Name       string
 	NsOp       int64
@@ -22,15 +22,15 @@ type BenchmarkResult struct {
 	Iterations int64
 }
 
-// BenchmarkStandard defines expected performance standards
+// BenchmarkStandard описывает ожидаемые стандарты производительности.
 type BenchmarkStandard struct {
 	Name         string
 	Description  string
 	ExpectedNsOp int64
 	Category     string
 }
 
-// Rating represents performance rating
+// Rating представляет оценку производительности.
 type Rating string
 
 const (
@@ -41,7 +41,7 @@ const (
 	RatingCritical   Rating = "CRITICAL"
 )
 
-// Color codes for terminal output
+// Цветовые коды для вывода в терминал.
 const (
 	colorReset  = "\033[0m"
 	colorRed    = "\033[31m"
@@ -53,9 +53,9 @@ const (
 	colorBold   = "\033[1m"
 )
 
-// Standards defines expected performance for each benchmark
+// Standards описывает ожидаемую производительность для каждого бенчмарка.
 var Standards = map[string]BenchmarkStandard{
-	// API Benchmarks
+	// Бенчмарки API
 	"BenchmarkHealthEndpoint": {
 		Name:         "Health Endpoint",
 		Description:  "Basic health check endpoint",
@@ -117,7 +117,7 @@ var Standards = map[string]BenchmarkStandard{
 		Category:     "API",
 	},
 
-	// Worker Benchmarks
+	// Бенчмарки Worker
 	"BenchmarkWorkerPool_ThroughputSmall": {
 		Name:         "Worker Pool Small",
 		Description:  "2-4 workers, 100 matches",
@@ -161,7 +161,7 @@ var Standards = map[string]BenchmarkStandard{
 		Category:     "Worker",
 	},
 
-	// Queue Benchmarks
+	// Бенчмарки Queue
 	"BenchmarkQueueEnqueue": {
 		Name:         "Queue Enqueue",
 		Description:  "Add match to Redis queue",
@@ -199,7 +199,7 @@ var Standards = map[string]BenchmarkStandard{
 		Category:     "Queue",
 	},
 
-	// Database Benchmarks
+	// Бенчмарки БД
 	"BenchmarkDBHealth": {
 		Name:         "DB Health",
 		Description:  "Database health check",
@@ -305,25 +305,25 @@ func main() {
 		fmt.Println("Note: Only standalone benchmarks (no DB/Redis required)")
 		fmt.Println()
 
-		// Run only benchmarks that don't require external services
-		// Exclude: API (needs full server), Queue (needs Redis), DB (needs Postgres)
-		// Include: Worker pool mocks, JSON parsing, UUID generation, Match creation
+		// Запускаем только бенчмарки, которым не нужны внешние сервисы.
+		// Исключаем: API (нужен полноценный сервер), Queue (нужен Redis), DB (нужен Postgres).
+		// Включаем: моки Worker pool, JSON parsing, UUID generation, Match creation.
 		args := []string{
 			"test",
 			"-tags=benchmark",
 			"-bench=" + *pattern,
 			"-benchmem",
 			"-benchtime=500ms",
 			"-timeout=30s",
-			"-run=^$", // Don't run regular tests
+			"-run=^$", // Не запускать обычные тесты.
 			"./tests/benchmark/...",
 		}
 		if *verbose {
 			args = append(args, "-v")
 		}
 
-		// #nosec G204 -- "go" hardcoded; args — hardcoded benchmark flags
-		// (bench regex, timeout, test path). CLI-utility, не server-endpoint.
+		// #nosec G204 -- "go" hardcoded; args - hardcoded benchmark flags
+		// (bench regex, timeout, test path). CLI-утилита, а не серверный эндпоинт.
 		cmd := exec.Command("go", args...)
 		cmd.Dir = findProjectRoot()
 
@@ -334,7 +334,7 @@ func main() {
 		err = cmd.Run()
 		output = stdout.Bytes()
 
-		// Print output in real-time for debugging
+		// Печатаем вывод для отладки.
 		if *verbose {
 			fmt.Println(string(output))
 		}
@@ -346,7 +346,7 @@ func main() {
 			}
 		}
 	} else {
-		// Read from stdin
+		// Читаем из stdin.
 		fmt.Println(colorCyan + "Reading benchmark results from stdin..." + colorReset)
 		fmt.Println("(Run with -run flag to execute benchmarks automatically)")
 		fmt.Println()
@@ -375,20 +375,20 @@ func main() {
 }
 
 func disableColors() {
-	// Can't reassign constants, so we'd need to use variables
-	// For simplicity, we'll skip this feature
+	// Константы нельзя переопределить, потребовались бы переменные.
+	// Для простоты эту фичу пропускаем.
 }
 
 func findProjectRoot() string {
-	// Try to find go.mod
+	// Пытаемся найти go.mod.
 	dir, _ := os.Getwd()
 	return dir
 }
 
 func parseBenchmarkOutput(output string) []BenchmarkResult {
 	var results []BenchmarkResult
 
-	// Pattern: BenchmarkName-N    iterations    ns/op    B/op    allocs/op
+	// Шаблон: BenchmarkName-N    iterations    ns/op    B/op    allocs/op.
 	re := regexp.MustCompile(`(Benchmark\w+)(?:-\d+)?\s+(\d+)\s+([\d.]+)\s+ns/op(?:\s+([\d.]+)\s+B/op)?(?:\s+(\d+)\s+allocs/op)?`)
 
 	for _, line := range strings.Split(output, "\n") {
@@ -476,7 +476,7 @@ func printResults(results []BenchmarkResult) {
 	fmt.Println(colorBold + "================================================================================" + colorReset)
 	fmt.Println()
 
-	// Group by category
+	// Группируем по категориям.
 	categories := map[string][]BenchmarkResult{
 		"API":    {},
 		"Worker": {},
@@ -537,7 +537,7 @@ func printResults(results []BenchmarkResult) {
 		}
 	}
 
-	// Summary
+	// Итоги.
 	fmt.Println(colorBold + "================================================================================" + colorReset)
 	fmt.Println(colorBold + "                              SUMMARY" + colorReset)
 	fmt.Println(colorBold + "================================================================================" + colorReset)
@@ -553,7 +553,7 @@ func printResults(results []BenchmarkResult) {
 	fmt.Printf("  %s---%s Critical  (> 5.0x):          %d\n", colorRed, colorReset, ratings[RatingCritical])
 	fmt.Println()
 
-	// Recommendations
+	// Рекомендации.
 	if ratings[RatingCritical] > 0 {
 		fmt.Printf("  %s!!! CRITICAL:%s Some benchmarks are >5x slower than expected.\n", colorRed, colorReset)
 		fmt.Println("      Immediate investigation required!")

cmd/worker/main.go

@@ -113,7 +113,7 @@ func main() {
 		events.MatchResultProcessed{},
 	)
 
-	// Redis Pub/Sub bridge: forward events to API process for WebSocket broadcast
+	// Мост Redis Pub/Sub: пересылает события в процесс API для рассылки по WebSocket.
 	redisEventPub := events.NewRedisEventPublisher(redisCache, log)
 	eventBus.Subscribe(
 		redisEventPub,
@@ -328,7 +328,7 @@ func tryBuildWithCompose(log *logger.Logger) bool {
 
 	for _, path := range composePaths {
 		if _, err := os.Stat(path); err == nil {
-			// #nosec G204 -- "docker compose" hardcoded; path — hardcoded список
+			// #nosec G204 -- "docker compose" hardcoded; path - hardcoded список
 			// composePaths, не из внешнего input.
 			cmd := exec.Command("docker", "compose", "-f", path, "build", "tjudge-cli")
 			cmd.Stdout = os.Stdout
@@ -370,7 +370,7 @@ func tryBuildDirectly(log *logger.Logger) bool {
 	for _, paths := range dockerfilePaths {
 		if _, err := os.Stat(paths.dockerfile); err == nil {
 			// #nosec G204 -- все args hardcoded (docker, build, -t, tag);
-			// paths.dockerfile/context — hardcoded struct-literal.
+			// paths.dockerfile/context - hardcoded struct-literal.
 			cmd := exec.Command("docker", "build",
 				"-t", "tjudge-cli:latest",
 				"-f", paths.dockerfile,

docs/ADDING_GAMES.md

@@ -5,15 +5,15 @@
 ## Обзор
 
 Каждая игра состоит из двух частей:
-1. **Исполнитель** — логика игры в tjudge-cli (Rust)
-2. **Плагин** — метаданные игры в Go-сервере
+1. **Исполнитель** - логика игры в tjudge-cli (Rust)
+2. **Плагин** - метаданные игры в Go-сервере
 
 ## Шаг 1: Реализация логики игры в tjudge-cli
 
 Добавьте новый тип игры в проект [tjudge-cli](https://github.com/bmstu-itstech/tjudge-cli):
 
 1. Создайте модуль игры в `src/games/your_game.rs`
-2. Реализуйте trait `Game` — определите протокол взаимодействия (инициализация, итерации, подсчёт очков)
+2. Реализуйте trait `Game`: определите протокол взаимодействия (инициализация, итерации, подсчёт очков)
 3. Зарегистрируйте новый тип игры в CLI-аргументах
 4. Соберите обновлённый Docker-образ `tjudge-cli`
 
@@ -79,4 +79,4 @@ curl -X POST http://localhost:8080/api/v1/tournaments/<tournament_id>/games/<gam
 
 - **Множитель очков** (`ScoreMultiplier`) нужен для балансировки. Если очки за раунд в вашей игре значительно выше или ниже, чем в Дилемме заключённого, подберите множитель так, чтобы вклад игры в общий рейтинг был сопоставим.
 - **Имя игры** должно быть одинаковым в tjudge-cli и в Go-плагине. Именно по нему система сопоставляет записи в БД с исполнителем.
-- **Правила** в формате Markdown отображаются участникам на странице игры. Включайте протокол взаимодействия, формат ввода/вывода и ограничения.
+- **Правила** в формате Markdown отображаются участникам на странице игры. Включайте протокол взаимодействия, формат ввода и вывода и ограничения.