Glossaries in the real world

A quick guide to using DeepL glossaries in translations

What are glossaries and why should you care?

A great feature of DeepL API is the ability to improve consistency when translating content across multiple languages. As an API user you can do this by including glossaries in your translations, which allow you to fine-tune how words and phrases should be translated from one language to another.

This is perfect for situations where technical terms or product information needs to be standardized - saving time and money by reducing the need for manual editing in a translation workflows.

A simple example from The Acme Startup Company

The best way to show how something works is to use a real world use case, and for this we’re heading to the cool headquarters of (the completely fictional) Acme Startup Company.

Acme have customers from all over the world and offer support over email and their in-app chat system. Their support staff work around the globe in order to provide 24 hour support, but different time zones and language difference might mean customers get a different experience each time they speak to an agent. Saying “Good morning” to a customer when it’s 7pm for them doesn’t sound great.

Acme prides itself on the quality of its support and wants to standardize how support agents interact with customers without removing human interaction. Acme reviewed the chat and email transcripts of a cross section of customer service messages, and built an initial list of the words and phrases they wanted to standardize when a customer is greeted.

Let’s dive in and help Acme out!

Getting started

First, we’re going to need a DeepL account in order to get hold of an API key so we can authenticate our API requests. For this demo, we’re going to use the DeepL Python client library in order to make the API requests, but all the glossaries functionality is available using cURL or any of our other client libraries. Check out the API docs and DeepL GitHub for more information.

First, we’ll install the DeepL Python library from the command line:

pip install --upgrade deepl

From here we can start putting together our Python code. In a file called main.py, We’ll begin by constructing a translator object, including your own auth key you can find in your account:

#main.py

import deepl
auth_key = "19f172ae-03a9-..."
translator = deepl.Translator(auth_key)

And finally, we’ll send a simple translation request, with an example of what Acme are currently experiencing:

#main.py

import deepl
auth_key = "19f172ae-03a9-..."
translator = deepl.Translator(auth_key)
result = translator.translate_text("Good evening, Gabrielle", target_lang="DE")
print(result.text) # "Guten Abend, Gabrielle"

As you can see, if Gabrielle was receiving this in the morning of their time zone, it might not set the right tone Acme are looking for in their customer service quality. Let’s help Acme out by creating a simple solution using a Glossary.

Creating a Glossary

To create our glossary, we’ll create a new file called glossary.py - this is because we only need to create the glossary once. Start with the same code to construct a translator object:

#glossary.py

import deepl
auth_key = "19f172ae-03a9-..."
translator = deepl.Translator(auth_key)

Then, we can create a list of entries we want to recognize and change when translating from English to German:

#glossary.py

import deepl
auth_key = "19f172ae-03a9-..."
translator = deepl.Translator(auth_key)

entries = {"Good morning": "Hallo",  # "Guten Morgen"
          "Good afternoon": "Hallo", # "Guten Tag"
          "Good evening" : "Hallo",  # "Guten Abend"
          "Greetings": "Hallo",      # "Grüße"
          "Dear": "Hallo"}           # "Liebe"

Lastly, we create the glossary by calling translator.create_glossary, giving it a name, setting the source and target languages, and assigning the entries we just created:

#glossary.py

import deepl
auth_key = "19f172ae-03a9-..."
translator = deepl.Translator(auth_key)

entries = {"Good morning": "Hallo",  # "Guten Morgen"
          "Good afternoon": "Hallo", # "Guten Tag"
          "Good evening" : "Hallo",  # "Guten Abend"
          "Greetings": "Hallo",      # "Grüße"
          "Dear": "Hallo"}           # "Liebe"
          
acme_glossary = translator.create_glossary(
  "Greetings Glossary",
  source_lang="EN",
  target_lang="DE",
  entries=entries,
)

print(acme_glossary.glossary_id) # "def3a26b-3e84..."

Running glossary.py will give us a response containing glossary_id, which we can add to our initial translation in main.py. Also be aware that when using a glossary, you will also need to include source_lang as part of your request:

#main.py

import deepl
auth_key = "19f172ae-03a9-..."
translator = deepl.Translator(auth_key)

result = translator.translate_text("Good evening, Gabrielle", source_lang="EN", target_lang="DE", glossary="def3a26b-3e84...")

print(result.text) # "Hallo, Gabrielle"

You’ll now see that the greeting of “Guten Abend, Gabrielle” has now been replaced with the much more consistent “Hallo, Gabrielle”. Try changing “Good evening” to “Good morning”, and you’ll see the Glossary doing its job and keeping all customer service messaging in harmony.

Wrapping up

This has been a really simple - but powerful - example to highlight how glossaries can help organizations maintain quality, accuracy and consistency in their messaging across multiple languages. Although this was a small snapshot into how glossaries could be used to make greetings consistent, it’s clear just how powerful glossaries can be when expanded into covering content such as product catalogs or technical documentation, where consistent naming is crucial.

Glossaries are incredibly flexible and give you the power to fine-tune your translations. Some more examples for you to try out could be:

• Always changing “Vereinigtes Königreich” to “UK” (rather than “United Kingdom”)

• Updating “pharmacy” in locales where it is more common to say “chemist” or “drug store”

• Ensuring “Casques d'écoute” always translates to “headphones” in a product catalog (instead of potentially “headset”)