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

ADR 0220 — Страница API переводится по каталогу

Статус​

Принято. 2026-10-16 (AT-565, решения владельца от 16.10).

Тема: docs. Выполняет пункт 7 0219 и открывает объявленное исключение из источника pt-BR в 0216.

Контекст​

Справочник API — это страница Redoc, генерируемая из openapi.json (0206), и её текст берётся из декораторов api: почти весь на английском, несколько десятков текстов на pt-BR. У сайта четыре локали, но страница выходила одинаковой во всех. Плагин принимает как spec только путь к файлу, а Docusaurus загружает config по разу на локаль с заданной DOCUSAURUS_CURRENT_LOCALE.

Решение​

  1. Источником описаний остаётся текст декораторов; api не трогается. Это ИСКЛЮЧЕНИЕ из источника pt-BR в ADR 0216: pt-BR, ru и zh-Hans переводят все тексты, а en — только тексты на pt-BR (эвристика: португальский диакритический знак или служебное слово вроде «não», «para», «que»).
  2. Перевод хранится в КАТАЛОГЕ для каждой локали, website/i18n/<locale>/openapi-textos.json, с ключом sha1 (12 hex) исходного текста и полями fonte и traducao. Он покрывает summary/ description на любом уровне spec и подпись тегов (x-displayName); ИМЯ тега не меняется, чтобы якорь #tag/<имя> сохранился.
  3. Spec локали ВЫВОДИТСЯ при сборке в docusaurus.config.ts (scripts/docs/openapi-por-locale.mjs) и пишется в website/.openapi/, игнорируемый git. Ничего выведенного не коммитится.
  4. ОСИРОТЕВШИЙ ключ (хеш, которого больше нет в spec) и НЕВЕРНАЯ запись (источник не совпадает с хешем или разное число фрагментов `…` в источнике и переводе) отклоняют docs:check; отсутствующая запись только предупреждает и откатывается к исходному тексту, как в D3 из 0219.
  5. 18 подписей LabelsConfig в Redoc 2.4.0 переводятся через theme.options.labels. Тексты, зашитые в код без опции («Request Body schema», «Response Schema», «Authorizations», «Search...», «Expand all», «Copy», «required», «API docs by Redocly» и подобные), остаются на английском.
  6. Паритет перевода получает отдельный раздел «API (Redoc)» — в отдельных текстах по локалям, без сложения с символами страниц.

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

  • Новый текст в api отображается как отсутствующий во всех каталогах до следующего раунда перевода; изменённый текст оставляет старую запись осиротевшей, и docs:check требует удалить её в том же PR (pnpm docs:openapi-textos <locale> добавляет новые ключи с traducao: "").
  • Каталоги рождаются пустыми; перевод текстов — отдельный раунд.
  • Страница на pt-BR смешивает подписи Redoc на английском с переведённым остальным — ограничение Redoc, а не выбор содержания.

Ссылки​

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