/translate - CODITECT Document Translation Command

Translate documents between languages while preserving original formatting, styles, and structure. Features interactive language detection, multi-format export, and comprehensive quality verification.

Usage

/translate <file> [--from <source_lang>] [--to <target_lang>] [--formats <list>] [options]

Arguments

Argument	Required	Description
<file>	Yes	Path to document (DOCX, PPTX)
--from	No	Source language code (auto-detect if omitted)
--to	No	Target language code (interactive prompt if omitted)
--formats	No	Export formats: docx, html, md, all (default: docx)

Options

Option	Description
-i, --interactive	Interactive mode for language selection
--verify	Run back-translation verification (page-by-page)
--resume <checkpoint>	Resume from checkpoint file
--batch-size <n>	Translation batch size (default: 20)
--output-dir <path>	Custom output directory
--dry-run	Show what would be translated without executing

Language Codes

Code	Language	Code	Language
en	English	pt	Portuguese
es	Spanish	fr	French
de	German	it	Italian
ja	Japanese	ko	Korean
zh-cn	Chinese (Simplified)	ru	Russian
ar	Arabic	hi	Hindi

Examples

Interactive Mode (Recommended)

# Full interactive: detects language, prompts for target, selects formats
/translate documento.docx -i

# Output:
# Detected Language: Portuguese (95.2% confidence)
# Sample text: "O objetivo deste documento é..."
# Is the source language Portuguese? (y/n): y
# Target Language Options:
#   1. English  2. Spanish  3. French ...
# Enter target language: 1
# Export Formats: 1. DOCX  2. HTML  3. Markdown  4. All
# Enter format numbers: 4

Basic Translation

# Portuguese to English with all export formats
/translate documento.docx --from pt --to en --formats all

# Single format output
/translate documento.docx --from pt --to en --formats docx

# Multiple specific formats
/translate documento.docx --from pt --to en --formats docx html

With Page-by-Page Verification

# Translate with comprehensive verification
/translate documento.docx --from pt --to en --verify --formats all

# Generates QC_ASSESSMENT_REPORT.md with:
# - Page-by-page similarity scores
# - Back-translation verification
# - Quality grade (A-F)

Resume Partial Translation

# Resume from checkpoint
/translate documento.docx --resume workspace/02_translation/translated_map.json

Custom Output Directory

# Specify CODITECT workspace location
/translate documento.docx --from pt --to en --output-dir ./CODITECT-Translation-Output

Output

The command produces:

1. CODITECT Workspace - Organized directory with all artifacts
2. Multi-Format Exports - DOCX, HTML, Markdown (optionally PDF)
3. QC Assessment Report - Comprehensive quality verification

Workspace Structure

CODITECT-Translation-<timestamp>/
├── 00_original_backup/          # Immutable backup of source
│   └── documento.docx
├── 01_extraction/               # Parsed content with metadata
│   └── content_map.json
├── 02_translation/              # Translation state (resumable)
│   └── translated_map.json
├── 03_verification/             # Page-by-page verification
│   └── verification_results.json
├── 04_exports/                  # All output formats
│   ├── documento-EN.docx
│   ├── documento-EN.html
│   └── documento-EN.md
└── 05_qc_reports/               # Quality assessment
    └── QC_ASSESSMENT_REPORT.md

Export Formats

Format	Description	Use Case
DOCX	Original formatting preserved	Business documents, editing
HTML	Web-ready with styling	Online publishing, email
Markdown	Plain text, lightweight	Documentation, version control
PDF	Print-ready (manual convert)	Final distribution

Quality Control

Automatic Checks

• Token ratio validation (translation not too short/long)
• Merged word detection and fixing
• Structural integrity (paragraph/table counts match)

Verification Mode

• Back-translation similarity scoring
• Flags items with <70% similarity for review
• Generates detailed verification report

Error Handling

Error	Resolution
API rate limit	Automatic exponential backoff
Translation timeout	Retry with smaller batch
Empty translation	Retry, then flag for review
Format corruption	Restore from checkpoint

Best Practices

1. Always backup - Original is automatically backed up
2. Use --verify for critical documents
3. Review QC report before distributing
4. Check formatting on complex documents with many styles
5. Use --batch-size 10 for very large documents

Execution Protocol

When /translate is invoked:

1. Detect Format - DOCX or PPTX
2. Create Workspace - Backup, extraction, translation, verification, final folders
3. Extract Content - Parse document into translation units with formatting metadata
4. Translate - Process in batches with micro-QC
5. Verify (if --verify) - Back-translate sample and score similarity
6. Rebuild - Inject translations preserving formatting
7. Generate Report - QC summary with statistics

Related Commands

Command	Purpose
/docx	DOCX manipulation utilities
/pptx	PPTX manipulation utilities
/pdf	PDF processing

Related Components

Component	Type	Purpose
document-translation-specialist	Agent	Full translation workflow
document-translation	Skill	Translation pipeline code
qa-reviewer	Agent	Quality verification

---

Track: F (Documentation) Version: 1.0.0 Author: CODITECT Team