A translation is a separate package in the same shape as the original: same pages, same section names, same examples by reference, in another language. This page creates one and explains what makes it official.
The agent copies the source's page tree and translates the prose of each block in place, without adding or removing a block. It replaces every `example` with `example ref="<id>"` pointing at the source's example. It sets the package language, names the source in `[translates]` and the same [subject](../glossary/index.xml#subject) in `[[documents]]`. `vibe doc check --translations` then compares the two trees: the same paths, the same [anchors](../glossary/index.xml#anchor), the same number and kinds of blocks; a difference is an error. The site, seeing a `translates` edge from a package in the source's group named `<source>-ru`, shows the translation as official and offers it in the language selector.
The language of the package is the existing `[i18n] canonical` field, a BCP-47 tag in lower case; there is no separate language field. `[translates]` names the source and a version range; `[[documents]]` repeats the source's subject, and vibe checks that the two agree.
The name `<source>-<lang>` in the source's group is what makes the translation official by default. A translation from another group is found and shown as a community translation, with its publisher.
The default name of a translation is the documentation's name with the language tag in lower case, `vibevm-docs-ru` or `vibevm-docs-pt-br`, in the same group.
A translation follows the source block for block, not sentence for sentence: within a block the translator writes what a native editor would write, replaces a joke with one that works in the language or drops it, and follows the glossary of the translation. It never authors examples: an example's output is checked once, on the source, and a translation points at it. It never adds an anchor, because a link into the source must land on the same block in every language, which is also what lets the reader switch languages without losing the place.
Rules quoted from a [specification](../glossary/index.xml#specification) stay in the specification's language, marked as such; translating normative text is not part of a documentation translation.
A translation records no revision or hash of the source. When the source changes, the structural check still passes as long as the shape did, and whether the translation's meaning lags is a human's question, answered at the periodic reconciliation and shown on the page as the date it was last read. The site shows a page that has no translation yet in the source language under the translation's address, with a note, never as missing.
Sidecar files inside the source package, `README.ru.md` beside `README.md`, are how specifications carry translations; documentation does not use them, because a manual's translation has its own author and its own rhythm.
A translation inherits the source's images unless it declares its own.