Note

One document per language, not localized fields

In a bilingual site, the invisible decision is where translations live in the CMS. Localized fields hide what is missing; one document per language turns absence into a verifiable fact.

Every bilingual site carries two decisions that look like details until the content exists. The visible one: what to do with the browser's language. The invisible one: where translations live in the CMS — duplicated fields inside each document, or one document per language, linked to its counterpart by reference.

Most examples pick localized fields, for good reasons: fewer documents, a single publish button, no reference to maintain. The problem shows up later, in the editor: an empty field and a not-yet-translated field are the same pixel. Nobody can look at the content list and say what is missing.

Absence as a fact

With one document per language, the link between the two versions is an explicit reference — the translation pair. A missing pair stops being a suspicion and becomes a fact a query returns: this note has no Portuguese version. The editor shows it; code can enforce it.

That is what turns "no section exists in only one language" from intention into rule: a gate that holds publication while the pair is missing or empty. A rule you cannot verify is an intention.

The cost, said out loud

Two documents cost discipline: each language has its own slug, its own publish action, and a reference to maintain. And the language switch has to resolve the other side's slug by following the pair, instead of repeating the path. It is a real cost — and exactly the cost that makes coverage verifiable instead of promised.

Architecture is rarely about the happy path. It is about which bad state you prefer: a blank nobody sees, or an absence that blocks publishing until someone looks.

This site chose the second. This note — which you can read in two languages — is the first document to live under that rule.