xliff agent reordered segments and broke translator review diff

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

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

Fix it

Step 1: Confirm the reorder

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

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

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