write down that addresses are never localised

Localisation stops at the words around the content. No path segment is
translated: reserved segments stay `page` and `tags` in every language, page
numbers stay ASCII, and a variant is reached at the English key under its prefix.
The theme contract gains the matching rule — a URL, key or path segment must
never go through `t`, `num` or `day`.

This is already how the code behaves; every localisation function lives in
internal/render/chrome.go and the content package, which owns every URL, cannot
reach it. Recorded because nothing in the code says so out loud.

state.md now names the five frontmatter keys the parser actually lifts, so
content-model.md's table reads as the accepted format rather than a list of what
runs — `slug` in particular is unread today.
This commit is contained in:
2026-08-01 02:23:35 +06:00
parent c244855ebc
commit 273023b340
3 changed files with 14 additions and 3 deletions
+6
View File
@@ -143,6 +143,12 @@ published URL never changes meaning; renames add `aliases` and emit permanent re
bundle between sections changes the URL the engine emits, and the old path resolves only through
`aliases` — so a section list is effectively permanent once anything is published.
**No path segment is ever localised.** Reserved segments stay `page` and `tags` in every language, page
numbers stay ASCII digits, and a slug is whatever the key says: `/bn/lekha/page/2/`, never a translated
spelling of it. Localisation is for the words around the content, never the address of it (ADR-0034). A
Bengali variant is therefore reached at the English key under a prefix — `/bn/posts/hello-world/` — and
the only thing that can change a variant's path is a `slug` override, which the parser does not read yet.
A language prefix wins over a section of the same name, so a site with Bengali content may not also have
a section called `bn`. The engine treats a leading segment as a language only when some bundle is written
in it.
+4
View File
@@ -25,6 +25,10 @@ Chrome text, dates and digits render in English or Bengali; authored text is unt
smoothing (ADR-0034). This repo holds engine source only — the site root is external and passed with
`-site` (ADR-0011).
Frontmatter the parser lifts today: `title`, `date`, `tags`, `aliases`, `order`. Every other key in
`content-model.md`'s table — including `slug`, `draft` and `type` — lands in `Extra` unread, so that table
is the accepted format, not a list of what runs.
Dependencies: three, all allowlisted — `goldmark`, `golang.org/x/text`, `gopkg.in/yaml.v3`.
## Counters — the earn-it authority
+4 -3
View File
@@ -65,9 +65,10 @@ Phrase keys today: `newer`, `older`, `empty`, `page-of` (two arguments), `positi
unknown language falls back to the default locale and an unknown key returns itself, so a missing
translation can never blank a page or fail a render.
Two rules a theme must keep: put the machine-readable form in the attribute and the localised form in the
text — `<time datetime="{{.Date.Format "2006-01-02"}}">{{day .Lang .Date}}</time>` — and never localise
`.Title`, `.HTML` or anything else the author wrote.
Three rules a theme must keep: put the machine-readable form in the attribute and the localised form in the
text — `<time datetime="{{.Date.Format "2006-01-02"}}">{{day .Lang .Date}}</time>`; never localise
`.Title`, `.HTML` or anything else the author wrote; and never pass a URL, key or path segment through
these functions. An address is not chrome (`content-model.md`).
A site root cannot add or override a phrase yet. A theme needing its own words writes them in its own
block; site-supplied strings wait for the settings cascade (`ideas/deferred-decisions.md`).