DeepL Python Library

Mustache templates often contain embedded tags (e.g., {{name}}) and HTML tags (e.g., <b>) that should not be translated. This example demonstrates a pattern for translating these templates by using DeepL's XML tag-handling capability.

To prevent the translation engine from altering the Mustache syntax, the process follows these steps:

1. Parse the template to separate literal text from Mustache tags.
2. Replace Mustache tags with unique placeholder XML tags (e.g., <m id=0 />).
3. Translate the resulting XML string via the DeepL API, which preserves the XML structure.
4. Parse the translated XML and swap the placeholder tags back for the original Mustache tags.

This ensures that Hello {{name}}. You have just won <b>{{value}} dollars</b>! becomes Hallo {{name}}. Sie haben gerade <b>{{value}} Dollar</b> gewonnen! in German.

DeepL has introduced v3 Glossary APIs that move beyond the monolingual model (where a glossary is tied to a single source_lang and target_lang).

In the new model, a single glossary contains one or more glossary dictionaries. Each dictionary is a self-contained unit with its own source_lang, target_lang, and set of entries. This allows a single glossary object to manage multiple language pairs simultaneously.

Key data models:

• MultilingualGlossaryInfo: The top-level object representing the entire glossary, containing a list of MultilingualGlossaryDictionaryInfo objects.
• MultilingualGlossaryDictionaryEntries: The object used when creating or defining the contents of a specific dictionary within a glossary.

To run the Mustache translator example, follow these steps:

1. Install the library: Ensure the deepl Python library is installed.
2. Set Authentication: Define your DeepL authentication key as the DEEPL_AUTH_KEY environment variable.
3. Execute: Run the script from the project root, specifying the target language with the --to flag.

Use the --help flag to see available command-line arguments.

To use the real-time audio translation CLI, you need to install the dependencies using uv or poetry. If you intend to use live microphone input, you must also install the mic dependency group and ensure your system has the necessary pyaudio system packages (e.g., portaudio19-dev on Debian/Ubuntu or portaudio on MacOS).

Standard Installation:

cd examples/voice/cli
uv sync
# or
poetry install

Installation with Microphone Support:

uv sync --group mic
# or
poetry install --with mic

The CLI requires your DeepL authentication key to be set as an environment variable named DEEPL_AUTH_KEY.

export DEEPL_AUTH_KEY=your-api-key-here

To use the JSON translation example, ensure you have installed the deepl library and set your DEEPL_AUTH_KEY environment variable. You can then run the script from the terminal, passing the target language with --to and the JSON string as an argument.

export DEEPL_AUTH_KEY=f63c02c5-f056-...
python examples/json --to de '{"greeting": "Hello!"}'

You can install the library from PyPI using pip. It is recommended to use the --upgrade flag to ensure you have the latest version.

If you are developing the library itself and need to manage dependencies, use poetry install.

pip install --upgrade deepl

To use the DeepL API, import the deepl package and instantiate a DeepLClient using your API authentication key. For production environments, it is recommended to fetch the key from an environment variable or configuration file rather than hard-coding it.

import deepl

auth_key = "YOUR_AUTH_KEY"
deepl_client = deepl.DeepLClient(auth_key)

import deepl

auth_key = "f63c02c5-f056-..."  # Replace with your key
deepl_client = deepl.DeepLClient(auth_key)

result = deepl_client.translate_text("Hello, world!", target_lang="FR")
print(result.text)  # "Bonjour, le monde !"

When translating documents, you receive a DocumentHandle to track the request. You can use this handle to check the DocumentStatus.

DocumentStatus provides:

• status: The current state (see Status enum).
• seconds_remaining: Estimated time until completion.
• billed_characters: Characters billed for the document.
• error_message: Description of any error encountered.

Use the .ok property to check if the status is not Status.ERROR, and .done to check if it is Status.DONE.

The DeepLClient can be configured with several parameters during instantiation:

• server_url: Override the default DeepL API URL (useful for testing).
• proxy: Configure a proxy (string URL or dictionary compatible with requests).
• verify_ssl: Boolean to enable/disable SSL certificate verification (defaults to True).
• send_platform_info: Boolean to opt-out of sending anonymous platform information (defaults to True).

Global Configuration (via deepl.http_client):

• max_network_retries: Set the number of automatic retries for failed HTTP requests (default is 5).
• user_agent: Set a custom User-Agent string.
• min_connection_timeout: Set connection timeout.