dptran

English | 日本語版

dptran is a command-line tool and library for using the DeepL API, written in Rust.

Features

Binary CLI

• Translate via CLI, interactive input, pipeline, or file/editor input
• Support for multi-line input, output to file, and removing line breaks
• DeepL API Free / Pro support
• Language code lookup and character usage tracking
• Glossary utilization (v2.4.0 or later)
• Result caching

Library

• API client for DeepL translation
• Language code and usage queries
• Glossary registration and management (v2.4.0 or later)

Installation

Binary crate

cargo install dptran

Library crate

dptran includes dependencies for the binary CLI by default. To use only the library, please disable default features.

cargo add dptran --no-default-features

Basic Usage

Set API Key

dptran api --api-key-free [Your API key]
# or set env: export DPTRAN_DEEPL_API_KEY=[Your API key]

If you want to use DeepL Pro API key, set it like this:

dptran api --api-key-pro [Your API key]
# or set env: export DPTRAN_DEEPL_API_KEY_PRO=[Your API key]

Translate

# simple translation (translate to default target language)
dptran Hello
こんにちは

# translate with target language
dptran -t FR Hello
Bonjour

# translate with source language
dptran -f EN -t JA Hello
こんにちは

# translate interactively (original text is not given at startup)
dptran -t JA
> Hello
こんにちは
> /to FR   # Change target language to French
> Hello
Bonjour
> /quit    # To exit interactive mode

# translate from a file and output to another file
dptran -i text.txt -o translated.txt
# The file `translated.txt` will contain the translated text.

# translate with a pipeline
echo "Hello" | dptran -t ZH
您好

# translate with line breaks removed
dptran -r "Hello
everyone!"
皆さん、こんにちは！

# translate from an editor (like vim, emacs. must be set in config)
dptran -e
# Editor will open

Options

• -t [LANG] Set the default target language
• -f [LANG] Set the default source language
• -i [FILE] Input from file
• -o [FILE] Output to file
• -r Remove line breaks
• -g [GLOSSARY_NAME] Use glossary

For more options and detailed usage, run:

dptran -h

Subcommands

• usage : Show character usage
• list : Show list of supported languages (-s for source languages, -t for target languages)
• glossary : Manage glossaries (create, delete, list, add/remove word pairs)
• config : General settings such as default target language and editor command
• api : API settings such as API keys and endpoint URLs
• cache : Cache settings such as enabling/disabling cache, setting max entries, and clearing cache
• help : Print this message or the help of the given subcommand(s)

Configuration

Change default target language:

dptran config --target-lang JA

Reset all settings:

dptran config --clear-all

Glossary Settings (glossaries API)

You can create and manage glossaries using the glossaries API to customize translations for specific words and phrases.

1. Create a glossary:

dptran glossary --create --name my_glossary

2. Add word pairs to the glossary:

dptran glossary --name my_glossary --source-lang EN --target-lang FR --add-word-pairs "Hello" "Bonjour" "Goodbye" "Au revoir"

3. List glossaries:

dptran glossary --list

4. Use the glossary (-g option):

dptran -f EN -t FR -g my_glossary Hello

5. Remove the glossary:

dptran glossary --remove --name my_glossary

Setting API Endpoint

You can set the API endpoint URL using the api subcommand:

dptran api --endpoint-of-translation <ENDPOINT_OF_TRANSLATION>
dptran api --endpoint-of-usage <ENDPOINT_OF_USAGE>
dptran api --endpoint-of-langs <ENDPOINT_OF_LANGUAGES>

Then you can use dptran with your own API endpoint, e.g., a local LLM server.
Note that the API endpoints must be compatible with the DeepL API specification.

Development & Testing

Run unit tests. To run tests that require a real DeepL API key, set the environment variable DPTRAN_DEEPL_API_KEY:

export DPTRAN_DEEPL_API_KEY=[API key]
cargo test -- --test-threads=1

Some require dummy API server to be running.
The dummey server will be run at http://localhost:8000/ by default.

pip3 install -r requirements.txt
uvicorn dummy_api_server.main:app --reload

Documentation

Crate page: https://crates.io/crates/dptran

Library docs: https://docs.rs/dptran

License

Licensed under either of:

• MIT License
• Apache License 2.0

Release Notes

• v2.4.0 (2025-12-30)

  • Binary CLI: Add support for Glossaries API
  • Binary CLI: Add validation to prevent incorrect option combinations
  • Binary CLI: Improve error handling
  • Binary CLI: Add dptran usage command
  • Library: Add support for Glossaries API
  • Library: Comply with DeepL API query structures. Support specifying all parameters for supported APIs.

• v2.3.4 (2025-10-04)

  • Binary CLI: Support inputting commands in interactive mode (/quit, /help, /from, /to, etc.)

• v2.3.3 (2025-09-07)

  • Binary CLI: Add clear-all and show options to API settings, change config --clear-all to not reset these API settings
  • Binary CLI: Improve error handling in do_translation()
  • Library: Modularize each API implementation in translate, languages, and usage

• v2.3.2 (2025-07-07)

  • Binary CLI: Fix issue where endpoint settings were not reflected in usage and lang commands
  • Library: Fix query encoding when sending requests

• v2.3.1 (2025-07-01)

  • Binary CLI & Library: Any api endpoint can be used
  • Binary CLI: Split set subcommand into config, api, and cache subcommands
  • Test: Use the python dummy API server for some tests