# 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

```text
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

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

Expected: You see the send path.

### Step 2: Replace tags with placeholders before sending

```bash
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

```bash
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

```bash
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/pst_AAcrRqJ0G4eQlh3Lgc_h5w