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 label
translations:
  en: Sign in
  nl: Aanmelden

A richer message with overrides and examples:

description: Dashboard welcome heading
# optional: a shorter one-line description of the message
summary: Personalized greeting on the dashboard
# optional: arbitrary structured metadata
meta:
  tags:
    - dashboard
    - personalization
translations:
  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: Ada

Message 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.signin
messages/nav/contact.yml     -> nav.contact
messages/footer/privacy.yml  -> footer.privacy

The 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 label

Summary#

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 label

Translations#

The base locale-to-string translation map. This is the primary authored content.

description: Sign in button label
translations:
  en: Sign in
  en-US: Sign in (US)
  nl: Aanmelden

Locale 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 label
translations:
  en: Sign in
overrides:
  - key: platform-web
    conditions:
      - attribute: platform # referencing attributes/platform.yml
        operator: equals
        value: web
    translations:
      en: Sign in from browser

Via segments#

Alternatively, if you are already defined reusable conditions via segments, you can reference them in the override like this:

description: Sign in button label
translations:
  en: Sign in
overrides:
  - key: platform-web
    segments: platform-web # referencing segments/platform-web.yml
    translations:
      en: Sign in from browser

See 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
    - onboarding

Examples#

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 label
examples:
  - description: Default greeting for English
    locale: en
    values:
      name: Ada

See 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 SDK
deprecationWarning: Use auth.signIn instead

When 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: true

This 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: false
translations:
  en: Environment-specific text

See 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.contact

See 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.signin
assertions:
  - locale: en
    target: web
    expectedTranslation: Sign in
  - locale: nl
    target: web
    expectedTranslation: Aanmelden

See 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-US

Duplicate 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.

Related#

• Overrides
• Conditions
• Locales
• Formats
• Segments
• Attributes
• Targets
• Examples
• Evaluation
• Testing
• CLI
• Modules / ICU