Localize the website through MessageFormat 2 catalogs
The website is translated; the product’s agent surfaces are not. Every string
on the site’s pages is a Unicode MessageFormat 2 (MF2) message in a catalog,
site/src/i18n/messages/<locale>/<area>.json, or prose in a file,
site/src/i18n/prose/<locale>/<name>.md. Pages turn a message ID into text
only through format(locale, id, values) in site/src/i18n/format.ts, and
site/src/i18n/message.ts is the only module that imports the messageformat
library. Dates, numbers and lists are formatted through Intl before they
reach a message, so no message uses MF2’s Draft functions, such as
:datetime and :unit.
UI strings are grouped in one catalog per area per locale, such as common,
home, sign, sources and adoption. An English entry is a plain MF2
string; a translated entry is { "message": ..., "source": ... }, where
source is a short hash of the English message it translates. Longer
hand-written text, How it works and Repo Canon’s introduction on its source
page, is one Markdown file per locale, rendered by its page; a translated file
records the hash of the whole English file in its front matter. These files
are the site’s copy, so they stay under site/, not under docs/. Islands get
finished strings as props; the MF2 runtime reaches the browser only in an
island that formats a value only the browser knows, such as the homepage’s
search.
There is no runtime fallback. format() throws on an unknown locale or ID, a
malformed entry, a message that does not parse and a missing variable, so a
gap fails the static build instead of showing English on a translated page.
One check, run by the site’s tests, compares each locale with English: exactly
the same message IDs and prose files, every message parsing, each translation
using its English message’s variables, while plural and select variants may
differ because Spanish and Catalan have many, and every recorded hash
matching the current English text. Each part passes or fails; a stale
translation fails like a missing one. pnpm --dir site i18n:source updates
hashes only for the entries a person names, never all at once, so a current
hash means someone updated that translation. The check imports nothing from
the site, so a Repo Canon i18n standard can lift it out later. A pseudo-locale,
generated from English with every text wrapped in ⟦ ⟧ and padded by about
30%, shows text that skipped the catalogs or overflows its box; only the
development server serves it.
site/src/i18n/locales.ts lists the locales, English first, and the routes
follow from it. English stays at the root, and every other locale is served
under /<tag>/ with the same English paths, such as /es/how-it-works/, so
the English site keeps every URL. The pages are [...locale] routes rather
than Astro’s i18n configuration: Starlight generates that configuration when
it has locales, and configuring both is an error, so the docs can still be
localized later. <html lang> is the page’s locale. GitHub Pages cannot
choose a language on the server, so a language switcher saves the visitor’s
choice, and a script on English pages sends a first visit on to the browser’s
first supported language. A saved choice wins over the browser; the browser’s
language never redirects away from /es/ or /ca/, and /docs/ never
redirects.
Product names, Repo Standards and Repo Canon, are never translated, and
sources’ descriptions from their own standards.yaml stay in their own
language. The CLI and its --json output, the agent prompts, llms.txt,
sources.json, the Markdown versions of pages and /docs/ stay English: they
are what agents read, or documentation rewritten in most product changes.
ICU MessageFormat 1, through intl-messageformat, was the alternative most
translation tools support today. MF2 is the stable Unicode standard, with the
same plural and select model and a path to Intl.MessageFormat; because
every call goes through format(), moving to MF1 would change the catalogs
and one module. Lingui, used in polity, ties call sites to its macros, a
build transform and PO catalogs, and its silent English fallback there hides
which messages were never translated. Prefixing English as /en/ would have
changed every existing URL.