# 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

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

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

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

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

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