Localization review contract¶
English remains canonical. The nine authored pages in Russian (ru) and
Simplified Chinese (zh-CN) have editorial and technical review by AIna-Dev,
requested by the owner and recorded as AI review under ADR 0015.
Generated API and other untranslated units display current English with explicit
fallback notices. Reviewed guides open directly without a visible review notice.
Actual master Pages publication remains a separate Task #27 acceptance step.
python -m tools.locale_documentation validate
python -m tools.build_locale_sites
The wrapper builds strict installed-wheel English and locale sites with the same
import guard and pinned toolchain. It verifies provenance attributes, links,
anchors and route reachability. Disposable build-evidence.json distinguishes
authoredTranslationReviewComplete from humanReviewComplete; AI reviews never
count as human reviews, and untranslated pages remain missing.
Unit identity and state¶
Stable IDs and canonical sourceHash retain the fuzzy-doc-unit-v1 payload.
Each existing translation records its path and basedOnSourceHash. Updating
canonical metadata alone cannot make an outdated translation current.
| Metadata state | Rendered text | Review meaning |
|---|---|---|
missing |
Current English fallback. | No translation or review is claimed. |
draft |
Localized draft. | Required review is incomplete. |
review |
Localized text under review. | Required review is incomplete. |
stale |
Current English fallback. | Source or reviewed translation has changed. |
approved |
Reviewed localized text. | Authorized roles reviewed the current source. |
Approval requires the roles selected by reviewClass, a named reviewer, a UTC
reviewedAt and current reviewedSourceHash. reviewerType defaults to human.
AI approval requires explicit project opt-in and reviewerType = "ai" on every
AI record. It additionally requires reviewedTranslationHash: SHA-256 of the
UTF-8 translation with normalized newlines. Missing roles, unauthorized reviewer
types, changed sources and changed reviewed translations fail validation.
An AI's actual review may be recorded; a human identity must never be invented.
Updating a translation¶
- Inspect the English change and refresh its canonical hash.
- Mark affected translations
stale, preserving previous review provenance. - Reconcile meaning, terminology, ownership/consent instructions, commands, code, paths and explicit heading anchors against the current source.
- Set the current
basedOnSourceHashand obtain actual authorized reviews. - Record the actual reviewer type, identity, role, UTC timestamp and matching source hash; AI records also bind the reviewed translation text hash.
- Approve only the reviewed text, run affected checks and let CI build the site.
Paths must remain inside the intended locale; unregistered overlays fail. Glossary concept IDs and notes remain English while preferred terms are localized. Source links to absent translations resolve to the locale's English fallback.
Release-1.2 evidence¶
The review snapshot lists all 18 reviewed translations and current hashes. Review does not imply deployment. Task #27 also requires a successful Pages deployment from the exact promoted master commit. Feature #8 and release-1.2 can close only after all their acceptance criteria are met. The stable release gate still requires a closed milestone with zero open items.