Skip to content

Translate JSON

Use it for a product record, a message object, or any JSON document whose keys must stay put.

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.

Request fields
FieldTypeRequiredDefaultAllowedDescription
fromstringyesnoneA supported language code. from also accepts auto.Source language code. The value auto asks the service to detect the source.
tostringyesnoneA supported language code. from also accepts auto.Language code to translate into.
jsonobject or JSON stringyesnoneA JSON object or array, or a string that parses as one.String values are translated. Keys, numbers, booleans, and null stay as sent.
protected_pathsstring[]noemptyAn array of path strings. Omitted is treated as empty.Dot paths whose values are not translated.
common_protected_pathsstring[]noemptyAn 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"
  ]
}
JSON

Success

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.