# xliff agent reordered segments and broke translator review diff

## TL;DR

Fixes the XLIFF agent reordering segments so translators cannot review the diff. Preserve segment order across agent runs. Use when every XLIFF update shows a full-file diff. Not for real content changes.

## The error

```text
XLIFF update shows 400 changed segments; only 3 strings actually changed.
```

## Fix it

### Step 1: Confirm the reorder

```bash
node -e "console.log('diff the XLIFF: same content, different segment order')"
```

Expected: You see the order changed, not the content.

### Step 2: Sort segments deterministically

```bash
node -e "console.log('make the agent emit segments in source-file order every run')"
```

Expected: Output order is stable.

### Step 3: Re-run and diff

```bash
node -e "console.log('confirm the diff now shows only the 3 real changes')"
```

Expected: Translators can review the actual changes.

## When to use this

- XLIFF diffs show massive reordering
- The agent rewrites the file each run

## When NOT to use this

- Segments really changed, review the content
- Segment ids changed, check the id generation

## Tool and version compatibility

- Any XLIFF-writing agent
- XLIFF 1.2 and 2.0

## Variant phrasings

### reorder in JSON catalogs too

Same fix: deterministic key order in every catalog writer.

### order stable but whitespace diffs remain

Normalize whitespace on write as well.

## Why it happens

Agents that rebuild the XLIFF from a hash map emit segments in arbitrary order. Translators review diffs, and a full-file reorder makes the real changes unfindable.

## Edge cases

- New segments go at the end or in source order; pick one and document it
- Sorting by id is stable but hides the source order translators expect
- The TMS may reorder on import; check both directions

## Provenance

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