Skip to content

A second language

The ebitex team
Part 15 of 20 of the series “Building Northwind Coffee”: a coffee cup, steaming, beside the part’s number.

Northwind sells into France now.

Here is everything that had to happen: add a locale in Settings, fill in the locales side of the values being translated, and pass one more value to the component that resolves the page.

No Contract changed. No Template changed. No renderer changed.

That sentence is the argument this whole series exists to make, and it is worth being precise about why it is true, because it is not because the product is clever. It is because of a decision made eleven parts ago.

The decision was in part 4

Every localizable field has been stored as an envelope since it was created:

{ default: "Ethiopia Guji", locales: {} }

One default, plus per-locale overrides. With one language that locales object is always empty, the envelope is always ceremony, and it has done nothing visible for eleven parts.

This is where it pays. The shape was already right, so adding French is filling in a map that was always there — not migrating anything, not changing a type, not touching a renderer that reads a value it will now read differently.

Compare that to what most teams actually live through, which is discovering they need a second language when a hundred pages already exist. Then every localizable-shaped field is a schema change, every one of those is a migration, every renderer that reads it needs revisiting, and it all has to happen at once because a half-migrated model is not a model.

Deciding the localization axis costs nothing on day one and costs a migration on day four hundred. It is the highest-leverage habit in content modelling, and it only works if you do it before you need it.

And note what the decision actually was. Not "we will support French" — nobody knew that in part 4. It was "this value could legitimately differ by language, and that one could not", which is a question you can answer about a field the moment you create it.

What we translated, and what we deliberately did not

Northwind translates its chrome, its front page, its catalogue page, the roast and process taxonomies, and one coffee.

Everything else stays in English, on purpose. Switch to French and walk around, and you see the fallback working: translated pages in French, untranslated ones in English, no gaps, no errors, no half-empty templates.

That is not a shortcut for the sample’s sake. A partly-translated site is a normal state, not a broken one — it is the state every multilingual site is in permanently, because translation lags publishing and always will. A model that only works when everything is translated is a model that never works.

Enumerable and localizable, composing: three French values over the three English defaults they translate. No Contract changed to get this.

Two things worth getting right

A taxonomy is content too. A category’s label is Localizable like any other display text, so translating the roast levels is translating content — not configuration, not a code change. Worth remembering when planning translation work: the closed sets need doing as well, and they are easy to forget precisely because nobody wrote them as prose.

Enumerable wraps the other way round. tasting-notes is localizable and enumerable, so the whole list is one translated value:

{ default: ["blackcurrant", "cocoa"], locales: { fr: ["cassis", "cacao"] } }

Not a list of separately-translated strings. This is the shape from part 4, and here is where getting it backwards would hurt: French might want four notes where English has three, and a list of individually-translated items cannot express that at all. Localizable outside, enumerable within.

The switcher, and one trap in it

The language choice lives in ?lang=, so a link opens in the language the person sending it was reading. Small, and the alternative — a cookie, or a guess from the browser — means a URL shared between two colleagues shows them different pages.

One trap the sample hit and is worth inheriting: every cached loader has to be keyed by locale.

Paths are materialised per locale slot, so a site with translated slugs genuinely has different URLs per language. A memo that ignores locale will happily hand a French reader an English path, and it will do it inconsistently, depending on who loaded the page first. Northwind does not have translated slugs today, which is exactly why this would have gone unnoticed until it did.

Where this leaves us

A bilingual site, and a content model that is identical to the one at the end of part 14.

If you take one thing from this series, take the fact that those two sentences are both true. Next: the same trick again, on a different axis — the same page saying different things to different readers.