Messagevisor

Workflow

State files

Messagevisor stores generated state under .messagevisor/ in your project root. This directory is automatically created and updated by the build command.

Common files

Directory structure
.messagevisor/
└── REVISION

With sets:

Directory structure
.messagevisor/
└── sets/
    ├── dev/REVISION
    ├── staging/REVISION
    └── production/REVISION

What REVISION means

The revision file identifies the generated state that build, benchmark, catalog, and other workflows use when they need a stable datafile revision reference.

This helps the next generated datafile to increment its revision number by 1, and remember it for future reference.

By default, the revision comes from the current project state when datafiles are built. You can override it during build:

Command
$ npx messagevisor build --revision=2026-05-06T100000Z

Individual targets can instead derive their datafile revision from the generated content hash:

targets/web.yml
description: Web
revisionFromHash: true
includeMessages:
  - "*"

For targets without revisionFromHash, the state revision is copied into generated datafiles. For targets with revisionFromHash: true, the datafile gets a content-hash revision instead. In both cases, applications and deployment tooling can answer "which translation artifact am I using?" without inspecting Git directly.

Commit or ignore?

That depends on your workflow:

  • commit it when generated artifacts are part of deployment
  • ignore it when build artifacts are produced later in CI or deployment pipelines

For most open source starter projects, ignoring generated state is simpler. For teams that publish datafiles from the repository itself, committing state files can make diffs and rollback behavior easier to audit.

General rule of thumb

  • Locally: do not commit generated state files
  • In CI: commit generated state files

Sets behavior

When sets: true is enabled, each set gets its own revision under .messagevisor/sets/<set>/REVISION, and each built set writes datafiles under datafiles/<set>/.

This keeps a staging build from overwriting production state and makes promotion flows easier to inspect.

Previous
Building datafiles
Next
Testing