Translate JSON
Submit a JSON object with context, hints, and protected paths, then download its translations.
Send a JSON object directly in a localization job when your application already has the source in memory. Lingo.dev stores it as a JSON document and produces one output for each target locale.
The quickstart provides a complete program. This reference covers the JSON-specific request fields.
Submit an inline document #
Create the job at POST /v2/organizations/:orgId/localization/jobs with an API key in X-API-Key and a stable Idempotency-Key for this submission:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "settings.json",
"format": {
"type": "json",
"options": {
"context": "Settings dialog in a team collaboration application",
"hints": { "$.save": ["Button that saves the edited settings"] },
"lockedKeys": ["$.productName"]
}
},
"source": {
"content": {
"save": "Save changes",
"cancel": "Cancel",
"productName": "Acme"
}
}
}
]
}The source must be a JSON object. It may contain nested objects and arrays. String leaves are translation candidates; numbers, booleans, and null values retain their JSON types. Protect string-valued identifiers, product names, or URLs when they should remain unchanged.
Inline sources use format.type: "json". For JSONC or another file format, upload the file's bytes.
Add context and select content #
Put JSON options inside the document's format.options:
| Option | Effect |
|---|---|
context | Nonempty text describing the content's purpose or audience. |
hints | JSONPath queries mapped to nonempty arrays of nonempty hints. Matching hints accumulate for selected strings. Defaults to an empty object. |
lockedKeys | Copy selected source values without translation. Defaults to []. |
preservedKeys | Reuse selected values from the previous target where available; otherwise copy the source. Defaults to []. |
ignoredKeys | Remove selected values from the output. Defaults to []. |
keyScope | Regenerate strings selected by a nonempty list of JSONPath queries. Requires a previous translation for every target locale. |
termScope | Regenerate strings matching a nonempty list of source terms. Requires a previous translation for every target locale. |
injectLocale | Write the target locale at one singular JSONPath location, such as $.meta.locale. That subtree is protected from translation. |
Use JSONPath in API requests. $.title selects a root property; $.nav.home selects a nested property; $['nav.home'] selects a literal key containing a dot; $..productName selects that property at any depth. Selecting an object or array includes its descendant strings. Bare key names are not valid API queries.
Key controls are resolved before translation. Ignored values are removed; locked source values take precedence over preserved target values. Scope selection does not override these controls. See the JSON format reference for output assembly and ICU messages.
termScope matches case-sensitive substrings of source strings. Any listed term can select a string: "cat" also matches "catalog", while "login" does not match "Login". The whole selected string is regenerated, not just the matching term. When keyScope and termScope are both present, a string must satisfy both. Use a precise JSONPath key selection when a substring would include unrelated messages.
Start and read the result #
Save the create response's id. Upload every entry in uploads if this job also references previous files or other documents, then call POST /v2/localization/jobs/:id/start.
Read GET /v2/localization/jobs/:id and inspect each document's targets. A target with status._tag: "Completed" has a status.downloadUrl. Download that URL with the same authentication to get the JSON object. The job response itself contains progress and artifact addresses, not the translated object.
For updates, submit the previous source and target artifacts as described in update an existing document. Keep the new source revision with the job ID so a delayed result cannot replace newer content.