translate:sync-hash never converges: reports 71/84 files as drifted and appends a blank line every run

[christian-byrne]

Summary

pnpm translate:sync-hash never converges. It reports 71 of 84 files as needing a hash sync when their hashes are already correct, and every run it appends one more blank line after the frontmatter of each translated file. The two are the same bug.

Found while adding a section to tutorials/image/qwen/qwen-image-layered.mdx (#1357), where the tool claimed drift on a page whose English source had not changed in seven months.

Reproduction

On a clean main:

$ bun .github/scripts/i18n/sync-hash-i18n.ts --dry-run tutorials/image/qwen/qwen-image-layered.mdx
  [ja] would sync hash: ja/tutorials/image/qwen/qwen-image-layered.mdx
  [zh] would sync hash: zh/tutorials/image/qwen/qwen-image-layered.mdx
  [ko] would sync hash: ko/tutorials/image/qwen/qwen-image-layered.mdx
Done: 3 updated, 0 already in sync, 0 missing target(s)

But the hashes are already right. Computing them with the repo's own functions:

computed block hashes: { _intro: "19900234", "Qwen-Image-Layered workflow": "ba937275",
                         "Model links": "98d12555", "FP8 version": "6bffdd17",
                         "Workflow settings": "b0f81aa2" }
computed aggregate:    bf2f2000
recorded in zh/ja/ko:  bf2f2000, same five block hashes

Running it for real produces this and nothing else, in all three languages:

@@ -13,6 +13,7 @@ translationBlockHashes:
 ---

+
 import UpdateReminder from '/snippets/ja/tutorials/update-reminder.mdx'

Run it three times, get three blank lines. It is unbounded.

Repo-wide on clean main:

$ bun .github/scripts/i18n/sync-hash-i18n.ts --dry-run
Done: 71 updated, 13 already in sync, 0 missing target(s)

Cause

syncOneFile only reports "unchanged" when both the hash and the full re-serialized text match:

const existingHash = getExistingHash(targetContent);
if (existingHash === expectedFileHash && output === targetContent) {
  return { status: "unchanged", warnings: [] };
}

output comes from syncChunkedHashes, which rebuilds the file as:

const { frontmatter, body } = parseFrontmatterAndBody(targetContent);
const bodyText = body.endsWith("\n") ? body : `${body}\n`;
const raw = `${frontmatter}\n${bodyText}`;

parseFrontmatterAndBody matches /^(---\n[\s\S]*?\n---)\n?([\s\S]*)$/ and returns frontmatter with a trailing \n already appended, then consumes one more \n into the separator. raw then adds its own \n back on top of a body that still begins with the remaining newlines. Round-tripping a file therefore gains one \n every time, output !== targetContent forever, and the unchanged branch is unreachable for chunked files.

Because the blank line is inside the body, it does not change any hash, which is why the recorded hashes stay correct while the tool keeps insisting they are not.

Impact

• --dry-run is not usable as a drift signal. "71 files need a hash sync" currently means "71 chunked files exist", not "71 files drifted". A genuine drift is indistinguishable from the noise.
• Every pnpm translate:sync-hash run dirties 71 files with a whitespace-only diff.
• It is already in the history: 6a4aa99 ("Sync translation hash metadata for ja/zh/ko docs.", Sync ja/zh/ko translation hash metadata #1228) added exactly this blank line to the qwen page along with the intended frontmatter change.

Suggested fix

Make the round-trip idempotent, in syncChunkedHashes:

const raw = `${frontmatter}${bodyText}`;

and have parseFrontmatterAndBody own the single separating newline, or normalise the leading blank run of body before reassembly. Then the output === targetContent guard starts working and --dry-run becomes meaningful again. Worth a test that asserts sync(sync(x)) === sync(x).

.github/scripts/i18n/sync-hash-i18n.ts and .github/scripts/i18n/chunked-translate.ts.

Note on a claim this disproves

It looked at first as though the zh/ja/ko mirrors were drifting because they carry an English-derived fingerprint. They are not. translationSourceHash is documented as "SHA-256 of its English source", so carrying the English hash is correct by design, and for this page the recorded value is exactly the value the current English source produces. The drift is in the tool's own reporting, not in the data.

[coderabbitai]

🔗 Related PRs

#1335 - i18n: fetch glossary locales from GitHub instead of local frontend repo [merged]
#1347 - docs: update MiniMax-H3 changelog link and sync CMS release notes [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[christian-byrne]

Fixed rather than left as a ticket. Two stacked PRs, both green:

• Make translate:sync-hash idempotent #1360 — the fix, 11 regression tests, and a CI job to run them. Closes this issue.
• Remove the blank lines translate:sync-hash added to translated pages #1361 — removes the blank lines already committed. Stacked on 1360.

Confirmed, with the numbers tightened

Five consecutive full runs on clean main:

run	reported	cumulative insertions
1	71 updated	253
2	17 updated	270
3	17 updated	287
4	17 updated	304
5	17 updated	321

Unbounded, and 17 files never converged. The suggested one-line fix is correct. After it: 60 → 0 → 0, and --dry-run prints Nothing to sync. Hashes already match English source. The 71 → 60 drop is the false positives disappearing; the remaining 60 are genuine English-source drift.

Two things the issue did not have

The regression test found a second instance of the same defect. When frontmatter contains nothing but translation metadata, stripping it leaves cleaned empty and ${open}${cleaned}\n${metaBlock} emits a blank first line inside the frontmatter:

run 0: "---\ntranslationSourceHash: aaaaaaaa\n…"
run 1: "---\n\ntranslationSourceHash: aaaaaaaa\n…"   ← gained a line
run 2: "---\n\ntranslationSourceHash: aaaaaaaa\n…"   ← stable from here

Bounded rather than unbounded, but still not idempotent, and live on zh/custom-nodes/workflow_templates.mdx. Fixed once as a shared frontmatterMetaPrefix and applied at all three call sites — chunked-translate.ts, sync-hash-i18n.ts, and translate-i18n.ts, which carried the identical code and is the main translation entry point.

Nothing ran the tests that already existed. .github/scripts/i18n/ shipped chunked-translate.test.ts and repair-fences.test.ts, and no workflow invoked them. That is why this was invisible to CI, and it means a regression test added without a runner would have been decoration. i18n-scripts-test.yml now runs bun test ./.github/scripts/i18n/; 31 tests pass (20 pre-existing + 11 new).

The already-committed blank lines

538 files, 604 deletions, 0 insertions, zero non-blank lines changed. Attributed against d56a77bd^ — the commit before the tool existed — rather than guessed at:

	files
translated files with ≥2 blank lines after frontmatter	542
grew since the tool landed	526
created after the tool landed	12
unchanged since before the tool existed (legitimate)	4

Worst case was 9 blank lines on zh/tutorials/video/minimax/minimax-h3.mdx. 6a4aa997 is one of the commits that added them, as the issue noted.

Kept as a separate stacked PR on purpose: folding a 538-file whitespace diff into a four-line logic fix would make the fix unreviewable, and the cleanup is only durable once the fix lands — run the old script once more and every line comes straight back.

Not addressed

After both land, 60 files still carry a genuinely stale translationSourceHash because their English sources changed and the translations have not been revisited. That needs a translator, not a tooling pass, and neither PR touches a hash.