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.

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"
  }
}

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

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

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

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).

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

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.

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

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):

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

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:

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.

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.

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

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

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

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

Full list: Error codes.

• 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