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 @lssm-tech/lib.translation-runtime for runtime resolution, formatting, diagnostics, snapshots, and optional adapters.

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.

1import { defineTranslation } from "@lssm-tech/lib.contracts-spec/translations";
2
3export const checkoutEn = defineTranslation({
4  meta: {
5    key: "checkout.messages",
6    version: "1.0.0",
7    domain: "checkout",
8    owners: [{ team: "growth" }],
9  },
10  locale: "en-US",
11  fallback: "en-US",
12  messages: {
13    "checkout.pay": {
14      value: "Pay {amount, number, currency}",
15      description: "Primary checkout submit label.",
16      placeholders: [{ name: "amount", type: "currency" }],
17    },
18  },
19});

Resolve at runtime

Create a runtime with requested locales, fallback locales, specs, and diagnostics. Server hosts should create one runtime per request; mobile hosts should pass device/user locales explicitly.

1import { createTranslationRuntime } from "@lssm-tech/lib.translation-runtime";
2import { checkoutEn, checkoutFr } from "./translations/checkout";
3
4const runtime = createTranslationRuntime({
5  defaultLocale: "en-US",
6  requestedLocales: [requestLocale, "fr-FR", "en-US"],
7  fallbackLocales: ["en-US"],
8  specs: [checkoutEn, checkoutFr],
9  onDiagnostic: (diagnostic) => reportI18nDiagnostic(diagnostic),
10});
11
12const label = runtime.t("checkout.pay", { amount: 42 });

Package-level helper pattern

For package-local copy, use createI18nFactory to expose a small typed helper while still registering real TranslationSpec catalogs.

1import { createI18nFactory } from "@lssm-tech/lib.contracts-spec/translations";
2import { packageEn, packageFr } from "./catalogs";
3
4export const packageI18n = createI18nFactory({
5  specKey: "my-package.messages",
6  catalogs: [packageEn, packageFr],
7});
8
9export 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.
• Create a translation runtime per server request when tenant, workspace, team, user, or request locale can differ.
• Serialize and hydrate the same runtime snapshot for SSR or streaming hosts; do not renegotiate locale during first client render.
• 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.