Messagevisor

Examples

Examples are authored, executable documentation for your Messagevisor project. They let you show how messages and locales behave without having to turn every scenario into a formal test.

Two kinds of examples

Messagevisor supports:

  • message examples
  • locale examples

Message examples

Message examples live inside a message file's examples array. After authoring them, inspect them with npx messagevisor examples --onlyMessages or browse them in the generated Catalog.

messages/dashboard/welcome.yml
translations:
  en: "Welcome, {name}!"
  nl: "Welkom, {name}!"
examples:
  - description: English greeting
    locale: en
    values:
      name: Ada
  - description: Dutch greeting
    locale: nl
    values:
      name: Selin

Good for:

  • showing override behavior
  • demonstrating one message across multiple locales
  • documenting required values or context

Locale examples

Locale examples live inside a locale file's examples array. After authoring them, inspect them with npx messagevisor examples --onlyLocales or browse them in the generated Catalog.

locales/en-US.yml
description: English (United States)
inheritFormatsFrom: en
inheritTranslationsFrom: en
examples:
  - description: USD money format
    rawMessage: "Price: {amount, number, money}"
    values:
      amount: 1234.56
  - description: Long date format
    rawMessage: "Date: {date, date, long}"
    values:
      date: "2025-01-15T00:00:00Z"

Good for:

  • formatting presets
  • plural/select/selectordinal behavior
  • target-aware format overrides
  • locale-specific raw-message demonstrations

Matrix expansion in examples

Examples support matrix for generating multiple examples from one definition:

messages/cart/items.yml
translations:
  en: "{count, plural, =0 {No items} one {# item} other {# items}}"
examples:
  - matrix:
      count: [0, 1, 5]
    description: Cart with ${{ count }} items
    locale: en
    values:
      count: ${{ count }}

This expands into three examples at runtime - one for each value of count.

Shared example fields

Examples can include:

  • description
  • values
  • context
  • formats
  • currency
  • timeZone
  • matrix

Message and locale examples then add their own subject-specific fields such as locale, message, or rawMessage.

timeZone uses the same spelling in examples, tests, SDK calls, and Intl-shaped format presets. Values are passed to Intl.DateTimeFormat, so use identifiers supported by your JavaScript runtime.

Running examples

Use the CLI when you want fast terminal feedback:

Command
$ npx messagevisor examples
$ npx messagevisor examples --locale=en-US
$ npx messagevisor examples --onlyMessages
$ npx messagevisor examples --onlyLocales
$ npx messagevisor examples --json --pretty

Use the generated Catalog when you want a browsable review surface with compact and expanded rows, filtering, evaluated output, and shareable links.

Examples vs tests

Examples are best when you want:

  • browsable documentation
  • onboarding material
  • human-readable behavior samples
  • stakeholder review in the catalog

Tests are best when you want:

  • pass/fail guarantees
  • regression protection
  • CI enforcement

In important areas, it is often worth having both.

For example, a checkout total message might have examples for PM and localization review, plus tests that guarantee specific currencies, locales, and plural branches stay correct.

Examples in the catalog

The catalog surfaces examples with:

  • compact and expanded views
  • filtering
  • shareable permalinks
  • evaluated output next to authored inputs

That makes examples especially good for review and collaboration.

Writing reviewer-friendly examples

Good examples use descriptions that explain the scenario, not only the mechanics:

examples:
  - description: Pro customer seeing the checkout banner on iOS
    locale: en-US
    context:
      plan: pro
      platform: ios
    values:
      name: Ada

That description is what a reviewer sees first in the catalog, so it should answer "who is this for?" and "why does this variant exist?"

Edge cases and behavior notes

Examples still use the real runtime path

Examples are not toy renderings. They use the same modules and evaluation machinery as the rest of the product.

ISO date strings are treated helpfully

Example values that look like ISO dates are coerced so date/time formatting examples work more naturally.