Trazlo — PDF Toolkit

Work in progress / En desarrollo

Privacy-first CLI tool for PDF operations. No data leaves your machine.

Trazlo is an offline alternative to services like iLovePDF. All processing happens locally on your computer — your files are never uploaded anywhere. Built for people who care about their data privacy, especially when handling sensitive documents.

---

Español

Herramienta CLI con enfoque en privacidad para operaciones con PDF. Todo el procesamiento ocurre localmente en tu computadora — tus archivos nunca se suben a ningún lado. Construida para personas que se preocupan por la privacidad de sus datos, especialmente al manejar documentos sensibles.

---

Features / Funcionalidades

Command / Comando	Description / Descripción
merge	Combine multiple PDFs into one / Unir varios PDFs en uno
split	Extract page ranges / Extraer rangos de páginas
img2pdf	Convert images (JPG/PNG/TIFF/BMP) to PDF / Convertir imágenes a PDF
pdf2img	Convert PDF pages to images / Convertir páginas de PDF a imágenes
compress	Reduce PDF file size / Reducir tamaño de archivo PDF
docx2pdf	Convert Word to PDF — requires LibreOffice / Convierte Word a PDF — requiere LibreOffice
pdf2docx	Convert PDF to Word — requires LibreOffice / Convierte PDF a Word — requiere LibreOffice

---

System Dependencies / Dependencias del sistema

Not all features require external programs. Here is what each one needs:

No todas las funciones requieren programas externos. Esto es lo que necesita cada una:

Program / Programa	Required for / Requerido para	Status
LibreOffice	docx2pdf, pdf2docx	Required / Requerido
Ghostscript	compress (advanced)	Optional / Opcional — pikepdf fallback included

pypdfium2 bundles its own PDF rendering engine. No Poppler installation needed.

pypdfium2 incluye su propio motor de renderizado. No se necesita instalar Poppler.

Install system dependencies / Instalar dependencias del sistema:

# Arch Linux
sudo pacman -S ghostscript libreoffice-still

# Debian / Ubuntu
sudo apt install ghostscript libreoffice

# Fedora
sudo dnf install ghostscript libreoffice

Without Ghostscript, compression still works via pikepdf (less aggressive). Without LibreOffice, docx2pdf and pdf2docx are unavailable — the rest of Trazlo works normally.

Sin Ghostscript, la compresión sigue funcionando con pikepdf (menos eficiente). Sin LibreOffice, docx2pdf y pdf2docx no estarán disponibles — el resto de Trazlo funciona con normalidad.

---

Installation / Instalación

Option 1 — pipx (recommended / recomendado)

Installs Trazlo globally. The trazlo command is available in every new terminal without activating anything.

Instala Trazlo globalmente. El comando trazlo estará disponible en cualquier terminal sin activar nada.

git clone https://github.com/Sebastian-Code-0/Trazlo.git
cd Trazlo
pipx install .

If pipx is not installed / Si pipx no está instalado:

# Arch Linux
sudo pacman -S python-pipx

# Debian / Ubuntu
sudo apt install pipx

# Or via pip / O via pip
pip install --user pipx

Option 2 — setup.sh (guided / asistido)

Interactive script that detects your OS, installs system dependencies, and sets up Trazlo automatically.

Script interactivo que detecta tu sistema operativo, instala las dependencias del sistema y configura Trazlo automáticamente.

git clone https://github.com/Sebastian-Code-0/Trazlo.git
cd Trazlo
bash setup.sh

The script will ask what you want to install and will prefer pipx if available, falling back to a local virtual environment with clear instructions.

El script pregunta qué deseas instalar y usa pipx si está disponible, con fallback a un entorno virtual local con instrucciones claras.

Option 3 — Manual virtual environment / Entorno virtual manual

git clone https://github.com/Sebastian-Code-0/Trazlo.git
cd Trazlo

python3 -m venv env
. env/bin/activate          # Linux / Mac (bash and zsh / bash y zsh)

pip install -e .            # base install
pip install -e ".[dev]"     # with test suite / con suite de tests

Activate the environment every time you open a new terminal / Activa el entorno cada vez que abras una terminal nueva:

. /path/to/Trazlo/env/bin/activate

---

Usage / Uso

Interactive menu / Menú interactivo:

trazlo

Direct commands / Comandos directos:

# Merge PDFs / Unir PDFs
trazlo merge -i file1.pdf file2.pdf file3.pdf -o merged.pdf

# Extract pages / Extraer páginas (single, range, open-ended / individual, rango, abierto)
trazlo split -i input.pdf -p 1-3,5,7- -o output.pdf

# Compress / Comprimir
trazlo compress -i large.pdf -o small.pdf --quality ebook

# Images to PDF / Imágenes a PDF
trazlo img2pdf -i photo1.jpg photo2.png -o album.pdf

# Whole folder / Carpeta completa
trazlo img2pdf -d ./photos/ -o album.pdf

# PDF to images / PDF a imágenes
trazlo pdf2img -i document.pdf -o ./pages/ --dpi 300 --fmt png

# DOCX to PDF — requires LibreOffice / requiere LibreOffice
trazlo docx2pdf -i report.docx -o report.pdf

# PDF to DOCX — requires LibreOffice / requiere LibreOffice
trazlo pdf2docx -i report.pdf -o report.docx

Quality levels for compression / Niveles de calidad para compresión:

Value	Use case / Uso
screen	Screen display, smallest size / Pantalla, tamaño mínimo
ebook	E-readers, good balance / E-readers, buen balance (default)
printer	Print quality / Calidad de impresión
prepress	High-quality print / Impresión de alta calidad
default	Ghostscript default / Por defecto de Ghostscript

---

Tech Stack

Language:       Python ≥ 3.10
Package name:   trazlo
Entry point:    trazlo

Python libs:    pypdf · pikepdf · pypdfium2 · img2pdf · pdf2docx · docx2pdf
System deps:    Ghostscript (optional) · LibreOffice (for DOCX functions)

---

Project Structure / Estructura del proyecto

Trazlo/
│
├── pdf_toolkit/          ← Python package / paquete Python
│   ├── cli.py            ← entry point, argument parsing and interactive menu
│   │                        punto de entrada, parseo de argumentos y menú interactivo
│   ├── merge.py          ← merge PDFs / une PDFs
│   ├── split.py          ← split by page ranges / divide por rangos de páginas
│   ├── compress.py       ← compress (Ghostscript or pikepdf fallback)
│   │                        comprime (Ghostscript o pikepdf como fallback)
│   ├── images.py         ← images ↔ PDF (via pypdfium2 and img2pdf)
│   ├── converters.py     ← DOCX ↔ PDF (via LibreOffice)
│   └── utils.py          ← internal helpers: subprocess, validation
│                            helpers internos: subprocess, validación
│
├── tests/                ← pytest test suite (37 tests)
├── pyproject.toml        ← package declaration: name, version, deps, entry point
│                            declaración del paquete: nombre, versión, deps, entry point
├── setup.sh              ← guided setup script (detects Arch / Debian / Fedora)
│                            script de instalación asistida (detecta Arch / Debian / Fedora)
├── requirements.txt      ← Python dependencies (mirrors pyproject.toml)
└── LICENSE               ← GPL v3

---

Roadmap

• OCR support for scanned PDFs / Soporte OCR para PDFs escaneados
• Password protection & encryption / Protección con contraseña y cifrado
• Page rotation & reordering / Rotación y reordenamiento de páginas
• Publish to PyPI / Publicar en PyPI

---

Author / Autor

Created by sv0

❤️ Support / Apóyame

If you find this tool useful, consider giving it a ⭐ on GitHub!

Si esta herramienta te resulta útil, considera darle una ⭐ en GitHub.

License / Licencia

This project is licensed under the GNU General Public License v3.0.

Este proyecto está bajo la Licencia Pública General de GNU v3.0.