Messagevisor

Workflow

Building datafiles

The build command turns authoring definitions into runtime JSON datafiles that applications and SDKs actually consume.

Run build

Command
$ npx messagevisor build
$ npx messagevisor build --target=web --locale=en-US
$ npx messagevisor build --set=production
$ npx messagevisor build --showSize

What gets built

For each target and locale combination, Messagevisor writes one datafile:

Directory structure
datafiles/
└── messagevisor-<target>-<locale>.json

The 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:

Nested target output
datafiles/a/b/messagevisor-c-<locale>.json

The datafile content still records the full target key, a.b.c.

What a built datafile contains

A built datafile contains:

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:

  1. inherited locale formats
  2. locale's own formats
  3. 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: true writes that target's datafiles with indentation
  • stringify: false keeps generated conditions and segment groups structured
  • revisionFromHash: true uses 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:

Command
$ npx messagevisor build --target=web --locale=en-US

This 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:

Command
$ npx messagevisor build --set=production

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

Previous
Linting
Next
State files