HTML and XML tag handling

By default the engine treats everything in text as prose, and a <strong> in the middle of a sentence is just a strange word. With tag_handling set, the input is parsed as markup: tags, attributes and entities are carried through unchanged and only the text between them is translated.

Enabling it

The value is case-insensitive; anything else is a validation_error.

Example

An e-mail template with a link and emphasis, translated into Dutch:

curl https://api.langapi.xyz/v1/translate \
  -X POST \
  -H "Authorization: Bearer la_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "text": ["<p>Your subscription renews on <em>{{renew_date}}</em>. <a href=\"/billing\">Manage billing</a></p>"],
        "target_lang": "NL",
        "tag_handling": "html"
      }'

{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "<p>Je abonnement wordt verlengd op <em>{{renew_date}}</em>. <a href=\"/billing\">Facturering beheren</a></p>"
    }
  ]
}

The <p>, <em> and <a> elements, the href value and the {{renew_date}} placeholder are all exactly as sent.

Translated and preserved

Attribute values are never translated, including alt and title. If those need translating, send their values as separate entries in text and put them back yourself.

Placeholders

Interpolation tokens that do not look like natural-language words pass through unchanged, with or without tag handling:

{count}   {{user_name}}   %s   %2$d   ${amount}   :attribute

If your template syntax is unusual, wrap each placeholder in an element and use xml, which makes the boundary unambiguous:

<msg>You have <ph id="n"/> unread messages from <ph id="sender"/>.</msg>

Whitespace and capitalisation

preserve_formatting: true keeps leading and trailing whitespace, line breaks and the capitalisation of the first character as sent, and stops the engine from tidying punctuation. Use it when strings are fragments that get concatenated in your code; without it a fragment may come back capitalised or with a full stop it did not have.

Markup is counted

Every character of the markup is part of text and is charged. Two ways to keep that in check:

1. Send the fragments that contain copy, not the surrounding page. A layout

wrapper that never changes still costs its characters on every request.

1. Remove <script> and <style> blocks before sending. They are never

translated but always counted.

Broken markup

The engine does not repair input. An unclosed tag is returned unclosed; malformed nesting comes back malformed. Nothing is validated on the way in, so if well-formedness matters downstream, validate before you send.

Glossaries inside markup

Glossary terms are matched within text nodes, so a glossary works as usual with tag handling on. A term that is split by a tag — <b>Work</b>space — cannot match; fix the markup rather than the glossary.