Messagevisor

Workflow

Configuration

Messagevisor reads project configuration from root messagevisor.config.js. This file defines how the project is laid out, how definitions are parsed, and which modules are active.

Example

messagevisor.config.js
const { createICUModule } = require("@messagevisor/module-icu");
module.exports = {
  modules: [createICUModule()],
};

Options reference

Configuration keys are validated strictly. Misspelled or unsupported keys fail fast instead of being ignored, so a setting that looks active cannot silently have no effect.

Core options

OptionTypeDefaultDescription
parserstring or objectymlFile parser to use. "yml" and "json" are built in.
namespaceCharacterstring.Separator between path segments in message keys
exportOverrideKeySeparatorstring":"Separator used in CSV exports for overrides (messageKey:overrideKey)
modulesarray[]Runtime modules for ICU, interpolation, etc.
setsbooleanfalseEnable multi-set project mode
promotionFlowsarray[]Restrict allowed set-to-set promotion directions
sourceLocalestring—Canonical locale used for translation contract and staleness checks
lintIcubooleantrueValidate ICU syntax and named format references during linting
icuSkeletonbooleanfalseAllow inline ICU skeleton styles such as {amount, number, ::currency/USD} when ICU linting is active
catalogBlockSizenumber262144Target size in bytes for each Catalog message block

Catalog indexes are written as compact per-type layers. The core layer contains keys and filter facets, while descriptions and display metadata are loaded separately by the Catalog UI. Message details are always stored in content-addressed blocks. Older single-file Catalog indexes remain readable.

Directory paths

All paths default to subdirectories of the project root. They can be overridden when your repository layout requires it.

OptionDefault path
localesDirectoryPathlocales
messagesDirectoryPathmessages
attributesDirectoryPathattributes
segmentsDirectoryPathsegments
targetsDirectoryPathtargets
testsDirectoryPathtests
datafilesDirectoryPathdatafiles
catalogDirectoryPathcatalog
exportsDirectoryPathexports
messagevisor.config.js
module.exports = {
  messagesDirectoryPath: "src/translations/messages",
  datafilesDirectoryPath: "public/datafiles",
};

Directory overrides are useful when:

  • integrating Messagevisor into an existing repository layout
  • separating authored definitions from generated artifacts
  • organizing sets or deployment outputs in a custom way

Parser configuration

parser can point to:

  • a built-in parser name such as yml or json
  • a custom parser implementation

This lets the same project model work with different source file formats while keeping the rest of the workflow stable.

See Parsers for more information.

Source locale

Set sourceLocale when translators should work from one canonical language:

messagevisor.config.js
module.exports = {
  sourceLocale: "en",
};

Lint then requires each message and override translation group to contain en, and verifies compatible ICU value contracts and required rich text tags while allowing locale appropriate grammar. Reviewed translation state records both sourceHash and targetHash, proving which source and target text were approved. Existing states with only a source hash need review before upgrading.

Modules

modules define how runtime syntax is interpreted.

Typical examples:

  • ICU message syntax
  • interpolation

This matters in CLI and SDK runtime behaviour.

If a message behaves differently than expected, check modules before assuming the message text itself is wrong.

See Modules for more.

ICU skeletons

lintIcu and icuSkeleton are separate from modules. Registering createICUModule() enables ICU evaluation. lintIcu controls whether messagevisor lint validates ICU syntax and named format references in message translations. It defaults to true:

messagevisor.config.js
module.exports = {
  lintIcu: true,
};

Set lintIcu: false only when a project intentionally stores text that looks like ICU but should not be validated by Messagevisor linting.

When ICU linting is enabled, icuSkeleton: true loosens style linting to allow inline skeleton styles:

messagevisor.config.js
const { createICUModule } = require("@messagevisor/module-icu");
module.exports = {
  modules: [createICUModule()],
  icuSkeleton: true,
};

Prefer named locale formats for shared product copy because they are easier to review and test across locales. Use inline skeletons when you deliberately need message-local ICU syntax.

Sets configuration

Set sets: true to enable multi-set projects.

messagevisor.config.js
module.exports = {
  sets: true,
};

When sets are enabled:

  • some CLI commands require --set
  • definitions are organized under sets/<name>/...
  • promotions become available as a dedicated workflow

Promotion flows

Use promotionFlows to restrict allowed set-to-set movements.

messagevisor.config.js
module.exports = {
  sets: true,
  promotionFlows: [
    { from: "dev", to: "staging" },
    { from: "staging", to: "production" },
  ],
};

This keeps promotion commands aligned with your release model instead of letting any set copy into any other set.

Configuration and precedence

Several runtime behaviors are shaped by both authored definitions and configuration:

  • parser decides how files are read
  • modules decide how message syntax is interpreted
  • directory paths decide where the CLI reads and writes
  • namespace configuration decides how file paths become keys
  • export configuration affects CSV interoperability

Project configuration as managed in messagevisor.config.js does not replace authored data. It shapes how that data is discovered and interpreted.

Previous
Projects
Next
Linting