Messagevisor

Custom modules

Custom modules let you extend Messagevisor runtime behavior without changing datafiles or authored message files. Use them when your app needs project-specific formatting, post-processing, diagnostics, or runtime integrations.

When to write a module

Write a module when behavior belongs at message evaluation time:

  • custom placeholder syntax
  • pseudo-localization
  • markdown or sanitizer transforms
  • observability hooks for missing or deprecated translations
  • custom diagnostics
  • feature flag or experiment resolver integration
  • message-specific behavior driven by meta

If you need to add a CLI workflow, write a plugin. If you need to read another authoring file format, write a parser. If the behavior changes evaluated translation output, a module is usually the right extension point.

Register modules

Register modules in messagevisor.config.js so CLI evaluation, examples, tests, and catalog output use them:

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

Register the same runtime modules on your SDK instance:

TypeScript
import { createMessagevisor } from "@messagevisor/sdk";
import { createICUModule } from "@messagevisor/module-icu";
import { createPseudoLocaleModule } from "./modules/pseudo-locale";
const m = createMessagevisor({
  datafile,
  modules: [createICUModule(), createPseudoLocaleModule()],
});

The CLI and the app are separate runtimes. If one has a module and the other does not, messages can pass tests but render differently in production.

Module shape

TypeScript
import type {
  MessagevisorFormatPayload,
  MessagevisorModule,
  MessagevisorModuleApi,
  MessagevisorTransformPayload,
} from "@messagevisor/sdk";
export interface MessagevisorModule {
  name?: string;
  setup?: (api: MessagevisorModuleApi) => void;
  format?: (payload: MessagevisorFormatPayload, api?: MessagevisorModuleApi) => unknown;
  transform?: (payload: MessagevisorTransformPayload, api?: MessagevisorModuleApi) => unknown;
  close?: () => void | Promise<void>;
}
HookWhen it runsTypical use
setupwhen the module is registeredsubscribe to diagnostics, register flag or variation resolvers
formatwhile formatting a translationinterpolation, ICU, named syntax, rich-text handling
transformafter all formatting modules have had a chancemarkdown, sanitizer, pseudo-localization, output wrappers
closewhen the SDK instance closesunsubscribe external listeners, flush buffers, close clients

format and transform hooks can return any value. Returning undefined keeps the current translation unchanged. Returning any other value passes that value to the next module.

For portable modules that should work across future SDKs, treat string input and string output as the baseline. JavaScript modules may return arrays, framework nodes, or other rich values, but those are JavaScript-enhanced capabilities. A module intended for Python, Java, Swift, PHP, Ruby, Go, and JavaScript should document when it only supports string output.

Execution order

Modules run in the order you register them:

TypeScript
const m = createMessagevisor({
  datafile,
  modules: [createInterpolationModule(), createICUModule(), createMarkdownModule()],
});

For each evaluation:

  1. Messagevisor finds the raw message.
  2. Every module with format runs in registration order.
  3. Every module with transform runs in registration order.
  4. The final value is returned from translate() or formatMessage().

This means a module that produces ICU syntax should run before the ICU module, while a module that sanitizes final HTML should usually run after formatting.

Payloads

format receives:

TypeScript
interface MessagevisorFormatPayload {
  translation: unknown;
  values?: MessageValues;
  locale: string;
  source: "translation" | "formatMessage";
  messageKey?: string;
  meta?: Record<string, unknown>;
  formats: FormatPresets;
  moduleOptions?: Record<string, unknown>;
}

transform receives:

TypeScript
interface MessagevisorTransformPayload {
  translation: unknown;
  locale: string;
  source: "translation" | "formatMessage";
  messageKey?: string;
  meta?: Record<string, unknown>;
}

Important payload details:

  • source: "translation" means the call came from translate() / t().
  • source: "formatMessage" means the call came from formatting a literal string.
  • messageKey and meta are only available for keyed translations.
  • formats is available to format hooks and contains the resolved locale+target+runtime format preset object.
  • moduleOptions is available to format hooks and contains the per-call object passed to translate() or formatMessage().

Minimal transform module

TypeScript
import type { MessagevisorModule } from "@messagevisor/sdk";
export function createUppercaseModule(): MessagevisorModule {
  return {
    name: "uppercase",
    transform({ translation }) {
      if (typeof translation !== "string") {
        return;
      }
      return translation.toUpperCase();
    },
  };
}
TypeScript
m.addModule(createUppercaseModule());
m.translate("nav.home"); // "HOME"
m.removeModule("uppercase");

Use name when you want duplicate detection, removeModule(name), or name-keyed moduleOptions.

Names and runtime management

Named modules can be managed after instance creation:

TypeScript
m.addModule(createUppercaseModule());
m.removeModule("uppercase");

If another registered module already uses the same name, Messagevisor reports a duplicate_module diagnostic and does not register the duplicate. Anonymous modules are allowed, but they cannot be removed by name and cannot receive name-keyed moduleOptions.

Custom placeholder module

Use format when you need access to values.

TypeScript
import type { MessagevisorModule } from "@messagevisor/sdk";
export function createPercentPlaceholderModule(): MessagevisorModule {
  return {
    name: "percent-placeholders",
    format({ translation, values }) {
      if (typeof translation !== "string") {
        return;
      }
      return translation.replace(/%\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (match, key) => {
        const value = values?.[key];
        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
          return String(value);
        }
        return match;
      });
    },
  };
}
TypeScript
m.formatMessage("Hello %{name}", { name: "Ada" });
// "Hello Ada"

For production use, prefer the built-in Interpolation module unless your project needs custom behavior.

Pseudo-localization module

Pseudo-localization is useful for UI expansion checks before translations are ready.

TypeScript
import type { MessagevisorModule } from "@messagevisor/sdk";
const map: Record<string, string> = {
  a: "á",
  e: "é",
  i: "í",
  o: "ó",
  u: "ú",
  A: "Á",
  E: "É",
  I: "Í",
  O: "Ó",
  U: "Ú",
};
export function createConfigurablePseudoLocaleModule(): MessagevisorModule {
  return {
    name: "pseudo",
    transform({ translation, locale }) {
      if (locale !== "en-XA" || typeof translation !== "string") {
        return;
      }
      const expanded = translation
        .split("")
        .map((character) => map[character] || character)
        .join("");
      return `[!! ${expanded} !!]`;
    },
  };
}

Markdown or sanitizer transform

Use transform for final-output post-processing.

TypeScript
import type { MessagevisorModule } from "@messagevisor/sdk";
export function createMarkdownModule(markdownToHtml: (input: string) => string): MessagevisorModule {
  return {
    name: "markdown",
    transform({ translation, meta }) {
      if (typeof translation !== "string" || meta?.format !== "markdown") {
        return;
      }
      return markdownToHtml(translation);
    },
  };
}

The meta check keeps markdown processing opt-in per message.

messages/legal/terms.yml
description: Terms link text
meta:
  format: markdown
translations:
  en: "Read **terms**"

Rich output

Modules are not limited to strings. Rich-text integrations can return arrays, framework nodes, or any other renderable value that the caller expects.

When handling rich output:

  • check the current value type before transforming it
  • return undefined for values the module does not own
  • avoid stringifying arrays or framework nodes unless that is the module's purpose
  • let framework packages such as React and Vue handle their own renderable output where possible

This is why most string-only modules start with:

TypeScript
if (typeof translation !== "string") {
  return;
}

Per-call module options

Modules can read options by their module name:

TypeScript
import type { MessagevisorModule } from "@messagevisor/sdk";
interface PseudoOptions {
  enabled?: boolean;
  wrapper?: string;
}
export function createPseudoLocaleModule(): MessagevisorModule {
  const name = "pseudo";
  return {
    name,
    format({ translation, moduleOptions }) {
      const options = moduleOptions?.[name] as PseudoOptions | undefined;
      if (!options?.enabled || typeof translation !== "string") {
        return;
      }
      const wrapper = options.wrapper || "!!";
      return `[${wrapper} ${translation} ${wrapper}]`;
    },
  };
}
TypeScript
m.translate("nav.home", undefined, {
  moduleOptions: {
    pseudo: {
      enabled: true,
      wrapper: "###",
    },
  },
});

Name-keyed options let one evaluation path change module behavior without changing the global SDK instance.

Diagnostics module

Modules can subscribe to diagnostics during setup. Module diagnostic subscriptions have their own logLevel, independent of the SDK instance log level.

TypeScript
import type { MessagevisorDiagnostic, MessagevisorModule } from "@messagevisor/sdk";
export function createMissingTranslationReporter(
  report: (diagnostic: MessagevisorDiagnostic) => void,
): MessagevisorModule {
  return {
    name: "missing-reporter",
    setup({ onDiagnostic }) {
      onDiagnostic(
        (diagnostic) => {
          if (diagnostic.code === "missing_translation") {
            report(diagnostic);
          }
        },
        { logLevel: "error" },
      );
    },
  };
}

Modules can also emit diagnostics:

TypeScript
export function createEmptyTranslationDiagnosticModule(): MessagevisorModule {
  return {
    name: "empty-translation",
    transform(payload, api) {
      const { translation, locale, messageKey, source } = payload;
      if (translation !== "") {
        return;
      }
      api?.reportDiagnostic({
        level: "warn",
        code: "empty_translation",
        message: "Empty translation",
        locale,
        messageKey,
        source,
      });
    },
  };
}

Diagnostics emitted by a named module include the module name. A module does not receive diagnostics that it reports itself.

Feature and experiment resolver module

Modules can wire feature flag and experiment resolvers into the SDK:

TypeScript
import type { Context } from "@messagevisor/types";
import type { MessagevisorModule } from "@messagevisor/sdk";
export function createFeaturevisorModule(featurevisor: {
  isEnabled(featureKey: string, context?: Context): boolean;
  getVariation(experimentKey: string, context?: Context): string;
}): MessagevisorModule {
  return {
    name: "featurevisor",
    setup({ setFlagResolver, setVariationResolver }) {
      setFlagResolver((featureKey, context) => featurevisor.isEnabled(featureKey, context));
      setVariationResolver((experimentKey, context) =>
        featurevisor.getVariation(experimentKey, context),
      );
    },
  };
}

This lets authored override conditions reference feature flags and experiments while the application owns the actual resolver implementation.

Cleanup

Use close when a module owns resources:

TypeScript
export function createBufferedReporterModule(reporter: { flush(): Promise<void> }): MessagevisorModule {
  return {
    name: "buffered-reporter",
    async close() {
      await reporter.flush();
    },
  };
}

When m.close() is called, modules close in reverse registration order. Messagevisor waits for async cleanup. If one module fails to close, Messagevisor still tries to close the remaining modules and rejects with a close error.

Testing custom modules

Test modules directly with the SDK:

TypeScript
import { createMessagevisor } from "@messagevisor/sdk";
import { createPseudoLocaleModule } from "./pseudo-locale";
it("pseudo-localizes en-XA output", function () {
  const m = createMessagevisor({
    locale: "en-XA",
    defaultTranslations: {
      "en-XA": {
        "nav.home": "Home",
      },
    },
    modules: [createPseudoLocaleModule()],
  });
  expect(m.translate("nav.home")).toEqual("[!! Hómé !!]");
});

For CLI behavior, register the same module in messagevisor.config.js and cover it with message examples or tests.

Checklist

  • give modules stable names
  • return undefined when the module does not handle the current value
  • preserve non-string rich outputs unless the module intentionally handles them
  • use format when you need values, formats, or moduleOptions
  • use transform for final output post-processing
  • keep module ordering explicit
  • register matching modules in config and SDK runtime
  • test both keyed translations and formatMessage() if your module supports both