Translation sync PRs conflict when multiple upstream PRs modify the same file — 62% failure rate in practice

[mmcky]

Problem

When two upstream PRs modify the same file and are merged before their corresponding translation sync PRs are reviewed/merged in the target repo, the second translation PR will have merge conflicts with the first.

How it happens

1. Upstream PR A modifies file.md → merged
2. Upstream PR B also modifies file.md → merged
3. Translation sync creates PR X (from A) against target main
4. Translation sync creates PR Y (from B) also against target main

Both PR X and PR Y are generated against the same target main — without accounting for each other. When PR X is merged first, PR Y conflicts because it was translated from the same base.

Case study

This occurred in QuantEcon/lecture-python-programming.fa:

• PR #93 synced upstream #521 (modifying numba.md)
• PR #95 synced upstream #524 (also modifying numba.md)

Both were created against the same target main. After PR #93 was merged, PR #95 had merge conflicts (mergeStateStatus: DIRTY). We had to manually close PR #95 and create a replacement PR #101 with the changes cleanly applied on top of the updated main.

Root cause

action-translation generates each sync PR's translation against the current target main, not against a branch that includes pending unmerged translation PRs. When upstream merges PRs faster than the translation repo reviews/merges them, conflicts are inevitable for files touched by multiple upstream PRs.

Impact

• Manual intervention required to resolve conflicts or recreate PRs
• Translation work in the conflicted PR may be partially wasted (re-translated from wrong base)
• Risk of lost or duplicated translation changes

Possible approaches (for discussion)

• Detect pending PRs: Before creating a new sync PR, check if there are open translation PRs touching the same file and either queue or rebase
• Sequential processing: Only create a new sync PR for a file if no open sync PR exists for that file
• Auto-rebase: Automatically rebase open translation PRs when earlier ones are merged
• Batch mode: Combine multiple upstream changes to the same file into a single translation PR
• Document the limitation: At minimum, document the recommended merge cadence for maintainers

No immediate fix is needed — this is a design consideration for future improvement.

[mmcky]

@HumphreyYang this is going to be an issue in zh-cn repo as well. So no need to analyse this deeply -- I will have a think about how to resolve these types of issues.

[mmcky]

Session Analysis: Full Extent of the Problem

We just completed a review of all 8 open translation PRs (#93–#100) in lecture-python-programming.fa. The results reveal this is a much bigger problem than the original single-file conflict case suggested.

Summary of outcomes

Original PR	Upstream	Files	Status	Outcome
#93	#521	need_for_speed.md, numba.md	✅ Merged directly	First in chain — no conflicts
#94	#522	jax_intro.md	✅ Merged directly	First in chain — no conflicts
#95	#524	numba.md	❌ Conflicts	Replaced by #101 (file checkout)
#96	#525	numpy_vs_numba_vs_jax.md	✅ Merged directly	First in chain — no conflicts
#97	#523	need_for_speed.md	❌ Conflicts	Replaced by #102 (file checkout + translation fix)
#98	#526	numba.md	❌ Conflicts	Replaced by #103 (file checkout)
#99	#527	jax_intro.md	❌ Conflicts	Replaced by #104 (file checkout)
#100	#528	jax_intro.md, numba.md, numpy_vs_numba_vs_jax.md	❌ Conflicts (severe)	Replaced by #105 (manual rewrite)

5 out of 8 PRs (62.5%) had merge conflicts. Only the first PR touching each file could merge cleanly; every subsequent PR for the same file conflicted.

The escalating severity problem

The conflict problem gets progressively worse as the chain grows:

1. Simple conflicts (PRs #95, #97, #98, #99): The translated files could be checked out from the conflicted branch and committed on top of current main. This works because the translation was done against a base that was "close enough" — only one prior PR's changes were missing.

2. Compound conflicts (PR #100): This PR touched 3 files (jax_intro.md, numba.md, numpy_vs_numba_vs_jax.md), all of which had been modified by 2-4 prior translation PRs. Checking out PR #100's files would have reverted all prior work from PRs #101-#104 (4 merged PRs). The translation was done against a base so far behind that it was unusable. We had to manually read the upstream diff and apply the English changes to the Persian files by hand, essentially doing the translation integration work ourselves.

Additional compounding issues discovered

1. Translation errors compound: When we fix a translation error in PR N (e.g., fixing پرمخاطب → مفصل in #104), PR N+1's files still contain the original error. If naively checked out, they revert the fix.

2. Structural divergence: When upstream restructures a document significantly (e.g., removing/adding sections in #527), the translation PR based on the old structure produces files that are architecturally incompatible with the current translated version.

3. Review waste: The automated translation review runs against the PR's own diff, not against current main. So the review scores (8-9/10) can mask the fact that the PR would revert important fixes if merged.

Core analysis

The fundamental issue is that each translation PR is a snapshot of the full translated file at a specific point in time, not a delta. When PR X translates file.md from English state A to Persian, it produces the entire Persian file. When PR Y later translates file.md from English state B, it also produces the entire Persian file — but from the pre-PR-X Persian base. The two full-file snapshots are inherently incompatible.

This is different from typical code conflicts where you have small, localised changes. Translation PRs replace large sections of content, so three-way merge is almost always impossible.

Proposed solutions (expanded)

1. Auto-merge with quality threshold (recommended for short term)

• If the translation quality review scores ≥ 9/10 and diff quality is 10/10, auto-merge the PR
• This eliminates the sequencing problem entirely for high-quality translations
• Generate a weekly digest report for editors showing what was auto-merged, with links to review comments and quality scores
• Editors can retroactively flag issues and the system can open fix PRs
• Risk: Translations with subtle errors merge without human review
• Mitigation: The automated review already catches most issues (it found پرمخاطب, هرگز, heading misalignment in this session)

2. Sequential queue with auto-rebase

• Maintain a per-file queue of pending translation PRs
• Only the oldest PR for each file is "active"; others are queued
• When an active PR is merged, auto-rebase the next queued PR (re-translate the delta against the new base)
• Pro: Guarantees conflict-free PRs
• Con: Adds complexity and latency; re-translation costs

3. Squash-and-batch mode

• When upstream merges multiple PRs to the same file within a time window (e.g., 24h), batch them into a single translation PR
• Pro: Reduces PR count and eliminates intra-batch conflicts
• Con: Larger diffs are harder to review; doesn't help if upstream PRs are spread over days

4. Delta-based translation (architectural change)

• Instead of producing full translated files, produce section-level patches
• The translation system would identify which sections changed and only translate those
• Patches can be applied sequentially without full-file conflicts
• Pro: Eliminates the snapshot problem entirely
• Con: Major architectural change; section boundary detection is complex

5. Rebase-on-merge hook

• When a translation PR is merged, automatically rebase all other open translation PRs that touch the same files
• Re-run translation only for sections that conflict
• Pro: Transparent to reviewers
• Con: Requires re-translation API calls; may invalidate existing reviews

Recommendation

For the immediate term, Option 1 (auto-merge with quality threshold) is the most practical. The automated review system already produces reliable quality scores, and the compound conflict problem only exists because PRs sit unmerged while subsequent ones accumulate. Auto-merging high-quality translations would:

• Eliminate the conflict chain entirely (each PR merges before the next is created)
• Reduce manual editor workload (editors review a weekly digest, not individual PRs)
• Preserve quality control (the automated review catches translation errors)
• Allow editors to focus on the ~10-20% of PRs that score below the threshold

For the medium term, Option 2 or 5 would handle the remaining edge cases where auto-merge isn't appropriate.

[mmcky]

@HumphreyYang I think this issue also explains why you started seeing content changes not related to the source PR. The main diverged for the PR comparisons.

[HumphreyYang]

Many thanks @mmcky.

@HumphreyYang I think this issue also explains why you started seeing content changes not related to the source PR. The main diverged for the PR comparisons.

It definitely contributes to the issue, but I also find that the first PR that modified the file edits content not present in the source PR.

I went through all the PRs and resolved conflicts, trying to align everything with the source main.

Manual resolution is not very easy becuase sometimes the merge conflict doesn’t capture the diff lines 100% accurately, which can result in duplicates if the diff is incomplete during conflict resolution.

But I want to get it done so I can send the latest main to Xiamen RAs : )