Messagevisor

Building blocks

Locales

Locales define available language variants, direction metadata, formatting presets, translation inheritance, and locale-scoped examples. They are the bridge between authored content and runtime formatting behavior.

Example

locales/en-US.yml
description: English (United States)
# optional: defaults to `ltr`
direction: ltr
# optionally inherit values from another base locale
inheritFormatsFrom: en
inheritTranslationsFrom: en
# define formatting rules keeping ICU syntax in mind
formats:
  number:
    money:
      style: currency
      currency: USD
      currencyDisplay: symbol

Locale keys

Locale keys are free-form strings, taken from the locale file itself (without extension).

In practice they usually follow BCP 47 style naming:

  • en
  • en-US
  • en-GB
  • nl-NL
  • ar-SA

Messagevisor does not invent locale semantics on its own. Whatever locale key you author is treated as data, then passed through to the runtime formatter behavior of your SDK modules.

Description

Human-readable documentation for the locale.

locales/en-US.yml
description: English (United States)

Direction

Use direction when the locale should be treated as left-to-right or right-to-left by consuming UIs.

locales/ar-SA.yml
description: Arabic (Saudi Arabia)
direction: rtl

Where this matters:

  • built datafiles carry locale direction
  • the JavaScript SDK exposes getDirection(locale?)
  • the React SDK exposes useDirection() and useLocaleInfo()
  • the Catalog uses it to render RTL content more faithfully

Important nuance:

  • direction is metadata, not layout behavior by itself
  • Messagevisor surfaces the value, but your app decides how and where to apply dir="rtl" or other RTL-aware presentation

Formats

Named formatting presets grouped by category. See Formats for the complete field reference.

Examples

Locale-scoped examples for documentation and debugging.

They are executable: you can inspect them with npx messagevisor examples --onlyLocales, and they also appear in the generated Catalog for reviewer-friendly browsing.

See Examples for the full authoring model.

Promotable

Controls whether this locale participates in sets-based promotion. Defaults to true.

Set promotable: false to prevent a locale definition from being copied when running promote.

promotable: false
description: Production-only locale

This is particular useful when you have multiple sets in your Messagevisor project per environment, and you want to linearly promote changes from one set to the next.

Learn more in Sets, Promotions, and Environments.

Inheritance

Let's imagine we have a base locale en and two regional variants en-US and en-GB:

locales/en.yml
description: English base

inheritTranslationsFrom

Use this when one locale should fall back to another locale's authored translations.

locales/en-GB.yml
description: English (United Kingdom)
inheritTranslationsFrom: en

How it works:

  1. Messagevisor tries the exact locale first
  2. if the message is missing there, it follows the inheritance chain
  3. if no inherited translation is found, that message key is omitted from the datafile for this locale; the SDK applies missing-key behavior at runtime if the app requests it

This is especially useful for regional variants where the base content lives in a parent locale and only some messages differ.

See Inheritance for the full end-to-end workflow, including export/import and pruning redundant regional translations.

Chains can be multi-level:

en-NL -> en-GB -> en

inheritFormatsFrom

Use this when a locale should reuse formatting presets (via formats) from another locale and only override the parts that differ.

locales/en-GB.yml
description: English (United Kingdom)
inheritFormatsFrom: en
# override the parts that differ
formats:
  number:
    money:
      style: currency
      currency: GBP
      currencyDisplay: symbol

Format inheritance is merged deeply, so a child locale can override just one preset or one branch without reauthoring the rest.

See Inheritance for pruning redundant child format presets with prune --formats.

mergeExamplesFrom

When set, this locale's examples are extended with examples from the specified parent locale.

locales/en-US.yml
description: English (United States)
mergeExamplesFrom: en

This is useful when you have a thorough set of format examples on a base locale and want regional variants to automatically include them in both the generated Catalog and the CLI examples command output.

A complete locale hierarchy example

locales/en.yml
description: English base
formats:
  number:
    decimal:
      maximumFractionDigits: 2
    money:
      style: currency
      currency: USD
  date:
    long:
      year: numeric
      month: long
      day: numeric
  time:
    short:
      hour: numeric
      minute: 2-digit
locales/en-US.yml
description: English (United States)
direction: ltr
inheritFormatsFrom: en
inheritTranslationsFrom: en
locales/en-GB.yml
description: English (United Kingdom)
direction: ltr
inheritFormatsFrom: en
inheritTranslationsFrom: en
formats:
  number:
    money:
      style: currency
      currency: GBP
locales/ar-SA.yml
description: Arabic (Saudi Arabia)
direction: rtl
formats:
  number:
    money:
      style: currency
      currency: SAR

Testing locales

Locale tests can assert:

  • resolved formats through expectedFormats
  • evaluated raw messages through rawMessage plus expectedTranslation
  • both at once
tests/locales/en-US.spec.yml
locale: en-US
assertions:
  - description: money preset has USD
    expectedFormats:
      number:
        money:
          currency: USD
  - description: plural formatting
    rawMessage: "{count, plural, =0 {No items} one {# item} other {# items}}"
    values:
      count: 2
    expectedTranslation: 2 items

See Testing for the full assertion shape.

Edge cases and behavior notes

Multiple inheritance chains are fine

A locale can specify both inheritFormatsFrom and inheritTranslationsFrom pointing to the same or different locales. They are resolved independently.

Circular inheritance is detected

The linter catches locale inheritance cycles and reports them as errors.

Direction is not formatting

Changing direction does not change number or date formatting by itself. It is separate locale metadata.

Duplicate audits use resolved translations

find-duplicates and the Catalog locale Duplicates tab compare resolved translation values for a locale.

If en-US inherits a value from en, that inherited value participates in duplicate detection.

Examples vs tests

  • examples are browsable documentation
  • tests are pass/fail assertions

The same authored behavior can often be represented in both.

Previous
Quick start
Next
Messages