GitOps

Messagevisor applies GitOps principles to translation management: all definitions live in a Git repository, all changes go through pull requests, and CI handles the build and publish pipeline automatically.

What is GitOps?#

GitOps is the practice of using Git as the single source of truth for your system's desired state. Instead of applying changes directly, clicking buttons in a dashboard, running manual scripts, or editing a database, you change files in a repository and let automation take it from there.

Every change is:

visible: tracked in commit history
reviewable: submitted as a pull request
reversible: rolled back by reverting a commit
auditable: attributed to a person and a timestamp

Software teams already use Git this way for code. Messagevisor extends the same discipline to translation content and runtime message configuration.

Why apply GitOps to translations?#

Translation management is usually handled outside of Git: in spreadsheets, translation management platforms, or internal dashboards. This introduces a set of familiar problems:

Changes are applied directly to production without review
There is no history of when a translation changed or who changed it
Rolling back a bad translation requires manual intervention
Testing a translation change before shipping it is difficult or impossible
The current live state of translations is unclear to engineers

GitOps solves all of these by making the repository the authoritative record.

How Messagevisor uses GitOps#

Translations are files#

Every message, locale, segment, attribute, and target in Messagevisor is a YAML file (or JSON or TOML if that's your preference via custom parsers).

The complete state of your translation system is expressed as a directory tree you can read, search, and diff.

messages/
├── auth/
│   ├── signin.yml
│   └── signout.yml
└── billing/
    └── total.yml
locales/
├── en.yml
└── nl.yml

Changes go through pull requests#

When a developer wants to add a message, change a translation, or add an override, they open a pull request. The pull request diff is the change record.

Reviewers can:

inspect exactly which strings changed
validate the logic of new overrides and segments
run the lint and test suite in CI before approving
request changes before anything reaches production

This makes translation changes as rigorous as code changes.

CI builds and publishes#

When a pull request is merged, CI runs npx messagevisor build and publishes the generated datafiles to a CDN or object storage. The moment the files land, every SDK instance that polls for updates picks up the new content.

.github/workflows/deploy.yml

- run: npx messagevisor build
- run: aws s3 sync datafiles/ s3://my-cdn-bucket/messagevisor/

See Deployment and GitHub Actions.

History is the audit log#

Because every change is a commit, git log and git blame answer questions that would otherwise require a database query or a ticket:

When was this translation added?
Who changed this override condition last week?
What was the English text for billing.total three months ago?

The catalog surfaces this history in a browsable UI without requiring direct Git access.

Review and collaboration#

GitOps makes translation changes visible to engineers and reviewers. For non-technical collaborators, think translators, product managers, content editors, etc., the catalog provides a read-only view of the full project without any need for Git access.

For teams that want non-engineers to contribute to translations, the pull request workflow still works: YAML is readable, and most translation changes are localized edits to string values that do not require deep knowledge of the surrounding schema.

Rollback is always available#

Because every state of the project has a corresponding commit, rolling back a bad translation is the same operation as rolling back a bad code change:

Command

$ git revert <commit>

After the revert is merged and CI runs, the previous translation is live again. No manual database edits, no emergency dashboard access, no support ticket.

GitOps and sets#

For projects that maintain multiple environments, like staging and production for example, Messagevisor's sets model each environment as a separate authoring tree inside the same repository.

The promote command moves changes between sets through the normal pull request flow.

See Sets and Environments.

Summary#

Practice	How Messagevisor applies it
Single source of truth	YAML files in the repository
All changes via Git	Pull requests for every translation change
Automated delivery	CI builds and publishes datafiles on merge
Audit trail	Git history and catalog change log
Rollback	`git revert` restores any prior state
Non-engineer access	Catalog provides a read-only view