Getting Started with the DeepL Language Translation API in Python

Sep 27th, 2021 11:00am by Mike Winters and Daniel Jones

Daniel Jones is a developer advocate at DeepL focusing on helping fellow developers create great things using the DeepL API. He has a background in Mechatronics Engineering, and object perception using Lidar for autonomous driving. He relocated from New Zealand to Hamburg, Germany in 2013.

There’s an API for almost everything these days, and language translation is no exception. In this tutorial, we’ll show you how to get started with the DeepL language translation API using our official open source Python client library.

Before we do that, we’ll answer a couple of questions: what is DeepL, and what are the use cases for a language translation API?

DeepL is our machine translation company with a mission to eliminate language barriers worldwide using artificial intelligence. We might not be the only language translation API out there, but we’re proud of the fact that we achieve some of the best translation quality worldwide according to blind tests and that we take data privacy really seriously. If you’d like to see what we’re all about, our web translator is a good place to get started.

The rest of this piece will focus on our API, which supports 24 source and target languages and makes it possible for developers to build translation directly into their products.

Common use cases for an API like DeepL’s include but are not limited to:

Website translation, especially for e-commerce companies or publishers with a large catalog of content that changes frequently
Cross-language communication via chat apps or customer service platforms, where content is user generated and needs to be translated on the fly
Building a custom document translation tool for use within a company (in addition to text, the DeepL API lets you translate Microsoft Word, PowerPoint, HTML, and plain text documents)

Let’s get started.

First Steps

Mike Winters

Mike Winters has spent the last seven years in product and community management roles for the companies behind products such as Apache Flink, Camunda, Garden.io, and now DeepL. He spends lots of time thinking and writing about the impact of emerging technologies on organizations of all shapes and sizes. An Ohio native, he's currently based in Berlin, Germany.

This tutorial was designed so that you can follow along for free — you’ll just need to create a DeepL API account first so that you can get access to an authentication key (note: at this time, it’s possible for users in these countries to create DeepL API Free and Pro accounts).

And we chose to stick to the basics in this tutorial, with the goal being to introduce what’s possible with our language translation API and hopefully spark an idea or two about how you might apply it to your use cases.

We’ll include the code snippets you need for every step of the tutorial, but there are a couple pages you might want to have open in separate tabs while you’re working:

The GitHub repo for the Python client library (the README includes documentation for the Python library along with many of the examples we’ll walk through below)
The DeepL API docs, which covers the REST interface that the Python library is built around and would be helpful if you’d like to experiment in a language besides Python

First step: you’ll need to install the library from PyPI using pip.

pip install --upgrade deepl

1	pip install --upgrade deepl

From this point forward, we’ll be writing Python code. Create a new file named deepl_tutorial.py (and be sure that neither your file nor the parent directory is named deepl).

The first thing we’ll need our script to do is create a translator object. This is where you’ll need the DeepL authentication key, which you can find in your account.

import deepl 

translator = deepl.Translator("YOUR_AUTH_KEY")

import deepl

translator = deepl.Translator("YOUR_AUTH_KEY")

Translating Text

It’s only appropriate that we’d kick things off with a “Hello, world!” example, so the first thing we’ll do is translate “Hello, world!” from English to German.

You’ll notice that we use the target_lang parameter to set our target language. DeepL can automatically detect the source language, so we don’t specify it below. But you’re also able to set the source language explicitly using the source_lang parameter.

result = translator.translate_text("Hello, world!", target_lang="DE") 

print(result) # “Hallo, Welt!”

result = translator.translate_text("Hello, world!", target_lang="DE")

print(result) # “Hallo, Welt!”

It’s also possible to translate multiple texts into the same target language at once. Here, we’ll translate Japanese and Spanish into US English (once again relying on DeepL’s language detection capabilities to identify the source languages).

result = translator.translate_text(["お元気ですか？", "¿Cómo estás?"], target_lang="EN-US")

1	result = translator.translate_text(["お元気ですか？", "¿Cómo estás?"], target_lang="EN-US")

We’ll print the results, and we’ll also verify the detected source languages.

print(result[0].text) # "How are you?"
print(result[0].detected_source_lang) # "JA" 

print(result[1].text) # "How are you doing?"
print(result[1].detected_source_lang) # "ES"

print(result[0].text) # "How are you?"

print(result[0].detected_source_lang) # "JA"

print(result[1].text) # "How are you doing?"

print(result[1].detected_source_lang) # "ES"

Supported Source and Target Languages

You’ve seen so far that DeepL can translate German, US English, Japanese, and Spanish, but in the introduction, we promised more than 20 source and target languages.

You can find the full list of supported source and target languages plus the two-letter language codes in the documentation.

It’s also possible to use the API to get lists of supported source and target languages.

print("Here's a list of supported source languages:") 
for language in translator.get_source_languages(): 
    print(f"{language.code} ({language.name})") # Example: "DE (German)"

print("Here's a list of supported target languages:") 
for language in translator.get_target_languages(): 
    print(f"{language.code} ({language.name})") # Example: "DE (German)"

print("Here's a list of supported source languages:")

for language in translator.get_source_languages():

print(f"{language.code} ({language.name})") # Example: "DE (German)"

print("Here's a list of supported target languages:")

for language in translator.get_target_languages():

print(f"{language.code} ({language.name})") # Example: "DE (German)"

Monitoring Usage

You might occasionally want to check in on how many characters you’ve translated — our API Free plan allows for 500,000 characters per month, while our API Pro plan offers volume-based pricing and no character limits.

usage = translator.get_usage() 
if usage.character.limit_exceeded: 
    print("Character limit exceeded.") 
else: 
    print(f"Character usage: {usage.character}")

usage = translator.get_usage()

if usage.character.limit_exceeded:

print("Character limit exceeded.")

else:

print(f"Character usage: {usage.character}")

Document Translation (and Formality, too)

We mentioned that the DeepL API also lets you translate Microsoft Word, PowerPoint, HTML, and plain text documents. To keep the tutorial simple, we’ll use an example with a text file.

Here’s a hypothetical use case. As non-native German-speakers who live in Germany, we might need to send emails to our landlords in German. Just to be sure our translations are precise, we’d like to check them with DeepL.

(As an aside: this is a small-scale example for the sake of the tutorial. However, this feature can be helpful for larger tasks, like translating a website’s worth of HTML files or a large collection of Word documents.)

I’m going to translate a text file with the following content:

Dear Sir or Madam,

I would like to inform you that we still do not have hot water in our apartment, now for five days in a row. Seeing as it's the middle of January, could you please send someone to repair the hot water heater?

Kind regards,

Your Favorite Tenant

The text file I’m translating is called email-to-landlord-en.txt, and I’d like the translated file to be called email-to-landlord-de.txt.

Two tips we’ll share before we translate a document:

Translating PowerPoint or Microsoft Word documents with the API count as a minimum of 50,000 characters toward your usage, even when there are fewer than 50,000 characters in the document. This is important to keep in mind if you’re watching your usage closely.
Be sure the file that you’re translating is in your working directory before running the following code snippet.

translator.translate_document_from_filepath(  

"email-to-landlord-en.txt",  

"email-to-landlord-de.txt",  

target_lang="DE",  

formality="more"  

)

translator.translate_document_from_filepath(

"email-to-landlord-en.txt",

"email-to-landlord-de.txt",

target_lang="DE",

formality="more"

)

Et voilà! My translated file email-to-landlord-de.txt is now available in my working directory with the following translated text:

Sehr geehrte Damen und Herren,

Ich möchte Sie darüber informieren, dass wir immer noch kein heißes Wasser in unserer Wohnung haben, nun schon fünf Tage in Folge. Da es Mitte Januar ist, könnten Sie bitte jemanden schicken, um den Warmwasserboiler zu reparieren?

Mit freundlichen Grüßen,

Ihr Lieblingsmieter

You might’ve noticed that when translating the text file, I introduced a new parameter called formality. Let’s consult the docs to see what it refers to:

Formality sets whether the translated text should lean towards formal or informal language. This feature currently only works for target languages “DE” (German), “FR” (French), “IT” (Italian), “ES” (Spanish), “NL” (Dutch), “PL” (Polish), “PT-PT” / “PT-BR” (Portuguese), and “RU” (Russian).

You can set “more” for more formal language and “less” for less formal language.

When reaching out to my landlord to request a repair, I know I want to use “more formal” German, and luckily, DeepL makes that easy. But if I were translating an email to send to a close friend, I could easily choose “less formal” German instead.

Wrapping up and Next Steps

Thanks for joining us to get hands-on with the DeepL API!

We hope you found the tutorial to be helpful, and if you have any feedback about the Python client library, we encourage you to create an issue in the GitHub repo. It’s an open source project, and we’d love to hear your ideas.

And the API documentation is the best place to learn about supported languages and file formats, plus more advanced use cases such as handling XML.

To stay updated on what we’re working on, we recommend checking out our blog.

That’s all for now. Happy translating!