extraction agent failed reordering catalog keys breaking git diff review

Fix the extraction agent reordering catalog keys and breaking git diff review

TL;DR

The agent writes keys in hash order, so make it write them sorted or in source order. Random order turns every extraction into a giant diff that no one can review. Sort keys alphabetically on write, or preserve first-seen source order, and diffs become readable again.

The error

Every extraction run rewrites locale/en.json with keys in a new random order
git diff shows 2000 changed lines for 3 changed strings

Fix it

Step 1: Confirm the ordering is nondeterministic

node scripts/extract-strings.js && git diff --stat locale/en.json | tail -2

Expected: The diff is huge for a no-change run.

Step 2: Enable sorted output in the extractor

grep -n "sort" scripts/extract-config.js | head -3

Expected: You find the sort option, or the place to add one.

Step 3: Sort keys on write

node -e "console.log('pattern: build the catalog object, then write with keys sorted alphabetically')"

Expected: Output order is now deterministic.

Step 4: Re-run twice and confirm a clean diff

node scripts/extract-strings.js && git diff --stat locale/en.json | tail -2

Expected: No diff on a no-change run, small diff on a real change.

When to use this

• Extraction reorders catalog keys every run
• Git diffs are unreadable after extraction

When NOT to use this

• Keys are stable but values changed, that is a real diff, review it
• You want source order, configure that instead of alphabetical

Tool and version compatibility

• Any JSON catalog writer
• Deterministic key ordering on serialize

Variant phrasings

nested keys reorder too

Sort recursively, not just the top level. Nested objects need the same treatment.

source order preferred over alphabetical

Valid choice. Preserve first-seen order deterministically instead of sorting.

Why it happens

JavaScript object key order follows insertion, and if the extractor inserts keys from a hash map or parallel workers, the order varies run to run. The JSON then differs textually while being semantically identical.

Edge cases

• Sorting changes the diff once, warn reviewers about the one-time reorder
• Keep the sort stable across Node versions, use an explicit comparator
• Some tools expect source order for context, pick the order your reviewers prefer

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Zvrgm34hrRKjXS2PU-qoZQ