JSON translation files are easy to start and surprisingly easy to fragment. Consistent keys, predictable locale files, and a clear export process help developers and content teams change interface copy without losing track of what ships.
Choose a key structure that reflects meaning
Organize keys around features and interface roles. Whether you store a nested object or flat dot notation, keep the naming system consistent across every locale.
- checkout.summary.title
- checkout.payment.error.card_declined
- account.profile.button.save
Keep locale catalogs structurally aligned
Every supported locale should describe the same set of product concepts. Automated checks can compare keys and reveal missing, extra, or mistyped entries before release.
Keep locale codes consistent with the format expected by your app, such as en, en-ZA, or pt-BR.
Separate source work from generated output
Treat your managed string inventory as the editable source and exported JSON as a delivery artifact. This reduces conflicting edits and makes review history easier to understand.
Validate values before delivery
Check that placeholders match the source, values are strings, JSON parses correctly, and approved translations exist for release-critical flows.
- Reject malformed JSON during import.
- Warn when placeholders are missing or renamed.
- Define a visible fallback for untranslated values.
Use exports or read-only delivery consistently
Some teams commit exported locale files with the application; others fetch catalogs through a read-only API. Pick one release path per application and document when catalogs update.