Markdown DOCX Translated AI

A TypeScript CLI tool to translate markdown and .docx files while preserving structure, formatting, and images.

Features

Markdown Translation

• Folder translation support - Translate all markdown files in a folder recursively
• Mass translation support - Translate to multiple languages using a language file
• Concurrent processing - Fast translation using parallel section processing (up to 5x faster)
• Folder structure preservation - Maintains original folder structure in language-specific output folders
• Support for complex markdown with multiple heading levels
• Always includes empty sections with trimmed whitespace
• Comprehensive test coverage

.docx Translation (NEW!)

• Full .docx support - Translate Microsoft Word documents while preserving formatting
• Image preservation - Extracts, preserves, and embeds images throughout translation
• Formatting preservation - Maintains bold, italic, headers, lists, and other formatting
• Error recovery - Graceful handling of context length exceeded errors

Usage

Translate Markdown Files

# Translate all markdown files in a folder to Spanish
mdta translate-md ./docs -t "Spanish"

# Translate to multiple languages with custom output folder
mdta translate-md ./docs -t "languages.txt" -o "translated-docs"

# Use custom concurrency and model
mdta translate-md ./docs -t "French" -c 5 -m "openai/gpt-4o"

# Output JSON format for all files
mdta translate-md ./docs -t "Chinese" --json

# more about commands
mdta -h

Translate .docx Files (NEW!)

# Translate all .docx files in a folder to Spanish
mdta translate-docx ./documents -t "es" -o "translated-docs"

# Translate to multiple languages with custom concurrency
mdta translate-docx ./documents -t "languages.txt" -o "output" -c 3

# Preserve formatting and include images
mdta translate-docx ./documents -t "fr" --preserve-formatting --include-images

# Use specific AI model for translation
mdta translate-docx ./documents -t "de" -m "openai/gpt-4o"

Example folder structure:

input-folder/
├── README.md
├── document.docx
├── docs/
│   └── api.md
└── guides/
    └── quickstart.docx

# After translation to Spanish:
translated/
└── es/
    ├── README.md
    ├── document.docx
    ├── docs/
    │   └── api.md
    └── guides/
        └── quickstart.docx

# For .docx-only translation:
translated-docx/
└── es/
    ├── document.docx
    └── guides/
        └── quickstart.docx

Language Files

For mass translation, create a language file (e.g., languages.txt) with one language per line:

# Target languages (one per line)
# Lines starting with # are comments
spanish
french
chinese
japanese
german

When using a language file, the tool will:

• Generate separate output files for each language
• Language codes are supported: 2-letter codes (e.g., "en", "es", "fr", "de") and locale format (e.g., "en-US", "es-ES", "fr-FR").

Note: You can pass language names or codes to -t. Codes are case-insensitive and support both 2-letter and locale formats, e.g., en, en-US, or en-Us.

Environment Setup

Set up your API key (OpenRouter is currently the only supported provider) or use an .env file:

export OPENROUTER_API_KEY="your-api-key-here"

Note: Currently only OpenRouter API keys are supported for AI translation services.

💼 Support & Hiring

If this project is helpful to you, please help by sharing this tool or hiring me(I need a job) or using our services. Learn more about me. I, just like you are, need to support a family.

🙏 Acknowledgments

• The open-source community for various dependencies