Onboarding non-engineers to the translation workflow

When translation repositories are maintained only by engineers, the people closest to the product voice and the target language are kept out of the workflow.

Product managers who want to improve onboarding copy file issues, wait for engineering capacity, and review pull requests they did not write. The result is copy that is technically correct but often phrased by someone whose last product writing was a ticket comment.

Translators who work in the same language every day can spot a mistranslation in the catalog but have no direct path to fix it.

Messagevisor's file format and tooling are designed to make non-engineer contributions as low-friction as possible, while keeping the review and validation gates that protect production quality.

What makes definitions approachable for translation edits#

The most common contribution a non-engineer makes to a translation repository is changing the value of a translation string. In Messagevisor, that looks like this:

description: Sign in button label
translations:
  en: Sign in
  nl: Aanmelden
  de: Anmelden

The file is human-readable. The translations map is a straightforward key-value structure. Changing "Sign in" to "Log in" requires editing one value. The surrounding structure like description, translations, and the indentation stays intact. A product manager who has edited a YAML file once can do this confidently.

The description field is especially important for non-engineers: it explains what the message is for and where it appears, without requiring the contributor to search the application codebase.

What non-engineers should know about the workflow#

The workflow for a non-engineer contributor is the same as for an engineer:

1. Open the Messagevisor repository in GitHub (or GitLab, or Bitbucket).
2. Find the message file to edit. The catalog can help locate the right key.
3. Make the change.
4. Submit the change as a pull request with a description of why the copy changed.
5. CI runs lint and tests automatically.
6. The relevant reviewer approves (via CODEOWNERS).
7. The pull request is merged and CI publishes the updated datafiles.

Steps 1–5 require no local tooling, no Git client, no development environment. GitHub's web editor handles it.

The catalog as a non-engineer interface#

The catalog provides a browsable, read-only view of the full translation project. It is the entry point for non-engineers who want to understand what copy exists without editing files.

$ npx messagevisor catalog

Or serve a pre-exported catalog:

$ npx messagevisor catalog export
$ npx messagevisor catalog serve

What non-engineers can do in the catalog:

• Browse messages by namespace to find the right key
• Read the description field to understand what a message is for and where it appears
• View all translations for a message across every locale in one row
• See overrides and conditions expanded in plain language
• View examples with evaluated output for specific locales and contexts
• Use deep links to share a specific message with a colleague ("here's the copy that needs to change")

The catalog does not require repository access to view. It can be published as a static site accessible to the whole team.

Writing descriptions that help non-engineers#

The quality of non-engineer contributions depends on the quality of description fields. Engineers authoring new messages should write descriptions that answer the questions a non-engineer would have:

description: "Banner shown at the top of the billing page for users on the free plan. Appears below the page header. Should be 60 characters or fewer to avoid wrapping on mobile."
summary: Billing upgrade prompt banner
translations:
  en: Upgrade to unlock unlimited projects
  nl: Upgrade voor onbeperkte projecten

The description field is for humans. It is shown in the catalog and in the CSV export. A description that includes placement context, character limits, and target audience helps a translator or product manager make a better decision.

Using summary for compact views#

The summary field (optional) is a shorter one-line description that appears in CSV exports and in catalog views where the full description would take too much space. Use it for the elevator pitch of what the message is:

description: "First step of the onboarding checklist. Shown after account creation. The copy should be encouraging and action-oriented."
summary: Onboarding step 1 - first action prompt
translations:
  en: Connect your first integration
  nl: Verbind je eerste integratie

Providing examples for non-engineer review#

Examples show non-engineers exactly what a message will look like when rendered, including interpolated values and formatted numbers. They appear in the generated Catalog, and engineers can inspect the same output on demand with npx messagevisor examples.

description: Total amount shown in the billing summary
translations:
  en-US: "Total: {amount, number, money}"
  nl-NL: "Totaal: {amount, number, money}"
examples:
  - description: Standard total in USD
    locale: en-US
    values:
      amount: 49.99
  - description: Standard total in Dutch
    locale: nl-NL
    values:
      amount: 49.99

A translator reviewing {amount, number, money} in the raw translation string may not know what that produces. The example shows them Total: $49.99 without ambiguity.

Making CI feedback readable to non-engineers#

When a non-engineer submits a pull request and CI fails, the error message is their only feedback. Messagevisor's lint output is designed to be human-readable:

ERROR  messages/onboarding/step1.yml
  Missing translation for locale 'de' - add a 'de' key under translations

Point non-engineers at the lint output in the CI check logs. For teams where this is a frequent onboarding friction point, add a short guide to the repository README that explains what the common lint errors mean and how to fix them.

CSV export for translators#

Translators working in bulk may prefer a spreadsheet workflow over editing YAML files one at a time. Messagevisor supports CSV export:

$ npx messagevisor export --output=translations.csv

The CSV contains one row per message (and per override, with the messageKey:overrideKey format) and one column per locale. Translators can fill in missing values and return the file. An engineer then applies the translations back to the YAML files.

This round-trip workflow lets translators use familiar tools while keeping YAML files as the authoritative source.

Setting up a CODEOWNERS file for team collaboration#

For teams where product managers or translators should be notified about specific content areas, add them to CODEOWNERS:

# Marketing team is notified for all marketing copy changes
messages/landing/        @marketing-team
# Product team reviews onboarding copy
messages/onboarding/     @product-team
# Translation lead reviews all new locale translations
locales/                 @i18n-lead

This means non-engineers are in the review loop when their content area changes - without them having to monitor the repository manually.

Adding non-engineers as reviewers without blocking engineers#

CODEOWNERS can be used to notify without blocking. If a team uses GitHub's "allow merge without required review from code owner" option, then non-engineers are notified about changes in their area and can choose to review, but the PR is not blocked waiting for them. This is useful when you want visibility without creating a bottleneck.

For content areas where the non-engineer's approval is genuinely required like legal copy or compliance text, keep the stricter setup with branch protection enforcing CODEOWNERS review.

A practical onboarding checklist#

When onboarding a non-engineer contributor:

1. Give them catalog access: Deploy or share the catalog URL so they can browse messages without needing repository access.

2. Show them how to edit in the GitHub web UI: Most translation changes are simple value edits. The GitHub web editor is sufficient for this.

3. Explain the description field: Show them a well-described message as a model. Explain that description is what the catalog shows and that it helps translators do their job.

4. Walk through the CI check: Show them where to find lint output when CI fails. Explain the most common errors: missing locale translations and syntax issues.

5. Introduce examples: Show them how examples help them verify that interpolated content looks right before approving a change. Engineers can inspect the same examples with npx messagevisor examples, while non-engineers can browse them in the generated Catalog.

6. Set expectations for review: Explain that CODEOWNERS means certain changes will automatically request review from the right people, and that merging requires approval.

Related#

• Catalog
• Export and import
• Messages
• Testing
• Establishing ownership
• GitOps
• Translations as code