Skip to content
ContractSpec
Start here
AI index

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-runtime

Use @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.

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

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

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