DeepL CLI

DeepL CLI is a simple command-line tool for the DeepL API, written in Crystal.

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

Installation

Download

• Download the Linux binary from the Releases
• Unzip: tar -xvf deepl.tar.gz
• Move to the executable path: sudo mv deepl /usr/local/bin/

Note: Binaries for Linux are statically linked. For macOS, we recommend using homebrew.

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

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
    -p, --language-pairs             List language pairs

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

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

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.

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

To list the languages in which glossaries can be created:

deepl glossary -p

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

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

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/

License

This project is licensed under the MIT License.

Happy translating!