# Translate docx

<p align="left" width="250">
    <a href="https://github.com/pixelprotest/translate-docx/actions">
        <img src="https://github.com/pixelprotest/translate-docx/actions/workflows/tests.yml/badge.svg" alt="Tests Status">
    </a>
    <a href="">
        <img src="https://img.shields.io/github/v/release/pixelprotest/translate-docx">
    </a>
    <a href="">
        <img src="https://img.shields.io/badge/python-3.13%20--%203.14-blue">
    </a>
    <a href="https://github.com/pixelprotest/translate-docx/blob/main/LICENSE">
        <img src="https://img.shields.io/badge/license-MIT-blue?style=flat">
    </a>
</p>

A CLI tool and python library for translating `.docx` files, with a focus on preserving all text formatting.

## Key Features

- **Lossless round-trip** - Extract and rebuild preserves all formatting
- **Citation preservation** - Superscripts (references) stay in original language
- **Pluggable translators** - Use any translation backend
- **Section-based** - Documents split by bold headers automatically

## Installation

```bash
pip install translate-docx
```

## Usage from Command Line 

```bash
# Basic translation e.g. from spanish to english
translate-docx input.docx output.docx -s es -t en

# With options
translate-docx input.docx output.docx -s es -t en --delay 1.0 --verbose

# Show document info
translate-docx info document.docx
```

## Usage as a Package
```python
from translate_docx import (
    extract_document, 
    translate_document, 
    rebuild_document, 
    GoogleTranslatorWrapper
)

doc = extract_document("input.docx")
translator = GoogleTranslatorWrapper(delay_between_calls=0.5, max_retries=3)
translated = translate_document(doc, translator, "es", "en")
rebuild_document(translated, "output.docx", template_path="input.docx")
```

## Supported Language Codes
```
ar - Arabic
zh - Chinese (Simplified)
nl - Dutch
en - English
fr - French
de - German
it - Italian
ja - Japanese
ko - Korean
pl - Polish
pt - Portuguese
ru - Russian
es - Spanish
tr - Turkish
```

## Known Limitations
- Tables and images not yet supported
- Headers/footers not yet supported
- Translated text may reflow (layout not guaranteed)

## License

MIT

## More Examples

See the `examples/` directory for complete runnable scripts.
