How to Translate i18n JSON Files Without Breaking Keys
A practical guide to translating i18n JSON files while preserving keys, placeholders, nested objects, and valid JSON syntax.
Step-by-step workflow
- 01Identify which JSON values are user-facing text and which keys must stay unchanged.
- 02Keep placeholders, variables, and ICU-style expressions visible during translation.
- 03Translate values in a structured editor instead of pasting the full JSON into a generic chat box.
- 04Validate that the output is still parseable JSON.
- 05Review translated strings in the product UI before shipping.
What to protect during translation
- Object keys, nested paths, and namespace names used by application code.
- Placeholders such as {name}, {{count}}, %s, and ICU expressions.
- Boolean, numeric, null, URL, and enum-like values that are not user-facing copy.
Pre-export checks
- Parse the translated file and confirm there are no JSON syntax errors.
- Compare key counts and nested paths against the source file.
- Search for changed placeholder names before handing the file to developers.
Common mistakes to avoid
- AvoidTranslating object keys such as checkout.button or errors.card_declined.
- AvoidChanging placeholder names or deleting braces inside translated strings.
- AvoidLosing nested object structure during copy-paste cleanup.
FAQ
Questions about this workflow
Should JSON keys be translated?
No. Keys are usually code-facing identifiers and should remain unchanged.
Can placeholders be translated?
Placeholder names should stay unchanged, while surrounding user-facing words can be translated.
How do I verify translated JSON?
Parse the file, inspect changed values, and test important screens in the app.