Glossary

Definitions for every term you will encounter when working with Messagevisor.

Archived#

An entity (message, locale, attribute, segment, or target) marked with archived: true. Archived entities are excluded from build output, CLI list commands, and CSV exports. They remain in the repository as a record but are invisible at runtime.

Archiving is the standard alternative to deletion when you want to keep history while removing runtime presence.

See Messages for an example.

Attribute#

A named piece of context that can be evaluated at runtime. Attributes describe things about the user or environment: subscription plan, platform, country, age, and so on.

Attributes are declared as YAML files and referenced inside segment conditions and inline override conditions.

attributes/plan.yml

description: User subscription plan
type: string

See Attributes.

BCP 47#

A standard for language tags maintained by the Internet Engineering Task Force (IETF). Common examples include en, en-US, en-GB, nl-NL, ar-SA, and zh-Hant-TW.

Messagevisor uses BCP 47 style locale keys by convention. The toolkit does not enforce the standard but passes locale keys through to whatever runtime formatter is in use.

Build#

The step that reads your YAML definitions and writes datafiles to disk. Running npx messagevisor build is the core CI step for most projects.

See Building datafiles.

Catalog#

A self-contained static web application generated from your project's definitions. The catalog lets you browse messages, locales, translations, overrides, relationships, history, and examples through a browser without touching the command line.

Command

$ npx messagevisor catalog

See Catalog.

Condition#

A rule that tests one or more attribute values against a predicate. Conditions appear inside segment definitions and as inline logic on overrides.

Single condition:

attribute: plan
operator: equals
value: pro

Compound condition:

and:
  - attribute: plan
    operator: equals
    value: pro
  - attribute: platform
    operator: equals
    value: mobile

See Segments and Overrides.

Context#

The runtime key-value map passed to the SDK when evaluating a message. The SDK matches context keys against attribute definitions and evaluates override conditions to decide which translation to return.

m.translate("auth.signin", {}, { context: { plan: "pro", platform: "ios" } });

Datafile#

A generated JSON file produced by the build step. Each datafile corresponds to one target and one locale combination. It contains the resolved translations, override logic, and metadata the SDK needs to evaluate messages at runtime.

Example output path

datafiles/messagevisor-web-en.json

Datafiles are the primary artifact consumed by SDKs. They are intentionally simple and self-contained so they can be served from a CDN without additional infrastructure.

See Building datafiles.

Datasource#

The storage abstraction Messagevisor uses to read entity definitions. The default datasource reads YAML or JSON files from the local filesystem. Custom datasources can fetch definitions from remote storage or databases.

See Datasource.

Deprecated#

A message marked with deprecated: true is flagged as obsolete. Unlike archived, deprecated messages still appear in build output. The SDK surfaces a warning when a deprecated message is evaluated, which signals to application developers that they should migrate away from it.

deprecated: true
deprecationWarning: Use auth.signIn instead

See Messages.

Direction#

Metadata on a locale that records whether the language flows left-to-right (ltr) or right-to-left (rtl).

locales/ar-SA.yml

direction: rtl

The SDK exposes this via getDirection(). The React package exposes useDirection(). The catalog renders translation content with direction awareness. Your application is responsible for applying dir="rtl" or equivalent layout behavior.

See Locales.

Environment#

An authoring tree representing one deployment stage: dev, staging, production, and so on. In Messagevisor, environments are modeled as sets.

See Environments and Sets.

Evaluation#

The process of resolving a message key and context into a final translated string. Evaluation traverses the target datafile, matches overrides against the supplied context, resolves locale inheritance, and applies modules.

See Evaluation.

Format preset#

A named formatting shorthand defined inside a locale under formats.number, formats.date, or formats.time. A preset gives a reusable name to a group of Intl options.

formats:
  number:
    money:
      style: currency
      currency: USD

When the ICU module is active, {amount, number, money} in a translation string resolves against this preset at runtime.

See Formats.

GitOps#

A workflow where all changes to definitions go through Git via pull requests, code review, and CI automation. Messagevisor is designed around GitOps principles: YAML files in a repository, builds triggered by merges, and history tracked by commits.

See Concepts / GitOps.

ICU#

The International Components for Unicode message format specification. ICU syntax expresses plurals, selects, date formatting, number formatting, and more inside a single string.

{count, plural, =0 {No items} one {# item} other {# items}}

Messagevisor supports ICU through the @messagevisor/module-icu package.

See Modules / ICU.

Interpolation#

The process of replacing {{placeholder}} tokens in a translation string with runtime values.

Hello, {{name}}!

Messagevisor supports interpolation through the @messagevisor/module-interpolation package as a lighter alternative to full ICU syntax.

See Modules / Interpolation.

Lint#

The step that validates YAML definitions before building or committing. Linting catches structural errors, missing required keys, duplicate override keys, and conditions that reference undeclared attributes.

Command

$ npx messagevisor lint

See Linting.

Locale#

A definition file that declares a language variant, its direction, formatting presets, and inheritance relationships with other locales.

locales/en-US.yml

description: English (United States)
direction: ltr
inheritTranslationsFrom: en
inheritFormatsFrom: en
formats:
  number:
    money:
      style: currency
      currency: USD

See Locales.

Locale inheritance#

The mechanism by which one locale inherits translation content or format presets from another. Controlled by inheritTranslationsFrom and inheritFormatsFrom on a locale definition.

When en-US has inheritTranslationsFrom: en, translations authored for en are automatically available to en-US without duplication - unless en-US has its own authored translation.

See Locales.

Message#

The primary translation entity in Messagevisor. A message maps to one YAML file and can have base translations for any locale, optional overrides, metadata, and examples.

messages/auth/signin.yml

description: Sign in button label
translations:
  en: Sign in
  nl: Aanmelden

See Messages.

Message key#

The unique identifier for a message, derived from its file path relative to the messages/ directory. Path separators are replaced by the configured namespaceCharacter (default .).

messages/auth/signin.yml  →  auth.signin
messages/nav/home.yml     →  nav.home

See Namespaces.

Meta#

Arbitrary structured data attached to a message. Meta is included in the built datafile and accessible to the SDK at runtime, but it has no effect on translation evaluation logic.

meta:
  tags:
    - billing
  analytics:
    event: billing_summary_view

Module#

A runtime extension that intercepts message evaluation to provide formatting behavior. The ICU module handles plural and select syntax. The interpolation module handles {{placeholder}} tokens. Modules are registered in messagevisor.config.js.

See Modules.

Namespace#

The logical grouping implied by a message's directory path. Namespaces do not exist as explicit entities; they emerge from directory structure.

messages/auth/         → auth namespace
messages/billing/      → billing namespace
messages/nav/          → nav namespace

See Namespaces.

Override#

A conditional translation alternative defined inside a message. An override fires when its segment or condition matches the runtime context. Overrides are evaluated top-to-bottom; the first match wins.

overrides:
  - key: plan-pro
    segments: plan-pro
    translations:
      en: Your Pro workspace is ready

See Overrides.

Parser#

The component that reads definition files from disk. The default parser reads YAML. JSON is also built in. Custom parsers can be registered for other formats.

See Parsers.

Plugin#

A code extension registered in messagevisor.config.js that adds or modifies CLI subcommands. Plugins are the extension point for custom workflows built on top of the Messagevisor toolchain.

See Plugins.

Promote#

The CLI command that previews or applies copying entities from one set to another - typically from staging to production. Promotion merges YAML files by key so that destination-only content is preserved.

Command

$ npx messagevisor promote --from=staging --to=production --apply

See Promotions.

Promotable#

A flag on any entity or individual override that controls whether it participates in promote. Default is true. Set promotable: false for environment-specific content that should not be copied between sets. On overrides, it also prevents override-only dependencies from being promoted.

See Messages and Promotions.

Segment#

A named, reusable condition that can be referenced by many overrides. Segments are defined as YAML files and evaluated at runtime against the supplied context.

segments/plan-pro.yml

description: Users on the Pro plan
conditions:
  attribute: plan
  operator: equals
  value: pro

See Segments.

Set#

A parallel authoring tree inside a sets/ directory. Each set has its own copies of locales, messages, attributes, segments, and targets, allowing you to maintain multiple independent versions of your definitions - typically one per environment.

sets/
├── dev/
├── staging/
└── production/

See Sets.

State file#

A versioned JSON artifact written by build and applied promotions. State files record which version of each entity was built or promoted, enabling incremental builds, diff views, and reproducible CI artifacts.

See State files.

Target#

A definition file that controls which messages, locales, and formats go into one datafile. A target is a build-time output slice.

targets/web.yml

description: Web application datafile
locales:
  - en
  - nl
includeMessages:
  - auth*
  - nav*

See Targets.

Translation#

A locale-keyed string inside a message or override. Translations are the actual human-readable content authored by your team.

translations:
  en: Sign in
  nl: Aanmelden
  de: Anmelden

Translation module#

See Module.

Values#

The runtime key-value map passed to a module when evaluating a translation string. Values substitute named placeholders in ICU or interpolation syntax.

m.translate("greeting", { name: "Ada" });
// "Hello, Ada!"