0068. Сайт документации и одиннадцать языков консоли

Статус: accepted. Owner: Ian Panaev. Дата: 2026-10-05.

Контекст

Пользовательская документация жила в README и в инженерных документах docs/ на русском. README накапливал историю изменений и расходился с кодом: «стадия 0.2», «сторонние протоколы не эмулируются» при работающих OCI, Git LFS и npm, «RU/EN-консоль». Пользователю негде было найти установку, работу с клиентами и справочник API по разделам, с поиском и на своём языке. Консоль говорила на двух языках, документация — на одном.

Решение

Сайт wiki/ (VitePress) публикуется на GitHub Pages: https://proanima.github.io/Arkvory/.

• Разделы: начало работы, установка и обновление, работа с Arkvory, клиенты и протоколы, эксплуатация, HTTP API, справочник API, справка; порядок задаёт wiki/.vitepress/structure.ts.
• Исходный язык — английский; переводы лежат в wiki/<code>/ с теми же страницами и id заголовков. Раздел для разработчиков — копия docs/ на русском, на других языках он помечен «на русском» и не переводится (AGENTS.md).
• Справочник API и страница ошибок генерируются перед каждой сборкой (scripts/wiki.mjs) из OpenAPI, политик операций и кодов ошибок. Тексты для читателей хранятся в wiki/i18n/api/<code>.json вместе с исходным текстом, с которого они написаны (en). Изменился контракт или английский текст — страница показывает источник, а tests/wiki.test.mjs падает, пока текст не обновлён. Расхождение справочника с API обнаруживается тестом.
• Подписи элементов консоли в страницах — ключи словаря ([[ui:key]]), сборка подставляет текст на языке страницы. Переименованный или удалённый ключ ломает сборку.
• Поиск локальный (MiniSearch), слова режутся Intl.Segmenter, так что китайский и японский ищутся по словам.
• Сборка — гейт docs (verify и release), отдельное задание CI. Workflow pages.yml собирает только main; право pages: write есть только у задачи публикации, которая не выполняет код репозитория (scripts/policy/pages-workflow.mjs).

Языки консоли: английский, русский, испанский, французский, немецкий, португальский (Бразилия), китайский (упрощённый), японский, корейский, хинди, арабский (справа налево). Один список — apps/web/src/languages.ts; сайт читает его же.

• Английский и русский в бандле. Остальные словари — apps/web/locales/<code>.json (у каждого текста — английский оригинал, с которого он переведён); сборка кладёт тексты в public/locales/, консоль загружает словарь при выборе языка.
• Маршрут GET /console/locales/:file отдаёт только имя из двух строчных латинских букв с .json: имя проверяется до обращения к файловой системе, с той же CSP, что и остальная консоль. Это статический маршрут консоли, не часть /api/v1.
• Не загрузился словарь — консоль остаётся на текущем языке (при запуске — английский); отсутствующий в файле текст показывается по-английски.
• Арабский: <html dir="rtl"> до первой отрисовки, логические свойства CSS; числа — латинскими цифрами (ar-u-nu-latn), как размеры и порты рядом.

Альтернативы

• Документация в README и docs/. Нет разделов, поиска и языков; именно это и разошлось.
• Перевести docs/. Инженерные документы меняются с кодом; их перевод на десять языков устаревал бы быстрее, чем пишется. Пользователю нужен другой текст: задача, шаги, ограничения.
• Сайт внутри сервера (/docs/). Работал бы без интернета, но добавил бы десятки мегабайт в каждый пакет и ещё одну поверхность сервера. Ссылка из консоли ведёт на опубликованный сайт; для закрытых сетей сайт собирается из исходников (npm run wiki -- build).
• Все словари консоли в бандле. Каждый язык добавил бы ~80 КБ к первой загрузке для всех.
• VitePress 1.6. Тянет уязвимую в dev-сервере ветку vite 5, и npm audit --audit-level=high падает; выбрана 2.0.0-alpha с vite 8 и чистым аудитом. Сайт статический, в рантайм сервера не попадает.

Последствия

• Новый текст консоли добавляется в английский и русский словари, затем во все apps/web/locales/*.json; тест называет каждый непереведённый или устаревший текст.
• Страница вики, изменённая по-английски, меняется в тех же коммитах во всех полностью переведённых языках (COMPLETE: английский, русский, испанский, немецкий, китайский, хинди, корейский, французский и португальский); тест называет страницу, id заголовка, метку или блок кода, которых не хватает. Остальные языки показывают английскую страницу-заглушку (с предупреждением на их языке) там, где перевода ещё нет; заглушки в git, их актуальность проверяет тест.
• Установщик Windows, мастер удалённой установки и arkvoryctl остаются на английском и русском; отзывы в хаб уходят с языком ru или en (контракт хаба).
• Публикация сайта требует включить GitHub Pages с источником «GitHub Actions» в настройках репозитория.

Проверка

tests/web-locales.test.mjs (словари, плейсхолдеры, выбор языка, RTL), tests/wiki.test.mjs (страницы, id, метки, тексты сайта, глоссарий, справочник API), tests/integration/sdk.test.mjs (маршрут словарей, отказ для чужих имён), tests/pages-policy.test.mjs (права workflow), гейт docs (сборка без битых ссылок), браузерный сценарий консоли во всех языках.