I18n

I18n

Flat key catalog, one JSON file per locale. Loud misses. Intl.* for anything that is not a string.

Zero hardcoded user-facing strings — every string an end user can read goes through t(). A literal in JSX or in an error message is a lint failure and fails x verify.

Catalogs

One file per locale, flat dot-keys after load, nested for authoring.

packages/i18n/src/catalogs/en.json  # framework strings — ships inside @ultimat3/i18n
packages/i18n/catalogs/en.json      # the app's own catalogs, same shape
packages/i18n/catalogs/es.json

{
  "nav": { "home": "Home", "billing": "Billing" },
  "post": {
    "published": "Published {title}",
    "count_one": "{count} post",
    "count_other": "{count} posts"
  }
}

Rule	Detail
Authoring	nested objects; flattenCatalog produces nav.home, post.published
Key segments	/^[A-Za-z0-9_-]+$/ — anything else is X_CATALOG_INVALID
Leaves	strings only. An array or a number leaf is X_CATALOG_INVALID
Collisions	a nested branch and a dotted key that flatten to the same path throw
Merge order	framework catalog first, app catalog last — apps override framework keys. Under en only: the framework catalog is English, so defineCatalogs seats it under core's DEFAULT_LOCALE (en) and nowhere else. An app shipping only es renders ⟦errors.notFound.title⟧ for a framework key it has not translated, which is the golden rule working — it used to be served English with isMiss reading false, a fallback locale chain wearing registration as a disguise
en	the reference locale. Its key set is what every other locale is diffed against

t()

import { t } from '@ultimat3/i18n';

export function billingHeading(count: number): string {
  return t('post.count', { count });
}

Aspect	Behavior
Signature	t(key: string, vars?: TranslateVars): string — TranslateVars is Record<string, string | number | boolean> plus optional count
Locale	ambient, read from the ALS request context. t() never takes a locale argument
Miss	returns ⟦key⟧. Never throws, never falls back to another locale, never returns the key bare
Typed keys	keys are generated into a union from the en catalog; an unknown key is a type error
Introspection	t.has(key), t.raw(key), t.keys(); isMiss(rendered) for assertions in tests
No concatenation	t('a') + ' ' + name is banned — put the slot in the string: t('a', { name })

Word order differs per language, so a concatenated sentence is untranslatable by construction. One key = one complete sentence or label.

Interpolation

Form	Renders
{name}	String(vars.name)
{{ / }}	a literal { / }
{name} with no vars.name	⟦name⟧ — loud, same reason a missing key is loud

t() interpolates on every call, with vars or without: t('greeting') on Hello {name} is Hello ⟦name⟧, exactly as t('greeting', {}) is, and {{ is unescaped either way. The template itself — to hand a client island its plural forms, say — is t.raw(key), never t(key).

Pluralization

CLDR categories via Intl.PluralRules, never an English n === 1 branch.

Locale	Categories it needs
en, de, es	one, other
pl, ru, uk	one, few, many, other
ar	zero, one, two, few, many, other
ja, zh, ko	other only

Pass count; the translator picks the key. Candidates, most specific first: key_<category> → key_plural → key_other → key. For count === 1: key_one → key. _plural is the two-form authoring shortcut; the _<category> suffixes are what a 3+ form locale needs.

Loud misses

Surface	Behavior on a missing key
dev render	⟦post.published⟧ in the DOM — visible in the page and in review screenshots
x verify	check 8 (SEO + i18n) fails with X_CATALOG_MISSING_KEYS
CI	same failure, --json shaped
Tests	isMiss(t('k')) is the assertion — never assert on ''

Silently falling back to English is what makes a half-translated app ship. The framework does not do it.

Strings in an island

t()'s catalog does not cross into an island, and a translator is not a prop. An island's own copy arrives already translated, as text. When it needs keys — t(key, { count }) after the page rendered, or the design system's ui.* strings — the page sends a slice and the island builds a translator over it (As of 2026-10):

Side	Call
page (server)	catalogSubset(t, ['app.post.likes']) from @ultimat3/i18n; uiCatalog(t) from @ultimat3/ui for every ui.* key
island	subsetTranslator(props.strings) from @ultimat3/i18n/subset; <UiProvider t={subsetTranslator(props.ui)}>

The slice carries every plural variant of each key, and a key it lacks renders ⟦key⟧ in the island exactly as on the server.

Commands

Command	Does
x i18n add <locale>	create catalogs/<locale>.json seeded with every default-locale key, values copied verbatim
x i18n sync <locale>	add keys the locale is missing; a key it already has is never overwritten, translated or not; never deletes
x i18n check --json	extract keys from source, diff against every catalog, report missing / unused / dynamic

Every command supports --json. add copies the source values rather than writing blanks: an untranslated string that renders beats a missing key that renders ⟦key⟧, and x i18n check still lists the locale's keys so a translator has a diffable starting point.

check reports three separate things, and only one of them fails the command:

Reported	Meaning	Exit
missing	a key source calls that the locale does not define	non-zero, one X_CATALOG_MISSING_KEYS finding per locale
unused	a key the locale defines that no t() call names	0 — informational
dynamic	t(plans.${plan}.name), a key the static extractor cannot resolve	0 — informational, with file, line and column

Before any of the three, check resolves @ultimat3/i18n from the app root, from every workspace and from the CLI itself. Two real directories is X_PACKAGE_DUPLICATED, and every registration gap is then reported as the install's fault with the install's fix (pin one version, bun install) — not as a misplaced defineCatalogs(): each copy keeps its own registry, so the app registers into one and the check reads the other.

A dynamic call contributes its static head (plans.) as a runtime-key prefix, so a key only ever reached that way is never listed unused — otherwise the list reads as "safe to delete" over live keys. An expression with no static head (a ternary over literals, a bare variable) contributes nothing: a guessed prefix would suppress real gaps.

Locale routing

As of 22.3.0. The routed locales are routedLocales(): the ones defineCatalogs() declared, default first. An app that declared none routes its fallback alone — no prefix, no per-locale files.

Path (default es-co, also en)	Locale	Answer
/precios	es-co	the /precios route
/en/precios	en	the /precios route — the prefix is stripped before the route table is matched. An isr page keeps the prefix in its store key and is revalidated by that route's ttl and tags (Routes)
/es-co/precios	—	301 to /precios (308 for a non-GET); the default is never prefixed
/fr/precios	—	404: fr is not routed, so /fr/precios is an ordinary path
/en/nothing	en	404, its error page in English

Rule	Detail
Prefix	authoritative on every surface: it beats ?locale=, the cookie, the user and Accept-Language. Stripped in @ultimat3/http's context stage, never by middleware — middleware wraps matched routes only
site/	the URL alone (RouteMeta.localeSource: 'path'). Unprefixed is always defaultLocale — no Accept-Language negotiation, because a CDN serves / as one file — and Vary drops accept-language
app/ / api/	unprefixed keeps query → cookie → user → header, configurable via configureLocales({ order }). The user rung is the actor's saved locale, which your authenticate hook sets (userActor({ id, locale, tz })); @ultimat3/http re-resolves once auth has run. An explicit choice outranks the browser: ?locale= is how an email preview link pins a locale, the cookie is what the language switcher writes, and Accept-Language is only the fallback when nobody has chosen. An order without 'header' never reads it, and the response drops accept-language from Vary (As of 22.10) — a CDN no longer stores one copy per browser language of a page that cannot differ by it
Static export	x build --target static renders each site/ page once per routed locale, in that locale's context: index.html (lang="es-co"), en/index.html (lang="en"), en/precios/index.html. Every static host serves /en/precios from that layout with no rewrite
Cookie	x_locale, written only by an explicit language switcher
Unsupported tag	skipped, not thrown — a stale cookie must never 500 a page. assertSupportedLocale throws X_LOCALE_UNSUPPORTED where an unknown tag is a caller bug
Direction	currentDirection() returns 'rtl' for ar, he, fa, ur, … and is written to <html dir>

API	From	Answers
routedLocales()	@ultimat3/i18n	the locales a URL may name, default first
localizedPath(path, locale)	@ultimat3/i18n	/precios + en → /en/precios; the default → /precios; / + en → /en/; an existing prefix is re-spelled, never doubled
splitLocalePrefix(pathname) / unlocalizedPath(pathname)	@ultimat3/i18n	the prefix split off, or the bare path
localizePath(path, locale, locales, defaultLocale)	@ultimat3/core	the same arithmetic over an explicit list — for browser code, which must not import the i18n barrel
<LocaleSwitcher locales={routedLocales()} path={pathname} />	@ultimat3/ui	links to this page in each locale; hrefFor overrides, defaultLocale defaults to locales[0]

meta receives locale, localizedPath(locale) and alternates ({ locale, path } per routed locale). The head then carries, with no route code:

Tag	Value
<link rel="canonical">, og:url	absolute, against APP_URL / SITE_ORIGIN / site.origin (Configuration)
<link rel="alternate" hreflang>	one per routed locale in BCP 47 region form (es-co → es-CO), plus x-default → the default locale's page. A route's own alternates replace the set whole
og:locale / og:locale:alternate	es_CO form — language and region only, so zh-hant-tw is zh_TW; the document's locale, then every other one

sitemap.xml lists every page once per locale, each with the same xhtml:link cluster. A single-locale app emits none of the cluster.

Numbers, dates, money

Never hand-rolled, never string-formatted in a component.

Value	Route
Number / percent	Intl.NumberFormat with the request locale
Date / time	Intl.DateTimeFormat with the request locale and an explicit IANA timeZone → Timezones and dates
Currency	Money = { minor, currency } formatted at the edge → Money

A colour is a token, a string is a key, a date needs a zone, an amount is minor units. Same four rules everywhere.

Errors

Code	Cause	Fix
X_LOCALE_UNSUPPORTED	tag is not in the supported set	x i18n add <locale>
X_CATALOG_MISSING_KEYS	a locale file is missing keys used in source (names up to 12 of them)	x i18n sync <locale>
X_CATALOG_INVALID	non-string leaf, bad key segment, or duplicate flat key	x i18n check --json
X_PACKAGE_DUPLICATED	two installed copies of @ultimat3/i18n, each with its own registry	pin one version in the package.json the finding names, then bun install

Full list: Error codes.

Rules

• Zero hardcoded user-facing strings. Everything through t().
• One key per complete sentence. Never concatenate translated fragments.
• en is the reference key set; other locales are diffed against it, never the reverse.
• A miss is ⟦key⟧ and a red build, never English.
• x i18n sync adds; deletion of a key is a deliberate edit in a PR.
• Supported locales live in app.config.ts; SUPPORTED_LOCALES is the framework's own set, which apps narrow or extend.

Source: packages/i18n/src