Purpose
glossary replaces each source term with its target after translation. do_not_translate copies those words through unchanged.
When to use it
Use a glossary for product names that must become a chosen translation, and do_not_translate for codes, brands, or words that must stay byte-for-byte.
Request
POSThttps://edge.harktranslate.com/api/v1/translator/text
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. |
| text | string | yes | none | 1 to 1,037,299 characters. | The string to translate, or the text whose language should be identified. |
| glossary | array of { source: string, target: string } | no | omitted | Up 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_translate | string[] | no | omitted | Up 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. |
Payload
Full request
curl -X POST "https://edge.harktranslate.com/api/v1/translator/text" \
-H "x-hark-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"from": "en",
"to": "vi",
"text": "The Hark API returns JSON.",
"glossary": [
{
"source": "Hark",
"target": "Hark"
}
],
"do_not_translate": [
"API"
]
}
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 same two fields are accepted on /text, /texts, /json, and /html. JSON paths and HTML selectors are separate controls, on their own articles. If a protected part cannot be restored, meta.degraded_segments is greater than 0.
200 body
{
"trans": "...",
"meta": {
"quality": "auto-latency",
"grade": "nmt",
"degraded_segments": 0
}
}Common mistakes
Two glossary rows with the same source
Each source may appear once. A duplicate source is HTTP 400.
The same word in both lists
A do_not_translate term must not equal a glossary source. Pick one control for that word.
More than 50 terms together
glossary and do_not_translate share a cap of 50 entries. Each source, target, and protected word is 1 to 256 characters.
An empty string
A blank source, target, or protected word is refused. Drop the row instead of sending "".