Building blocks
Messages
Messages are the core translation entities in Messagevisor. They hold base translations, optional metadata, examples, and conditional overrides that react to segments or conditions.
Example#
description: Sign in button labeltranslations: en: Sign in nl: AanmeldenA richer message with overrides and examples:
description: Dashboard welcome heading# optional: a shorter one-line description of the messagesummary: Personalized greeting on the dashboard# optional: arbitrary structured metadatameta: tags: - dashboard - personalizationtranslations: en: Welcome back, {name} nl: Welkom terug, {name}overrides: - key: plan-pro segments: plan-pro translations: en: Welcome back, {name}. Your Pro workspace is ready. nl: Welkom terug, {name}. Je Pro-werkruimte staat klaar.examples: - description: Default greeting for English locale: en values: name: AdaMessage keys#
Message keys come from file paths relative to the messages/ directory, with the configured namespaceCharacter replacing path separators.
Default behavior:
messages/auth/signin.yml -> auth.signinmessages/nav/contact.yml -> nav.contactmessages/footer/privacy.yml -> footer.privacyThe separator character is controlled by namespaceCharacter in project's Configuration.
Description#
Human-readable documentation for the message. Shown in the Catalog and used by linting. Not included in runtime datafiles.
description: Sign in button labelSummary#
A shorter one-line description of the message. Used in CSV exports and UIs where the full description is too long.
summary: Sign in button labelTranslations#
The base locale-to-string translation map. This is the primary authored content.
description: Sign in button labeltranslations: en: Sign in en-US: Sign in (US) nl: AanmeldenLocale inheritance applies at build time. A regional locale like en-US can inherit from en through inheritTranslationsFrom, so you only need to author the strings that differ.
Overrides#
Conditional translations that are applied instead of the base translation when runtime conditions match.
Via conditions#
Assuming you already have your desired attributes defined, you can create an override with conditions like this:
description: Sign in button labeltranslations: en: Sign inoverrides: - key: platform-web conditions: - attribute: platform # referencing attributes/platform.yml operator: equals value: web translations: en: Sign in from browserVia segments#
Alternatively, if you are already defined reusable conditions via segments, you can reference them in the override like this:
description: Sign in button labeltranslations: en: Sign inoverrides: - key: platform-web segments: platform-web # referencing segments/platform-web.yml translations: en: Sign in from browserSee Overrides for the full override authoring model, and Conditions for the full operator and composition reference shared by conditions and segment definitions.
Meta#
Arbitrary structured metadata stored in the datafile alongside the translation. It does not affect evaluation logic but is available to the SDK at runtime through getMessageMeta() or the React useSdk() hook.
Useful if you wish to react differently via custom SDK modules.
meta: tags: - auth - onboardingExamples#
Message-scoped examples for documentation and debugging.
They are executable: you can inspect them with npx messagevisor examples --onlyMessages, and they also appear in the generated Catalog so reviewers can see evaluated output next to authored context.
description: Sign in button labelexamples: - description: Default greeting for English locale: en values: name: AdaSee Examples for the full authoring model.
Deprecated#
Mark a message as deprecated so the SDK can signal it at runtime.
deprecated: true# optional warning emitted by SDKdeprecationWarning: Use auth.signIn insteadWhen set, deprecated and deprecationWarning are included in the built datafile and surfaced to the SDK.
Archived#
When set to true it removes the message from normal runtime flows.
Archived messages are excluded from build output, CSV exports, and list commands.
archived: trueThis is the built-in availability switch. There is no separate published/unpublished state for messages.
Promotable#
Controls whether this message participates in sets-based promotion. Defaults to true.
Set promotable: false to prevent a message from being copied when running promote.
promotable: falsetranslations: en: Environment-specific textSee Promotions for how this interacts with set-to-set workflows. Especialy when covering linear promotion flows for multiple environments.
ICU message syntax#
When using the ICU module, translations can contain ICU syntax such as plurals, selects, and named format references:
translations: en: | {count, plural, =0 {No items in cart} one {# item in cart} other {# items in cart} }With named number format:
translations: en-US: "Total: {amount, number, money}"The named format money is defined in the locale's formats.number presets. See Formats and ICU Module.
Namespace-based organization#
Nesting messages in subdirectories creates logical namespaces:
messages/├── auth/│ ├── signin.yml -> auth.signin│ └── signout.yml -> auth.signout├── billing/│ ├── total.yml -> billing.total│ └── invoice.yml -> billing.invoice└── nav/ ├── home.yml -> nav.home └── contact.yml -> nav.contactSee Namespaces for configuration.
Creating messages#
Creating manually#
You can create a message definition file manually in the messages/ directory.
From the CLI#
$ npx messagevisor create --messages --keys=$'auth.signin\nauth.signout'This generates skeleton files with an empty translation for the first locale. You fill in the translations afterwards.
Testing messages#
Message tests validate resolved translations:
message: auth.signinassertions: - locale: en target: web expectedTranslation: Sign in - locale: nl target: web expectedTranslation: AanmeldenSee Testing for the full assertion shape including matrix, context, and values.
Finding duplicate copy#
To find active message keys that resolve to the same translation value, run:
$ npx messagevisor find-duplicates$ npx messagevisor find-duplicates --locale=en-USDuplicate detection is grouped by locale and applies translation inheritance before comparing values. The catalog also shows this in each locale's Duplicates tab.
Edge cases and behavior notes#
Override evaluation order matters#
Overrides are evaluated in the order they appear in the file. The first override whose conditions or segments match is the one used.
Changing override order changes runtime behavior.
Raw syntax depends on modules#
Message text is just a string until runtime modules interpret it. ICU plural/select syntax, named formats, and other behaviors depend on the configured modules in application runtime.
Target context can simplify overrides at build time#
When a target defines partially known context upfront, the builder can eliminate impossible override branches before the SDK sees the datafile.
That means the runtime datafile may have fewer override branches than the authored source.
Locale inheritance applies to overrides too#
Each override has its own translations map. Locale inheritance is resolved for override translations the same way it is for base translations.

