DeepL Python Library

Warnings

• breaking Dropped support for Python 3.8 and older versions.
  Fix: Upgrade your Python environment to version 3.9 or higher.
• breaking DeepL API deprecation of GET requests to /translate endpoint and query parameter authentication for all endpoints. While the `deepl-python` library versions 1.0.0+ handle this internally, direct API users or those using older versions of the client library (prior to v1.0.0) might be affected.
  Fix: Ensure you are using `deepl-python` library version 1.0.0 or newer. All authentication should be done via the `Authorization` HTTP header, which the library handles automatically when initialized with an `auth_key`. Direct API calls to `/translate` should use POST requests with data in the request body.
• gotcha When using the `custom_instructions` parameter in `translate_text()`, the API will default to the `quality_optimized` model type. Combining `custom_instructions` with the `latency_optimized` model type will result in an error.
  Fix: Avoid explicitly setting `model_type='latency_optimized'` when also providing `custom_instructions`. Allow the default `quality_optimized` or choose a compatible model type.
• gotcha The DeepL API uses different endpoints for Free and Pro accounts. Free users must specify `server_url="https://api-free.deepl.com"` when initializing `DeepLClient`.
  Fix: Initialize the client with the correct `server_url` parameter: `deepl.DeepLClient(auth_key, server_url="https://api-free.deepl.com")` for free accounts, or omit for Pro accounts (default is `https://api.deepl.com`).
• gotcha The generic 'EN' language code for target languages is deprecated. You must use a specific regional variant.
  Fix: Use 'EN-US' for American English or 'EN-GB' for British English as `target_lang`.
• gotcha The library implements retries with exponential backoff for HTTP 429 (too many requests) and 500 (internal server error) responses. However, HTTP 456 (quota exceeded) indicates your account's character limit has been reached and requires user action (upgrading plan or increasing cost control limits).
  Fix: Handle `deepl.exceptions.QuotaExceededException` to inform the user or prompt for account changes. Monitor your DeepL account usage and cost control settings.
• gotcha In `v1.28.0`, the `NotFoundException` error message was improved by removing the misleading 'check server_url' suggestion. This implies that previously, users might have incorrectly tried to change `server_url` for 404 errors that were not related to endpoint configuration.
  Fix: For `NotFoundException` (HTTP 404), ensure the resource (e.g., glossary ID, style rule ID) exists and the API key is correct, rather than assuming a `server_url` misconfiguration. Upgrade to `v1.28.0` or newer for clearer error messages.

Install

• pip install --upgrade deepl Install latest version

Imports

• DeepLClient

  import deepl
  deepL_client = deepl.DeepLClient(auth_key)

  The `Translator` class was used in earlier versions (e.g., prior to v1.0.0 and in some older documentation) but `DeepLClient` is the current and recommended class for interacting with the API.

Quickstart

Initializes the DeepLClient with an API key, preferably from an environment variable, and performs a basic text translation. Note the `server_url` option for DeepL API Free users.

import os
import deepl

auth_key = os.environ.get("DEEPL_AUTH_KEY", "") # Replace with your key or set DEEPL_AUTH_KEY environment variable
if not auth_key:
    print("Please set the DEEPL_AUTH_KEY environment variable.")
    exit(1)

# For DeepL API Free, use server_url="https://api-free.deepl.com"
deepL_client = deepl.DeepLClient(auth_key)

text_to_translate = "Hello, world!"
target_language = "FR"

try:
    result = deepL_client.translate_text(text_to_translate, target_lang=target_language)
    print(f"Translated text: {result.text}")
    print(f"Detected source language: {result.detected_source_lang}")
except deepl.exceptions.DeepLException as e:
    print(f"Error during translation: {e}")