Документация для пользователей: сайт wiki/

Сайт https://proanima.github.io/Arkvory/ собирается из wiki/ (VitePress): начало работы, установка, работа с Arkvory, клиенты и протоколы, эксплуатация, HTTP API и справочник API на всех языках консоли, плюс копия этих инженерных документов на русском. Решение: ADR 0068; языки: LOCALIZATION.

npm run build                # тексты консоли и контракт API нужны генератору
npm run wiki -- dev          # живой просмотр: http://localhost:5173/
npm run wiki -- build        # wiki/.vitepress/dist, как публикует Pages
npm run wiki -- ids          # явные id всем ## и ### английских страниц
npm run gate -- docs         # сборка как в CI

Где что лежит

Путь	Что
wiki/<section>/<page>.md	Английская страница — источник для всех языков
wiki/<code>/<section>/<page>.md	Та же страница на ru, es, fr, de, pt, zh, ja, ko, hi, ar
wiki/.vitepress/structure.ts	Разделы и порядок страниц; страницы справочника API
wiki/.vitepress/text/<code>.json	Что говорит сайт: разделы, кнопки, поиск, слова справочника
wiki/i18n/api/<code>.json	Тексты операций, ошибок и полей справочника API
wiki/i18n/terms/<code>.json	Глоссарий переводчиков
scripts/wiki.mjs, scripts/wiki/*.mjs	Генерация справочника, ошибок и раздела разработчиков, сборка
.github/workflows/pages.yml	Публикация из main

Не в git (пишет генератор перед сборкой): wiki/**/api/reference/, wiki/**/api/errors.md, wiki/internal/.

Для кого и как писать

Читатели — инженеры CI/CD, администраторы, разработчики интеграций, игровые студии. Страница помогает сделать дело:

• Сначала задача, потом подробности. Второе лицо, настоящее время, короткие предложения. Без рекламы и «просто».
• Каждое число — из кода: значения по умолчанию, лимиты, порты, пути. Есть лимит — скажите, что происходит при его достижении.
• Только то, что есть. Планы (ROADMAP, PROJECT_PLAN, TWO_NODE_PLAN) на сайт не попадают.
• Без путей исходников. Пользователь видит экраны, поля, команды, файлы, адреса, переменные окружения.
• Инженерный документ может устареть; при расхождении прав код, а документ исправляется в том же изменении.

Подписи консоли

Не пишите название кнопки словами — пишите ключ словаря консоли:

Нажмите [[ui:backupRun]], затем откройте [[ui:backupPoints]].

Сборка подставит текст на языке страницы. Метка — только текст без {…}; в заголовках меток нет. Переименовали или удалили ключ — сборка и tests/wiki.test.mjs упадут.

Структура страницы

• Front matter: title: (коротко, как в боковой панели) и, желательно, description: (одно предложение: для поисковиков и превью ссылок; тест его не требует).
• Один заголовок #. Разделы ##, пункты ###.
• У каждого ## и ### — явный id на английском: ## Restore a point {#restore}. Переводы сохраняют id, поэтому ссылка ../operate/backups#restore работает на любом языке. npm run wiki -- ids добавит недостающие (slug заголовка, как у VitePress).
• Ссылки между страницами относительные, без .md. Операция справочника — якорь по operationId: ../api/reference/uploads#createUpload.
• Процедуры — нумерованные списки, параметры — таблицы, у блоков кода указан язык.
• {{ в тексте не пишите: это шаблон Vue. В коде — можно.

Справочник API

Страницы api/reference/* и api/errors пишет scripts/wiki.mjs generate из openapi.json, политик операций (operation-policy.js) и кодов ошибок. У операции — заголовок и описание из wiki/i18n/api/<code>.json, правило доступа и повторов, параметры (включая параметры пути), поля тела запроса и ответа с ограничениями схемы, пример curl.

Текст операции хранит исходник, с которого написан (en): английский — текст контракта, перевод — английский текст для читателя. Изменился исходник — страница показывает его, а тест требует обновить текст. Новая операция без текста тоже роняет тест.

Языки, у которых переведено не всё

Полностью переведены en, ru, es, de, zh, hi, ko, fr и pt (COMPLETE в wiki/.vitepress/structure.ts): для них нехватка страницы — ошибка теста. Остальные языки могут показывать английскую страницу там, где своей ещё нет: это файл-заглушка (<!-- arkvory-untranslated -->, предупреждение на языке читателя и <!--@include--> английской страницы). Заглушки лежат в git, чтобы у каждого языка были все страницы; их пишет npm run wiki -- stubs, тест требует, чтобы они были актуальны. Перевести страницу — перезаписать её заглушку (сначала удалите файл или прочитайте его); npm run wiki -- check <код> перечисляет, что ещё осталось английским. Язык добавляется в COMPLETE, когда переведено всё.

Перевод

Изменённая английская страница меняется во всех языках в том же коммите. tests/wiki.test.mjs сравнивает каждую страницу с английской: те же id заголовков, те же метки [[ui:]], столько же блоков кода, нет лишних страниц. Код, команды, пути, имена переменных и полей не переводятся. Термины — по глоссарию языка.