i18n-messages
How to add or change user-facing copy in this repo (EN + PL catalogue). Use whenever adding, editing or removing any string a user will see, or when the i18n parity test goes red.
SKILL.md.claude/skills/i18n-messages/SKILL.md
GitHubThe product ships in two locales, en (the source and the schema) and pl. The full contract is
docs/SPEC.md §9, owned by docs/I18N.md - this is the working procedure.
Adding or changing a string
- Never hardcode user-facing copy in a component. Add a dotted key to
src/lib/i18n/messages/en.tsin the group its surface belongs to, and render it throught(). The groups are a reading aid, not a namespace: moving a key between them touches nothing else. - The same key lands in
pl.tsin the same change. English is the schema, so the compiler catches a missing key; it cannot catch the four things that make copy look finished and read wrong, andsrc/lib/i18n/__tests__/parity.test.tsdoes: a renamed placeholder, a plural branch Polish needs and English does not, an empty value, and an English sentence sitting in the Polish catalogue. Runpnpm test- red output names the exact key. - Author a real translation. A word that is genuinely identical in both languages goes in the
PROPER_NOUNSlist in the parity test, where adding it is a visible decision rather than a quiet weakening of the untranslated check. - Removing a key removes it from both files.
Traps that pass a naive check
- Polish has four CLDR plural categories (
one,few,many,other) where English has two. A message with a count goes through the plural machinery; anif (n === 1)in a component is a defect (SPEC §9). - Placeholders are part of the key's contract:
{count}must survive translation under the same name.as constinen.tsis what makes the literal type carry them. - Numbers, dates and money inside messages are formatted by the message formatter with the active locale, never concatenated in pre-formatted.
Intl.DisplayNamesandIntl.Locale.prototype.textInfoare banned insrc/lib/i18n, andsource-rules.test.tsenforces it: their output differs between workerd and WebKit, which is a hydration mismatch rather than a tolerance. Both facts live in the frozen table inlocales.ts.- Stored rows carry keys and parameters, never sentences - a notification row or an email envelope written as prose is unreadable to someone who later switches language.
Verification
pnpm test (parity + source rules) is the law here.