Managing regional language variants

Regional English is not a single locale. Wording shifts ("Sign up" vs "Register"), spelling shifts ("Authorize" vs "Authorise"), and presentation shifts with market: date order, currency symbols, tax labels, even how billing appears on screen. A full translation file per region duplicates thousands of identical strings and forces manual updates whenever shared copy changes.

Messagevisor's locale inheritance model lets regional locales override only what differs and inherit everything else from a base locale.

The inheritance model#

A locale can declare inheritTranslationsFrom and inheritFormatsFrom. At build time, Messagevisor walks the inheritance chain to resolve each message and format preset. You author the difference, not the duplicate.

The resolution order for translations is:

The regional locale's own authored translation for this message
If missing, follow the inheritTranslationsFrom chain
If nothing is found in the chain, that message key is omitted from the datafile for this locale

Format resolution starts with the inherited locale's formats, then layers the regional locale's own format declarations on top by style name. If the regional locale declares the same style, that style object replaces the inherited style in full; sibling styles continue to inherit.

Structuring a locale hierarchy#

locales/en.yml

description: English base
formats:
  number:
    decimal:
      maximumFractionDigits: 2
    money:
      style: currency
      currency: USD
      currencyDisplay: symbol
  date:
    long:
      year: numeric
      month: long
      day: numeric
  time:
    short:
      hour: numeric
      minute: 2-digit

locales/en-US.yml

description: English (United States)
inheritTranslationsFrom: en
inheritFormatsFrom: en

locales/en-GB.yml

description: English (United Kingdom)
inheritTranslationsFrom: en
inheritFormatsFrom: en
formats:
  number:
    money:
      style: currency
      currency: GBP
      currencyDisplay: symbol
  date:
    long:
      year: numeric
      month: long
      day: numeric

locales/en-AU.yml

description: English (Australia)
inheritTranslationsFrom: en
inheritFormatsFrom: en
formats:
  number:
    money:
      style: currency
      currency: AUD
      currencyDisplay: symbol

en-US, en-GB, and en-AU all inherit from en.

Only en-GB and en-AU need to override the money format because their currency differs. The rest of the formatting presets are inherited unchanged.

Authoring only the strings that differ#

For most messages, the en base translation is correct for all regional variants. You only need to author a regional translation when the text genuinely differs:

messages/auth/register.yml

description: Registration action label
translations:
  en: Sign up
  en-GB: Register
  nl: Registreren

At build time, a datafile for en-US will inherit the en translation ("Sign up"). A datafile for en-GB will use its own authored translation ("Register").

You do not need to repeat "Sign up" for en-US explicitly.

messages/billing/taxLabel.yml

description: Label for the tax line item on invoices
translations:
  en: Tax
  en-GB: VAT
  en-AU: GST

messages/common/colour.yml

description: Generic colour label used in product settings
translations:
  en: Color
  en-GB: Colour
  en-AU: Colour

Messages that are truly the same across all English variants require no regional entries at all. The base en translation is resolved for every inheriting locale.

Multi-level chains#

Inheritance chains can span more than one level. A locale that represents a market-specific variant of a regional variant can chain through both:

locales/en-NL.yml

description: English for Netherlands market
inheritTranslationsFrom: en-GB
inheritFormatsFrom: en-GB
formats:
  number:
    money:
      style: currency
      currency: EUR
      currencyDisplay: symbol

en-NL inherits translations from en-GB, which itself inherits from en.

Messagevisor walks the full chain until it finds a translation. The currency format is overridden to EUR since this locale is used in the Netherlands.

Merging examples across the chain#

Use mergeExamplesFrom when you want a regional locale to include the base locale's examples in the generated Catalog and CLI examples command output:

locales/en-GB.yml

description: English (United Kingdom)
inheritTranslationsFrom: en
inheritFormatsFrom: en
mergeExamplesFrom: en
formats:
  number:
    money:
      style: currency
      currency: GBP

This is useful when the base en locale has a thorough set of format examples covering number, date, and time presets, and you want those documented for en-GB without re-authoring them.

Target-level locale filtering#

Not every locale needs to be included in every datafile. Targets control which locales are emitted, so you can build a web datafile that includes only the locales your web app actually supports:

targets/web.yml

description: Web application datafile
includeMessages:
  - auth*
  - nav*
  - billing*
  - common*
locales:
  - en
  - en-US
  - en-GB
  - en-AU
  - nl-NL
context:
  platform: web

A separate mobile target might cover a different locale set, or the same one with different format presets for the platform.

Testing regional variants#

Test each regional locale's translations and format resolutions explicitly to catch cases where the inheritance chain is not working as expected:

tests/messages/billing/taxLabel.spec.yml

message: billing.taxLabel
assertions:
  - description: Generic English uses Tax
    locale: en
    target: web
    expectedTranslation: Tax
  - description: British English uses VAT
    locale: en-GB
    target: web
    expectedTranslation: VAT
  - description: Australian English uses GST
    locale: en-AU
    target: web
    expectedTranslation: GST
  - description: US English inherits from en
    locale: en-US
    target: web
    expectedTranslation: Tax

Test locale format inheritance separately using locale tests:

tests/locales/en-GB.spec.yml

locale: en-GB
assertions:
  - description: GBP money format is resolved
    expectedFormats:
      number:
        money:
          currency: GBP
          currencyDisplay: symbol
  - description: en-GB inherits date long format from en
    expectedFormats:
      date:
        long:
          year: numeric
          month: long

CLI evaluation for a specific locale#

Quickly verify what a message resolves to for a regional locale before committing a test:

Command

$ npx messagevisor evaluate --message=billing.taxLabel --locale=en-GB --target=web
$ npx messagevisor evaluate --message=billing.taxLabel --locale=en-AU --target=web