Skip to main content
Tinbox can translate PDF files directly using vision-capable multimodal models, eliminating the need for OCR and preserving the original formatting.

​
Why Vision Models for PDFs?

Traditional PDF translation tools rely on OCR (Optical Character Recognition), which often leads to:
  • Formatting loss
  • Text extraction errors
  • Poor handling of complex layouts
  • Issues with non-standard fonts
Tinbox uses multimodal models to understand PDFs as images, providing more accurate translations while maintaining context.
PDF translation requires a vision-capable model. Text-only models will fail. Supported models include GPT-4o, Claude Sonnet, and Gemini Pro Vision.

​
System Requirements

1

Install Poppler

PDF processing requires the poppler-utils system package:
macOS
brew install poppler
Linux (Ubuntu/Debian)
sudo apt-get install poppler-utils
Windows (Chocolatey)
choco install poppler
2

Install Tinbox with PDF Support

pip install -e ".[pdf]"
# Or install all features
pip install -e ".[all]"
3

Set API Key

Configure your API key for a vision-capable model provider:
export OPENAI_API_KEY="your-api-key"
# Or use Anthropic
export ANTHROPIC_API_KEY="your-api-key"
# Or use Google
export GOOGLE_API_KEY="your-api-key"

​
Basic PDF Translation

PDF files automatically use the page algorithm, which processes documents page-by-page: 
tinbox translate --to es --model openai:gpt-4o document.pdf
The --algorithm page flag is automatically applied for PDF files. You don’t need to specify it manually.

​
Vision-Capable Models

Choose from these supported vision models: 
tinbox translate --to de --model openai:gpt-4o document.pdf

​
Quality Settings

​
Adjusting DPI

Control the quality of PDF rasterization with the --pdf-dpi flag. Higher DPI = better quality but more tokens: 
# Default (200 DPI) - balanced quality and cost
tinbox translate --to es --model openai:gpt-4o document.pdf

# Higher quality (300 DPI) - better for detailed documents
tinbox translate --to es --pdf-dpi 300 --model openai:gpt-4o document.pdf

# Lower quality (150 DPI) - faster and cheaper
tinbox translate --to es --pdf-dpi 150 --model openai:gpt-4o document.pdf
For most documents, the default 200 DPI provides excellent results. Use 300 DPI for documents with small text or complex diagrams.

​
Reasoning Effort

Adjust the model’s reasoning effort for quality vs. cost tradeoffs: 
# Minimal reasoning (default) - faster and cheaper
tinbox translate --to de --reasoning-effort minimal --model openai:gpt-4o document.pdf

# High reasoning - better quality, higher cost
tinbox translate --to de --reasoning-effort high --model openai:gpt-4o document.pdf

​
Large PDF Files

For large PDFs, use checkpointing to enable resume functionality: 
tinbox translate --to es \
  --checkpoint-dir ./checkpoints \
  --model openai:gpt-4o \
  large_document.pdf
If the translation is interrupted, simply run the same command again to resume from the last saved checkpoint.
Learn more about handling large documents in the Large Documents guide.

​
Cost Control

Preview costs before translating and set spending limits: 
# Dry run to estimate costs
tinbox translate --to es --dry-run --model openai:gpt-4o document.pdf

# Set maximum cost limit
tinbox translate --to es --max-cost 10.00 --model openai:gpt-4o document.pdf

​
Common Issues

Error: PDF translation failsThis usually means:
  1. Poppler is not installed - run tinbox doctor to check
  2. You’re using a text-only model - switch to a vision-capable model like GPT-4o
Text extraction quality issues
  • Try increasing DPI: --pdf-dpi 300
  • Use a higher reasoning effort: --reasoning-effort high
  • Ensure you’re using the latest vision model
High costs
  • Lower the DPI: --pdf-dpi 150
  • Use --dry-run first to preview costs
  • Set a budget with --max-cost

​
Complete Example

Here’s a complete workflow for translating a PDF with optimal settings: 
# 1. Check system setup
tinbox doctor

# 2. Estimate costs
tinbox translate --to es --dry-run --model openai:gpt-4o document.pdf

# 3. Translate with checkpointing and cost limit
tinbox translate --to es \
  --model openai:gpt-4o \
  --checkpoint-dir ./checkpoints \
  --max-cost 20.00 \
  --output document_es.pdf \
  document.pdf

# 4. If interrupted, resume
tinbox translate --to es \
  --model openai:gpt-4o \
  --checkpoint-dir ./checkpoints \
  --output document_es.pdf \
  document.pdf

​
Next Steps

Large Documents

Best practices for translating large PDFs

Checkpoints & Resume

Learn about checkpoint functionality

Using Glossaries

Maintain consistent terminology

CLI Reference

Complete command-line reference

Build docs developers (and LLMs) love

Get started for freeTalk to us