Evaluation
Evaluation is the part of Messagevisor where authored definitions turn into actual runtime results. This includes translation lookup, raw-message formatting, segment matching, format resolution, and module execution.
Main evaluation modes#
There are three practical evaluation surfaces:
- message-key evaluation
- raw-message evaluation
- segment evaluation
Message-key evaluation#
This uses a real message key from your project.
Examples:
- SDK
translate(messageKey, values, options) - CLI
evaluate --message=... - message tests
- target tests using
message
This path depends on:
- the built datafile
- target inclusion/exclusion
- locale inheritance
- target context simplification
- runtime context
- modules
Raw-message evaluation#
This evaluates a literal string through the runtime modules for a locale.
Examples:
- SDK
formatMessage(rawMessage, values, options) - CLI
evaluate --rawMessage=... - locale tests using
rawMessage - target tests using
rawMessage - locale examples with
rawMessage, which can be inspected withnpx messagevisor examples --onlyLocalesand in the generated Catalog
Use this when you want to inspect runtime formatting behavior without creating or referencing a real message key.
Segment evaluation#
This answers one question: does this segment match the supplied context?
Examples:
- CLI
evaluate --segment=... - segment tests
This is the cleanest path when you are debugging conditional logic before layering message behavior on top.
Evaluation inputs#
Depending on the surface, evaluation can use:
- locale
- target
- context
- values
- currency
- timeZone
- formats
- module options
Precedence and layering#
Evaluation behavior usually follows this shape:
- authored definitions
- built target+locale datafile
- SDK instance state
- per-call evaluation overrides
- module execution
This is why it is so useful to keep examples, tests, and SDK usage aligned: they all help you inspect the same layered behavior.
Runtime context vs target context#
This distinction matters a lot:
- target context shapes the built artifact ahead of runtime
- runtime context is supplied when evaluation happens
If something seems to disappear before runtime, target context is often the reason.
Missing translations#
When a known message key is absent from a built target datafile, Messagevisor follows the normal SDK missing-translation behavior instead of inventing a special target-only evaluation model.
That keeps:
- CLI behavior
- SDK behavior
- target test behavior
aligned with one another.

