Messagevisor

Multi-brand or multi-product translations in one repository

Organizations that operate multiple brands or products face a translation management problem that sits between two extremes. Maintaining completely separate repositories per brand means duplicating infrastructure, CI pipelines, and shared content like common UI strings. Merging everything into one flat namespace means brand-specific copy is mixed with shared copy in ways that make ownership and review difficult.

Messagevisor's namespace structure and target system give you a middle path: one repository, shared infrastructure, isolated namespaces per brand, and purpose-built datafiles that each brand's applications can consume without seeing other brands' content.

Structuring namespaces by brand

Messagevisor message keys are derived from file paths. A well-chosen directory structure creates natural brand isolation:

Directory structure
messages/
├── common/           # Shared across all brands
│   ├── nav/
│   ├── errors/
│   └── forms/
├── brand-alpha/      # Exclusive to Brand Alpha
│   ├── landing/
│   ├── onboarding/
│   └── checkout/
├── brand-beta/       # Exclusive to Brand Beta
│   ├── landing/
│   ├── dashboard/
│   └── billing/
└── internal/         # Internal tooling, never shipped to end users
    └── admin/

Message keys then look like:

  • common.nav.home - shared across brands
  • brand-alpha.landing.headline - exclusive to Brand Alpha
  • brand-beta.billing.invoiceTitle - exclusive to Brand Beta

This structure makes CODEOWNERS governance straightforward:

.github/CODEOWNERS
messages/brand-alpha/   @brand-alpha-team
messages/brand-beta/    @brand-beta-team
messages/common/        @platform-team

Per-brand targets

Each brand gets its own target that includes only the messages it needs:

targets/brand-alpha-web.yml
description: Brand Alpha web application
includeMessages:
  - common*
  - brand-alpha*
excludeMessages:
  - internal*
locales:
  - en
  - en-US
  - nl-NL
  - de-DE
context:
  platform: web
  brand: brand-alpha
targets/brand-beta-web.yml
description: Brand Beta web application
includeMessages:
  - common*
  - brand-beta*
excludeMessages:
  - internal*
locales:
  - en
  - en-US
  - fr-FR
context:
  platform: web
  brand: brand-beta
targets/brand-beta-mobile.yml
description: Brand Beta mobile application
includeMessages:
  - common*
  - brand-beta*
  - brand-beta.notifications*
excludeMessages:
  - internal*
locales:
  - en
  - en-US
  - fr-FR
context:
  platform: mobile
  brand: brand-beta

The includeMessages filter ensures that Brand Alpha's datafile never contains Brand Beta's messages, and vice versa. Each brand's application loads only its own artifact.

Shared messages with brand-specific overrides

Some messages share a common base but need brand-specific variants. Rather than duplicating the message under each brand's namespace, keep the shared base and use overrides to customize per brand:

messages/common/nav/home.yml
description: Home navigation label used across all brands
translations:
  en: Home
  nl: Home
  de: Startseite
  fr: Accueil
overrides:
  - key: brand-alpha
    conditions:
      attribute: brand
      operator: equals
      value: brand-alpha
    translations:
      en: Dashboard
  - key: brand-beta
    conditions:
      attribute: brand
      operator: equals
      value: brand-beta
    translations:
      en: Overview
      fr: Vue d'ensemble

When the brand-alpha-web target is built with context: { brand: brand-alpha }, the builder evaluates the overrides against the known context. The brand-beta override is an impossible branch for this target and is stripped from the datafile. Brand Alpha's web artifact contains only "Dashboard" for the home label.

Brand-exclusive messages

For messages that exist only for one brand and have no shared base, author them entirely under the brand's namespace:

messages/brand-alpha/landing/headline.yml
description: Brand Alpha landing page main headline
meta:
  owner: brand-alpha-team
  surface: landing-page
translations:
  en: The platform built for your team
  nl: Het platform dat is gebouwd voor jouw team
  de: Die Plattform für Ihr Team
messages/brand-beta/landing/headline.yml
description: Brand Beta landing page main headline
meta:
  owner: brand-beta-team
  surface: landing-page
translations:
  en: Collaborate faster with Brand Beta
  fr: Collaborez plus vite avec Brand Beta

No overlap, no risk of one brand's headline appearing in the other brand's application.

Locale configurations per brand

Brands serving different markets may need different locale configurations. You can define brand-specific format presets by creating locale files that reflect each brand's market:

locales/en-US.yml
description: English (United States)
direction: ltr
inheritTranslationsFrom: en
inheritFormatsFrom: en
formats:
  number:
    money:
      style: currency
      currency: USD

Brand Beta operates in Europe, so its French locale needs EUR formatting:

locales/fr-FR.yml
description: French (France)
direction: ltr
formats:
  number:
    money:
      style: currency
      currency: EUR
      currencyDisplay: symbol
  date:
    long:
      year: numeric
      month: long
      day: numeric

Each brand's target specifies which locales to include. Brand Alpha targets en-US, nl-NL, and de-DE. Brand Beta targets en-US and fr-FR. The locale files are shared infrastructure - each brand's target cherry-picks the locales it needs.

Build output per brand

Build produces one file per target and locale combination:

Command
$ npx messagevisor build --showSize
Directory structure
datafiles/
├── messagevisor-brand-alpha-web-en-US.json
├── messagevisor-brand-alpha-web-nl-NL.json
├── messagevisor-brand-alpha-web-de-DE.json
├── messagevisor-brand-beta-web-en-US.json
├── messagevisor-brand-beta-web-fr-FR.json
├── messagevisor-brand-beta-mobile-en-US.json
└── messagevisor-brand-beta-mobile-fr-FR.json

Each brand's application loads only its own datafiles. The Brand Alpha web app loads messagevisor-brand-alpha-web-en-US.json. The Brand Beta mobile app loads messagevisor-brand-beta-mobile-fr-FR.json. They never overlap.

Testing brand isolation

Write target tests to assert that brand isolation is working correctly - that Brand Alpha's datafile never contains Brand Beta's messages:

tests/targets/brand-alpha-web.spec.yml
target: brand-alpha-web
assertions:
  - description: Common nav messages are included
    expectedToIncludeMessages:
      - common.nav.home
      - common.errors.notFound
  - description: Brand Alpha landing messages are included
    expectedToIncludeMessages:
      - brand-alpha.landing.headline
  - description: Brand Beta messages are excluded
    expectedToNotIncludeMessages:
      - brand-beta.landing.headline
      - brand-beta.billing.invoiceTitle
  - description: Internal messages are excluded
    expectedToNotIncludeMessages:
      - internal.admin.dashboard
tests/targets/brand-beta-web.spec.yml
target: brand-beta-web
assertions:
  - description: Brand Beta overview copy resolves in French
    locale: fr-FR
    message: common.nav.home
    expectedTranslation: Vue d'ensemble
  - description: Brand Alpha exclusive messages are excluded
    expectedToNotIncludeMessages:
      - brand-alpha.landing.headline
      - brand-alpha.onboarding.step1

Shared CI, per-brand publish

A single CI workflow can build all brand targets and publish each to the right location:

.github/workflows/messagevisor.yml
name: Messagevisor
on:
  pull_request:
  push:
    branches: [main]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx messagevisor lint
      - run: npx messagevisor test
  build-and-publish:
    runs-on: ubuntu-latest
    needs: validate
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx messagevisor build
      - name: Publish Brand Alpha datafiles
        run: |
          aws s3 sync datafiles/ s3://brand-alpha-cdn/messagevisor/ \
            --include "messagevisor-brand-alpha-*"
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      - name: Publish Brand Beta datafiles
        run: |
          aws s3 sync datafiles/ s3://brand-beta-cdn/messagevisor/ \
            --include "messagevisor-brand-beta-*"
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}