Purpose
POST /json translates string values and returns the same structure. protected_paths and common_protected_paths leave chosen values untouched.
When to use it
Use it for a product record, a message object, or any JSON document whose keys must stay put.
Request
POSThttps://edge.harktranslate.com/api/v1/translator/json
Send Content-Type: application/json and authenticate with the x-hark-key header.
| Field | Type | Required | Default | Allowed | Description |
|---|---|---|---|---|---|
| from | string | yes | none | A supported language code. from also accepts auto. | Source language code. The value auto asks the service to detect the source. |
| to | string | yes | none | A supported language code. from also accepts auto. | Language code to translate into. |
| json | object or JSON string | yes | none | A JSON object or array, or a string that parses as one. | String values are translated. Keys, numbers, booleans, and null stay as sent. |
| protected_paths | string[] | no | empty | An array of path strings. Omitted is treated as empty. | Dot paths whose values are not translated. |
| common_protected_paths | string[] | no | empty | An array of key names. Omitted is treated as empty. | Key names left untranslated at every nesting level. |
Payload
Full request
curl -X POST "https://edge.harktranslate.com/api/v1/translator/json" \
-H "x-hark-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"from": "en",
"to": "vi",
"json": {
"title": "Hello",
"sku": "SKU-1042",
"meta": {
"id": "row-9"
}
},
"protected_paths": [
"meta.id"
],
"common_protected_paths": [
"sku"
]
}
JSONSuccess
HTTP 200. Strings written as ... are the response shape, not a captured translation. meta.quality is what you asked, meta.grade is what served, and meta.degraded_segments counts protected parts that could not be restored. Keys, numbers, booleans, and null are returned as sent. A protected_paths entry is a dot path from the root. A common_protected_paths entry is a key name, matched at every level.
200 body
{
"trans": {
"title": "...",
"sku": "SKU-1042",
"meta": {
"id": "row-9"
}
},
"meta": {
"quality": "auto-latency",
"grade": "llm",
"degraded_segments": 0
}
}Common mistakes
A path that is not a string in an array
protected_paths is an array of dot paths, such as ["meta.id"]. A bare string is not a path list.
Protecting the wrong path
meta.id protects that one value. id protects a root key named id, and does not protect meta.id.