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.
| 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. |
| html | string | yes | none | An HTML document. | Text nodes are translated. Tags, attributes, and classes are returned unchanged. |
| protected_selectors | string[] | no | omitted | Up 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"
]
}
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. 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.