JSON is the most common format for app text, and also one of the easiest to break. A single missing quote can stop an application from loading. Translators need a safe way to work on the words while the structure stays untouched, and that is where a dedicated tool earns its place.
Why JSON files need special care
A JSON file stores text as keys and values, often nested several levels deep. The keys are read by code, so they must never change. Only the values are meant for translation.
Opening such a file in a text editor invites mistakes. A stray comma, a deleted bracket or a changed key can break an entire screen, and the error may only appear after release.
How a CAT tool protects the structure
A cat translation tool reads the file, extracts only the values and shows them as segments. Keys and syntax stay hidden or locked, so the translator cannot damage them by accident.
When the work is done, the tool rebuilds the file with the translated values in the original positions. The result is valid JSON that the developer can drop straight into the project.
Keys as context
Key names often describe where text appears, such as checkout.button.pay. Good tools display the key beside the segment, which gives translators a useful hint about meaning and length.
Developers can help by choosing descriptive keys. A name like button_1 says nothing, while profile.save_changes tells the translator exactly what the text does.
Placeholders and variables
App text contains variables such as {count} or %s. They must appear in the translation exactly as written, though their position in the sentence may change with grammar.
CAT tools protect these tokens and warn when one goes missing. That single feature prevents many of the bugs that appear in translated apps.
Plural forms
English has two plural forms, but other languages have more. Russian has three or four, and Arabic has six. A file that supports only one and many leaves translators stuck.
Use a plural format the tool understands, such as ICU message syntax. Translators then supply every form their language needs, and the app picks the right one automatically.
Step by step instructions
If you want a detailed walkthrough, our guide on how to translate a JSON file covers each stage with examples. It shows how to prepare the file, import it and check the result.
Read it alongside your first real project. Seeing the steps applied to your own strings makes the process much easier to remember.
Handling nested objects
Large files contain groups of keys under headings such as menu, errors or settings. A good tool keeps the grouping visible, so translators can work through one area at a time.
This also helps with consistency. Related strings sit together, and the translator can see how similar messages were phrased a few lines earlier.
Length and layout limits
Translated text is often longer than English. A button that fits "Save" may not fit its German equivalent. Developers should share character limits or allow flexible layouts.
The tool can flag strings that exceed the limit, and screenshots help translators choose shorter wording when space is tight.
Following community guidelines
Open projects publish useful guidance for localizers. The Mozilla localization guidelines are a good example, with clear advice on tone, terminology and placeholders that applies well beyond one product.
Borrowing good practice from established projects saves you from inventing rules and gives translators a familiar reference.
Quality checks before export
Run validation before you export. Checks catch missing placeholders, empty values, mismatched tags and inconsistent terms. Many teams also check that the resulting file parses correctly.
Add a quick review of the most visible screens. A native speaker checking the login, home and payment texts finds most of the serious problems in minutes.
Keeping files in sync with development
Source files change with every release. The tool should detect new, edited and deleted keys, and send only the changes to translators.
This avoids retranslating everything and keeps costs low. It also prevents the old problem of translations falling behind the latest version of the app.
Working with a team
Developers, translators and reviewers all touch the same files. Shared memories and glossaries keep their work consistent, and roles make sure each person sees only what they need.
Clear ownership helps. Decide who approves a string, who updates the source and who is responsible for each language.
Common mistakes to avoid
Teams sometimes send raw files to translators by email, or let people edit the JSON by hand. Both habits invite broken syntax and lost changes.
Another frequent error is changing key names after translation has started. Agree on keys early, because renaming them later means matching strings again by hand.
Testing the translated build
Load the app in each language and click through the main flows. Look for truncated text, missing strings and variables that show as raw code.
Fixing these issues early costs very little, while discovering them after release means emergency patches and unhappy users.
A simple first project
Pick one small file with a few dozen strings. Import it, translate it, run the checks and test the result in the app. Note any problems with formatting or context.
After one successful cycle, extend the process to the rest of the application. The earlier lessons make every later file faster to handle.