Skip to content

Glossary and protected words

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.

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.

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.
textstringyesnone1 to 1,037,299 characters.The string to translate, or the text whose language should be identified.
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.

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"
  ]
}
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 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 "".