# Перевести документацию {#root} @status:doc/work @audience:author [p01] Перевод — отдельный пакет той же формы, что оригинал: те же страницы, те же имена разделов, те же примеры по ссылке, на другом языке. Эта страница создаёт такой пакет и объясняет, что делает его официальным. [p02] ```prompt Создай пакет org.acme/notes-flow-docs-ru в текущем проекте VibeVM, как пакет в дереве под vibevm/vibepacks/, как русский перевод org.acme/notes-flow-docs. Отзеркаль его дерево страниц файл в файл, сохрани каждый якорь и блок и замени каждый пример ссылкой на пример источника. Напиши манифест с [translates] и тем же предметом в [[documents]]. Запусти vibe doc check --translations. ``` - needs: навык vibevm, установленный у вашего агента; исходный пакет документации в том же проекте outcome: у перевода те же файлы и якоря, что у источника, `[i18n] canonical = "ru"`, `[translates]` указывает на источник, и `vibe doc check --translations` не находит структурных отличий - assert: `grep -q "canonical = \"ru\"" vibevm/vibepacks/org.acme/notes-flow-docs-ru/v0.1.0/vibe.toml` - assert: `vibe doc check --translations --path vibevm/vibepacks/org.acme/notes-flow-docs-ru/v0.1.0` ## Что происходит {#what-happens} [p03] Агент копирует дерево страниц источника и переводит прозу каждого блока на месте, не добавляя и не удаляя блоков. Каждый `example` он заменяет на `example ref=""`, указывающий на пример источника. Он задаёт язык пакета, называет источник в `[translates]` и тот же [предмет](../glossary/index.xml#subject) в `[[documents]]`. `vibe doc check --translations` затем сравнивает два дерева: те же пути, те же [якоря](../glossary/index.xml#anchor), то же число и виды блоков; отличие — ошибка. Сайт, видя ребро `translates` от пакета в группе источника с именем `-ru`, показывает перевод как официальный и предлагает его в переключателе языков. > [p04] 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. > > ## Манифест {#the-manifest} [p05] Язык пакета — существующее поле `[i18n] canonical`, тег BCP-47 в нижнем регистре; отдельного поля языка нет. `[translates]` называет источник и диапазон версий; `[[documents]]` повторяет предмет источника, и vibe проверяет, что они согласуются. > [p06] The language of a `doc` package is the existing `[i18n].canonical` of PROP-003 §2.7 (default `en`); there is no separate `lang` field. `[i18n].available` of a `doc` package is empty by construction: a translation is another package. > > > [p07] The `documents` of a translation MUST equal the `documents` of its source; `vibe check` verifies it. > > [p08] Имя `-` в группе источника — то, что делает перевод официальным по умолчанию. Перевод из другой группы находится и показывается как перевод сообщества, с его издателем. > [p09] An **official** translation is one that declared `translates` on the source and is published by the **same group** as the source under the name `-`; everything else is a community translation (§6). > > [p10] Имя перевода по умолчанию — имя документации с тегом языка в нижнем регистре, `vibevm-docs-ru` или `vibevm-docs-pt-br`, в той же группе. > [p11] The official-by-default translation of a documentation `/` into a language `` is named `/-`, where `` is a BCP-47 tag in lower case (`ru`, `pt-br`, `zh-hans`). > > ## Правила перевода {#the-rules} [p12] Перевод следует источнику блок за блоком, а не предложение за предложением: внутри блока переводчик пишет то, что написал бы редактор-носитель, заменяет шутку той, что работает на его языке, или убирает её и следует глоссарию перевода. Он никогда не сочиняет примеры: вывод примера проверяется один раз, на источнике, а перевод на него указывает. Он никогда не добавляет якорь, потому что ссылка в источник должна попадать на тот же блок на каждом языке; благодаря этому же читатель переключает язык, не теряя места. > [p13] A translation MUST NOT author examples: it uses `example ref=""` pointing at the source's example, so that command output is checked once, on the source (PROP-045 `##ROW-DOCVOCAB-EXAMPLE-REF`). > > > [p14] **Switching the language keeps the place.** The language selector leads to the same page in the other language **with the same fragment** (`#pNN` or `#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 (`` of the source, `rel=canonical` to 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 cookie `lang` for 365 days — the same name the landing uses, so the domain root and `/doc/` remember one choice. > > [p15] Правила, процитированные из [спецификации](../glossary/index.xml#specification), остаются на языке спецификации и помечены как таковые; перевод нормативного текста не входит в перевод документации. > [p16] 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. > > ## Когда источник двигается {#staleness} [p17] Перевод не записывает ни ревизию, ни хеш источника. Когда источник меняется, структурная проверка проходит, пока совпадает форма, а отстал ли смысл перевода, решает человек: на это отвечают при периодической сверке, и ответ показывается на странице как дата, когда её читали в последний раз. Страницу, у которой перевода ещё нет, сайт показывает на языке источника по адресу перевода, с пометкой, и никогда как отсутствующую. > [p18] 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 --translations` verifies 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 from `reviews.toml`. > > ## Особые случаи и правила {#edge-cases} [p19] Файлы-спутники внутри исходного пакета, `README.ru.md` рядом с `README.md`, — так переводы носят спецификации; документация ими не пользуется, потому что у перевода руководства свой автор и свой ритм. > [p20] **Amendment 2026-09-11 ([PROP-057 §5](../../common/PROP-057-documentation-packages-and-site.xml)).** Packages of kind `doc` reuse this section's BCP-47 tags, the `[i18n].canonical` field as the package's own language, and the preference chain of §2.7.2–§2.7.3 (`I18nDecl`, `project_preference_chain`, the lockfile's `language_chain`) — but they do **not** take part in the sidecar layout of §2.7.1: a translation of documentation is a **separate package** of kind `doc`, named `-` 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].available` of a `doc` package 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. > > [p21] Перевод наследует изображения источника, если не объявляет собственных. > [p22] A translation inherits the images of its source unless it declares its own. > >