Workflow
Building datafiles
The build command turns authoring definitions into runtime JSON datafiles that applications and SDKs actually consume.
Run build#
$ npx messagevisor build$ npx messagevisor build --target=web --locale=en-US$ npx messagevisor build --set=production$ npx messagevisor build --showSizeWhat gets built#
For each target and locale combination, Messagevisor writes one datafile:
datafiles/└── messagevisor-<target>-<locale>.jsonThe exact file name includes the target and locale because build output is intentionally target-specific.
Advanced target layouts can nest target definitions in subdirectories. A target at targets/a/b/c.yml has key a.b.c and builds to:
datafiles/a/b/messagevisor-c-<locale>.jsonThe datafile content still records the full target key, a.b.c.
What a built datafile contains#
A built datafile contains:
- target-filtered translations
- resolved locale metadata, including locale direction
- resolved target-aware formats
- only the segments needed by included overrides
- target metadata needed by the runtime
- revisions and serialization shaped by target-level datafile options
In other words, build is not just serialization. It is the point where Messagevisor converts authoring definitions into a compact runtime artifact.
Resolution and precedence#
Several kinds of resolution happen during build:
Message inclusion#
Targets decide which messages are present through includeMessages and excludeMessages.
Translation inheritance#
Locales can fall back through inheritTranslationsFrom.
Format resolution#
Formats are resolved in this order:
- inherited locale formats
- locale's own formats
- target-level locale format overrides
Per-call runtime overrides such as assertion-level formats are not baked into the datafile. Those happen later at evaluation time using SDKs.
Context-aware simplification#
If a target defines partially known context upfront, build can simplify the runtime artifact by keeping only the branches that remain relevant for that target.
Target datafile options#
Targets can control datafile serialization:
pretty: truewrites that target's datafiles with indentationstringify: falsekeeps generated conditions and segment groups structuredrevisionFromHash: trueuses a content hash for that target's datafile revision
These options live in target files because they affect the runtime artifact for that specific target.
Single-target and single-locale builds#
Building one target+locale pair is often the fastest debugging flow:
$ npx messagevisor build --target=web --locale=en-USThis is especially useful when:
- a message behaves differently across targets
- a format override only exists for one locale
- you want to inspect output size or shape without generating everything
Sets-aware builds#
For sets-based projects:
$ npx messagevisor build --set=productionUse this when:
- building an environment-specific artifact
- validating a promoted set before deployment
State files#
Build can interact with Messagevisor state files depending on your project settings and options.
If you are debugging incremental behavior or revisions, also read State files.
Edge cases and behavior notes#
Build output is target-aware, not universal#
If two targets have different included messages or format overrides, their datafiles are intentionally different even for the same locale.
Direction survives build#
Locale direction is preserved into the datafile so SDKs and tools like the catalog can surface it.
Build is the source of truth for target tests and SDK runtime#
Target assertions and many runtime debugging flows operate on the same built shape. If something looks odd at runtime, build output is usually the right artifact to inspect.

