Anyone who has localized technical documentation knows the scenario: the translation reads fine, but importing it back fails -- tag counts do not match, nesting is scrambled, variable placeholders have vanished. The content is right and the structure is broken, so the segment is rejected. This accounts for a substantial share of rework in technical translation, and it is almost entirely preventable through configuration.
Two kinds of tags, handled differently
Structural tags -- div, section, table, ul -- wrap complete blocks of content. They are usually processed as units and do not participate in word-order changes. These are the easy case.
Inline tags -- strong, em, a, span, code -- sit inside a sentence and mark a fragment of it. This is where the trouble is. A word emphasized in the source will move, change length, split into two words, or merge into one in the target. The tag has to follow the meaning, not the position.
Why regex extraction always fails eventually
The usual first attempt is to strip tags into placeholders, translate the plain text, then put the tags back. That works passably between languages with similar word order and collapses across language families.
English to Chinese reorders heavily, so positional reinsertion lands in the wrong place. Nesting makes it worse -- an outer link containing inner emphasis loses its hierarchy during extraction and cannot be reconstructed. And when a tag spans a sentence boundary, you cannot even determine which sentence it belonged to.
The correct approach has the engine understand the markup and place tags during decoding rather than stitching them back afterwards. Enable tag handling on the text translation API call and markup is preserved as untranslatable structure and repositioned for the target language.
Give variable placeholders a recognizable format
Software strings are full of variables: Welcome back, PLACEHOLDER or You have N days left in your trial. Placeholder syntax varies wildly across frameworks -- braces, percent signs, dollar-brace, double braces.
Some of those formats look enough like natural language that a model will happily translate them. The safer approach is to normalize to one unambiguous, obviously non-linguistic format and add those patterns to the untranslatable list. Watch spacing and punctuation around variables too: Chinese needs no space where English does, and naive reinsertion produces doubled spaces or collided punctuation.
CDATA, comments, and attribute boundaries
XML has a few positions that get missed. CDATA sections usually contain translatable body text, yet many parsers skip them by default. Comments sometimes carry translator instructions that should be preserved but not translated. Among attributes, alt, title, placeholder, and aria-label need translation while class, id, href, and data-* must never be touched.
Maintain an explicit allowlist rather than a blocklist. A missed entry on an allowlist means one string went untranslated; a missed entry on a blocklist can break styling or links outright.
Replace manual checking with automated validation
The useful property of tag problems is that they are fully machine-detectable. Before writing a translation back, validate: tag counts match between source and target, tag types correspond one to one, nesting is well-formed, and the set of variable placeholders is identical. Block and flag on any failure.
This is cheap to implement and turns tag rework from routine into exceptional. For teams on CAT tools, run it before import so broken segments never enter translation memory -- once a bad segment is in the TM it gets reused indefinitely. The CAT tool integration guide covers where this belongs in the workflow.
Test the hardest samples first
Do not validate a new configuration on ordinary paragraphs. Use the worst cases you have: inline tags nested three deep, five variables in one sentence, tags spanning sentence boundaries, links inside table cells. If those pass, everyday content will not surprise you.
Freeze that set as a regression suite and rerun it after every engine upgrade or configuration change. Technical documentation runs to high volume, so one configuration defect multiplies into thousands of errors -- catching it up front is far cheaper than repairing it later. For integration detail see the API quickstart and the SDK list.