Перевести документацию
01Перевод — отдельный пакет той же формы, что оригинал: те же страницы, те же имена разделов, те же примеры по ссылке, на другом языке. Эта страница создаёт такой пакет и объясняет, что делает его официальным.
Создай пакет org.acme/notes-flow-docs-ru в текущем проекте VibeVM, как пакет в дереве под vibevm/vibepacks/, как русский перевод org.acme/notes-flow-docs. Отзеркаль его дерево страниц файл в файл, сохрани каждый якорь и блок и замени каждый пример ссылкой на пример источника. Напиши манифест с [translates] и тем же предметом в [[documents]]. Запусти vibe doc check --translations.навык vibevm, установленный у вашего агента; исходный пакет документации в том же проекте
у перевода те же файлы и якоря, что у источника, [i18n] canonical = "ru", [translates] указывает на источник, и vibe doc check --translations не находит структурных отличий
grep -q "canonical = \"ru\"" vibevm/vibepacks/org.acme/notes-flow-docs-ru/v0.1.0/vibe.tomlvibe doc check --translations --path vibevm/vibepacks/org.acme/notes-flow-docs-ru/v0.1.0
Что происходит
03Агент копирует дерево страниц источника и переводит прозу каждого блока на месте, не добавляя и не удаляя блоков. Каждый example он заменяет на example ref="<id>", указывающий на пример источника. Он задаёт язык пакета, называет источник в [translates] и тот же предмет в [[documents]]. vibe doc check --translations затем сравнивает два дерева: те же пути, те же якоря, то же число и виды блоков; отличие — ошибка. Сайт, видя ребро translates от пакета в группе источника с именем <source>-ru, показывает перевод как официальный и предлагает его в переключателе языков.
04 A translation MUST mirror the source tree file for file: the same paths, the same anchors, the same fact identifiers, the same number and kinds of blocks. Adding or removing an anchor is forbidden. A set difference of anchors is a check error, not a warning.
Манифест
05Язык пакета — существующее поле [i18n] canonical, тег BCP-47 в нижнем регистре; отдельного поля языка нет. [translates] называет источник и диапазон версий; [[documents]] повторяет предмет источника, и vibe проверяет, что они согласуются.
06 The language of adocpackage is the existing[i18n].canonicalof PROP-003 §2.7 (defaulten); there is no separatelangfield.[i18n].availableof adocpackage is empty by construction: a translation is another package.
07 Thedocumentsof a translation MUST equal thedocumentsof its source;vibe checkverifies it.
08Имя <source>-<lang> в группе источника — то, что делает перевод официальным по умолчанию. Перевод из другой группы находится и показывается как перевод сообщества, с его издателем.
09 An official translation is one that declaredtranslateson the source and is published by the same group as the source under the name<docname>-<lang>; everything else is a community translation (§6).
10Имя перевода по умолчанию — имя документации с тегом языка в нижнем регистре, vibevm-docs-ru или vibevm-docs-pt-br, в той же группе.
11 The official-by-default translation of a documentation<group>/<docname>into a language<lang>is named<group>/<docname>-<lang>, where<lang>is a BCP-47 tag in lower case (ru,pt-br,zh-hans).
Правила перевода
12Перевод следует источнику блок за блоком, а не предложение за предложением: внутри блока переводчик пишет то, что написал бы редактор-носитель, заменяет шутку той, что работает на его языке, или убирает её и следует глоссарию перевода. Он никогда не сочиняет примеры: вывод примера проверяется один раз, на источнике, а перевод на него указывает. Он никогда не добавляет якорь, потому что ссылка в источник должна попадать на тот же блок на каждом языке; благодаря этому же читатель переключает язык, не теряя места.
13 A translation MUST NOT author examples: it usesexample ref="<id>"pointing at the source's example, so that command output is checked once, on the source (PROP-045##ROW-DOCVOCAB-EXAMPLE-REF).
14 Switching the language keeps the place. The language selector leads to the same page in the other language with the same fragment (#pNNor#id), which the block-for-block mirror of §5 makes possible. When the page does not exist in the chosen language, the site serves the source language under the chosen language's address as a statically materialised fallback (<html lang>of the source,rel=canonicalto the source page,noindex), shows a bilingual notice «this page is only in … so far» once per session, and rewrites internal links so navigation stays in the chosen language. The chosen language is remembered in the cookielangfor 365 days — the same name the landing uses, so the domain root and/doc/remember one choice.
15Правила, процитированные из спецификации, остаются на языке спецификации и помечены как таковые; перевод нормативного текста не входит в перевод документации.
16
Normative specifications stay in the specification's language: a rule shows the rule's text in the source language with a mark; translating normative text is outside this wave.
Когда источник двигается
17Перевод не записывает ни ревизию, ни хеш источника. Когда источник меняется, структурная проверка проходит, пока совпадает форма, а отстал ли смысл перевода, решает человек: на это отвечают при периодической сверке, и ответ показывается на странице как дата, когда её читали в последний раз. Страницу, у которой перевода ещё нет, сайт показывает на языке источника по адресу перевода, с пометкой, и никогда как отсутствующую.
18 A translation stores neither a revision nor a hash of the source page (§14: a «since then» comparison needs a history the product does not keep).vibe doc check --translationsverifies structure only — paths, anchors, count and kinds of blocks; whether the adaptation lags in meaning is a human's question at full reconciliation, and the site shows the adaptation's last read-aloud date fromreviews.toml.
Особые случаи и правила
19Файлы-спутники внутри исходного пакета, README.ru.md рядом с README.md, — так переводы носят спецификации; документация ими не пользуется, потому что у перевода руководства свой автор и свой ритм.
20 Amendment 2026-09-11 (PROP-057 §5). Packages of kinddocreuse this section's BCP-47 tags, the[i18n].canonicalfield as the package's own language, and the preference chain of §2.7.2–§2.7.3 (I18nDecl,project_preference_chain, the lockfile'slanguage_chain) — but they do not take part in the sidecar layout of §2.7.1: a translation of documentation is a separate package of kinddoc, named<documentation-name>-<lang>in the same group for the official-by-default case, declaring the source through the[translates]table and mirroring its tree file for file.[i18n].availableof adocpackage is therefore empty by construction, and the coverage check of §2.7 that expects sidecars does not apply to it. The reason is ownership: a translation has its own author, its own rhythm and its own officiality, and the unit of ownership in this project is the package.
21Перевод наследует изображения источника, если не объявляет собственных.
22 A translation inherits the images of its source unless it declares its own.