building a workflow for translators and engineers

Here’s a practical way to think about a translator + engineer workflow: make it easy for translators to work in a content-friendly environment, and easy for engineers to ship changes without breaking language data.

A solid workflow structure

1) Source content lives in one place

• Product/UI text, docs, or marketing copy should come from a single source of truth
• Store it in a format that engineers can manage cleanly:
  • JSON, YAML, PO files, XLIFF, CSV, or a localization platform
• Avoid hardcoding strings in the app

2) Use clear string keys

• Example:
  • nav.home
  • checkout.button.pay_now
• Keys should be stable and descriptive
• Don’t use the English text as the key unless you really want translation churn

3) Separate responsibilities

Engineers

• Extract strings
• Add/update keys
• Handle pluralization, interpolation, and fallback logic
• Ensure locale files are validated in CI

Translators

• Translate in a platform or file format designed for translation
• See context: screenshots, comments, character limits, notes
• Avoid direct code editing if possible

4) Add context for translators

This is one of the biggest workflow improvements. Include:

• Screenshot or UI location
• Short description of where the string appears
• Tone guidance
• Gender/plural rules
• Character limits
• Placeholder meaning, e.g. {count}, {username}

5) Review and QA

• Translation review by a second translator or locale lead
• Automated checks:
  • missing keys
  • unused keys
  • placeholder mismatch
  • invalid ICU/plural syntax
• In-app QA on a staging environment

6) Sync with release process

A typical cycle:

1. Engineers add new source strings
2. Strings are pushed to a localization system
3. Translators translate
4. Review happens
5. Engineers pull translations back into the app
6. QA validates in staging
7. Release

---

Recommended tooling setup

Good options

• Localization platforms: Lokalise, Crowdin, Phrase, Transifex
• Open-source / file-based: POEditor, Weblate
• Developer-friendly libraries:
  • JavaScript/TypeScript: i18next, FormatJS, react-intl
  • iOS/macOS: NSLocalizedString, String Catalogs
  • Android: strings.xml
  • Backend: ICU MessageFormat support

Best practice

Use a platform if:

• many languages
• multiple translators
• frequent releases
• need screenshots, comments, and workflow states

Use file-based only if:

• small team
• low translation volume
• simple app

---

A simple end-to-end workflow example

1. Engineer adds a new string:
   • profile.save_button = "Save changes"
2. System exports it to localization tool
3. Translator sees:
   • context: “button on profile settings page”
   • screenshot
   • character limit: 16
4. Translator enters localized text
5. Reviewer approves
6. CI checks for:
   • all locales present
   • no missing placeholders
7. App ships with updated translations

---

Common pitfalls to avoid

• Translators editing code directly
• No context for ambiguous strings
• Reusing the same English string key for multiple meanings
• Hardcoded concatenation like "Hello " + name
• Missing support for plural forms and gender
• No validation in CI
• No clear ownership over translation updates

---

If you want a robust workflow, include these rules

• Every string needs a stable key
• Every string needs context
• Every translation passes automated checks
• Engineers own implementation
• Translators own localization quality
• Final approval happens in staging

If you want, I can also give you:

1. a sample translation workflow diagram,
2. a GitHub-based workflow, or
3. a tool stack recommendation for web/mobile/product docs.