Deprecating and retiring message keys

Translation keys accumulate over time. A feature ships, its onboarding flow is replaced six months later, and the original messages remain. They are referenced nowhere in the application, but still authoring overhead and still appearing in every datafile build. At scale this creates real friction: build output is larger than it needs to be, the catalog is harder to navigate, and new engineers cannot tell which messages are still in use.

Messagevisor gives you two tools for handling this lifecycle: deprecated for signaling keys that should be removed from application code, and archived for removing them from runtime artifacts entirely.

The two-phase retirement workflow#

Deleting a message key immediately is risky if the application still references it in code. The SDK falls back gracefully on missing keys, but a sudden absence of a string in a UI is still a user-visible problem. A safer pattern is to use a grace period:

1. Mark the message deprecated: true with an explanatory deprecationWarning.
2. Let the SDK surface the deprecation warning in application logs so engineers can find all call sites.
3. Once all call sites are removed from the application code, mark the message archived: true.
4. Archived messages are excluded from build output and invisible to the runtime.

Marking a message as deprecated#

description: Original onboarding welcome heading, replaced by onboarding.intro
deprecated: true
deprecationWarning: Use onboarding.intro instead. This key will be removed after 2026-06-01.
translations:
  en: Welcome to the product
  nl: Welkom bij het product

The deprecated and deprecationWarning fields are included in the built datafile. The JavaScript SDK emits a deprecated_message warning diagnostic at runtime whenever the deprecated message is evaluated. Engineers running the application locally will see it in their console before any user is affected.

The message still resolves, and deprecation does not break anything. It is a signal, not a removal.

Handling the SDK diagnostic#

The SDK reports diagnostics that pass the configured logLevel.

By default, logLevel is "info", so diagnostics are written to the console with a [Messagevisor] prefix unless you provide onDiagnostic.

Use onDiagnostic when you want to route SDK diagnostics to your own observability pipeline:

import { createMessagevisor } from "@messagevisor/sdk";
const m = createMessagevisor({
  datafile,
  context: { platform: "web" },
  onDiagnostic: (diagnostic) => {
    if (diagnostic.code !== "deprecated_message") {
      return;
    }
    logger.warn("[Messagevisor]", diagnostic.deprecationWarning, diagnostic);
    datadogRum.addError(new Error(diagnostic.deprecationWarning || diagnostic.message));
  },
});

This gives you a way to identify and track deprecated message call sites in production without requiring engineers to manually audit all call sites.

The diagnostic includes messageKey, locale, and deprecationWarning. Set logLevel: "warn" when you only want warnings and errors in the console, or logLevel: "debug" in local development when you also want to inspect override matching decisions.

Archiving a message after all call sites are removed#

Once no part of the application references onboarding.welcome any more, remove it from runtime artifacts by archiving it:

description: Original onboarding welcome heading, replaced by onboarding.intro
archived: true
translations:
  en: Welcome to the product
  nl: Welkom bij het product

Archived messages are:

• excluded from build output
• excluded from CSV exports
• excluded from the catalog browsable message list
• excluded from lint checks that require translations to be present

The definition remains in the repository for Git history purposes. If you want to fully remove the key, delete the file and commit the deletion.

Summary of the lifecycle#

Related#

• Messages
• Testing
• Targets
• Sets
• Promotions
• JavaScript SDK
• Building datafiles