diff --git a/docs/content-model.md b/docs/content-model.md index a372f4d..f9490a3 100644 --- a/docs/content-model.md +++ b/docs/content-model.md @@ -72,7 +72,7 @@ readable by templates (ADR-0002). Never add a required field. | `title` | string | Only required field | | `date` / `updated` | date | Publication; `updated` drives feeds and `Last-Modified`. An unquoted `2026-07-30` or an RFC 3339 timestamp; undated bundles sort after dated ones | | `type` | string | Post type; defaults from the top-level section | -| `slug` | string | Overrides the derived slug. The engine serves the new path only; the old one 404s unless it appears in `aliases` | +| `slug` | string | Overrides the derived slug for the bundle in **every** language (ADR-0035). The engine serves the new path only; the old one 404s unless it appears in `aliases`. Two variants declaring different slugs is ambiguous — logged, dropped, derived path kept | | `aliases` | []string | Paths the engine redirects permanently to this bundle's canonical URL (ADR-0008). A scalar or a list; surrounding slashes optional. An alias naming a real bundle, or claimed by two bundles, is ambiguous — logged and dropped, and the real bundle keeps its URL | | `draft` | bool | Excluded from queries and feeds | | `nocache` | bool | Never cache this bundle's render. Named so absence means cacheable, per ADR-0002 | @@ -146,8 +146,9 @@ bundle between sections changes the URL the engine emits, and the old path resol **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. +Bengali variant is therefore reached at the same key under a prefix — `/bn/posts/hello-world/`. A `slug` +override renames the bundle in every language at once (ADR-0035); nothing gives one variant an address of +its own. The parser does not read `slug` 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 diff --git a/docs/decisions.md b/docs/decisions.md index d5e190f..78db789 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -422,3 +422,21 @@ that grows with the theme; a site root cannot yet add or override a key, so a th must write them in its own block. Revisit if: a site root needs its own chrome strings. That is the settings cascade's problem (`ideas/deferred-decisions.md`), not a second table. + +## ADR-0035 — A slug belongs to the bundle, not to a variant +Date: 2026-07-30 · Status: accepted (confirms ADR-0009's "same path" clause against a per-language address) +Decision: `slug` renames the bundle in every language, so a variant is always reached at the bundle's one +path under its language prefix — `/posts/hello-world/` and `/bn/posts/hello-world/`, never a Bengali +spelling of the address. Where two variants declare different slugs the declaration is ambiguous: log both +and keep the derived path, the same way colliding keys and contested aliases are handled (ADR-0029). The +engine never derives a slug from a title in any language; a path changes only because an author wrote one. +Why: the alternative makes the path a function of (key, language) rather than of the key alone, which +costs a second lookup direction in the resolver and a permalink shape that differs per language — while +invariant 3 says identity is stable across translations and ADR-0009 already promised the same path under +a prefix. A Bengali-looking address is a real reader benefit, but not one worth a second identity rule +before anything is published. +Consequence: cheap — one path shape, one lookup direction, `/bn/` stays pure prefixing, and a translation +can be added or dropped without touching a URL. Expensive — a Bengali reader sees a Latin address, and +changing that later needs this decision reversed plus an alias for every path already published. +Revisit if: Bengali becomes the dominant language of the site — the trigger ADR-0009 already names. That +is a default-language change, not per-variant slugs.