Translations
The required page set, the shared glossary, the prohibited translations, and how staleness is detected automatically.
Editorial Verified 2026-08-31
Navigation or explanatory writing with no source-sensitive claim of its own.
- Page ID
-
contribute/translations - Normative authority
- No normative source. Navigation only.
- Networks
- none
- Documentation version
- 2026.08
- Audience
- developer
- Owner
- bitcoin-universe-docs
English is the source
Section titled “English is the source”Every translation is made from the English page, and records the hash of the English body it was
made from in translationSourceHash.
When the English body changes, the recorded hash no longer matches, and the site shows a notice on the translated page automatically. Nobody has to remember to flag it.
The required set
Section titled “The required set”Eight locales are configured: English, Portuguese, Spanish, French, Japanese, Russian, Simplified Chinese, and Traditional Chinese.
A defined set of core pages must exist in every locale, listed in
site/src/data/site.json under requiredLocalizedPages. CI fails when one is missing.
Pages outside that set fall back to English, and Starlight shows a fallback notice, which is honest rather than pretending a translation exists.
What is never translated
Section titled “What is never translated”| Never translated | Why |
|---|---|
Operation names such as ft, dft, dmt, nft, mod, sl |
They are protocol literals |
| Schema property names | They are wire format |
| Route paths and query parameter names | They are the contract |
| Header names | They are the contract |
| Error codes | Clients branch on them |
| Hashes, transaction ids, Atomical ids | They are data |
| Code blocks, in full | Copying a translated identifier breaks the reader’s build |
| Product and repository names | They are names |
CI compares code blocks between a translation and its English source and fails on a mismatch.
Shared glossary
Section titled “Shared glossary”The glossary is the reference for every term. Translate a term the same way everywhere, and add the English term in brackets on first use in a page when the translation is not already established.
Prohibited mistranslations
Section titled “Prohibited mistranslations”| English | Do not translate as |
|---|---|
| burn | spend, lose, send |
| candidate | owner, holder |
| verified winner | applicant, requester |
| coloured output | any word implying it is ordinary bitcoin |
| ready | running, live, configured |
| deprecated | removed, deleted |
| proposed | planned, upcoming, coming soon |
| partial coverage | complete, full |
Each pair exists because the wrong word changes what a reader will do.
Adding a translation
Section titled “Adding a translation”- Copy the English page into the locale directory.
- Translate the prose. Leave every code block, identifier, and route untouched.
- Compute the English body hash and record it in
translationSourceHash. - Keep the same
pageId. - Run
npm run check.
Reviewing a translation
Section titled “Reviewing a translation”- Does every status word still mean exactly what it means in English?
- Are all code blocks byte-identical to the English source?
- Are the safety warnings as strong as the English ones? A softened warning is a defect.
- Does it read as though a person wrote it?
Do not merge an obviously machine-produced translation with inconsistent terminology.