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

t()

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.

Interpolation

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.

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.

Ordinals and select

As of 2026-11-06. The suffix mechanism, two more families; no ICU syntax. One selection (selectMessageKey) serves t() and a mail's render alike.

A family the catalog lacks falls through to the key's own plural, as before. A select value is a key segment ([A-Za-z0-9-], ≤ 32) or it selects nothing. The typed key admits the stem (invite), as it does a plural stem. x i18n check counts every member used through its stem, a locale owes the stem and not each value (a language without gender defines invite_select_other alone), and a family with no _other is X_I18N_FAMILY_INCOMPLETE, red in the i18n step.

Loud misses

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

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

A form's validation messages key on the issue's rule, never on its English message — the framework's diagnostic text changes without a semver signal, the rule names do not (SCHEMA_RULES, @ultimat3/schema). Ship one key per rule in the slice and pass params: messageFor: (issue) => t(`form.${issue.rule}`, issue.params) — form.string.min → At least {min} characters. A third-party schema names no rule; fall back to a generic key for those.

Commands

Every command supports --json. add and sync copy the source value inside the marker, so the text sits where the translation goes and x i18n check counts the key as missing until a person replaces it. Source means every shape below; a key only a mail or a push names is a key.

Any other value of these is listed dynamic.

check reports five separate things, and three of them fail the command:

The last two are the parity rules, and both compare a locale with the reference locale en (As of 2026-10). A key en defines and another locale lacks is a missing key, not a parity finding, and that holds for a key only reached dynamically (t(plans.${plan}.name)). A key only another locale defines is unused there. A ⟦key⟧ placeholder is a missing key too — never a copy. Every finding names the locale, the catalog key and the file packages/i18n/catalogs/<locale>.json; x verify's i18n step and x i18n check report them from one implementation, so the command and the gate answer about an app with one voice.

Before any of the five, 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.

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.

Numbers, dates, money

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.

Errors

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