Skip to content

Translate JSON

Translates string values inside a JSON value and returns the same structure.

POSThttps://edge.harktranslate.com/api/v1/translator/json

Request

Send JSON (Content-Type: application/json). Form-encoded bodies are also accepted. 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.
qualitystringnoauto-latencyliteral, nmt, llm, auto-llm, auto-latency. Case-insensitive.The grade of answer you accept. llm, nmt and literal serve only that grade and respond 503 when it cannot be served. auto-latency (the default) returns the fastest answer of any grade. auto-llm prefers an LLM answer and returns the fastest other answer when the LLM one is late. meta.grade reports what actually served.
contextstringnoomittedAn optional string. No values are published.Optional content register. Omit it to use the default register.
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.
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.
glossaryarray of { source: string, target: string }noomittedUp to 50 entries, shared with do_not_translate. Each source and target is 1 to 256 characters, unique by source, with no control characters.Replaces each source term with its target after translation. Omitted or empty leaves the text unchanged.
do_not_translatestring[]noomittedUp to 50 terms combined with glossary. Each term is 1 to 256 characters, unique, and not equal to a glossary source.Terms copied through unchanged. Omitted or empty leaves the text unchanged.

Response

Success is HTTP 200.

Response fields
FieldTypeDescription
transobject or arrayTranslated text, in the same order as the input when the input is a list.
meta.qualitystringThe quality the request sent, or auto-latency when it sent none.
meta.gradestringGrade of the answer that was served: literal, nmt or llm.
meta.degraded_segmentsnumberHow many protected parts of the answer could not be restored.
{
  "trans": { "title": "...", "id": "keep-me" },
  "meta": {
    "quality": "auto-latency",
    "grade": "llm",
    "degraded_segments": 0
  }
}

Samples

Replace YOUR_API_KEY or set HARK_API_KEY. The samples call https://edge.harktranslate.com/api/v1/translator.

JSON object

curl
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",
    "id": "keep-me"
  },
  "protected_paths": [
    "id"
  ]
}
JSON
JavaScript
const response = await fetch("https://edge.harktranslate.com/api/v1/translator/json", {
  method: "POST",
  headers: {
    "x-hark-key": process.env.HARK_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "from": "en",
    "to": "vi",
    "json": {
      "title": "Hello",
      "id": "keep-me"
    },
    "protected_paths": [
      "id"
    ]
  }),
});

if (!response.ok) {
  throw new Error(`Hark responded ${response.status}`);
}

console.log(await response.json());
Python
import os
import requests

response = requests.post(
    "https://edge.harktranslate.com/api/v1/translator/json",
    headers={"x-hark-key": os.environ["HARK_API_KEY"]},
    json={
        "from": "en",
        "to": "vi",
        "json": {
            "title": "Hello",
            "id": "keep-me",
        },
        "protected_paths": [
            "id",
        ],
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

Request and response transcripts

One example for this endpoint, written into the page so you can read it without running a request.

POST /jsonProtected JSON paths

Request
{
  "from": "en",
  "to": "ja",
  "json": {
    "cart": {
      "title": "Your cart",
      "empty": "Your cart is empty.",
      "checkout": "Proceed to checkout"
    },
    "brand": "Northwind",
    "errors": [
      "Card declined",
      "Address is required"
    ]
  },
  "protected_paths": [
    "brand"
  ]
}
Response
{
  "trans": {
    "cart": {
      "title": "あなたのカート",
      "empty": "カートは空です。",
      "checkout": "チェックアウトに進む"
    },
    "brand": "Northwind",
    "errors": [
      "カードが拒否されました",
      "住所は必須です"
    ]
  }
}

Status codes and machine codes are listed on the error catalog, including 200, 202, 400, 401, 403, 404, 413, 429, and 503.