Перейти к основному содержимому

ADR 0219 — Справочник входит в перевод

Статус​

Принято. 2026-10-15 (AT-564, решения владельца от 15.10).

Тема: docs. Пересматривает, не редактируя его, пункт 0216, который оставлял docs/reference/** вне перевода.

Контекст​

ADR 0216 сделал pt-BR источником документации, а en, ru и zh-Hans — измеряемыми переводами, но оставил docs/reference/** вне перевода, потому что он «генерируется». Это верно лишь отчасти: из десяти страниц reference/ шесть написаны вручную (artifacts, brb, git-providers, internal-api, permissions, rulesets) и были на английском, а у четырёх генерируемых (configuration, events, llm-providers, scripts) вокруг сгенерированного блока есть ручной текст. Читатель сайта на pt-BR попадал на целые страницы на английском, а паритет их не учитывал.

Решение​

  1. docs/reference/** ВХОДИТ в перевод и в паритет, кроме reference/paridade-de-traducao.md (сам отчёт) и reference/openapi.json.
  2. Источником шести ручных страниц становится pt-BR в docs/, а нынешний английский текст становится копией en.
  3. На генерируемых страницах сгенерированный БЛОК тоже переводится: генератор пишет источник на pt-BR и блок в копию каждой локали по таблице фиксированных текстов.
  4. Отставание, возникающее с каждой новой переменной или событием, принимается как предупреждение отчёта о паритете и плашки страницы, а не как провал.
  5. Заголовок, на который ведут ссылки, получает явный якорь {#current-slug} до перевода, чтобы внешние ссылки не ломались.
  6. Плашка перевода указывает реальный язык страницы через idioma_original во frontmatter.
  7. Страница API (Redoc) тоже будет переведена; это AT-565, а этот ADR только фиксирует решение.
  8. Правило traducao в docmap начинает следить за страницами docs/reference/, кроме страницы паритета.

Последствия​

  • Паритет начинает учитывать reference/, и в первом отчёте цифры падают: непереведённые страницы показываются как отсутствующие или устаревшие, пока до них не дойдут раунды перевода.
  • В docmap нет отрицания glob, поэтому правило traducao перечисляет страницы reference/ по одной; новая страница справочника входит в него в том же PR.
  • Генератор получает отдельный вывод на каждую локаль (пункт 3) — работа для отдельного раунда; до тех пор сгенерированный блок копий остаётся на языке источника.

Ссылки​

  • 0216 — четыре языка, pt-BR как источник.
  • 0206 — страница API на Redoc.