Translations as code

Messagevisor treats translation definitions as code: structured, versioned, testable, and deployed through the same pipeline as the rest of your software.

The conventional approach#

Traditional translation workflows look something like this:

Engineers extract string keys from source code
Translators fill in values in a spreadsheet or a translation management platform
Someone exports a JSON or YAML file
The file is dropped into the repository or uploaded to a CDN manually
Repeat for every language and every release

This approach works at small scale, but it produces several problems as complexity grows:

Translation files have no schema. Any key can hold any string, and there is no machine-readable way to express what a translation is for, what runtime values it accepts, or under what conditions a different translation should appear.
There are no tests. Whether a translation resolves correctly for a given context, locale, and message format is verified manually, if at all.
History is shallow. The commit message says "update translations" but the diff is a wall of string changes with no author attribution, no change rationale, and no way to trace a specific change to a specific person or decision.
Behavioral logic lives in the application. If different users should see different text, engineers write conditional code in the application layer. Those conditions are invisible to translators, undocumented, and untested as a set.

What "translations as code" means#

Treating translations as code means applying software engineering discipline to the full translation system, not just the string values, but the targeting rules, locale inheritance, formatting behavior, and runtime context that shape what each user actually sees.

In Messagevisor, this means:

Definitions are structured#

Every message, locale, segment, and attribute is a typed YAML file with a documented schema. A message does not just hold a string, it holds a description, a translation map, optional overrides with explicit conditions, and metadata the SDK can read at runtime.

messages/billing/total.yml

description: Total amount in the billing summary
translations:
  en-US: "Total: {amount, number, money}"
  en-GB: "Total: {amount, number, money}"
  nl-NL: "Totaal: {amount, number, money}"
# optional overrides
overrides:
  - key: vat-included
    conditions:
      attribute: region
      operator: in
      value: [DE, AT, CH]
    translations:
      en-GB: "Total (incl. VAT): {amount, number, money}"

The behavioral logic "show VAT-inclusive text for these regions" lives in the definition, not scattered across the application.

Definitions are versioned#

Every change to every definition is tracked in Git.

You can answer questions like:

"what was the German translation for checkout.confirm six months ago?", or
"who added the plan-pro override to dashboard.welcome?"

without checking a database or asking a colleague.

Definitions are testable#

Messagevisor has a built-in test system. Tests express assertions about what a specific message should resolve to for a given locale, target, and context. They run in CI.

tests/messages/billing/total.spec.yml

message: billing.total
assertions:
  - locale: en-US
    target: web
    values:
      amount: 149.99
    expectedTranslation: "Total: $149.99"
- locale: en-GB
    target: web
    context:
      region: DE
    values:
      amount: 149.99
    expectedTranslation: "Total (incl. VAT): £149.99"

See Testing.

Behavioral logic is in definitions, not application code#

Segment conditions, override rules, and locale fallback chains are authored in YAML and evaluated by the SDK at runtime. Application code calls translate(key, values, { context }) and receives a string. It does not contain the logic for which string to return.

This means:

Targeting rules can be changed without application code deployment
Rules are readable and reviewable by non-engineers
The same logic applies consistently across every platform that uses the same datafile

Datafiles are build artifacts#

The build step compiles definitions into datafiles: self-contained JSON files optimized for the SDK.

Each datafile corresponds to one target and one locale. Datafiles can be served from a CDN with no backend, cached aggressively, and updated independently of application deployments.

This means translation changes can ship on their own timeline, without requiring an application release.

What this enables#

Translation changes without app deployments. Because datafiles are separate from the application bundle, updating a translation means merging a pull request, running CI, and publishing a new datafile. The running application picks it up at the next poll interval.

Testable runtime behavior. The test suite covers not just "does this key exist" but "does this key resolve correctly for this locale, this context, and these values." Bad translations and broken override logic are caught before production.

Audit trail for every change. Git history and the catalog change log give you an immutable record of who changed what and when - at the granularity of individual string values, not just file-level edits.

Review before shipping. New translations, modified overrides, and updated segments go through pull request review before they affect any user. The diff is readable to anyone who understands YAML, and CI validates it automatically.

Single source of truth across platforms. Mobile, web, backend, and embedded surfaces all read from the same generated datafiles. There is no risk of one platform showing different text than another because they share definitions.

The tradeoffs#

Translations as code is a good fit for teams that:

want to apply engineering discipline to their localization process
need to reason about runtime behavior (overrides, locale inheritance, format presets) as part of the translation definition
value code review and CI validation as part of their quality process
deploy through a CI/CD pipeline and can include a build step

It is a different model from a hosted translation management platform with a live editor, real-time preview, and role-based access control for non-technical translators. Those platforms have their own strengths. Messagevisor is designed for teams where engineers are primary authors or close collaborators in the translation workflow, and where the definition of correct behavior is worth expressing precisely.