Messagevisor

Inheritance

Inheritance lets a locale reuse translations, formats, and examples from another locale while only authoring the differences. It is the workflow you want for regional variants such as en-US, en-GB, nl-NL, and nl-BE.

What can be inherited

Locale files support three inheritance fields:

FieldPurpose
inheritTranslationsFromReuse message and override translations from another locale
inheritFormatsFromDeep-merge format presets from another locale
mergeExamplesFromInclude examples from another locale in CLI examples output and generated catalog views

These fields are independent. A locale can inherit translations from one parent, formats from another parent, or use the same parent for both.

Author the base locale

Start with the broadest reusable locale:

locales/en.yml
description: English base
formats:
  number:
    money:
      style: currency
      currency: USD
      currencyDisplay: symbol
  date:
    long:
      year: numeric
      month: long
      day: numeric
messages/auth/signin.yml
description: Sign in button label
translations:
  en: Sign in

This base locale becomes the source of truth for all regional variants unless they need a different string or format.

Add regional locales

Regional locales can inherit both translations and formats:

locales/en-US.yml
description: English (United States)
direction: ltr
inheritTranslationsFrom: en
inheritFormatsFrom: en
mergeExamplesFrom: en

Override only the parts that differ:

locales/en-GB.yml
description: English (United Kingdom)
direction: ltr
inheritTranslationsFrom: en
inheritFormatsFrom: en
formats:
  number:
    money:
      style: currency
      currency: GBP
      currencyDisplay: symbol
messages/account/billingAddress.yml
translations:
  en: Billing address
  en-GB: Billing address
  en-US: Billing address

When a regional translation matches the inherited value, it is redundant and can be pruned later.

Translation resolution

Given this chain:

Inheritance chain
en-GB -> en

Messagevisor resolves each message for en-GB in this order:

  1. direct en-GB translation
  2. inherited en translation
  3. if still missing, that message key is omitted from the datafile for this locale; at runtime the SDK applies missing-key behavior if the app requests it

Override translations follow the same rule. If an override has en copy and the en-GB locale inherits from en, the override is available in the en-GB datafile unless en-GB overrides it directly.

Format resolution

Runtime format resolution is a deep merge:

  1. SDK constructor defaultFormats for the active locale, as runtime defaults
  2. inherited parent formats
  3. child locale formats
  4. target-level format overrides for that locale
  5. SDK per-call format overrides

Deep merge means en-GB can replace only formats.number.money.currency while keeping the rest of the parent format preset families.

Build impact

Inheritance is resolved when building datafiles:

Command
$ npx messagevisor build --target=web --locale=en-GB

The resulting datafile contains the resolved translation and format behavior needed by the SDK. The application does not need to know which locale authored the original value.

Testing inheritance

Use locale tests for resolved formats:

tests/locales/en-GB.spec.yml
locale: en-GB
assertions:
  - description: Inherits date format and overrides money currency
    expectedFormats:
      number:
        money:
          currency: GBP
      date:
        long:
          month: long

Use message tests for inherited translations:

tests/messages/auth/signin.spec.yml
message: auth.signin
assertions:
  - description: en-GB inherits base English copy
    locale: en-GB
    target: web
    expectedTranslation: Sign in

Exporting inherited work

CSV export records whether each locale cell is direct, inherited, or missing when status columns are enabled:

Command
$ npx messagevisor export --locale=en-GB --target=web

Useful filters:

Command
$ npx messagevisor export --locale=en-GB --onlyUntranslated
$ npx messagevisor export --locale=en-GB --onlyDirectlyUntranslated

Use --onlyUntranslated when inherited values count as translated. Use --onlyDirectlyUntranslated when a translator should provide direct regional copy even if a parent locale currently fills the gap.

Importing regional translations

After a translator returns a CSV, preview the import:

Command
$ npx messagevisor import exports/en-GB.csv

Then apply it:

Command
$ npx messagevisor import exports/en-GB.csv --apply

Applied imports update only changed direct translations. If a CSV value matches the inherited result and there is no direct value, Messagevisor can skip it instead of creating redundant regional copy.

Pruning redundant translations

Over time, regional locale files can accumulate direct translations that match inherited parent values. Preview redundant translations:

Command
$ npx messagevisor prune --translations --locale=en-GB

Apply the cleanup:

Command
$ npx messagevisor prune --translations --locale=en-GB --apply

You can narrow pruning by target or message patterns:

Command
$ npx messagevisor prune --translations --target=web --includeMessages="checkout*"

Pruning redundant formats

Format pruning removes child locale format entries that duplicate inherited effective formats:

Command
$ npx messagevisor prune --formats --locale=en-GB
$ npx messagevisor prune --formats --locale=en-GB --apply

This keeps locale files readable. The child locale should only show what truly differs from the parent.

Finding duplicate translation values

Use find-duplicates when you want to audit repeated resolved copy across message keys:

Command
$ npx messagevisor find-duplicates
$ npx messagevisor find-duplicates --locale=en-GB

The command applies inheritTranslationsFrom before comparing values, so duplicates introduced through fallback chains are visible. It ignores overrides, archived messages, and empty values. The catalog exposes the same data in each locale's Duplicates tab.

Sets-aware inheritance

In sets-based projects, each set has its own locale files and inheritance chains. Use --set to inspect or clean one environment:

Command
$ npx messagevisor test --set=staging --keyPattern=en-GB
$ npx messagevisor prune --translations --set=staging --locale=en-GB

Promotion copies authored definitions between sets. It does not magically merge inheritance chains across sets, so validate the destination after promotion.

Review in the catalog

The catalog helps reviewers see whether a regional locale relies on inherited copy or direct copy. Pair catalog review with examples so product and localization reviewers can inspect resolved output without reading every locale file. The same authored examples can also be inspected in the terminal with npx messagevisor examples.