Skip to content

Translate HTML

Use it for a fragment or a document where tags, attributes, and selected subtrees must survive.

Purpose

POST /html translates text nodes and returns the markup. protected_selectors, translate="no", and class="notranslate" keep a subtree as sent.

When to use it

Use it for a fragment or a document where tags, attributes, and selected subtrees must survive.

Request

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

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.
htmlstringyesnoneAn HTML document.Text nodes are translated. Tags, attributes, and classes are returned 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.

Payload

Full request

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>SKU-1042</code></p>",
  "protected_selectors": [
    "code"
  ]
}
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. The selector matches the element, and that element plus its subtree stay untranslated.

200 body

{
  "trans": "<p>... <code>SKU-1042</code></p>",
  "meta": {
    "quality": "auto-latency",
    "grade": "llm",
    "degraded_segments": 0
  }
}

Common mistakes

  • Sending the fragment to POST /text

    Plain text and HTML are different routes. /text does not apply selectors.

  • A selector outside the allowed characters

    Each selector is 1 to 128 characters and may use letters, digits, and _.:#[]="'* >+~-. Up to 32 selectors.