Skip to content

Translate HTML

Translates visible text nodes and returns the markup with tags left in place.

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

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.
htmlstringyesnoneAn HTML document.Text nodes are translated. Tags, attributes, and classes are returned unchanged.
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.
protected_selectorsstring[]noomittedUp to 32 CSS selectors. Each is 1 to 128 characters and uses only letters, digits, and the characters _.:#[]="'* >+~-.Matching elements and their subtrees stay untranslated. Applies when the body is HTML.

Response

Success is HTTP 200.

Response fields
FieldTypeDescription
transstringTranslated 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": "<p>...</p>",
  "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.

HTML document

curl
curl -X POST "https://edge.harktranslate.com/api/v1/translator/html" \
  -H "x-hark-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "from": "en",
  "to": "vi",
  "html": "<p>Hello <code>keep</code></p>",
  "protected_selectors": [
    "code"
  ]
}
JSON
JavaScript
const response = await fetch("https://edge.harktranslate.com/api/v1/translator/html", {
  method: "POST",
  headers: {
    "x-hark-key": process.env.HARK_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "from": "en",
    "to": "vi",
    "html": "<p>Hello <code>keep</code></p>",
    "protected_selectors": [
      "code"
    ]
  }),
});

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/html",
    headers={"x-hark-key": os.environ["HARK_API_KEY"]},
    json={
        "from": "en",
        "to": "vi",
        "html": "<p>Hello <code>keep</code></p>",
        "protected_selectors": [
            "code",
        ],
    },
    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 /htmlHTML keeps tags

Request
{
  "from": "en",
  "to": "de",
  "html": "<div class=\"card\">\n  <h3>Wireless earbuds</h3>\n  <p>\n    Up to <strong>30 hours</strong> of battery life.\n    <a href=\"/specs\">See all specs</a>\n  </p>\n  <button data-sku=\"EB-220\">Add to cart</button>\n</div>"
}
Response
{
  "trans": "<div class=\"card\">\n  <h3>Kabellose Ohrhörer</h3>\n  <p>\n    Bis zu <strong>30 Stunden</strong> der Akkulaufzeit.\n    <a href=\"/specs\">Alle Spezifikationen ansehen</a>\n  </p>\n  <button data-sku=\"EB-220\">In den Warenkorb legen</button>\n</div>"
}

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