Environment-specific translations

Development, staging, and production do not have to share the same translation content all the time.

• Dev needs placeholders that expose untranslated keys.
• Staging needs realistic copy for QA and stakeholder review.
• Production must reflect what was approved for release.

Keeping those versions in separate repositories, or switching between them with runtime flags in application code, creates drift and guesswork about what is live where.

Messagevisor addresses this with sets: independent authoring trees in a single repository, linked by a promotion workflow that moves content from one environment to the next.

What sets give you#

When sets are enabled, your repository contains multiple complete definition trees:

sets/
├── dev/
│   ├── locales/
│   ├── messages/
│   ├── segments/
│   ├── targets/
│   └── tests/
├── staging/
│   ├── locales/
│   ├── messages/
│   ├── segments/
│   ├── targets/
│   └── tests/
└── production/
    ├── locales/
    ├── messages/
    ├── segments/
    ├── targets/
    └── tests/

Each set is completely independent. A message in sets/dev/ does not automatically appear in sets/production/. Content flows between sets through explicit promotion commands, not silent inheritance.

Enabling sets#

module.exports = {
  sets: true,
  promotionFlows: [
    { from: "dev", to: "staging" },
    { from: "staging", to: "production" },
  ],
};

The promotionFlows constraint enforces your intended direction. Attempting promote --from=production --to=dev will fail clearly rather than silently doing something unexpected.

Authoring environment-specific content#

Some messages have genuinely different content per environment. A banner that reads "You are viewing a staging environment" should only exist in the staging set. A skeleton placeholder like "[TODO: nav.home]" in dev should never reach production.

description: Home navigation label
translations:
  en: "[TODO: nav.home]"
  nl: "[TODO: nav.home nl]"

description: Home navigation label
translations:
  en: Home
  nl: Home

description: Home navigation label
translations:
  en: Home
  nl: Home

For messages that should stay environment-specific and not be overwritten when content is promoted from dev, set promotable: false:

description: Banner shown on non-production environments
promotable: false
translations:
  en: You are viewing the staging environment. Content here is not final.

With promotable: false, running promote --from=staging --to=production will not touch this message in the production set.

Environment-specific segments#

Segments can also be environment-specific. A segment that matches internal users by email domain might be appropriate in staging for QA review but inappropriate in production where it could expose unreleased content to people it should not:

description: Internal QA users
promotable: false
conditions:
  attribute: email
  operator: endsWith
  value: "@yourcompany.com"

Setting promotable: false on the segment keeps it from leaking into production when you run a promotion.

Promoting content between environments#

Once content in dev has been reviewed and is ready for staging:

$ npx messagevisor promote --from=dev --to=staging

Review the preview output first. Then apply the promotion:

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

After promotion, validate the destination set:

$ npx messagevisor lint --set=staging
$ npx messagevisor test --set=staging
$ npx messagevisor build --set=staging

This sequence ensures that promoted content is valid and tests pass before the staging datafiles are published.

Building environment-specific datafiles#

Each set produces its own datafiles:

$ npx messagevisor build

This writes:

datafiles/
├── dev/
│   └── messagevisor-web-en-US.json
├── staging/
│   └── messagevisor-web-en-US.json
└── production/
    └── messagevisor-web-en-US.json

Build output from sets/production/ is completely separate from output from sets/staging/. Applications running against staging point at staging datafiles; production applications point at production datafiles.

CI workflows per environment#

Learn more in GitHub Actions.

Testing a specific environment#

When debugging a promotion or investigating a difference between environments, you can scope your test run to a specific set:

$ npx messagevisor test --set=staging
$ npx messagevisor test --set=production --keyPattern=checkout

This is faster than testing all sets and gives you targeted confidence before a deploy.

Checking divergence between environments#

To understand what content differs between staging and production before a promotion:

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

The --showUnchanged flag includes messages that would not be affected, giving you the full picture of what is and is not in sync.

Audit trail for promotions#

When you want a durable record of what moved between environments - useful for compliance reviews or change approval workflows - use the --audit flag:

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

The generated audit file lists every message and override that was added, updated, or unchanged in the destination set. Commit it to your repository or attach it to your change management ticket.

Related#

• Sets
• Promotions
• Messages
• Segments
• Building datafiles
• GitHub Actions
• GitOps