Messagevisor

Workflow

Catalog

The catalog is a browsable view of your Messagevisor project: definitions, their relationships, history, examples, and generated views. It is the easiest way to review a project with other humans in a visual way.

Preview

From an example project:

Catalog preview

Main commands

Command
$ npx messagevisor catalog         # run in dev mode
$ npx messagevisor catalog --port=3100
$ npx messagevisor catalog --with-translation-search
$ npx messagevisor catalog --with-duplicates
$ npx messagevisor catalog export  # static export to catalog/ directory
$ npx messagevisor catalog export --with-translation-search
$ npx messagevisor catalog export --with-duplicates
$ npx messagevisor catalog serve   # serve the static catalog locally
$ npx messagevisor catalog serve --port=3100
CommandDescription
catalogRun locally so it auto updates as you edit files
catalog exportGenerate static catalog files on disk (preferably in CI)
catalog serveServe the static catalog locally

Both catalog and catalog serve use port 3000 by default. Pass --port=<number> or -p <number> when that port is already in use.

By default, catalog export skips the translation-value search index. This keeps generation faster for large projects with many messages, locales, and overrides.

If you want message list search to support translation:"keyword" queries, opt in when generating the catalog:

Command
$ npx messagevisor catalog --with-translation-search
$ npx messagevisor catalog export --with-translation-search

catalog serve only serves an already generated catalog. If the catalog was exported with translation search enabled, the message list shows the translation:"keyword" search hint and can search translation values. Otherwise, that hint is hidden and message search stays focused on keys and metadata.

Duplicate reports

By default, catalog export skips duplicate translation reports. This avoids running duplicate detection for every locale when you only need the browsing UI.

If you want locale pages to include a Duplicates tab, opt in when generating the catalog:

Command
$ npx messagevisor catalog --with-duplicates
$ npx messagevisor catalog export --with-duplicates

catalog serve only serves an already generated catalog. If the catalog was exported with duplicate reports enabled, each locale page shows duplicate resolved translation values in its Duplicates tab. Otherwise, that tab is hidden. You can still run find-duplicates any time for a terminal audit.

Routing behavior

By default, the catalog uses browser routing, assuming it is hosted on the root of (sub)domain.

That means:

  • URLs are clean
  • deep links do not include #
  • refreshes on deep routes work as long as the host serves index.html for unmatched app routes

If you need hash routing instead, opt in explicitly:

Command
$ npx messagevisor catalog export --hashRouter
$ npx messagevisor catalog serve --hashRouter

Use hash routing when:

  • your host cannot fall back to index.html
  • you want static routing behavior without server-side rewrite support

What the catalog shows

The catalog includes:

  • messages, locales, attributes, segments, and targets
  • entity relationships
  • translations, overrides, formats, and history
  • set-aware views for sets-based projects
  • locale and message examples
  • locale duplicate translation reports when generated with --with-duplicates
  • permalinkable example rows and translation rows where supported
  • locale direction metadata, including RTL-aware rendering for translated content

Why use the catalog

The catalog is useful for:

  • code review
  • onboarding teammates
  • sharing deep links to a specific message, override, translation row, or example
  • finding duplicate translation values for a locale when generated with --with-duplicates
  • comparing locale and target behavior without running ad hoc CLI commands repeatedly

For product managers, content designers, localization leads, and legal reviewers, the catalog is the human-readable layer over the same definitions engineers validate in CI. It lets reviewers see copy, context, examples, and targeting rules without needing to understand every YAML field.

Review workflow

A practical catalog review usually looks like this:

  1. run npx messagevisor catalog while authoring
  2. open the message, locale, or target being changed
  3. inspect translations, overrides, examples, and related segments
  4. export, host, and share deep links in the pull request for reviewers
  5. run tests before merging

For hosted documentation or release review, generate the static catalog with catalog export and publish it next to the built datafiles or as a CI artifact.

This is meant to be private for your organization, and not shared with the wider world.

Export and deployment notes

The catalog is a generated artifact. Treat it like build output:

  • regenerate when project content changes
  • publish static files if you want a hosted catalog
  • prefer browser routing when your host supports SPA fallback routes
Previous
Testing
Next
Deployment