Internationalization§

The plan puts i18n inside M7 rather than after it, with a reason worth restating: "retrofitting i18n is the most expensive deferred decision at this size." M7 shipped without it, so this is that debt paid — and, as with docs/accessibility.md, the section that makes this page worth reading is the one listing what is not done.

The line§

Display is localised. The command grammar is not.

A command invocation is serialisable by design — that is what makes macros, the audit log, replay and the eventual CRDT path work. A locale-dependent parser would make a recorded WALL 0,0 3,5 draw one wall in Berlin and a different one in Boston. See docs/adr/0011-decimal-comma-and-the-coordinate-grammar.md; it is the substantive decision on this page.

If you write decimal commas: every single-number field accepts them (2,5, <30,5, a height of 2,7). For coordinates, use ; between components — 3,5;7,2 is (3.5, 7.2). Without it, 3,5 is the point (3, 5), which is what the grammar has always meant.

Using it§

import { DE, createTranslator } from "@massing/i18n";
import { createRibbon } from "@massing/ribbon";

const locale = navigator.language.split("-")[0] ?? "en";
const i18n = createTranslator({ locale, catalogue: locale === "de" ? DE : {} });

createRibbon(container, { handlers, translate: i18n });

translate is optional. Omitting it gives byte-identical English output, which is what keeps M9 from depending on massing adopting i18n first.

Three properties worth knowing, because each is a decision rather than an accident:

• A missing string falls back, to the locale's English, then to the item's own literal. A ribbon renders three sources of label — the inherited tool table, plugin manifests, and contextual tabs from an IFC class — and only the first is catalogued. Rendering tool.some-plugin-verb.label at a user would be worse than English.
• Translator.missing() reports fallbacks as data, so a test can assert how far a translation reaches. Noticing untranslated text by looking at the screen does not scale past one language.
• plural() asks Intl.PluralRules, so Polish gets its four categories. PluralKey is derived from the .other keys, so a typo in a plural call is a compile error.

Adding a message§

1. Add the key and English text to packages/i18n/src/en.ts. MessageKey is keyof typeof EN, so every call site knows about it immediately.
2. Use it. t() for a sentence, plural() for anything counted.
3. npm run gate:messages.

For a plural, add .one and .other at minimum — .other is required, because it is the fallback every other locale relies on.

Adding a locale§

Copy the shape of packages/i18n/src/de.ts. It is typed Catalogue — Partial<Record<MessageKey, string>> — so a partial translation compiles and a stale key does not.

Translate the availability.* keys first. Availability.reason is a required field precisely so that a dimmed control always explains itself, and a refusal that falls back to English in a localised UI undermines the one feature it belongs to.

The gate§

npm run gate:messages checks the three things neither the compiler nor a unit test can:

1. Plural completeness per locale. CLDR categories are a runtime fact, so MessageKey cannot know Polish needs few and many. A partially-pluralised message renders the wrong grammar while looking finished. A locale that has not started a message is a translation gap, not a plural bug, and is not gated.
2. The tool catalogue tracking the tool table. A tool added upstream arrives with an English label and no key, and silently stops being translatable. Checked in both directions, so a stale key fails too.
3. Orphan keys — defined and never looked up. Real translator effort for no user-visible result.

Translation coverage is printed, never gated. Gating it would mean either blocking a release on a language's last string, or committing machine output to turn the number green — and the second is worse than the gap, because it reads as reviewed and nobody looks again.

That last sentence is why the printed line carries two facts, not one:

de: 99/99 (100%) translated, not native-reviewed

When German was 32%, the percentage was the "somebody still needs to look at this" signal. Completing the catalogue did not answer the concern behind that signal — it removed the signal — so the review status is now printed alongside it and a locale joins REVIEWED in scripts/check-messages.mjs in the same commit as a reviewer's corrections. A claim of review that is traceable to a diff is worth something; a percentage is not.

All three checks were sabotage-tested: dropping a German plural form, adding an unused key, and removing a tool key each failed the gate with the right message. The third failed twice — once in tsc (the German catalogue's now stale key) and once in the gate (the missing English key), which is the two-directional check working.

What is not done§