examples

DeepL CLI Examples

This directory contains practical, real-world examples of using the DeepL CLI.

Quick Links

Core Commands

Translate:

• Basic Translation - Simple text translation examples
• File Translation & Caching - Translating files with smart caching for text-based formats
• Batch Processing - Translating multiple files
• Context-Aware Translation - Using context for better translation quality
• Document Translation - Translating complete documents (PDF, DOCX, HTML, etc.) while preserving formatting
• Document Format Conversion - Converting document formats during translation
• Structured File Translation - Translating JSON/YAML i18n locale files while preserving structure
• Model Type Selection - Choosing quality vs. speed trade-offs
• XML Tag Handling - Advanced XML/HTML tag handling for fine-tuned translation control
• Custom Instructions - Guide translations with custom instructions for domain, style, and terminology
• Table Output Format - Structured table output for comparing translations across multiple languages
• Cost Transparency - Tracking billed characters for translation cost analysis

Write:

• Writing Enhancement - Using DeepL Write API for grammar, style, and tone improvement

Voice:

• Voice Translation - Real-time speech translation via the Voice API

Resources

• Glossaries - Managing glossaries for consistent terminology

Workflow

• Watch Mode - Real-time file monitoring and auto-translation
• Git Hooks Integration - Automating translation validation in git workflow
• CI/CD Integration - Using DeepL CLI in automated workflows

Configuration

• Configuration - Setting up and managing configuration
• Custom Config Files - Using multiple configuration files for different projects
• Cache Management - Working with the translation cache
• Style Rules - Listing and using pre-configured style rules for consistent translations

Information

• Usage Monitoring - Monitoring API character usage and quota
• Supported Languages - Listing source and target languages supported by DeepL
• Language Detection - Detecting the language of text input
• Shell Completions - Setting up bash, zsh, and fish shell completions

Administration

• Admin API - Managing API keys and viewing organization usage analytics

Getting Started

• Setup Wizard - Interactive first-time setup with deepl init

Advanced

• Advanced Translation - Tag handling versions, beta languages, custom API URLs, and document minification

Prerequisites

All examples assume you have:

1. Installed DeepL CLI (npm install -g deepl-cli or npm link)
2. A DeepL API key configured (deepl auth set-key YOUR_API_KEY)

Running Examples

Each example is a standalone bash script that you can run directly:

# Make executable
chmod +x examples/*.sh

# Run an example
./examples/01-basic-translation.sh

Or follow along and run commands individually.

Running All Examples

You can run all examples at once using the run-all.sh script:

# Run all examples
./examples/run-all.sh

# Run all examples in fast mode (skip slow examples like watch mode)
./examples/run-all.sh --fast

# Stop on first failure
./examples/run-all.sh --stop-on-error

# Show help
./examples/run-all.sh --help

Note: Running all examples will make real API calls and consume your DeepL API quota.

Example Files

The sample-files/ directory contains sample documents used in the examples.

Contributing Examples

Have a useful example? Please contribute! See ../CLAUDE.md for guidelines.