# 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