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
$ npx messagevisor list --datafiles

After a build, use npx messagevisor list --datafiles to review generated paths and both raw and gzip-compressed artifact sizes.

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:

  • target-filtered translations
  • resolved locale metadata, including locale direction
  • resolved target-aware formats, optionally trimmed to only formats used by emitted messages
  • 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. Both fields accept one string pattern or an array of patterns. Omitted includeMessages includes all messages; explicit includeMessages: [] includes none.

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
  4. target-level format filtering through either includeFormats / excludeFormats or includeOnlyUsedFormats

Format layers merge by type and style name. If a locale or target declares a style that already exists, that full style object replaces the earlier style. Sibling styles that are not declared continue to flow through.

Format filters run after the resolved format object is assembled. This lets a target ship only the format types and style names it needs. includeOnlyUsedFormats: true is mutually exclusive with includeFormats and excludeFormats; it keeps only named ICU number, date, and time presets referenced by the messages and overrides emitted into that datafile.

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