0006 — Языковая политика: английский первый, русский как перевод

Статус: accepted
Дата: 2026-08-06

Контекст

Репозиторий — публичная витрина. README на английском, бейджи ведут на живое демо, но всё, что заинтересованный читатель открывает следующим — вся docs/, SECURITY.md, комментарии в коде — было на русском. Иностранный разработчик, пришедший из README, упирался в стену на втором клике.

Прежняя версия этой записи фиксировала обратную политику («разделение по аудитории: docs/ — русский») и ссылалась на CLAUDE.md §18 — файл, которого в этом репозитории нет: ссылка досталась в наследство от приватного проекта-источника. То есть правило было и неверным для публичного репо, и частично непроверяемым.

Вопрос в том, на каком языке проект пишется, а не на каких он читается.

Решение

Английский — первый язык проекта. Русский остаётся полным переводом там, где читатель русскоязычен по определению.

Английский — источник правды: docs/ (все страницы), README.md, SECURITY.md, идентификаторы кода, комментарии, докстринги, commit-сообщения, комментарии в CI-workflow, сообщения логов и вывод management-команд и скриптов для разработчика.
Русский — перевод и интерфейс заказчика: страницы *.ru.md в docs/, публикуемые на /ru/, README.ru.md, SECURITY.ru.md, всё пользовательское в админке Django (verbose_name, help_text, choices, fieldsets) — админка это рабочее место русскоязычного заказчика, интерфейс продукта, а не документация, — тексты UI сайта в шаблонах, тело уведомлений заказчику (Lead.as_message(), тема письма, имя сделки в amoCRM), а также демо-данные сид-миграций и фикстуры тестов.

Граница проходит по читателю: то, что читает разработчик, — на английском; то, что читает заказчик или посетитель сайта, — на русском.

Сайт документации собирается mkdocs-static-i18n в суффиксном режиме: deploy.md — английский источник, deploy.ru.md — его перевод. Английская версия отдаётся на /, русская на /ru/, переключатель языка — в шапке.

При расхождении версий права английская. Перевод может отставать, источник — нет.

Последствия

Плюсы:

Репозиторий читается снаружи целиком: README, доки, политика безопасности и комментарии в коде — на одном языке.
Русскоязычный читатель ничего не теряет: перевод полный, 1:1, на том же сайте.
Правило записано явно, поэтому новые страницы и новый код не воспроизводят разнобой заново.

Минусы / плата:

Каждую правку документации надо вносить дважды — в page.md и page.ru.md. Забытый второй файл оставляет устаревший перевод (смягчается правилом выше: английский прав).
Миграция существующих комментариев и докстрингов затронула 47 файлов разом — большой диф без изменения поведения, из-за которого git blame по этим строкам указывает на коммит перевода, а не на изменение, где код появился.

История

2026-06-29 — 2026-08-06: действовало «разделение по аудитории»: английский для внешней витрины (README, коммиты, идентификаторы), русский для всего, чем пользовалась работающая команда (docs/, комментарии, докстринги, админка).
2026-08-06: заменено текущей политикой. Запись переписана на месте, а не заменена новой, поэтому этот раздел сохраняет след изменения.
2026-08-06: отложенный этап закрыт в тот же день — переведены комментарии, докстринги, сообщения логов, вывод management-команд и скриптов, комментарии в шаблонах, JS/CSS, .env.example, compose.yaml, pyproject.toml и deploy/. Репозиторий полностью соответствует политике.