Translation: a beginner's guide

An introduction to sending translation requests with the DeepL API

This guide explains the fundamentals of translating text with the DeepL API. We’ll explore:

• getting an API key
• using client libraries
• language codes and regional variants
• where to send your request
• choosing a model_type
• limits

Let’s get started!

Getting an API key

If you haven’t already signed up for a DeepL API account, you’ll need to do so. Visit our plans page, choose a plan, and sign up.

If you already have a DeepL account for the translator, you need to log out of your account, then create a new account for the DeepL API.

When you send a request to our API, you use your API key to identify yourself. You can find that API key here.

And now you’re ready to make your first API request!

For more information about API keys and authentication, see Authentication

Finding your client library

Like many APIs, the DeepL API uses HTTP requests and responses to receive and send data. While you can construct your own HTTP requests, most people find it easier to let their favorite programming language generate requests and handle the responses. To this end, DeepL provides official client libraries for six popular languages:

• Python
• JavaScript
• PHP
• C#
• Java
• Ruby

The DeepL community has contributed client libraries for other programming languages, including Dart, Go, and Rust.

The documentation on this site frequently includes code samples in these languages. For more about how to use the DeepL API in your favorite language, try the links above.

JavaScript/TypeScript users: for security reasons, you cannot call the DeepL API directly from client-side JavaScript. To do this during testing or prototyping, try one of these quick proxies.

Making a translation request

Source and target languages

The source language is the language you’re translating from. The target language is the language you’re translating to.

Any DeepL API translation request must include these two parameters:

• text: some text to translate
• target_lang: the target language

That’s all you need! Since DeepL is quite good at detecting the source language, normally you can omit the source_lang parameter. If your text is very short, contains a mix of languages, or if you want to specify the source language for any other reason, you can include source_lang.

A sample translation request

For example, if you wanted to translate the phrase “Hello, bright universe!” from German to Japanese:

• “Hello, everybody” is the text
• German is the source_lang
• Japanese is the target_lang

The first tab below shows the HTTP request you’d use here and a typical response from the API. Other tabs show how you’d make this request using cURL and using our official client libraries. To see how you’d handle the response in your favorite programming language, check the appropriate tab.

HTTP Request

If you chose a free API plan and you are writing cURL or HTTP requests, replace https://api.deepl.com with https://api-free.deepl.com.

Sample request

POST /v2/translate HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 72
Content-Type: application/json

{"text":["Hello, bright universe!"],"target_lang":"JA"} 

Sample response

{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "こんにちは、輝く宇宙"
    }
  ]
}

cURL

If you chose a free API plan and you are writing cURL or HTTP requests, replace https://api.deepl.com with https://api-free.deepl.com.

Set the API key

export API_KEY={YOUR_API_KEY}

Sample request

curl -X POST https://api.deepl.com/v2/translate \
  --header "Content-Type: application/json" \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --data '{
    "text": ["Hello, bright universe!"], 
    "target_lang": "JA"
}'

Sample response

{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "こんにちは、輝く宇宙"
    }
  ]
}

Python

Sample request

import deepl

auth_key = "{YOUR_API_KEY}" # replace with your key
deepl_client = deepl.DeepLClient(auth_key)

result = deepl_client.translate_text("Hello, bright universe!", target_lang="JA")
print(result.text)

Sample output

こんにちは、輝く宇宙

In production code, it’s safer to store your API key in an environment variable.

JavaScript

Sample request

import * as deepl from 'deepl-node';

const authKey = "{YOUR_API_KEY}"; // replace with your key
const deeplClient = new deepl.DeepLClient(authKey);

(async () => {
    const result = await deeplClient.translateText('Hello, bright universe!', null, 'JA');
    console.log(result.text);
})();

Sample output

こんにちは、輝く宇宙

In production code, it’s safer to store your API key in an environment variable.

PHP

Sample request

use DeepL\Client;

$authKey = "{YOUR_API_KEY}"; // replace with your key
$deeplClient = new \DeepL\DeepLClient($authKey);

$result = $deeplClient->translateText('Hello, bright universe!', null, 'JA');
echo $result->text;

Sample output

こんにちは、輝く宇宙

In production code, it’s safer to store your API key in an environment variable.

C#

Sample request

using DeepL; // this imports the DeepL namespace. Use the code below in your main program.

var authKey = "{YOUR_API_KEY}"; // replace with your key
var client = new DeepLClient(authKey);

var translatedText = await client.TranslateTextAsync(
    "Hello, bright universe!",
    null,
    LanguageCode.Japanese);
Console.WriteLine(translatedText);

Sample output

こんにちは、輝く宇宙

In production code, it’s safer to store your API key in an environment variable.

Java

Sample request

import com.deepl.api.*;

public class Main {
    public static void main(String[] args) throws DeepLException, InterruptedException {
        String authKey = "{YOUR_API_KEY}"; // replace with your key
        DeepLClient client = new DeepLClient(authKey);

        TextResult result = client.translateText("Hello, bright universe!", null, "JA");
        System.out.println(result.getText());
    }
}

Sample output

こんにちは、輝く宇宙

In production code, it’s safer to store your API key in an environment variable.

Ruby

Sample request

require 'deepl'

DeepL.configure do |config|
    config.auth_key = '{YOUR_API_KEY}' # replace with your key
end

translation = DeepL.translate 'Hello, bright universe!', nil, 'JA'
puts translation.text

Sample output

こんにちは、輝く宇宙

In production code, it’s safer to store your API key in an environment variable.

Sending multiple text strings

If you look at the HTTP request above, you’ll notice that the translation text is in square brackets - in an array. In fact, a translation request can include multiple text strings:

HTTP Request

If you chose a free API plan and you are writing cURL or HTTP requests, replace https://api.deepl.com with https://api-free.deepl.com.

Sample request

POST /v2/translate HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 121
Content-Type: application/json

{
  "text": [
    "¿En qué lenguaje programan los programadores españoles?",
    "Sí++"
  ],
  "target_lang": "HI"
}

Sample response

{
  "translations": [
    {
      "text": "स्पेनिश प्रोग्रामर कौन-सी प्रोग्रामिंग भाषाएँ उपयोग करते हैं?",
      "detected_source_language": "ES"
    },
    {
      "text": "हाँ++",
      "detected_source_language": "ES"
    }
  ]
}

cURL

If you chose a free API plan and you are writing cURL or HTTP requests, replace https://api.deepl.com with https://api-free.deepl.com.

Set the API key

export API_KEY={YOUR_API_KEY}

Sample request

curl -X POST https://api.deepl.com/v2/translate \
  --header "Content-Type: application/json" \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --data '{
    "text": [
      "¿En qué lenguaje programan los programadores españoles?",
      "Sí++"
    ],
    "target_lang": "HI"
  }'

Sample response

{
  "translations": [
    {
      "text": "स्पेनिश प्रोग्रामर कौन-सी प्रोग्रामिंग भाषाएँ उपयोग करते हैं?",
      "detected_source_language": "ES"
    },
    {
      "text": "हाँ++",
      "detected_source_language": "ES"
    }
  ]
}

Python

Sample request

import deepl

auth_key = "{YOUR_API_KEY}" # replace with your key
deepl_client = deepl.DeepLClient(auth_key)

result = deepl_client.translate_text(
    [
        "¿En qué lenguaje programan los programadores españoles?",
        "Sí++"
    ],
    target_lang="HI"
)

print (f"{result[0].text}\n{result[1].text}")

Sample output

स्पेनिश प्रोग्रामर कौन-सी प्रोग्रामिंग भाषाएँ उपयोग करते हैं?
हाँ++

In production code, it’s safer to store your API key in an environment variable.

JavaScript

Sample request

import * as deepl from 'deepl-node';

const authKey = "{YOUR_API_KEY}"; // replace with your key
const deeplClient = new deepl.DeepLClient(authKey);

(async () => {
  const result = await deeplClient.translateText(
    [
      "¿En qué lenguaje programan los programadores españoles?",
      "Sí++"
    ],
    null,
    'HI'
  );

  console.log(result[0].text + "\n" + result[1].text);
})();

Sample output

स्पेनिश प्रोग्रामर कौन-सी प्रोग्रामिंग भाषाएँ उपयोग करते हैं?
हाँ++

In production code, it’s safer to store your API key in an environment variable.

PHP

Sample request

use DeepL\Client;

$authKey = "{YOUR_API_KEY}"; // replace with your key
$deeplClient = new \DeepL\DeepLClient($authKey);

$result = $deeplClient->translateText([
    "¿En qué lenguaje programan los programadores españoles?",
    "Sí++"
  ], 
  null,
  'HI'
);

echo $result[0]->text . "\n" . $result[1]->text;

Sample output

स्पेनिश प्रोग्रामर कौन-सी प्रोग्रामिंग भाषाएँ उपयोग करते हैं?
हाँ++

In production code, it’s safer to store your API key in an environment variable.

C#

Sample request

using DeepL; // this imports the DeepL namespace. Use the code below in your main program.

var authKey = "{YOUR_API_KEY}"; // replace with your key
var client = new DeepLClient(authKey);

var translated = await client.TranslateTextAsync(
    [
      "¿En qué lenguaje programan los programadores españoles?",
      "Sí++"
    ],
    null,
    LanguageCode.Hindi
);

Console.WriteLine(translated[0].Text + "\n" + translated[1].Text);

Sample output

स्पेनिश प्रोग्रामर कौन-सी प्रोग्रामिंग भाषाएँ उपयोग करते हैं?
हाँ++

In production code, it’s safer to store your API key in an environment variable.

Java

Sample request

import com.deepl.api.*;
import java.util.List;

public class Main {
    public static void main(String[] args) throws DeepLException, InterruptedException {
        String authKey = "{YOUR_API_KEY}"; // replace with your key
        DeepLClient client = new DeepLClient(authKey);
        
        List<TextResult> results = client.translateText(
            List.of(
                "¿En qué lenguaje programan los programadores españoles?",
                "Sí++"
            ),
            null,
            "HI"
        );
        
        System.out.println(results.get(0).getText() + "\n" + results.get(1).getText());
    }
}

Sample output

स्पेनिश प्रोग्रामर कौन-सी प्रोग्रामिंग भाषाएँ उपयोग करते हैं?
हाँ++

In production code, it’s safer to store your API key in an environment variable.

Ruby

Sample request

require 'deepl'

DeepL.configure do |config|
    config.auth_key = '{YOUR_API_KEY}' # replace with your key
end

translations = DeepL.translate(
    [
        "¿En qué lenguaje programan los programadores españoles?",
        "Sí++"
    ],
    nil,
    'HI'
)

puts translations[0].text
puts translations[1].text

Sample output

स्पेनिश प्रोग्रामर कौन-सी प्रोग्रामिंग भाषाएँ उपयोग करते हैं?
हाँ++

In production code, it’s safer to store your API key in an environment variable.

Jokes are notoriously difficult to translate, especially jokes that rely on an indefensible pun

In fact, these text strings can be in different languages. If you don’t set the source language, DeepL will detect that separately for each string.

HTTP Request

If you chose a free API plan and you are writing cURL or HTTP requests, replace https://api.deepl.com with https://api-free.deepl.com.

Sample request

POST /v2/translate HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 110
Content-Type: application/json

{
  "text": [
    "What does the 'R' in 'Recursion' stand for?",
    "Recursão"
  ],
  "target_lang": "HA"
}

Sample response

{
  "translations": [
    {
      "text": "Menene R ke nufi a cikin 'Recursion'?",
      "detected_source_language": "EN"
    },
    {
      "text": "Maimaita",
      "detected_source_language": "PT"
    }
  ]
}

cURL

If you chose a free API plan and you are writing cURL or HTTP requests, replace https://api.deepl.com with https://api-free.deepl.com.

Set the API key

export API_KEY={YOUR_API_KEY}

Sample request

curl -X POST https://api.deepl.com/v2/translate \
  --header "Content-Type: application/json" \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --data '{
    "text": [
      "What does the '\''R'\'' in '\''Recursion'\'' stand for?",
      "Recursão"
    ],
    "target_lang": "HA"
  }'

Sample response

{
  "translations": [
    {
      "text": "Menene R ke nufi a cikin 'Recursion'?",
      "detected_source_language": "EN"
    },
    {
      "text": "Maimaita",
      "detected_source_language": "PT"
    }
  ]
}

Python

Sample request

import deepl

auth_key = "{YOUR_API_KEY}" # replace with your key
deepl_client = deepl.DeepLClient(auth_key)

result = deepl_client.translate_text(
    [
        "What does the 'R' in 'Recursion' stand for?",
        "Recursão"
    ],
    target_lang="HA"
)

print (f"{result[0].text}\n{result[1].text}")

Sample output

Menene R ke nufi a cikin 'Recursion'?
Maimaita

In production code, it’s safer to store your API key in an environment variable.

JavaScript

Sample request

import * as deepl from 'deepl-node';

const authKey = "{YOUR_API_KEY}"; // replace with your key
const deeplClient = new deepl.DeepLClient(authKey);

(async () => {
  const result = await deeplClient.translateText(
    [
      "What does the 'R' in 'Recursion' stand for?",
      "Recursão"
    ],
    null,
    'HA'
  );

  console.log(result[0].text + "\n" + result[1].text);
})();

Sample output

Menene R ke nufi a cikin 'Recursion'?
Maimaita

In production code, it’s safer to store your API key in an environment variable.

PHP

Sample request

use DeepL\Client;

$authKey = "{YOUR_API_KEY}"; // replace with your key
$deeplClient = new \DeepL\DeepLClient($authKey);

$result = $deeplClient->translateText([
    "What does the 'R' in 'Recursion' stand for?",
    "Recursão"
  ], 
  null,
  'HA'
);

echo $result[0]->text . "\n" . $result[1]->text;

Sample output

Menene R ke nufi a cikin 'Recursion'?
Maimaita

In production code, it’s safer to store your API key in an environment variable.

C#

Sample request

using DeepL; // this imports the DeepL namespace. Use the code below in your main program.

var authKey = "{YOUR_API_KEY}"; // replace with your key
var client = new DeepLClient(authKey);

var translated = await client.TranslateTextAsync(
    [
      "What does the 'R' in 'Recursion' stand for?",
      "Recursão"
    ],
    null,
    LanguageCode.Hausa
);

Console.WriteLine(translated[0].Text + "\n" + translated[1].Text);

Sample output

Menene R ke nufi a cikin 'Recursion'?
Maimaita

In production code, it’s safer to store your API key in an environment variable.

Java

Sample request

import com.deepl.api.*;
import java.util.List;

public class Main {
    public static void main(String[] args) throws DeepLException, InterruptedException {
        String authKey = "{YOUR_API_KEY}"; // replace with your key
        DeepLClient client = new DeepLClient(authKey);
        
        List<TextResult> results = client.translateText(
            List.of(
                "What does the 'R' in 'Recursion' stand for?",
                "Recursão"
            ),
            null,
            "HA"
        );
        
        System.out.println(results.get(0).getText() + "\n" + results.get(1).getText());
    }
}

Sample output

Menene R ke nufi a cikin 'Recursion'?
Maimaita

In production code, it’s safer to store your API key in an environment variable.

Ruby

Sample request

require 'deepl'

DeepL.configure do |config|
    config.auth_key = '{YOUR_API_KEY}' # replace with your key
end

translations = DeepL.translate(
    [
        "What does the 'R' in 'Recursion' stand for?",
        "Recursão"
    ],
    nil,
    'HA'
)

puts translations[0].text
puts translations[1].text

Sample output

Menene R ke nufi a cikin 'Recursion'?
Maimaita

In production code, it’s safer to store your API key in an environment variable.

Language codes and variants

The DeepL API can translate in any of these supported languages. Normally, any supported source language can be used as a target language, and vice versa. But it’s best to check the list to make sure.

To specify a language, use its ISO-639 language code, such as FR for French or VI for Vietnamese. While most language codes have two letters, a few have three. For example, the code for Cantonese is YUE.

For certain target languages, DeepL supports a set of regional variants, which are listed among the supported languages. For example, en-GB indicates British English, and en-US indicates English spoken in the United States. To specify a variant, append to the language code a hyphen, then the ISO-3166 country code. So, for Brazilian, Portuguese, use pt-BR.

In the DeepL API, language codes are case-insensitive. It accepts language codes in uppercase or lowercase, or a mix of the two. So, for Brazilian Portuguese you could use pt-BR, pt-br, PT-BR, or even pT-Br.

Regional variants can only be used in target languages. If you try a source language with a variant like ZH-HANS, the API will return an error.

If DeepL supports variants of a given language, you are encouraged to choose one. If you don’t include the variant in a raw HTTP request, DeepL will translate into the variant which has been designated as the default. If you’re using a client library, the API will throw an error.

Although you can ask the API to translate from one language variant to another, the methods described in our How To Translate Between Language Variants guide yield better results.

Where to send your request

The URL you send requests to depends on your API plan. If you are using a free plan, you’ll use https://api-free.deepl.com. For a paid plan, use https://api.deepl.com.

If you’re using a client library, you don’t need to worry about this, as DeepL’s client libraries detect your account type and send requests to the correct URL.

You may also wish to send requests to an API endpoint corresponding to a specific geographic region, for data residency or compliance needs, or to minimize latency. For more information, instructions on how to set this up, and code samples featuring the server_url parameter, see Regional API Endpoints.

Model type

DeepL hosts many AI models for language translation. As AI is evolving rapidly, we are constantly working on our models and deploying new ones. It would be difficult for users to determine which model to choose for a particular language pair, text, and parameters. Rather than requiring users to select a specific model for a given translation, DeepL follows a simpler approach:

• The translator app offers a choice between “classic” and “next-gen” models. “Classic” models often maximize speed, and “next-gen” models generally maximize quality.
• The DeepL API offers the model_type parameter, which lets you choose whether you would prefer a model that maximizes translation quality or a model that runs as quickly as possible. The API will then make its best effort to execute your translation with such a model, and its response will tell you what sort of model we used.

As our models evolve, the distinction between “classic” and “next-gen” is not always meaningful. For some language pairs or translation requests, only one DeepL model can be used. Under some circumstances, we might offer more than two options. The API will simply do the work of choosing for you. The response indicates which model type was used.

The model_type parameter can have one of three values:

• latency_optimized: aims to maximize speed
• quality_optimized: aims to maximize quality
• prefer_quality_optimized: a legacy value, whose behavior is currently identical to quality_optimized

Naturally, the API tries to provide excellent translation quality and low latency for every request.

If you omit the model_type, the API normally defaults to latency_optimized.

Special cases

• if your request omits the source_lang, the API uses next-gen models to ensure the best possible language detection
• tag handling v2 requires next-gen models. Setting both model_type=latency_optimized and tag_handling_version=v2 yields an error.
• for some languages, like Thai, the API uses the same model regardless of requested model_type. This behavior may change as our models evolve.

Limits

The total request body size for text translation requests is limited to 128K. As a request consists of multiple elements along with your text, this means your text can’t hit 128K exactly, but has to be a little smaller.

If you need to send larger strings, you can place them in documents, which have a limit of 10 MB. If that’s not high enough, get in touch with us.

For more, see Usage and Limits.

Summary and next steps

Congratulations! Now you know how to send the DeepL API a translation request including any of these parameters:

Item	parameter	required?
source language	source_lang	optional
target language	target_lang	required
text to translate	text	required
optimize for speed or quality	model_type	optional

Here are some possible next steps:

• Play with translation requests using these parameters and other options in our playground or Postman.
• For complete information on the /translate endpoint, see the /translate reference
• See this introduction to DeepL glossaries
• To learn how to translate text in files - PDFs, presentations, powerpoints, HTML, images, and more - see the /document reference
• To translate audio, see the /voice endpoint