translation agent sent html tags to translation api and markup validation failed

Fix the translation agent sending HTML tags to the translation API

TL;DR

The agent sends raw markup to the API, so strip or protect the tags before sending. Translation APIs mangle or drop HTML, and markup validation fails on the way back. Either send text-only segments with placeholders for tags, or use the API's markup-handling mode if it has one.

The error

Translation agent: markup validation failed on returned strings
API mangled bold tags, some translations missing the markup

Fix it

Step 1: Find where the agent sends the strings

grep -n "translate(" scripts/translate-agent.js | head -5

Expected: You see the send path.

Step 2: Replace tags with placeholders before sending

node -e "console.log('pattern: replace each tag with a placeholder like [b1], translate the text, restore tags after')"

Expected: The API never sees raw markup.

Step 3: Validate tag restoration on return

node -e "console.log('after restoring, check every placeholder was replaced and tags balance')"

Expected: No placeholder leaks into shipped strings.

Step 4: Re-run the batch and validate markup

node scripts/translate-agent.js | tail -3

Expected: Markup validation passes.

When to use this

• A translation agent sends HTML to the API and markup breaks
• Returned translations have mangled tags

When NOT to use this

• The API supports HTML natively and you enabled it, check that mode
• Tags are fine but the text is wrong, that is a quality issue

Tool and version compatibility

• Translation APIs with text-only or markup modes
• Placeholder-based tag protection

Variant phrasings

API has a markup mode you did not enable

Enable it instead of placeholders. Native handling beats regex protection.

placeholders get translated

Use the API's protected-terms or do-not-translate list for your placeholder format.

Why it happens

HTML is not translatable text, it is structure. Sending it raw lets the MT engine reorder, drop, or translate inside tags, and the result fails the markup validation that keeps your UI intact.

Edge cases

• Placeholders must be unique per tag instance, reused ones restore wrong
• Nested tags need ordered placeholders, flat replacement breaks nesting
• Test with RTL languages, tag order around bidi text is fragile

Provenance

Resolved from the public thread: https://vectle.com/posts/pstAAcrRqJ0G4eQlh3Lgch5w