Deepl client does not allow 'en' and 'pt' target languages

[frq-asgard-toge]

The documentation states that it is possible to use 'en' as a valid target language, just as being able to use pt and zh.
The API supports this as well and will translate content just fine.

So why does the Java Client have specific checks that throw an exception when you are trying to use them?

deepl-java/deepl-java/src/main/java/com/deepl/api/Translator.java

Lines 920 to 936 in 9087e77

	*
	* @param sourceLang Language code of the input language, or <code>null</code> to use
	* auto-detection.
	* @param targetLang Language code of the desired output language.
	* @throws IllegalArgumentException If either language code is invalid.
	*/
	protected static void checkValidLanguages(@Nullable String sourceLang, String targetLang)
	throws IllegalArgumentException {
	if (sourceLang != null && sourceLang.isEmpty()) {
	throw new IllegalArgumentException("sourceLang must be null or non-empty");
	}
	if (targetLang.isEmpty()) {
	throw new IllegalArgumentException("targetLang must not be empty");
	}
	switch (targetLang) {
	case "en":
	throw new IllegalArgumentException(

You can reproduce that the regular 'en' tag works with the API via the following cURL command:
curl -v -XPOST -H 'Authorization: DeepL-Auth-Key my-deepl-key' -H "Content-type: application/json" -d '{"source_language": "DE", "text":["Hallo große Welt da draußen"],"target_lang":"EN"}' 'https://api.deepl.com/v2/translate'

[JanEbbing]

This is intentional, let me explain the reasoning:

• The API needs to be backwards compatible and this comes from a time before we had language variants (just english and just portuguese).
• The Client libraries were developed once we had the variants already, so they could ensure this safer behaviour.
• Using "en" and "pt" as a target language is actually slightly confusing/surprising to the user - it simply infers a "default variant" that we choose behind the scenes and uses that as the target language. So, in the CLs we opted to make this decision explicit and push it to the user instead of our backend.

[frq-asgard-enro]

The unfortunate part about this design decision is that the return value of getTargetLanguages is now unreliable. If you put the languages returned from this method into a user facing combobox, some of them will lead to errors.

So could you please reconsider.

I will also point out that simply filtering the languages based on these same checks in getTargetLanguages would not be the best possible solution. The API of this library should properly reflect the behavior of the online API.
Either support the short language code - or don't, but don't support in the API and fake non-support in the client lib.

[JanEbbing]

The API endpoint does not return "en" when requesting the target languages (only when requesting source languages):

$ curl -X GET 'https://api.deepl.com/v2/languages' \
--header 'Authorization: DeepL-Auth-Key KEY' \
--header 'Content-Type: application/json' \
 --data '{"type":"target"}'
[{"language":"BG","name":"Bulgarian","supports_formality":false},{"language":"CS","name":"Czech","supports_formality":false},{"language":"DA","name":"Danish","supports_formality":false},{"language":"DE","name":"German","supports_formality":true},{"language":"EL","name":"Greek","supports_formality":false},{"language":"EN-GB","name":"English (British)","supports_formality":false},{"language":"EN-US","name":"English (American)","supports_formality":false},{"language":"ES","name":"Spanish","supports_formality":true},{"language":"ET","name":"Estonian","supports_formality":false},{"language":"FI","name":"Finnish","supports_formality":false},{"language":"FR","name":"French","supports_formality":true},{"language":"HU","name":"Hungarian","supports_formality":false},{"language":"ID","name":"Indonesian","supports_formality":false},{"language":"IT","name":"Italian","supports_formality":true},{"language":"JA","name":"Japanese","supports_formality":true},{"language":"KO","name":"Korean","supports_formality":false},{"language":"LT","name":"Lithuanian","supports_formality":false},{"language":"LV","name":"Latvian","supports_formality":false},{"language":"NB","name":"Norwegian","supports_formality":false},{"language":"NL","name":"Dutch","supports_formality":true},{"language":"PL","name":"Polish","supports_formality":true},{"language":"PT-BR","name":"Portuguese (Brazilian)","supports_formality":true},{"language":"PT-PT","name":"Portuguese (European)","supports_formality":true},{"language":"RO","name":"Romanian","supports_formality":false},{"language":"RU","name":"Russian","supports_formality":true},{"language":"SK","name":"Slovak","supports_formality":false},{"language":"SL","name":"Slovenian","supports_formality":false},{"language":"SV","name":"Swedish","supports_formality":false},{"language":"TR","name":"Turkish","supports_formality":false},{"language":"UK","name":"Ukrainian","supports_formality":false},{"language":"ZH","name":"Chinese (simplified)","supports_formality":false},{"language":"ZH-HANS","name":"Chinese (simplified)","supports_formality":false}]

The only case where this doesn't apply is chinese ("ZH") due to an incompatibility with some TMS, but we do allow "ZH" as a target language in client libraries as well. I'll check if java returns "EN" as a target language, but I'd be surprised. Is this in an older version maybe?

[JanEbbing]

I get the expected output when querying the target languages through the library:
Code:

        DeepLClient client = new DeepLClient(authKey, new DeepLClientOptions());
        List<Language> targetLanguages = client.getTargetLanguages();
        for (Language l : targetLanguages) {
            System.out.println("Language " + l.getName() + ", Code "+ l.getCode());
        }

Language Bulgarian, Code bg
Language Czech, Code cs
Language Danish, Code da
Language German, Code de
Language Greek, Code el
Language English (British), Code en-GB
Language English (American), Code en-US
Language Spanish, Code es
Language Estonian, Code et
Language Finnish, Code fi
Language French, Code fr
Language Hungarian, Code hu
Language Indonesian, Code id
Language Italian, Code it
Language Japanese, Code ja
Language Korean, Code ko
Language Lithuanian, Code lt
Language Latvian, Code lv
Language Norwegian, Code nb
Language Dutch, Code nl
Language Polish, Code pl
Language Portuguese (Brazilian), Code pt-BR
Language Portuguese (European), Code pt-PT
Language Romanian, Code ro
Language Russian, Code ru
Language Slovak, Code sk
Language Slovenian, Code sl
Language Swedish, Code sv
Language Turkish, Code tr
Language Ukrainian, Code uk
Language Chinese (simplified), Code zh
Language Chinese (simplified), Code zh-HANS

If you get "EN" as a target language, could you please tell me the version number/how I can reproduce that?

[frq-asgard-toge]

@JanEbbing It seems that this API documentation is out of date then?

https://developers.deepl.com/docs/api-reference/languages/openapi-spec-for-retrieving-languages
and
https://developers.deepl.com/docs/api-reference/languages

Both of them mention that the target is a query parameter and that the request is a GET request. That one only returns source languages though it seems. Its confusing that you can still GET /languages, which will return the list of source languages, but the query parameter itself does not seem to change the output.

However from your cURL Output above, it seems that you can also provide the request body in the GET request?

(Edit: For me, Calling https://api.deepl.com/v2/languages?type=target responds with my API Key will return all of the source languages. I am confused though, because it seems that the java client is following the same behaviour?)'

(Edit: It seems that if you include Content-Type: application/json in the GET request headers although not providing any body will make it return the source language list)

[frq-asgard-toge]

Compare:

curl -H "Authorization: DeepL-Auth-Key KEY" "https://api.deepl.com/v2/languages?type=target"
versus
curl -H "Authorization: DeepL-Auth-Key KEY" -H "Content-Type: application/json" "https://api.deepl.com/v2/languages?type=target"

My random guess is that your backend expects some request data object, and since it sees that the Content-Type header is present it ignores the query parameters entirely, but since there is no body it just returns the source languages and ignores the rest. I had the Content-Type header in there by mistake assuming that in a GET request it wouldn't make a difference

[frq-asgard-toge]

The only case where this doesn't apply is chinese ("ZH") due to an incompatibility with some TMS, but we do allow "ZH" as a target language in client libraries as well. I'll check if java returns "EN" as a target language, but I'd be surprised. Is this in an older version maybe?

Btw it seems that this is not up to date with the language list then? Because from my own request that I did just now and your command output, ZH-HANT is missing entirely, which according to this doc here should be there?

https://developers.deepl.com/docs/resources/supported-languages

[JanEbbing]

For Arabic and traditional chinese (AR, ZH-HANT), please refer to the info box at the top of https://developers.deepl.com/docs/resources/supported-languages, they have not been added to the output yet as they are not supported for document translation yet. You can use them for text translation.

I think your issue stems from the type=target not being applied, so you actually get back the source languages. Our API unfortunately just silently swallows unexpected parameters rather than explicitly failing, but it would be backward incompatible to suddenly fail these requests. I'll check the right curl command in a bit and get back to you

[JanEbbing]

For the curl request, both of these work for me if you want to send x-www-form-urlencoded requests:

$ curl -X GET 'https://api.deepl.com/v2/languages' \
--header 'Authorization: DeepL-Auth-Key KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' -d "type=target"

[{"language":"BG","name":"Bulgarian","supports_formality":false},{"language":"CS","name":"Czech","supports_formality":false},{"language":"DA","name":"Danish","supports_formality":false},{"language":"DE","name":"German","supports_formality":true},{"language":"EL","name":"Greek","supports_formality":false},{"language":"EN-GB","name":"English (British)","supports_formality":false},{"language":"EN-US","name":"English (American)","supports_formality":false},{"language":"ES","name":"Spanish","supports_formality":true},{"language":"ET","name":"Estonian","supports_formality":false},{"language":"FI","name":"Finnish","supports_formality":false},{"language":"FR","name":"French","supports_formality":true},{"language":"HU","name":"Hungarian","supports_formality":false},{"language":"ID","name":"Indonesian","supports_formality":false},{"language":"IT","name":"Italian","supports_formality":true},{"language":"JA","name":"Japanese","supports_formality":true},{"language":"KO","name":"Korean","supports_formality":false},{"language":"LT","name":"Lithuanian","supports_formality":false},{"language":"LV","name":"Latvian","supports_formality":false},{"language":"NB","name":"Norwegian","supports_formality":false},{"language":"NL","name":"Dutch","supports_formality":true},{"language":"PL","name":"Polish","supports_formality":true},{"language":"PT-BR","name":"Portuguese (Brazilian)","supports_formality":true},{"language":"PT-PT","name":"Portuguese (European)","supports_formality":true},{"language":"RO","name":"Romanian","supports_formality":false},{"language":"RU","name":"Russian","supports_formality":true},{"language":"SK","name":"Slovak","supports_formality":false},{"language":"SL","name":"Slovenian","supports_formality":false},{"language":"SV","name":"Swedish","supports_formality":false},{"language":"TR","name":"Turkish","supports_formality":false},{"language":"UK","name":"Ukrainian","supports_formality":false},{"language":"ZH","name":"Chinese (simplified)","supports_formality":false},{"language":"ZH-HANS","name":"Chinese (simplified)","supports_formality":false}]


$ curl -X GET 'https://api.deepl.com/v2/languages?type=target' \
--header 'Authorization: DeepL-Auth-Key KEY' \
--header 'Content-Type: application/x-www-form-urlencoded'

[{"language":"BG","name":"Bulgarian","supports_formality":false},{"language":"CS","name":"Czech","supports_formality":false},{"language":"DA","name":"Danish","supports_formality":false},{"language":"DE","name":"German","supports_formality":true},{"language":"EL","name":"Greek","supports_formality":false},{"language":"EN-GB","name":"English (British)","supports_formality":false},{"language":"EN-US","name":"English (American)","supports_formality":false},{"language":"ES","name":"Spanish","supports_formality":true},{"language":"ET","name":"Estonian","supports_formality":false},{"language":"FI","name":"Finnish","supports_formality":false},{"language":"FR","name":"French","supports_formality":true},{"language":"HU","name":"Hungarian","supports_formality":false},{"language":"ID","name":"Indonesian","supports_formality":false},{"language":"IT","name":"Italian","supports_formality":true},{"language":"JA","name":"Japanese","supports_formality":true},{"language":"KO","name":"Korean","supports_formality":false},{"language":"LT","name":"Lithuanian","supports_formality":false},{"language":"LV","name":"Latvian","supports_formality":false},{"language":"NB","name":"Norwegian","supports_formality":false},{"language":"NL","name":"Dutch","supports_formality":true},{"language":"PL","name":"Polish","supports_formality":true},{"language":"PT-BR","name":"Portuguese (Brazilian)","supports_formality":true},{"language":"PT-PT","name":"Portuguese (European)","supports_formality":true},{"language":"RO","name":"Romanian","supports_formality":false},{"language":"RU","name":"Russian","supports_formality":true},{"language":"SK","name":"Slovak","supports_formality":false},{"language":"SL","name":"Slovenian","supports_formality":false},{"language":"SV","name":"Swedish","supports_formality":false},{"language":"TR","name":"Turkish","supports_formality":false},{"language":"UK","name":"Ukrainian","supports_formality":false},{"language":"ZH","name":"Chinese (simplified)","supports_formality":false},{"language":"ZH-HANS","name":"Chinese (simplified)","supports_formality":false}]

curl -H "Authorization: DeepL-Auth-Key KEY" "https://api.deepl.com/v2/languages?type=target" also works,

curl -H "Authorization: DeepL-Auth-Key KEY" -H "Content-Type: application/json" "https://api.deepl.com/v2/languages?type=target" doesnt, as you specify Content-Type to be json but don't provide JSON data.

[JanEbbing]

Maybe what's unclear is that type defaults to source languages? Otherwise I don't understand your question.

[frq-asgard-enro]

Thanks Jan for these clarifications. toge will be back in the office on tuesday and we'll let you know if anything is unclear.