DeepL API in Python: Setup Guide + Build vs. Partner Call

Getting an API Key

Sign up for a DeepL API account. The Free plan covers 500,000 characters per month. That's enough for most prototyping and even light production use before you need a paid tier. Your authentication key is in the account dashboard.

pip install --upgrade deepl

Your First Translation

import deepl
translator = deepl.Translator("YOUR_AUTH_KEY")
result = translator.translate_text("Hello, world!", target_lang="DE")
print(result.text)  # Hallo, Welt!

translate_text() also takes a source_lang if you want to skip auto-detection, and a list of strings for batch jobs. Auto-detection is reliable for full sentences but gets shaky on single words or code-mixed text, so pass source_lang explicitly whenever you already know it.

Supported Target Languages

DeepL supports 30+ target languages, with some split into regional variants (EN-US vs EN-GB, for example). Call translator.get_target_languages() at runtime instead of hardcoding a list, since this also tells you which languages support formality control.

for lang in translator.get_target_languages():
    print(lang.code, lang.name, lang.supports_formality)

Controlling Formality

German, French, Spanish, and several other languages distinguish formal from informal address. DeepL is one of the few translation APIs that lets you control this directly:

result = translator.translate_text(
    "Could you send me the file?",
    target_lang="DE",
    formality="more"
)

Accepted values: less, more, prefer_less, prefer_more, or the default. Not every target language supports every level, which is why the supports_formality check above matters before you build a setting around it.

Keeping Terminology Consistent with Glossaries

A generic translation call doesn't know that your product calls a feature "workspace" and not "team space." Glossaries fix that:

glossary = translator.create_glossary(
    "product-terms",
    source_lang="EN",
    target_lang="DE",
    entries={"workspace": "Arbeitsbereich", "teammate": "Teammitglied"}
)

result = translator.translate_text(
    "Invite a teammate to your workspace.",
    target_lang="DE",
    glossary=glossary
)

This is the difference between translation that reads like it came from your team and translation that reads like it came from an API. Worth setting up before you ship anything customer-facing, not after users start noticing inconsistent terminology.

Translating Documents

The API translates whole files (.docx, .pptx, .html, .txt) while keeping the original formatting:

translator.translate_document_from_filepath(
    "input.docx",
    "output_de.docx",
    target_lang="DE"
)

This call is synchronous and blocks until the translation finishes. For anything beyond a handful of documents, use the async pair instead so you're not holding a connection open:

handle = translator.translate_document_upload(
    "input.docx", target_lang="DE"
)
status = translator.translate_document_get_status(handle)

Handling Limits and Failures

usage = translator.get_usage()
if usage.character.limit_reached:
    print("Character limit reached.")

Wrap live calls in a retry with backoff. A translation feature that goes down every time DeepL has a slow minute is worse than not having one:

import time
import deepl

def translate_with_retry(translator, text, target_lang, retries=3):
    for attempt in range(retries):
        try:
            return translator.translate_text(text, target_lang=target_lang)
        except deepl.TooManyRequestsException:
            time.sleep(2 ** attempt)
        except deepl.QuotaExceededException:
            raise
    raise RuntimeError("DeepL translation failed after retries")

QuotaExceededException should never be silently retried. Treat it as a signal to alert someone, not a transient error.

DeepL vs. Google, Azure, and AWS Translation APIs

DeepL isn't the only option, and it isn't the right fit for every project. Here's how the four major translation APIs compare as of this writing:

When DeepL is the right call: your primary markets are European, translation quality matters more than raw language count, and you want formality control without building it yourself.

When it isn't: you need broad coverage across 50+ languages including low-resource ones, or your stack is already deep in one cloud provider.

The API calls above are the easy part. What actually slows teams down once this ships to real users:

Signs you can handle this yourself

Signs it's worth bringing in help

That's the point where some teams bring in a dedicated engineering partner instead of building it solo. If that's where you are: you keep 100% ownership of the code and IP, you approve every engineer who touches your codebase before they start, and you talk directly to the engineers, not through a project manager relay. InApps holds ISO 27001 certification, which matters if the feature touches customer content that needs to stay secure in transit and at rest.

InApps' AI Agent Development team builds the AI-layer work, and the Custom Software Development team handles the architecture around it. For teams already building AI features elsewhere, Generative AI Integration covers wiring LLM-based features into an existing codebase.

Questions about integrating translation, localization, or other AI-driven features into your product? Talk to our team about what a dedicated engineering partner can take off your plate.