Add translation tracking

MC
2mo ago
+688-52

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).