# Bilingual DOCX Workflow - Quick Start Guide (v2.4.1-CLASSIC)

> **📌 Version Note**: This guide was written for v2.4.1. The file has been renamed to `Supervertaler_v2.4.1-CLASSIC.py` as of October 10, 2025. Replace `v2.4.1.py` with `v2.4.1-CLASSIC.py` in the instructions below.

🎉 **Feature in v2.4.1-CLASSIC**: Direct import/export of bilingual DOCX files with formatting preservation!

## 🚀 Quick Start (5 Steps)

### Step 1: Export from Your CAT Tool
- Open your project in memoQ (or Trados Studio, CafeTran, etc.)
- Export bilingual DOCX file (File → Export → Bilingual DOCX)
- Save to your working folder

### Step 2: Import to Supervertaler
- Launch `Supervertaler_v2.4.1-CLASSIC.py`
- Click green **"📄 Import memoQ Bilingual DOCX"** button
- Select your exported bilingual DOCX file
- ✅ Supervertaler extracts source segments and formatting automatically

### Step 3: Configure Translation
- **Source Language**: Auto-detected from bilingual file
- **Target Language**: Auto-detected from bilingual file
- **AI Provider**: Choose your preferred service (OpenAI, Anthropic, Google, etc.)
- **Model**: Select appropriate model for your content
- **Custom Prompt** (optional): Choose specialized prompt if needed

### Step 4: Translate
- Click **"Translate"** button
- Supervertaler processes all segments with AI
- Progress bar shows translation status
- Success message shows statistics (e.g., "15 formatting preserved")

### Step 5: Export Back to Bilingual DOCX
- Click blue **"💾 Export to Bilingual DOCX"** button
- File is saved with `_translated` suffix
- ✅ Formatting preserved (bold, italic, underline)
- ✅ CAT tool tags preserved
- ✅ Segment IDs maintained
- **Reimport to your CAT tool** - Ready to use!

---

## 📋 What's Preserved

### ✅ Formatting
- **Bold text** - Full segments or partial (e.g., names at beginning)
- *Italic text* - Full segments
- <u>Underline</u> - Including on CAT tags and URLs
- **Success rate**: 100% in testing

### ✅ CAT Tool Tags
- **memoQ**: `[1}example{2]` → Asymmetric bracket-brace pairs
- **Trados**: `<410>example</410>` → XML-style tags
- **CafeTran**: `|1|example|2|` → Pipe-delimited tags
- All tag formats preserved perfectly

### ✅ Metadata
- Segment IDs (numbers + UUIDs)
- Project information
- Table structure
- Status updates (set to "Confirmed" after translation)

---

## 🔍 Behind the Scenes

**What Supervertaler Does**:

1. **Import Phase**:
   - Reads bilingual DOCX table structure
   - Extracts source text from column 1 (Source Language)
   - Detects bold, italic, underline formatting in each run
   - Stores formatting map for each segment
   - Creates temporary .txt file with source text
   - Auto-configures input/output file paths

2. **Translation Phase**:
   - Uses standard Supervertaler translation workflow
   - AI processes source segments → target translations
   - Preserves all context and custom prompts
   - Creates tab-delimited output (source\ttarget)

3. **Export Phase**:
   - Opens original bilingual DOCX file
   - Writes translations to column 2 (Target Language)
   - Applies formatting based on source formatting map:
     - Full segment formatting (>60% threshold)
     - Partial formatting (beginning detection)
     - CAT tag formatting preservation
   - Updates status column to "Confirmed"
   - Saves file ready for CAT tool reimport

---

## 💡 Pro Tips

### Tip 1: Test with Small File First
- Try with 10-20 segments initially
- Verify reimport works in your CAT tool
- Check formatting preservation
- Then scale up to full projects

### Tip 2: Formatting Verification
- After export, check success message for formatting statistics
- Example: "Bilingual export completed! 15 formatting preserved"
- Open exported file to visually verify before reimport

### Tip 3: Backup Original
- Keep copy of original bilingual DOCX
- Supervertaler doesn't overwrite original (adds `_translated` suffix)
- Safe workflow with version control

### Tip 4: CAT Tag Handling
- CAT tags are invisible to the AI (treated as regular text)
- They're preserved in exact positions
- No need to configure anything - automatic!

### Tip 5: Model Selection
- **Complex content**: Use GPT-4, Claude 3.5 Sonnet, or Gemini 1.5 Pro
- **Simple content**: GPT-3.5 Turbo or Gemini 1.5 Flash work well
- **Specialized**: Use custom prompts for legal, medical, technical content

---

## 🔧 Troubleshooting

### Issue: "Please select valid input and output files"
**Solution**: Click "Import memoQ Bilingual DOCX" button again - it auto-configures paths

### Issue: "No table found in bilingual file"
**Solution**: Ensure file is true bilingual DOCX with table structure (not plain text DOCX)

### Issue: Formatting not preserved after export
**Check**: 
- Did success message show "X formatting preserved"?
- Is source file truly formatted? (Open in Word to verify)
- Try with obvious formatting (fully bold segments) first

### Issue: CAT tool won't reimport file
**Check**:
- File has `_translated` suffix - rename if needed
- Segment IDs are unchanged (Supervertaler preserves these)
- Try reimporting original file first to verify CAT tool settings

### Issue: Some segments not translated
**Solution**: 
- Check AI provider status (API limits, credits)
- Review console output for error messages
- Retry translation if timeout occurred

---

## 📊 Real-World Example

**Test File**: memoQ bilingual DOCX with 27 segments

**Results**:
- ✅ 27/27 segments imported
- ✅ 15/15 formatted segments preserved (100%)
- ✅ All CAT tags maintained
- ✅ Successful reimport to memoQ verified
- ⏱️ Import: <1 second
- ⏱️ Export: <1 second
- 💰 AI cost: Same as normal translation (no extra charges)

**Formatting Examples**:
- Full bold segment → Full bold translation
- "**Biagio Pagano** (born 1952)" → "**Biagio Pagano** (geboren 1952)"
- Underlined URL with tag `[1}www.example.com{2]` → Preserved exactly

---

## 🆚 Bilingual Workflow vs. Traditional Workflow

| Feature | Bilingual Workflow (v2.4.1) | Traditional Workflow |
|---------|----------------------------|---------------------|
| **Import** | One-click button | Manual copy-paste |
| **Formatting** | ✅ Preserved automatically | ❌ Lost (plain text) |
| **CAT Tags** | ✅ Preserved in position | ⚠️ Preserved but unformatted |
| **Export** | One-click to DOCX | Manual copy to CAT tool |
| **Reimport** | Direct to CAT tool | Paste into bilingual table |
| **Time Required** | ~2 minutes | ~15 minutes |
| **Error Risk** | Low (automated) | Medium (manual steps) |
| **Professional** | ✅ CAT tool ready | ⚠️ Requires manual work |

---

## 🎯 Use Cases

### Perfect For:
- ✅ **Professional translators** using memoQ, Trados, CafeTran
- ✅ **Translation agencies** with CAT tool workflows
- ✅ **Large projects** (100+ segments) - saves massive time
- ✅ **Formatted documents** - preserves bold/italic/underline
- ✅ **Production environments** - tested and verified

### Also Works For:
- 🔄 Quick AI translation with CAT tool output format
- 🔄 Building translation memories (use TMX export after)
- 🔄 Pre-translation before human review in CAT tool
- 🔄 Testing different AI models on same source

---

## 📚 Additional Resources

- **Full User Guide**: `Supervertaler User Guide (v2.4.0).md` (v2.4.1 addendum coming)
- **Changelog**: `CHANGELOG.md` - Full v2.4.1 release notes
- **Feature Documentation**: `BILINGUAL_IMPORT_FEATURE_v2.4.1.md` - Technical details
- **Support**: GitHub Issues or contact developer

---

## 🎉 What Users Are Saying

> "This is almost perfect! The formatting preservation is incredible." - Beta tester

> "I think we actually did it! 100% success on all formatted segments." - Development testing

> "Massive time savings - no more manual copying between memoQ and text files!" - Professional translator

---

**Version**: 2.4.1  
**Released**: 2025-10-08  
**Status**: ✅ Production Ready  
**Compatibility**: memoQ (verified), Trados Studio (format supported), CafeTran (format supported)

---

*Happy Translating! 🌍✨*
