DeepL CLI

DeepL CLI is a fast and lightweight command-line tool for using DeepL API translation from the terminal.

• Supports document translation pdf, docx, txt, etc.
• Supports glossaries
• Precompiled binaries available

Installation

Download

• Download the binary from the Releases

Homebrew

brew install kojix2/brew/deepl-cli

Proxy settings (optional)

export HTTP_PROXY=http://[IP]:[port]
export HTTPS_PROXY=https://[IP]:[port]

Prerequisites

You will need an API key for DeepL. Create one here and set it as an environment variable:

export DEEPL_AUTH_KEY=your_api_key_here

Usage

deepl [options] <file>

Translate text

deepl [options] <file>

Options:

    -i, --input TEXT                 Input text
    -f, --from [LANG]                Source language [AUTO]
    -t, --to [LANG]                  Target language [EN]
    -p, --paste                      Input text from clipboard
    -g, --glossary NAME              Glossary name
    -F, --formality OPT              Formality (default more less)
    -C, --context TEXT               Context (experimental)
    -S, --split-sentences OPT        Split sentences
    -A, --ansi                       Do not remove ANSI escape codes

Note: ANSI escape sequences are removed by default.

Translate documents

To translate a document, use the doc subcommand:

deepl doc [options] <file>

Options for document translation:

    -f, --from [LANG]                Source language [AUTO]
    -t, --to [LANG]                  Target language [EN]
    -g, --glossary NAME              Glossary name
    -F, --formality OPT              Formality (default more less)
    -o, --output FILE                Output file
    -O, --output-format FORMAT       Output file format
    -U, --upload-only                Upload file only
        --handle FILE                Document handle file

Supported file formats.

• docx - Microsoft Word Document
• pptx - Microsoft PowerPoint Document
• xlsx - Microsoft Excel Document
• pdf - Portable Document Format
• htm / html - HTML Document
• txt - Plain Text Document
• xlf / xliff - XLIFF Document, version 2.1

Manage glossaries

For glossary management, use the glossary subcommand:

deepl glossary [options]

Options for glossary management:

    list                             List glossaries
    create                           Create a glossary
    delete                           Delete glossaries
    edit                             Edit glossaries
    view                             View glossaries
    -l, --list                       List glossaries

Improve text (Rephrase)

Use the rephrase subcommand to rewrite text in different styles or tones.

Usage: deepl rephrase [options] <file>

Options for rephrase:

    -i, --input TEXT                 Input text
    -s, --writing-style STYLE        academic business casual default simple
    -t, --tone TONE                  confident diplomatic enthusiastic friendly

Examples

Below are examples for translating text, translating documents, and working with glossaries.

Translate text

To translate the text "Hola mundo" from Spanish (ES) to English (EN):

deepl -i "Hola mundo" -t en        # Translation: Hello world

Or, using standard input:

echo "Hola mundo" | deepl -t en    # Translation: Hello world

Standard input translation is useful for quick references.

git --help | deepl -t fr | less

The man command can also be translated (by removing ANSI escape sequences):

man git | deepl -t de | less

To translate multiple lines, press Ctrl+D when you have finished typing. This is particularly useful when copying and pasting from the clipboard.

deepl -f es
# Hola
# mundo
# Ctrl + D

Translate text from the clipboard:

deepl --paste

You can also pass a text file as an argument:

deepl -t tr foo.txt

It's possible to pass multiple text files:

deepl -t nl foo.txt bar.txt

If you are translating multiple files, you might want to add the filename to the header:

bat --style header *.txt | deepl -t it

To use a glossary for translation:

deepl -g myglossary -f ru

To refer to the original text, you can use tee dev/stderr:

fortune | tee /dev/stderr | deepl

Translate Documents

You can directly translate documents:

deepl doc your.pdf -t pt
# The translated document will be saved as your_PT.pdf

To use a glossary for translation:

deepl doc -g myglossary -f pl

To translate a PDF document and save it in docx format:

deepl doc input.pdf -O docx -o output.docx

Document translation temporarily writes a handle file such as input.pdf.deepl-handle.json and removes it after a successful download, unless --handle FILE is specified. The handle file contains the DeepL document key. Treat it as a secret. It is written with 0600 permissions by default.

To upload a document and check or download it later:

deepl doc -U input.pdf
deepl doc status --handle input.pdf.deepl-handle.json
deepl doc download --handle input.pdf.deepl-handle.json -o output.pdf

To translate multiple files, use Unix commands such as find, xargs, fd:

find . -name "*.pdf" -exec deepl doc -t ja {} \;

ls -1 *.docx | xargs -L1 deepl doc -t ko

fd -e pdf -e docx -x deepl doc -t zh

Glossaries

The DeepL API supports glossaries. See here for the format of the glossary file. The Glossary API has been migrated to version 3.

To create a glossary:

deepl glossary create -n mydic -f en -t pt mydict.tsv

To list glossaries:

deepl glossary list

To list only the names of the glossary:

deepl glossary -l

To use a glossary for text translation:

deepl -g mydict -f en deep.txt

To use a glossary for document translation:

deepl doc -g mydict -f en deep.pdf

To display the contents of the glossary:

deepl glossary view mydict

Rephrase

Change writing style:

bin/deepl rephrase -i "Thanks" -s academic
# Expressions of gratitude are extended.

Change tone:

bin/deepl rephrase -i "Thanks" -t friendly
# Thank you so much! I really appreciate it.

Information

To display a list of available source languages:

deepl -f

To display a list of available target languages:

deepl -t

To output usage information:

deepl -u

# https://api.deepl.com/v2
# character_count: 614842
# character_limit: 1000000000000

Environment Variables

Name	Description
DEEPL_AUTH_KEY	DeepL API authentication key
DEEPL_TARGET_LANG	Default target language
DEEPL_USER_AGENT	User-Agent
EDITOR	Text editor for editing glossary

DeepL CLI automatically detects the target language, but if this does not work, the environment variable DEEPL_TARGET_LANG can be set.

Contributing

• Fork this repository
• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features

Development

Compilation from source code

git clone https://github.com/kojix2/deepl-cli
cd deepl-cli
shards build --release -Dclipboard

A compiled binary file will be created in the bin directory. Installation is simply copying the generated binary.

Clipboard support is enabled only when the Crystal compile-time flag clipboard is set. Without this flag, the --paste option is not available and EasyClip is not required at compile time:

shards build --release
bin/deepl --version # deepl-cli 0.5.4 (clipboard disabled)

To build with clipboard support explicitly:

crystal build src/cli.cr -o bin/deepl --release -D clipboard
# or with shards:
shards build --release -Dclipboard

sudo cp bin/deepl /usr/local/bin

If you encounter a bug, follow the command with the -d option and run it. You can view the backtrace.

deepl doc -d a.pdf

DeepL API Library

• https://github.com/kojix2/deepl.cr/

Difference from the official DeepL CLI

Built for a different audience.

• The official DeepL CLI is mainly intended for developers working with the DeepL API.
• This project is for people who want a lightweight translation tool they can use directly from the terminal.

License

This project is licensed under the MIT License.

Happy translating!