Consumer i18n setup
Use ContractSpec i18n without losing ownership of translation contracts
Author translations as ContractSpec specs, resolve them through the framework-independent runtime, and project to adapters only when a host app needs them. This keeps web, server, mobile, CLI, and tests aligned on one source of truth.
Install the reusable packages
bun add @lssm-tech/lib.contracts-spec @lssm-tech/lib.translation-runtimeUse @lssm-tech/lib.contracts-spec/translations for catalogs and the createI18nFactory runtime. Use @lssm-tech/lib.translation-runtime for ICU formatting, shard loading, diagnostics, and optional adapters.
1. Translation contracts
Author TranslationSpec catalogs in or near the package that owns the copy. Keep meta.key stable, locale as BCP 47, placeholders documented, and owners explicit.
packages/platform/delivery/contracts-spec-compat/src/translations@lssm-tech/lib.contracts-spec/translations
2. Runtime resolution
Use one createI18nFactory per stable spec key to resolve the request locale within its supported set, apply catalog fallbacks, interpolate {placeholder} values, and build locale-scoped SSR hydration payloads.
packages/foundation/contracts-spec/src/translations/i18n-factory.ts@lssm-tech/lib.contracts-spec/translations
3. Optional adapters
Project TranslationSpec catalogs to i18next only when a host app already uses i18next. Keep ContractSpec specs and hydration payloads canonical.
packages/platform/ui/translation-runtime/src/adapters/i18next.ts@lssm-tech/lib.translation-runtime/i18next
Define the contract first
The spec layer owns keys, locales, versions, owners, placeholders, fallback intent, and translator context. Do not make framework JSON files or i18next resources the canonical source.
import { defineTranslation } from "@lssm-tech/lib.contracts-spec/translations";
const meta = {
key: "checkout.messages",
version: "1.0.0",
domain: "checkout",
owners: ["growth"],
};
// The root catalog declares no fallback; locale variants fall back to it.
export const checkoutEn = defineTranslation({
meta,
locale: "en",
messages: {
"checkout.pay": {
value: "Pay {amount}",
description: "Primary checkout submit label.",
placeholders: [{ name: "amount", type: "currency" }],
},
},
});
export const checkoutFr = defineTranslation({
meta,
locale: "fr",
fallback: "en",
messages: { "checkout.pay": { value: "Payer {amount}" } },
});Resolve at runtime
Create one factory per stable spec key with its catalogs and supported locales. Server hosts create a locale-scoped instance per request; mobile hosts pass the device or user locale explicitly.
import { createI18nFactory } from "@lssm-tech/lib.contracts-spec/translations";
import { checkoutEn, checkoutFr } from "./translations/checkout";
// One factory per stable spec key. supportedLocales defaults to en, fr, es;
// "fr-FR" resolves to the "fr" catalog.
const checkoutI18n = createI18nFactory({
specKey: "checkout.messages",
catalogs: [checkoutEn, checkoutFr],
});
// t() interpolates {placeholder} values, so format the amount first.
const amount = new Intl.NumberFormat(requestLocale, {
style: "currency",
currency: "EUR",
}).format(42);
const label = checkoutI18n.create(requestLocale).t("checkout.pay", { amount });Package-level helper pattern
For package-local copy, use createI18nFactory to expose a small typed helper while still registering real TranslationSpec catalogs.
import { createI18nFactory } from "@lssm-tech/lib.contracts-spec/translations";
import { packageEn, packageFr } from "./catalogs";
export const packageI18n = createI18nFactory({
specKey: "my-package.messages",
catalogs: [packageEn, packageFr],
});
export const t = packageI18n.create("fr-FR").t;Production checklist
Define TranslationSpec catalogs before wiring UI strings into components.
Validate catalogs in tests so missing placeholders, invalid locales, and duplicate keys fail early.
When workspace, team, user, or request locale can differ, order them with resolveTranslationPreferenceContext, pick one with negotiateLocale, and create one locale-scoped instance per request with factory.create(locale).
Ship the factory hydration payload to SSR or streaming clients and rehydrate it with createI18nFactoryFromHydrationPayload; do not renegotiate locale during first client render.
Format ICU plural, select, number, and date messages with createIntlMessageFormatter; factory t() only interpolates {placeholder} values.
Let React Native hosts detect locale and load required Intl polyfills before formatting ICU messages.
Use diagnostics as release evidence: missing keys, fallback usage, invalid snapshots, and adapter warnings should be visible in CI or observability.