SDK runtime compatibility and platform differences

Messagevisor keeps evaluation behavior portable across SDKs while allowing each platform to use its native internationalization runtime.

Capability matrix#

Portable means shared evaluation semantics, not identical method names or byte identical formatted strings. Framework adapters use the JavaScript runtime rather than defining another datafile contract.

Capability	Shared contract	Platform boundary
Conditions and segments	Strict types, portable operators and regular expressions	Do not pass expressions outside the portable subset
Translation selection	Ordered overrides, fallback resolution, locale datafiles	Application context and resolver callbacks come from the host app
Datafile updates	Merge by key, format presets by type and name, whole locale replacement	No independent target ownership inside a merged locale
ICU messages	Values, plurals, selects, named number, date and time presets	Requires the ICU module; supported formatter options depend on the native runtime
Direct formatting	Locale presets and explicit runtime options	Intl, ICU and CLDR versions can change presentation
Rich output	Plain string translations work across SDKs	React and Vue node callbacks are JavaScript integration features
Formatter parts	Parts helper APIs support structured rendering	Token boundaries are not portable; some SDKs return simplified or literal parts
Diagnostics, events and modules	Observable failures, state changes and module lifecycle	Use each SDK's callback, concurrency and cleanup APIs
Conformance	Execute shared semantic cases and project assertions	Record reviewed native output differences explicitly; do not skip formatter cases

Runtime implementations#

SDK	Formatting runtime	Important limits and reference
JavaScript	Host `Intl`, with the ICU module for messages	Optional Intl families and range APIs depend on the host; React and Vue support rich nodes
Java	ICU4J	Native ICU data determines exact output; see formatting and conformance
Swift	Apple Foundation	String translation results, simplified parts, and native compact notation limits; see platform behaviour

An API being present does not mean every JavaScript formatter option is available on every platform. Check the relevant SDK reference and test the options your application uses.

Portable evaluation contract#

Conditions and segments intentionally avoid runtime-specific coercion:

values are type-strict;
condition and segment arrays are implicit AND groups;
not negates the implicit AND of its direct children;
regular expressions support the portable flags i, m, s, and u only, with u mapped to each platform's native Unicode-aware mode, while lookaround, advanced groups, backreferences, and possessive quantifiers are rejected;
before and after require timezone-qualified ISO date-time values, such as 2026-07-17T12:00:00Z;
invalid expressions, invalid dates, missing segments, and type mismatches do not match.

These rules apply in both authoring lint and SDK runtime evaluation. They make a definition behave consistently in JavaScript, Java, Swift, and future SDKs.

Localization runtime differences#

SDKs use the platform's native Intl, ICU, or CLDR implementation. Exact punctuation, spacing, date order, and localized names can vary legitimately between runtime versions. Cross-platform tests should express such known differences explicitly instead of rewriting output inside an SDK.

Some JavaScript formatter families depend on optional browser APIs such as Intl.ListFormat and Intl.DisplayNames. When an API is unavailable, the SDK reports an unsupported_formatter diagnostic. Invalid options report invalid_format, while requesting an unknown named preset reports missing_format.

JavaScript baseline#

The Messagevisor CLI and Node.js tooling allow Node.js 20.19 or newer. Repository development and CI use the exact release pinned in .nvmrc, currently Node.js 24.16.0. Locale-sensitive output is verified only on that pinned release because Node.js releases can ship different ICU and CLDR data. Applications on an allowed lower Node.js release should review their own locale-sensitive output when upgrading or comparing environments.

The JavaScript SDK is published for browser and server use without relying on newly introduced collection or iterator helpers in its runtime path. Core evaluation relies on ordinary ES5-compatible output and standard primitives. Direct formatter helpers rely on the corresponding Intl family:

Intl.NumberFormat, Intl.DateTimeFormat, and Intl.PluralRules are baseline formatter requirements;
Intl.RelativeTimeFormat, Intl.ListFormat, and Intl.DisplayNames are needed only when using those helpers;
formatRange and formatRangeToParts availability depends on the host Intl.DateTimeFormat implementation.

Applications targeting older browsers should provide the standard JavaScript and Intl polyfills required by their own support matrix. The repository smoke test executes the packed SDK in the latest available Chrome rather than promising output parity with historical browser ICU releases. Unsupported optional formatter families emit unsupported_formatter so an application can monitor gaps without changing condition or translation semantics.

The Java SDK requires Java 17 or newer and uses ICU4J. Exact localized formatter strings may differ from JavaScript when the installed ICU/CLDR data differs; the portable conformance contract deliberately excludes those presentation-level differences.

The Swift SDK supports the Apple platforms declared in its package and uses Foundation's native locale data. Reviewed differences remain explicit in project test expectations rather than being hardcoded into the SDK.

Datafile compatibility#

SDKs consume datafiles generated by the Messagevisor CLI. The datafile's schemaVersion describes its shape, while messagevisorVersion records the installed CLI version that generated it. Keep the CLI and SDK on compatible release lines when adopting breaking schema changes.

For SDK work across languages, the JavaScript SDK is the behavioural source of truth and the repository's versioned portable conformance fixture defines the shared cases that every SDK should execute. The fixture covers condition and segment semantics, the accepted regular expression subset, fallback order, override behaviour, datafile merge and replacement, diagnostic envelopes, module cleanup, state event ordering, and child owned parent datafile event snapshots. Revision 4 adds hardening cases including format preservation and invalid datafile handling. It does not guarantee byte identical localised output across host ICU or CLDR versions. Check each SDK's conformance results against the fixture revision being adopted rather than assuming a release has already passed new cases.