deepl-cli

This README is the one indexed from the repository at its latest ref, not from the tag for this version.

# DeepL CLI

[![build](https://github.com/kojix2/deepl-cli/actions/workflows/build.yml/badge.svg)](https://github.com/kojix2/deepl-cli/actions/workflows/build.yml)
[![Lines of Code](https://img.shields.io/endpoint?url=https%3A%2F%2Ftokei.kojix2.net%2Fbadge%2Fgithub%2Fkojix2%2Fdeepl-cli%2Flines)](https://tokei.kojix2.net/github/kojix2/deepl-cli)

DeepL CLI is a fast and lightweight command-line tool for using [DeepL API](https://www.deepl.com/pro-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](https://github.com/kojix2/deepl-cli/releases)

### Homebrew

[![deepl-cli (macos)](https://github.com/kojix2/homebrew-brew/actions/workflows/deepl-cli-macos.yml/badge.svg)](https://github.com/kojix2/homebrew-brew/actions/workflows/deepl-cli-macos.yml)

```sh
brew install kojix2/brew/deepl-cli
```

### Proxy settings (optional)

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

## Prerequisites

You will need an API key for DeepL. [Create one here](https://www.deepl.com/pro-api) and set it as an environment variable:

```sh
export DEEPL_AUTH_KEY=your_api_key_here
```

## Usage

```sh
deepl [options] <file>
```

### Translate text

```sh
deepl [options] <file>
```

Options:

```txt
    -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:

```sh
deepl doc [options] <file>
```

Options for document translation:

```txt
    -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:

```sh
deepl glossary [options]
```

Options for glossary management:

```txt
    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.

```sh
Usage: deepl rephrase [options] <file>
```

Options for rephrase:

```txt
    -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):

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

Or, using standard input:

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

Standard input translation is useful for quick references.

```sh
git --help | deepl -t fr | less
```

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

```sh
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.

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

Translate text from the clipboard:

```sh
deepl --paste
```

You can also pass a text file as an argument:

```sh
deepl -t tr foo.txt
```

It's possible to pass multiple text files:

```sh
deepl -t nl foo.txt bar.txt
```

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

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

To use a glossary for translation:

```sh
deepl -g myglossary -f ru
```

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

```sh
fortune | tee /dev/stderr | deepl
```

### Translate Documents

You can directly translate documents:

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

To use a glossary for translation:

```sh
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:

```sh
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`:

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

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

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

### Glossaries

The DeepL API supports glossaries. See [here](https://developers.deepl.com/docs/api-reference/glossaries#formats) for the format of the glossary file. The Glossary API has been migrated to version 3.

To create a glossary:

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

To list glossaries:

```sh
deepl glossary list
```

To list only the names of the glossary:

```sh
deepl glossary -l
```

To use a glossary for text translation:

```sh
deepl -g mydict -f en deep.txt
```

To use a glossary for document translation:

```sh
deepl doc -g mydict -f en deep.pdf
```

To display the contents of the glossary:

```sh
deepl glossary view mydict
```

### Rephrase

Change writing style:

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

Change tone:

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

### Information

To display a list of available source languages:

```sh
deepl -f
```

To display a list of available target languages:

```sh
deepl -t
```

To output usage information:

```sh
deepl -u

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

### Environment Variables

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>DEEPL_AUTH_KEY</td>
      <td>DeepL API authentication key</td>
    </tr>
    <tr>
      <td>DEEPL_TARGET_LANG</td>
      <td>Default target language</td>
    </tr>
    <tr>
      <td>DEEPL_USER_AGENT</td>
      <td>User-Agent</td>
    </tr>
    <tr>
      <td>EDITOR</td>
      <td>Text editor for editing glossary</td>
    </tr>
  </tbody>
</table>

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

```sh
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:

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

To build with clipboard support explicitly:

```sh
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.

```sh
deepl doc -d a.pdf
```

### DeepL API Library

- [https://github.com/kojix2/deepl.cr/](https://github.com/kojix2/deepl.cr/)

## Difference from the official DeepL CLI

Built for a different audience.

- The official [DeepL CLI](https://github.com/DeepLcom/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!