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 @contractspec/lib.contracts-spec @contractspec/lib.translation-runtime

Add

i18next

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

TranslationSpec[]

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.

import { createTranslationRuntime } from '@contractspec/lib.translation-runtime';
import { checkoutMessages } from './translations/checkout.messages';

const runtime = createTranslationRuntime({
  catalogs: [checkoutMessages],
  locale: 'fr-FR',
  fallbackLocales: ['fr', 'en-US'],
  onDiagnostic: (diagnostic) => reportTranslationIssue(diagnostic),
});

const label = runtime.t('checkout.pay', {
  amount: 4200,
  currency: 'EUR',
});

Project to i18next when needed

Import from

@contractspec/lib.translation-runtime/i18next

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.

import { createInstance } from 'i18next';
import {
  createI18nextInitOptions,
  exportContractSpecToI18next,
} from '@contractspec/lib.translation-runtime/i18next';

const exported = exportContractSpecToI18next([checkoutMessages], {
  locale: 'en-US',
  assumeIcuFormatter: true,
});
const { options, diagnostics } = createI18nextInitOptions(exported, {
  lng: 'en-US',
});

const i18next = createInstance();
await i18next.init(options);
reportAdapterDiagnostics(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.

// Server: negotiate once, preload catalogs, and serialize the runtime snapshot.
const runtime = createTranslationRuntime({
  catalogs,
  locale: negotiatedLocale,
  fallbackLocales,
});
const snapshot = runtime.createSnapshot();

// Client: hydrate from the same snapshot so locale, resources, and fallback state match.
const hydratedRuntime = createTranslationRuntime({ snapshot });

Production checklist

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