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:

Field	Purpose
`inheritTranslationsFrom`	Reuse message and override translations from another locale
`inheritFormatsFrom`	Deep-merge format presets from another locale
`mergeExamplesFrom`	Include 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:

direct en-GB translation
inherited en translation
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 layered by format type and style name:

SDK constructor defaultFormats for the active locale, as runtime defaults
inherited parent formats
child locale formats
target-level format overrides for that locale
SDK per-call format overrides

If a child locale declares formats.number.money, that whole money style object replaces the inherited money style. Sibling styles such as formats.number.decimal or formats.date.long still inherit when the child does not declare them.

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. When the catalog is generated with --with-duplicates, it 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.

What can be inherited#

Author the base locale#

Add regional locales#

Translation resolution#

Format resolution#

Build impact#

Testing inheritance#

Exporting inherited work#

Importing regional translations#

Pruning redundant translations#

Pruning redundant formats#

Finding duplicate translation values#

Sets-aware inheritance#

Review in the catalog#

Related#