Treating localisation like code in a YAML monorepo (2023)

Background

Several teams owned different services but shared the same user‑facing copy. Keys drifted, variable names changed, and nobody was quite sure which version was the truth. The fix wasn’t a new tool; it was a few habits and some guardrails.

Stakeholders: frontend and backend engineers, a localisation PM, and translators/reviewers for fr‑FR, de‑DE, es‑419 and zh‑TW.

What I built

A monorepo folder layout per feature with a clear naming scheme, pre‑commit checks for missing variables and duplicate keys, and CI that refused unsafe changes; exports were assembled per feature so translators saw tidy packages.

A short note on key naming and placeholders so engineers could add copy without guessing.

How we ran it together

Engineers opened PRs for copy; CI checked the basics; PMs exported by feature; translators returned YAML that passed the same checks; merges were quick because nothing surprising happened at runtime.

Outcome

Fewer regressions, faster merges, and better context for translators who no longer had to read four files to understand one message.

If I were starting this today

I’d keep the same approach and add a tiny ‘orphan key’ report to find strings that never appear in the UI anymore.