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#
description: English (United States)# optional: defaults to `ltr`direction: ltr# optionally inherit values from another base localeinheritFormatsFrom: eninheritTranslationsFrom: en# define formatting rules keeping ICU syntax in mindformats: number: money: style: currency currency: USD currencyDisplay: symbolLocale keys#
Locale keys are free-form strings, taken from the locale file itself (without extension).
In practice they usually follow BCP 47 style naming:
enen-USen-GBnl-NLar-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.
description: English (United States)Direction#
Use direction when the locale should be treated as left-to-right or right-to-left by consuming UIs.
description: Arabic (Saudi Arabia)direction: rtlWhere this matters:
- built datafiles carry locale direction
- the JavaScript SDK exposes
getDirection(locale?) - the React SDK exposes
useDirection()anduseLocaleInfo() - the Catalog uses it to render RTL content more faithfully
Important nuance:
directionis 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: falsedescription: Production-only localeThis 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:
description: English baseinheritTranslationsFrom#
Use this when one locale should fall back to another locale's authored translations.
description: English (United Kingdom)inheritTranslationsFrom: enHow it works:
- Messagevisor tries the exact locale first
- if the message is missing there, it follows the inheritance chain
- 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 -> eninheritFormatsFrom#
Use this when a locale should reuse formatting presets (via formats) from another locale and only override the parts that differ.
description: English (United Kingdom)inheritFormatsFrom: en# override the parts that differformats: number: money: style: currency currency: GBP currencyDisplay: symbolFormat 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.
description: English (United States)mergeExamplesFrom: enThis 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#
description: English baseformats: number: decimal: maximumFractionDigits: 2 money: style: currency currency: USD date: long: year: numeric month: long day: numeric time: short: hour: numeric minute: 2-digitdescription: English (United States)direction: ltrinheritFormatsFrom: eninheritTranslationsFrom: endescription: English (United Kingdom)direction: ltrinheritFormatsFrom: eninheritTranslationsFrom: enformats: number: money: style: currency currency: GBPdescription: Arabic (Saudi Arabia)direction: rtlformats: number: money: style: currency currency: SARTesting locales#
Locale tests can assert:
- resolved formats through
expectedFormats - evaluated raw messages through
rawMessageplusexpectedTranslation - both at once
locale: en-USassertions: - 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 itemsSee 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.

