Runtime and adapters

Translation runtime and i18next adapter

Use ContractSpec as the canonical translation contract layer, then resolve and format messages through a framework-independent runtime. i18next is supported as an optional downstream adapter, not as the source of truth.

Install the runtime

bun add @lssm-tech/lib.contracts-spec @lssm-tech/lib.translation-runtime

Add

only when an app imports the adapter subpath. Core server, React, React Native, CLI, and test code can use the runtime without loading i18next.

Use the ContractSpec runtime

The runtime consumes canonical

catalogs, supports BCP 47 tags such as en-US, ar-EG, and zh-Hans, and delegates ICU parsing/formatting to a mature formatter engine instead of a custom parser.

1import { createI18nFactory } from '@lssm-tech/lib.contracts-spec/translations';
2import { checkoutEn, checkoutFr } from './translations/checkout.messages';
3
4// One factory per stable spec key; resolution stays on the canonical
5// createI18nFactory stack (the deprecated createTranslationRuntime engine
6// was removed — see the migration note below).
7const checkoutI18n = createI18nFactory({
8  specKey: 'checkout.messages',
9  catalogs: [checkoutEn, checkoutFr],
10});
11
12const instance = checkoutI18n.create('fr-FR');
13const label = instance.t('checkout.pay', { amount: 4200, currency: 'EUR' });

Project to i18next when needed

Import from

to export resources by locale, namespace, and message key. The namespace defaults to the stable bundle key, dotted message keys stay flat with keySeparator false, and metadata remains in a sidecar manifest.

1import { createInstance } from 'i18next';
2import {
3  createI18nextInitOptions,
4  exportContractSpecToI18next,
5} from '@lssm-tech/lib.translation-runtime/i18next';
6
7const exported = exportContractSpecToI18next([checkoutMessages], {
8  locale: 'en-US',
9  assumeIcuFormatter: true,
10});
11const { options, diagnostics } = createI18nextInitOptions(exported, {
12  lng: 'en-US',
13});
14
15const i18next = createInstance();
16await i18next.init(options);
17reportAdapterDiagnostics(diagnostics);

SSR, streaming, and hydration

Negotiate locale on the server, preload catalogs needed for streamed content, and hydrate the client from the same serialized state. Never let client-only language detection choose a different locale after the server has rendered.

1// Server: build a locale-scoped hydration payload from the factory and ship it.
2import {
3  createI18nFactory,
4  createI18nFactoryHydrationPayload,
5  serializeI18nFactoryHydrationPayload,
6} from '@lssm-tech/lib.contracts-spec/translations';
7
8const factory = createI18nFactory({ specKey: 'checkout.messages', catalogs });
9const payload = createI18nFactoryHydrationPayload(
10  factory.snapshot(negotiatedLocale),
11);
12const serialized = serializeI18nFactoryHydrationPayload(payload); // inline into HTML
13
14// Client: rehydrate the SAME locale-scoped catalogs before first paint — no
15// locale renegotiation, no key/fallback flash.
16import { createI18nFactoryFromHydrationPayload } from '@lssm-tech/lib.contracts-spec/translations';
17
18const hydrated = createI18nFactoryFromHydrationPayload(serialized).create(
19  negotiatedLocale,
20);

Production checklist

• Use createI18nFactory (or createManagedCompanyOsI18n) as the runtime — the deprecated createTranslationRuntime engine and its ./runtime, ./registry, and ./runtime-helpers subpaths were removed.

• For SSR, ship a locale-scoped factory hydration payload and rehydrate it before first paint; do not renegotiate locale on the client.

• Keep TranslationSpec as the source of truth; do not flatten metadata into i18next JSON as the canonical model.

• Keep stable bundle identity in TranslationSpec.meta.key and keep BCP 47 language tags in TranslationSpec.locale.

• Use ICU messages for plural, select, selectordinal, number, date, currency, list, and relative-time formatting.

• Create one runtime per SSR request when tenant, project, or user overrides are involved.

• Serialize the same runtime snapshot or exported adapter resources used by the server for hydration.

• Configure an ICU-capable i18next formatter plugin when rendering ContractSpec ICU messages through i18next.

• Treat adapter diagnostics as release blockers in production pipelines instead of silently rendering raw keys.