Tirsvad
f5fb0238f3
English pages are generated and have no suffix; translations are named <Page>.da and <Page>.ms, written by hand in wiki/, reviewed and checked for staleness through a source hash. Add the ADR type to the registry.
100 lines
4.0 KiB
Markdown
100 lines
4.0 KiB
Markdown
# ADR-0001: Wiki structure, page names and languages
|
|
|
|
## Metadata
|
|
| Key | Value |
|
|
| --- | --- |
|
|
| ID | ADR-0001 |
|
|
| CrossReference | [MIL-005], [BC-001] |
|
|
|
|
## Version History
|
|
| Date | Status | Author | Reviewer | Change | Commit |
|
|
| --- | --- | --- | --- | --- | --- |
|
|
| 2026-10-10 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending |
|
|
|
|
Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
|
|
|
|
---
|
|
|
|
## Context
|
|
|
|
MIL-005 puts the documentation on the Gitea wiki in English, Danish and
|
|
Bahasa Malaysia. Before translations are written, three things must be fixed,
|
|
because the generator, the publishing workflow and the translators all depend
|
|
on them: which pages exist, how a translated page is named, and which copy is
|
|
authoritative.
|
|
|
|
Forces:
|
|
|
|
- The Gitea wiki is a flat list of pages; a hyphen in a page name is shown as
|
|
a space, and a `/` in a name needs encoding in links and in the REST API.
|
|
- The English pages are generated from `README.md` and `guides/`
|
|
(`tools/build_wiki.py`) and published only by the workflow from `main`
|
|
(task 8). A translation must therefore live in this repository too, so it is
|
|
reviewed like any other change.
|
|
- A translation silently goes stale when the English page changes. Rule 8 of
|
|
`AGENTS.md` requires each translated page to name the English source it
|
|
follows, so staleness must be detectable without the network.
|
|
- The Business Case sets no deadline and the Product Owner language is
|
|
English, so English stays the single authoritative text.
|
|
|
|
Options for the page name of a translation:
|
|
|
|
1. **Suffix with a dot:** `Home` (English), `Home.da`, `Home.ms`. One flat
|
|
namespace, English has no suffix, and the files are `wiki/Home.da.md`.
|
|
2. **Folder per language:** `da/Home`, `ms/Home`. Mirrors the repository
|
|
layout but needs encoded links and an encoded API path.
|
|
3. **Suffix with a hyphen:** `Home-da`. Simple, but Gitea reads the hyphen as
|
|
a space, so the title shows as "Home da".
|
|
|
|
Options for the source of truth of a translation:
|
|
|
|
1. **Generated by machine on every change.** No stale pages, but no review by
|
|
a native reader and wording that changes between runs.
|
|
2. **Written once, kept in `wiki/`, reviewed, and checked for staleness.**
|
|
Reviewed wording is stable; staleness is flagged by a check.
|
|
|
|
## Decision
|
|
|
|
The wiki has five pages (Home, Onboarding, Credentials, Troubleshooting,
|
|
Capabilities). The English page has no suffix and is generated; a translation
|
|
is the page name plus `.da` or `.ms` (`Home.da`, `Credentials.ms`), written by
|
|
hand in `wiki/<Page>.<lang>.md`, reviewed by a native reader, and published by
|
|
the same workflow. English is authoritative.
|
|
|
|
Each translation starts with the comment
|
|
`<!-- translation of <Page>.md, source sha256 <first 12 hex of the English file> -->`,
|
|
so a check can report a translation whose English source has changed. Code
|
|
blocks, commands, file names and the workflow's error messages stay in
|
|
English. Terms are kept consistent through a term list (`docs/wiki-terms.md`,
|
|
created in MIL-005 task 4).
|
|
|
|
## Consequences
|
|
|
|
**Positive:**
|
|
|
|
- One flat set of 15 pages that the existing generator and publisher handle
|
|
without a new code path.
|
|
- A stale translation is detectable offline from the recorded hash.
|
|
- Translations are reviewed and stable, and reach the wiki only by merge.
|
|
|
|
**Negative:**
|
|
|
|
- Dots in page names are not yet verified on this wiki; MIL-005 task 7 (#38)
|
|
must publish and open them. The fallback is `Home_da`, which changes only
|
|
the file names and links.
|
|
- A translation is not updated by itself; a person must re-translate when the
|
|
check reports it stale, so the translations can lag the English pages.
|
|
- The check, and the language switcher line at the top of each page, are
|
|
still to be built in task 4.
|
|
|
|
## Affected Artifacts
|
|
|
|
- [MIL-005] — closes task 1 (issue #32) and defines the naming that tasks 4
|
|
and 5 follow.
|
|
- [BC-001] — the wiki in three languages is in its scope list.
|
|
|
|
---
|
|
|
|
[MIL-005]: ../milestones/mil-005-wiki-and-translations.md
|
|
[BC-001]: ../business-case.md
|