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.

Parsed source entities use an ephemeral cache under .messagevisor/cache/. The cache is separate from revision state, is safe to remove, and should be ignored by source control. Set MESSAGEVISOR_NO_CACHE=1 when you need to force a completely fresh parse.

Common files

Directory structure
.messagevisor/
├── REVISION
└── cache/          # generated, never committed

With sets:

Directory structure
.messagevisor/
├── REVISION        # project build revision
├── cache/          # generated, never committed
└── 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?

This applies to revision state such as REVISION and promotions/. It never applies to .messagevisor/cache/, which is always ignored.

That depends on your workflow:

  • commit revision state 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 revision state files, never the cache

Add .messagevisor/cache to your project .gitignore so the cache stays out of source control:

.gitignore
.messagevisor/cache

Staging state files with Git

When a workflow commits revision state, pass the directory to git add:

Command
$ git add .messagevisor/

Git walks the directory itself and skips everything your .gitignore covers, so the cache is left alone and the command exits cleanly.

Avoid a shell glob such as git add .messagevisor/*. The shell expands that glob before Git runs, so Git receives .messagevisor/cache as an explicitly named path and refuses to add an ignored path:

Output
The following paths are ignored by one of your .gitignore files:
.messagevisor/cache
hint: Use -f if you really want to add them.

The command then exits non-zero, which fails the step in most CI shells. This is easy to miss because the glob only matches the cache once it exists, so the same workflow can succeed on a fresh clone and fail on the next run. Quoting the glob as git add '.messagevisor/*' also works, because Git expands it rather than the shell, though passing the directory reads more clearly.

Pair it with a guard so a run that produces no revision change does not fail on an empty commit:

Command
git add .messagevisor/
if git diff --cached --quiet; then
  echo "No state file changes to commit"
else
  git commit -m "[skip ci] Revision $(cat .messagevisor/REVISION)"
  git push
fi

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

After the selected sets finish building, the builder also writes the root .messagevisor/REVISION. This is the project build revision, not the production set revision. Building only --set=staging updates staging state and the root revision; unselected sets keep their previous revisions and artifacts. Each selected set advances from its own revision state, so set revisions need not match the root revision.

An explicit --revision supplies the revision for datafiles without updating stored revision files. --no-state-files also suppresses revision file writes. A target with revisionFromHash: true uses a content hash for each datafile regardless of the numeric project or set revision.

A deployment poller should inspect the revision of the actual published target and locale datafile, or a deployment manifest covering all required artifacts. A changed root revision does not prove that a particular set, target, or locale was rebuilt or published. Use the relevant set revision only when the deployment guarantees it represents all artifacts that consumer needs.

Previous
Building datafiles
Next
Testing