translation-toolkit/skills/mpi-translation-review/references/edit-suggestions-in-bilingual.md

Edit Suggestions in bilingual.dj

When the user asks to add edit suggestions directly into bilingual.dj, use this two-tier approach.

Two files

• bilingual.dj — clean: inline corrections applied, NO {% %} comment lines
• commented.dj — same content + {% ... %} comment lines interleaved

This lets the user diff them side by side.

Inline corrections

Apply directly to the English text. These are fixes the reviewer is confident about:

• Typos, mechanical issues (Chinese punctuation in EN, double periods, stray *, unbalanced quotes)
• Grammar fixes (subject-verb agreement, missing articles)
• Wording improvements (clunky literal translations → idiomatic English)

Apply with patch (mode='replace'). Verify uniqueness before replacing — many EN paragraphs are long single lines, so match a unique substring. Never use regex-based string replacement in execute_code.

{% %} comment lines

For translation decisions worth documenting but not "correct" per se:

CN paragraph
EN paragraph
{% reason for the choice, alternative renderings %}
(blank)

The comment goes AFTER the EN line (before the blank separator). One comment per issue. Keep them terse.

What to comment on:

• Literal translation of idioms (单线程 → "single-threaded")
• Translation choices that differ from literal meaning (精神利益 → "nourishing the spirit")
• Standard Buddhist terminology (正命 → "Right Livelihood")
• Glosses added/dropped (道场 — "(Dojo)" parenthetical removed)
• Idiom translations (甘之若饴 → "as sweet as syrup")
• Paired terms where one rendering influences the other (魔性 → "demon-nature" to parallel "Buddha-nature")
• Scripture citations with Sanskrit titles (普贤行愿品 → "Gaṇḍavyūha Sūtra")

What NOT to comment on:

• Obvious corrections (typos, grammar)
• Names, dates, simple connectives
• Standard renderings with no interesting choice

Pitfalls

• Never split a paragraph mid-sentence with a {% %} comment. Comments go AFTER the full EN paragraph, before the blank separator. If a string replacement inserts \n{% %} in the middle of a paragraph, it breaks the interleaved structure.

• Check for merged comments: after inserting, scan for {% ... %} followed by EN text on the same line. These must be split so the EN text continues on the next line.

• Collapse triple+ blank lines: comment insertions can create extra blanks. Run re.sub(r'\n\n\n+', '\n\n', text) after all insertions.