Text Aligner ⚡

Text Aligner is a high-performance, production-grade bilingual text and subtitle alignment workbench. It automatically aligns sentences across 109+ languages using multilingual neural embeddings (Google LaBSE) coupled with a two-pass dynamic programming alignment algorithm, with specialized support for subtitle timecodes and Right-to-Left (RTL) scripts like Arabic.

---

🌟 Key Features

🧠 Intelligent Neural Alignment

• Two-Pass Dynamic Programming: Computes high-confidence 1:1 anchor beads in Pass 1, followed by constrained search in Pass 2 to discover complex alignments (1:1, 1:N, N:1, N:M, insertions 0:1, and deletions 1:0).
• Overlap Encoding: Evaluates sliding multi-sentence candidate concatenations against BERT embeddings for superior multi-sentence matching accuracy.
• SRT Timecode Anchoring: Automatically extracts synchronized subtitle cues as hard DP constraints, preventing misalignment drift across hour-long videos.
• Drift Detection: Tracks cumulative index-offset across document progression and automatically flags suspicious passages for human review.

🖥️ Modern Interactive GUI (PySide6 / Qt)

• Visual Bezier Canvas: Renders interactive, confidence-colored bezier curve connectors between source and target segments.
• Bi-directional Synchronized Scrolling: Proportional viewport matching keeps corresponding text aligned on screen regardless of sentence length disparities.
• Full Editing Suite:
  • Click-to-Link: Click a source segment and click a target segment to link or re-assign.
  • Merge (M): Merge adjacent segments on either side with automatic link re-indexing.
  • Split (S): Split long sentences at punctuation or midpoint boundaries.
  • Flagging (C / R / F): Rapidly confirm, reject, or flag beads for QA.
  • 200-Step Undo/Redo (Ctrl+Z / Ctrl+Y): Complete history tracking for all edit actions.
• Top-N Candidate Suggestions: Live cosine-similarity suggestions panel displays the top matching translations for any selected sentence.
• First-Class RTL Support: Native right-to-left layout and Arabic diacritic normalization for Arabic, Hebrew, Urdu, and Persian.

🔍 Comprehensive QA Tools & Analytics

• Real-time Confidence Slider: Dynamically filter low-confidence beads and dim them on the canvas to prioritize review.
• Search & Filter: Search by keyword across source, target, or both sides; filter by QA review flags.
• Jump Navigation: Keyboard shortcuts (Ctrl+↓ / Ctrl+↑) to jump directly to low-confidence links, unmatched segments (Ctrl+N), or flagged items (Ctrl+Shift+F).
• Confidence Distribution Histogram: Integrated 10-bucket visualization of overall corpus alignment quality.
• Quality Dashboard: Comprehensive statistical summary report (bead distributions, mean/median confidence, drift warnings).

⚡ Batch Processing & Workflows

• Batch Alignment Queue: Queue multiple document pairs for automated, background sequential processing.
• Folder Auto-Matching: Automatically pairs source and target directories matching files by filename stems (e.g. ep01_en.srt ↔ ep01_ar.srt).
• Revision Snapshots: Save named point-in-time project milestones and rollback to any previous version.

📁 Industry-Standard Format Support

Format	Import	Export	Notes
SRT Subtitles (.srt)	✅	✅	Preserves timecodes, cleans HTML/bidi markers, automatic timestamp anchoring
Plain Text (.txt)	✅	✅	Supports paragraph-separated and one-sentence-per-line modes
Word Documents (.docx)	✅	—	Extracts clean paragraph text via python-docx
TMX 1.4b (.tmx)	✅	✅	Translation Memory exchange with x-score confidence attributes
XLIFF 1.2 (.xlf, .xliff)	—	✅	Industry-standard CAT tool interchange (Trados, memoQ, Phrase)
Tabular (.csv, .tsv)	—	✅	Delimiter-separated bilingual corpus output
JSON Lines (.jsonl)	—	✅	Machine learning dataset preparation
Text Aligner Project (.tal)	✅	✅	Compact, fast binary format preserving segments, links, and revision snapshots

---

🚀 Quick Start

1. Installation

Clone the repository and install requirements:

git clone https://github.com/adam76064/text-aligner.git
cd text-aligner

# Install dependencies
pip install -r requirements.txt

2. Launching the GUI

Simply run:

python main.py

• On first launch, the Setup Wizard will guide you through model location and language preferences.
• If you have a local copy of Google LaBSE, place it in ./LaBSE (or configure via Align → Model Settings…). Otherwise, the model will be loaded from Hugging Face.

3. Headless CLI Usage

Text Aligner provides a full command-line interface for scripts and server pipelines:

# Align two files and export to TMX
python main.py align examples/sample_en.srt examples/sample_ar.srt --lang-src en --lang-tgt ar --export tmx -o output.tmx

# Export to XLIFF, CSV, or JSONL
python main.py align doc_en.txt doc_ar.txt --lang-src en --lang-tgt ar --export xliff -o output.xliff

# Inspect an existing .tal project file
python main.py info my_project.tal

# Segment a text file into sentences
python main.py segment document.txt --lang ar

---

⌨️ Keyboard Shortcuts Cheatsheet

Shortcut	Action
Click src → Click tgt	Create or re-assign link (linking mode)
Escape	Cancel linking mode
C	Confirm selected link
R	Reject selected link
F	Flag selected link for review
Delete / Backspace	Delete selected link
Shift+Click × 2 → M	Merge two selected adjacent segments
S	Split selected segment at sentence boundary
Ctrl+Z	Undo
Ctrl+Y / Ctrl+Shift+Z	Redo
Ctrl+↓ / Ctrl+↑	Jump to next / previous low-confidence link
Ctrl+N	Jump to next unmatched (nil) bead
Ctrl+Shift+F	Jump to next flagged link
Ctrl+S	Save project (.tal)
F1	Open in-app keyboard shortcuts reference

---

🏗️ Project Architecture

text-aligner/
├── aligner_io/             # Readers & writers for all supported formats
│   ├── readers/            # txt, srt, docx, tmx readers
│   └── writers/            # csv, tmx, xliff, jsonl, txt writers
├── core/                   # Core alignment engine
│   ├── aligner.py          # Two-pass dynamic programming aligner
│   ├── embedder.py         # LaBSE loader & overlap transformer
│   ├── normalizer.py       # Unicode NFKC & Arabic text normalizer
│   ├── project.py          # Canonical Project & Snapshot data model
│   ├── scorer.py           # Confidence scoring & statistics
│   └── segmenter.py        # NLTK sentence splitter with Arabic rule engine
├── gui/                    # PySide6 desktop interface
│   ├── commands/           # QUndoCommand classes (Link, Flag, Merge, Split)
│   ├── dialogs/            # Model Manager, Wizard, Snapshots, Batch Queue, QA
│   ├── models/             # SegmentModel, LinkModel, LinkProxyModel
│   ├── widgets/            # SegmentListView, LinkCanvas, AlignmentEditor, QA dock
│   └── workers/            # Long-lived EmbeddingWorker, AlignmentWorker, BatchWorker
├── scripts/                # Packaging and deployment scripts (PyInstaller & Inno Setup)
├── tests/                  # Complete test suite (93 unit tests)
├── examples/               # Sample subtitle and alignment files
├── main.py                 # Unified application entry point (GUI / CLI)
├── cli.py                  # Command-line interface
└── requirements.txt        # Runtime dependencies

---

📦 Building a Standalone Windows Executable

To package Text Aligner into a standalone Windows application folder:

python scripts/build_windows.py --clean

The output will be created in dist/TextAligner/TextAligner.exe.

To generate a Windows installer setup wizard, open scripts/installer.iss in Inno Setup and click Compile.

---

🧪 Running Tests

The test suite covers normalization, sentence segmentation, two-pass DP alignment, serialization, and all IO formats:

python -m pytest tests/ -v

---

📄 License

This project is licensed under the MIT License.