Greptile Summary

This PR fixes a correctness bug in the docs-i18n pipeline where a failed postprocessLocalizedDocs call could permanently strand translated files with stale English-root links. Previously, encodeFrontMatter wrote a finalized source_hash immediately on translation, so a subsequent postprocessLocalizedDocs failure left the output file in a state that shouldSkipDoc considered complete — meaning those broken files would be silently skipped on every retry until the English source changed.

The fix is minimal and well-targeted:

• encodeFrontMatter now writes postprocess_version: pending instead of the real version, making newly translated files non-skippable by default.
• shouldSkipDoc now requires both a matching source_hash and postprocess_version == locale-links-v1 before allowing a skip.
• postprocessLocalizedDocs upgrades pending → locale-links-v1 on success, including the edge case where body links are already correct but the marker still needs finalizing (covered by TestPostprocessLocalizedDocsFinalizesPostprocessVersionWithoutBodyRewrite).
• Two new regression tests in main_test.go cover the end-to-end pipeline wiring and the sticky-failure path.

The logic in setPostprocessVersion correctly handles both the insert-at-end and mid-block insertion cases. The continue guard in postprocessLocalizedDocs will never prematurely skip a file carrying the pending marker since updatedFrontMatter != frontMatter whenever the version needs upgrading.

• One minor style note in the new test: a dead outputPath assignment on line 94 is immediately overwritten by the processFileDoc return value.

Confidence Score: 4/5

Safe to merge — the fix is minimal, logically correct, and well-covered by new regression tests.

Score reflects a clean, targeted bug fix with thorough test coverage and no critical issues identified. One minor dead-assignment in test code prevents a perfect score.

No files require special attention beyond the minor style note in scripts/docs-i18n/main_test.go.

This is a comment left during a code review.
Path: scripts/docs-i18n/main_test.go
Line: 94-96

Comment:
**Dead variable assignment before immediate overwrite**

The `outputPath` declared on line 94 is never read — it is unconditionally overwritten two lines later by the `:=` on line 96. Both computations produce the same path (`filepath.Join(docsRoot, "zh-CN", "gateway", "index.md")`), so there is no behavioral impact, but the first declaration is dead code. Consider removing it and relying solely on the return value from `processFileDoc`:

```suggestion

	skip, outputPath, err := processFileDoc(context.Background(), fakeDocsTranslator{}, docsRoot, sourcePath, "en", "zh-CN", true)
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "docs: require i18n postprocess before sk..." | Re-trigger Greptile}

Thanks for the context here. I swept through the related work, and this is now duplicate or superseded.

Keep open for maintainer handling: this draft, MEMBER-authored, maintainer-labeled PR is superseded by #92668 and current main has the more complete output-state implementation, but protected item rules prevent automatic cleanup close.

Root-cause cluster
Relationship: superseded
Canonical: #92668
Summary: This PR and #92668 address the same docs-i18n postprocess-before-skip root cause; the latter is merged and is the canonical implementation on main.

Members:

• canonical: fix(docs): finalize i18n postprocess before skip #92668 - The merged PR body explicitly says it supersedes this PR, and current main contains its more complete output-state implementation.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Canonical path: Close this PR as superseded by #92668.

So I’m closing this here and keeping the remaining discussion on #92668.

Thanks @hxy91819. Closing as superseded by your later #92668, which explicitly supersedes this branch and shipped in v2026.6.8.

Current main uses explicit needs-translation, needs-postprocess, and ready output states; preserves legacy matching-hash localized outputs without retranslating them; honors the --max mutation bound; and includes focused failure and finalization coverage. This older draft is conflicted and has no distinct remaining work.