[mcmah309]

PR Title

Adds translation tracking to the api so you can see how translations were mapped between the documents. Enabled through an opt-in config flag.

PR Type

• ✨ Enhancement
• 🐛 Bug Fix
• 📚 Documentation
• 🏗️ Refactor
• 🧪 Test
• 🧹 Chore

Breaking Changes

Contributor Checklist

• I have fully read and understood the CONTRIBUTING.md guide.
• I have performed a self-review of my own code.
• My changes follow the project's code style and guidelines
• I have linked the related issue(s) in the description above (if applicable)
• I have updated relevant documentation (if applicable)
• I have added necessary tests that prove my fix is effective or that my feature works (if applicable)
• All new and existing tests passed locally with my changes
• My changes generate no new warnings or errors
• I understand that due to limited maintainer resources, only small PRs are accepted. Suggestions with proof-of-concept patches are appreciated, and my patch may be rewritten if necessary.

Testing Instructions

Screenshots (if applicable)

Additional Notes

---

Summary by cubic

Adds opt-in translation tracking that maps source paragraphs to translated outputs with geometry and layout info, exposed via TranslateResult.translation_tracking.

New Features

• enable_translation_tracking on TranslationConfig collects per-paragraph input/output, page_number, box, layout_label, placeholders, and optional per-character char_boxes.
• Debug mode also collects tracking and writes it to translate_tracking.json, without attaching it to the result.
• Split-part page numbers are rebased to document indices; merged results concatenate tracking and renumber multi_paragraph_id.

Migration

• Enable with enable_translation_tracking=True; read translation_tracking from TranslateResult (only present when enabled).

^{Written for commit f6c0be6. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 5 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>