Messagevisor

Workflow

Code generation

Messagevisor can generate TypeScript helpers from your project, mainly to make runtime integrations more typed and ergonomic.

Generate TypeScript

Command
$ npx messagevisor generate-code --language typescript --out-dir src/generated

Generated files are application helpers, not source definitions. Commit them when your application build expects them to be present, or generate them in CI when you prefer generated code to stay out of pull requests.

Bind helpers to an instance

Generated createTranslations(m) returns { t, translate } bound to the supplied SDK instance. Both helpers accept the generated union of authored message keys, including any generation filters. They retain the SDK's translation overloads without changing which instance handles a call.

src/welcome.ts
import { createMessagevisor, type DatafileContent } from "@messagevisor/sdk";
import { createICUModule } from "@messagevisor/module-icu";
import { createTranslations } from "./generated";
export async function welcome(datafile: DatafileContent, plan: string) {
  const requestInstance = createMessagevisor({
    datafile,
    context: { plan },
    modules: [createICUModule()],
  });
  try {
    const { t } = createTranslations(requestInstance);
    return t("dashboard.welcome", { name: "Ada" });
  } finally {
    await requestInstance.close();
  }
}

Use a key from your own generated project and pass the loaded datafile for the request's locale. This example owns and closes a root SDK instance per request. Alternatively, bind helpers to a shared root and pass request locale and context in each translation's options. See server evaluation and the shared loading recipe.

The legacy generated setInstance(m) plus global t and translate helpers remain available for a single application instance. That setter changes module level state: never call it with a request specific instance on a shared server. Concurrent requests could otherwise translate through another request's locale or context. Bind helpers with createTranslations(m) inside each request instead. The factory does not fetch datafiles, mutate the global helper, or own the instance lifecycle.

React helpers

Command
$ npx messagevisor generate-code --language typescript --out-dir src/generated --react

Filtering

Command
$ npx messagevisor generate-code --language typescript --out-dir src/generated --target=web
$ npx messagevisor generate-code --language typescript --out-dir src/generated --includeMessages="auth*"

What code generation is for

Code generation is useful when you want:

  • typed message key access
  • project-aware helper code
  • a smoother integration layer in TypeScript or React apps
  • autocomplete for available message keys
  • fewer hard-coded string keys in application code

For example, generated helpers can make it easier for app developers to discover dashboard.welcome while still letting product and localization reviewers inspect the real source in messages/dashboard/welcome.yml.

What it is not for

Code generation does not replace:

  • build
  • runtime datafiles
  • the SDK itself

Think of it as a typed convenience layer around the same underlying project model.

Current scope

Only TypeScript generation is supported today.

The command can filter by --target, --includeMessages, and --excludeMessages, which is useful when one app only consumes a subset of a larger Messagevisor project.

For sets-based projects, pass --set=<set> to generate against the same authored tree that will be built and deployed.

Checking application call sites today

Code generation catches mistyped keys when application code uses the generated types, but Messagevisor does not yet ship a source-code extractor. For an interim CI check:

  1. generate the typed key union into a deterministic directory;
  2. fail CI when regeneration changes committed output;
  3. search application code for literal calls such as translate("..."), t("..."), or your wrapper API;
  4. compare those literals with npx messagevisor list --messages --json;
  5. treat dynamic keys as a reviewed exception instead of guessing their possible values.

This can identify literal calls to undefined keys and defined keys with no discovered literal call sites. It cannot prove that a key assembled dynamically is unused. Runtime deprecated_message diagnostics remain the safer last-mile signal while migrating or retiring keys.

Previous
Catalog
Next
Deployment