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.