Documentation Snapshot and Localization

Version boundary

The documentation selector uses only the App release channel and App version. The selected App commit is the source of truth for every generated section.

Site API and Bundle versions remain visible in the generated metadata, but they do not have independent selectors. Changing the App version switches every section together, which prevents a document from describing an API or Built-in Provider that the selected App does not contain.

The dedicated Site API repository can continue publishing installable package artifacts. The App documentation nevertheless uses its checked-in packages/site-api snapshot because that is the exact contract compiled by the selected App commit.

Guide source and translations

English Markdown in docs/Developer is canonical. Korean and Japanese translations mirror the same relative path below docs/Developer/i18n.

Missing translations fall back to canonical English and are visibly marked as a fallback. Human and AI-assisted translations follow the same rules:

• preserve code identifiers, API names, signatures, and literal values;
• preserve versions, channels, paths, commands, links, diagrams, and code;
• preserve heading order and implementation claims;
• update the translation in the App source tree rather than generated website content.

If Site API or an included Bundle gains authored guides, it may keep them beside its source under the corresponding package. The App exporter collects those guides into the same snapshot and the same release workflow.

Generated reference

Reference pages are regenerated from source comments for every App snapshot. Generated Markdown is disposable and is not edited or translated directly.

• Symbol names, signatures, types, source paths, and literals remain unchanged.
• Shared generated words such as Interface, Properties, Parameters, and Returns are translated by the documentation site’s locale catalog.
• Longer TSDoc prose is translated through Sidecar catalogs separated into App, Site API, and Bundle sections.
• Sidecar entries use stable Symbol Keys and a hash of the canonical prose so a changed English explanation cannot silently reuse an outdated translation.
• App and first-party Built-in Bundle references include private and protected declarations. Site API reference exposes its public consumer contract.

A stable Symbol Key uses the package id, normalized module path, symbol kind, qualified symbol name, and member name. TypeDoc reflection ids and line numbers are not stable translation keys.

Export and publication

The App workflow produces one content-only archive containing a manifest, App guides, all generated references, translation Sidecars, Site API schemas, and SHA-256 hashes. It must not contain dependencies, build caches, credentials, machine-local paths, or website components.

Stable snapshots come from immutable App tags. Staging and Nightly snapshots record an exact commit SHA. The website validates and imports the complete archive below one App version, then rebuilds navigation and search.

The current local docs:import command already follows this boundary: it reads one App checkout and creates App design, App source, Site API, and Built-in Sites sections together.