Guides · JSON
Translate JSON files without breaking them
A JSON language file is keys and values, and only the values need translating. Drop the file into a continuous project in the hub or sync it from your code, and every string comes back translated with the placeholders protected, the plurals handled branch by branch and the keys and nesting exactly as they were. When you translate JSON files again after a change, only the changed strings are translated again. Machine translation on models we host does the first pass, the checks run on every string, and a person decides what ships.
How to translate JSON files, in three steps
- Add the file. In a continuous project, the Integration tab has an upload card: drop the JSON and the hub shows each namespace and how many keys it holds before anything is sent (how a sync works). From code, the command-line tool reads a config that names the source file and the target pattern, and the SDK or the REST API sync the same way. Nested objects are flattened to dot-notation keys and rebuilt into the same shape on the way out.
- Translate in the CAT editor. Every value is a row with translation memory, termbase, machine translation and the live checks. ICU MessageFormat is understood: a placeholder like {name} is protected through translation, and a plural or select message is translated branch by branch so every form gets its own text.
- Pull the translations. The command-line tool writes one file per locale in the same shape as the source, the SDK fetches them at runtime, and
validate --cifails a build on a missing or empty key. A signed webhook tells your systems when translations are ready.
Keys stay keys. Values get translated. The file comes back in the same shape.
- file formats the command-line tool reads and writes: JSON, YAML, PO, iOS strings, xcstrings, Android XML, ARB, XLIFF
- 8
- keys renamed, reordered or lost: the structure is rebuilt as it came
- 0
- MessageFormat parsed: placeholders protected, plural and select branches translated separately
- ICU
- sync to re-run any time: the same file twice never creates a duplicate
- 1
Values, not keys
The structure is rebuilt exactly as it came
A key maps to one stable string in the project. Nested JSON is flattened to dot-notation keys for translation, so a value at menu.header.title is stored under that key and rebuilt into the same nested shape when your app fetches it or the command-line tool writes the locale file. Keys, order and nesting come back as they went in.
- Keys untouched
- Nesting rebuilt
- Multi-namespace files
- Flat files too
Placeholders and plurals
ICU MessageFormat, understood not guessed
A placeholder such as {name} or {count} is protected through machine translation and the review, and the placeholder and message-syntax checks flag any string where one went missing or changed. Plural and select messages are handled per branch, so one, few and other each get a translation of their own instead of a sentence stretched over all three.
- Placeholders protected
- Plural branches translated separately
- Select branches too
- Placeholder and syntax checks
Changed strings only
Re-sync after a change and only the change is translated
A new or changed source string marks its target languages as pending, and the pipeline translates those strings and no others, with your memories, glossaries and machine-translation settings. Syncs are idempotent, so running the same one twice never creates duplicates, and a sync that fails on the way is retried with increasing delays rather than dropped.
- Changed source → pending targets
- Translated automatically
- Idempotent syncs
- Retried, never dropped
From the command line
Push, pull, validate, in your pipeline
To translate JSON files from a pipeline, the command-line tool reads a config that names each source file and its target pattern, with globs for a folder of files, and speaks JSON, YAML, PO, iOS strings, xcstrings, Android XML, ARB and XLIFF. Its validate step reports missing, empty and orphan keys and fails the build in CI, and it can emit TypeScript types for your keys, so a typo in a key is a compile error, not a blank label.
- 8 formats
- Globs for whole folders
- validate --ci
- TypeScript types for keys
In the editor
The same editor, memory and checks as for documents
Every string your sync lands in is a row in the same CAT editor translators use for documents, with the same translation memory, termbase and 18 live checks, so a term is translated the same way in the app, the manual and the website. Hand a namespace to a translator through an offer, add a review stage, and the strings ship when the stage is done.
- One editor for strings and documents
- Shared memory and termbase
- Reviewed by a person
- Offers and review stages
At runtime
Fetch from the SDK, or ship the files
The core SDK serves strings cache-first with background sync in Node, the browser and React, keyed by locale, namespace and key; or pull locale files with the command-line tool and ship them with your build. Signed webhooks announce when a translation is ready and when a sync has completed, so your deploy can wait for the languages it needs.
- Core and React SDK
- Locale files from the CLI
- Signed webhooks
- Continuous projects
FAQ
Translating JSON files, answered
Create a continuous project with the target languages, open its Integration tab in developer mode and drop the JSON on the upload card; the hub shows the namespaces and key counts, then syncs them. Review the strings in the CAT editor and pull the locale files with the command-line tool, or let the SDK fetch them at runtime.
Yes. Keys are never renamed or reordered. Nested objects are flattened to dot-notation keys for translation and rebuilt into the same nested shape on the way out, and flat files and multi-namespace files work the same way.
ICU MessageFormat is parsed, not guessed: placeholders are protected through translation and checked on every row, and plural or select messages are translated branch by branch so each form gets its own wording.
Drop or sync your i18next JSON namespaces as they are: nested keys, interpolation placeholders and plural forms are handled, and the React SDK or the pulled locale files plug back into your setup. The developer API page has the quickstart.
Yes, through the command-line tool, which reads and writes JSON, YAML, PO, iOS strings, xcstrings, Android XML, ARB and XLIFF against the same project, so a mobile app and a web app share one memory and one termbase.
Re-sync the file. The changed string marks its target languages as pending and is translated again automatically; every other string stays as it was. Running the same sync twice is safe: a key maps to one stable string, so there are no duplicates.
Yes. Send an offer for the namespace to a translator through the platform or add a review stage to the project; the strings open in the same editor with memory, termbase and checks, and a signed webhook announces when the translation is ready.
A sync is accepted immediately and processed in the background as a job you can watch, namespace by namespace, so a large file is a matter of waiting, not of splitting. A continuous project can carry a monthly cap on machine-translation tokens if you want one; strings past the cap are stored and wait for the next month.
Translate JSON files and read the locale files back
Free to start with 3,000 words: the editor, the memory and the command-line tool are there from the first key.