Messagevisor

Advanced

Plugins

Messagevisor projects can inject extra CLI plugins through messagevisor.config.js. This is the escape hatch for project-specific workflows that should live beside the built-in commands.

Example

messagevisor.config.js
module.exports = {
  plugins: [
    {
      command: "hello",
      options: {
        greeting: { type: "string" },
        loud: { type: "boolean" },
      },
      handler: async ({ parsed }) => {
        const greeting = parsed.greeting || "hello from a project plugin";
        console.log(parsed.loud ? greeting.toUpperCase() : greeting);
      },
      examples: [{ command: "hello", description: "run the hello plugin" }],
    },
  ],
};

Project plugins are appended to the built-in project-aware CLI commands.

Good use cases

Plugins are useful when you need:

  • project-specific export/import helpers
  • validation or reporting commands
  • internal workflow shortcuts

They are especially useful for organization-specific workflows around translations, for example:

  • exporting review summaries for a localization vendor
  • checking naming conventions that are too specific for core linting
  • publishing datafiles to an internal service after build
  • generating product-manager-friendly reports from the catalog JSON
  • adapting Messagevisor content to a vendor-specific XLIFF 2.0 or XLIFF 1.2 workflow

What plugins should not replace

If the behavior is part of the normal Messagevisor authoring model, it usually belongs in core definitions, tests, targets, or modules first.

Plugins are best for workflow-specific integration, not for replacing the content model.

Plugin shape

A plugin has the same shape as built-in CLI commands:

  • command: yargs-style command name
  • options: accepted command options, keyed by name; declare type and optional aliases, choices, or descriptions
  • handler: async function that receives project config, datasource, parsed options, and root path
  • examples: command examples shown in CLI help

The handler runs with the loaded project configuration, so it can reuse custom paths, parser settings, sets configuration, and project datasource behavior. CLI parsing is strict: a plugin must declare every flag it accepts in options; unknown flags fail before the handler runs.

For XLIFF adapters, preserve message and override identity, ICU placeholders, rich-text tags, notes, locale direction, and translation workflow state. Imports should preview mutations before applying them and reject ambiguous or unknown units. See Export and import for the current interchange policy.

If the behavior changes message evaluation, write a module instead. If it validates authored entities, first check whether a test, lint, or schema rule is a better fit.

Previous
Parsers
Next
Datasource