Skip to content

Commit a02d8a6

Browse files
Hive Agentclaude
andcommitted
feat: add getLanguagesForResource() and getLanguageResources()
Expose GET /v3/languages (with resource and include parameters) and GET /v3/languages/resources as public DeepLClient methods, returning the new LanguageSupport / LanguageFeature and LanguageResource / ResourceFeature models. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 3f50d13 commit a02d8a6

9 files changed

Lines changed: 483 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
### Added
99
- Added `LanguageCode` constants for the target language variants `de-CH`,
1010
`de-DE`, `es-ES`, `es-419`, `fr-CA`, `fr-FR`, `zh-Hans` and `zh-Hant`.
11+
- Added `DeepLClient.getLanguagesForResource()`, which calls
12+
`GET /v3/languages` for a given resource (`translate_text`, `glossary`,
13+
`write`, ...) with optional `include` values (`beta`, `external`) and
14+
returns `LanguageSupport` objects with per-language feature support.
15+
- Added `DeepLClient.getLanguageResources()`, which calls
16+
`GET /v3/languages/resources` and returns `LanguageResource` objects
17+
describing each resource's features and whether they need source and/or
18+
target language support.
1119

1220
### Changed
1321
- The bare target languages `en` and `pt` are no longer rejected

‎deepl-java/src/main/java/com/deepl/api/DeepLClient.java‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -793,6 +793,61 @@ public List<StyleRuleInfo> getAllStyleRules() throws DeepLException, Interrupted
793793
return getAllStyleRules(null, null, null);
794794
}
795795

796+
/**
797+
* Retrieves the languages supported by the given DeepL API resource, along with the features each
798+
* language supports for that resource.
799+
*
800+
* @param resource Resource to retrieve languages for, for example {@link
801+
* LanguageResource#RESOURCE_TRANSLATE_TEXT} or {@link LanguageResource#RESOURCE_GLOSSARY}.
802+
* @param include Optional list of include values, for example {@link
803+
* LanguageSupport#INCLUDE_BETA} or {@link LanguageSupport#INCLUDE_EXTERNAL}. By default, or
804+
* if <code>null</code>, only stable languages and features are returned.
805+
* @return List of {@link LanguageSupport} objects with per-feature support information.
806+
* @throws IllegalArgumentException If resource is <code>null</code> or empty.
807+
* @throws InterruptedException If the thread is interrupted during execution of this function.
808+
* @throws DeepLException If any error occurs while communicating with the DeepL API.
809+
*/
810+
public List<LanguageSupport> getLanguagesForResource(
811+
String resource, @Nullable List<String> include) throws DeepLException, InterruptedException {
812+
validateParameter("resource", resource);
813+
ArrayList<KeyValuePair<String, String>> queryParams = new ArrayList<>();
814+
queryParams.add(new KeyValuePair<>("resource", resource));
815+
if (include != null) {
816+
for (String value : include) {
817+
queryParams.add(new KeyValuePair<>("include", value));
818+
}
819+
}
820+
String relativeUrl = "/v3/languages" + createQueryString(queryParams);
821+
HttpResponse response = httpClientWrapper.sendGetRequestWithBackoff(relativeUrl);
822+
checkResponse(response, false, false);
823+
return jsonParser.parseLanguageSupportList(response.getBody());
824+
}
825+
826+
/**
827+
* Functions the same as {@link DeepLClient#getLanguagesForResource(String, List)} but returns
828+
* only stable languages and features.
829+
*
830+
* @see DeepLClient#getLanguagesForResource(String, List)
831+
*/
832+
public List<LanguageSupport> getLanguagesForResource(String resource)
833+
throws DeepLException, InterruptedException {
834+
return getLanguagesForResource(resource, null);
835+
}
836+
837+
/**
838+
* Retrieves the resources supported by the DeepL API, along with their features and whether each
839+
* feature requires support from the source and/or target language.
840+
*
841+
* @return List of {@link LanguageResource} objects, one per supported resource.
842+
* @throws InterruptedException If the thread is interrupted during execution of this function.
843+
* @throws DeepLException If any error occurs while communicating with the DeepL API.
844+
*/
845+
public List<LanguageResource> getLanguageResources() throws DeepLException, InterruptedException {
846+
HttpResponse response = httpClientWrapper.sendGetRequestWithBackoff("/v3/languages/resources");
847+
checkResponse(response, false, false);
848+
return jsonParser.parseLanguageResourceList(response.getBody());
849+
}
850+
796851
/**
797852
* Retrieves a list of translation memories available for the account associated with the DeepL
798853
* API auth key. The maximum number of translation memories returned is controlled by pageSize
Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
// Copyright 2026 DeepL SE (https://www.deepl.com)
2+
// Use of this source code is governed by an MIT
3+
// license that can be found in the LICENSE file.
4+
package com.deepl.api;
5+
6+
/**
7+
* Support level of a single feature for a language, as returned by {@link
8+
* DeepLClient#getLanguagesForResource(String, java.util.List)}.
9+
*/
10+
public class LanguageFeature {
11+
/** Feature: automatic source-language detection. */
12+
public static final String FEATURE_AUTO_DETECTION = "auto_detection";
13+
/** Feature: formality control. */
14+
public static final String FEATURE_FORMALITY = "formality";
15+
/** Feature: glossary support. */
16+
public static final String FEATURE_GLOSSARY = "glossary";
17+
/** Feature: style rules. */
18+
public static final String FEATURE_STYLE_RULES = "style_rules";
19+
/** Feature: tag handling. */
20+
public static final String FEATURE_TAG_HANDLING = "tag_handling";
21+
/** Feature: translation memory. */
22+
public static final String FEATURE_TRANSLATION_MEMORY = "translation_memory";
23+
/** Feature: tone control (write). */
24+
public static final String FEATURE_TONE = "tone";
25+
/** Feature: writing style (write). */
26+
public static final String FEATURE_WRITING_STYLE = "writing_style";
27+
/** Feature: transcription (voice). */
28+
public static final String FEATURE_TRANSCRIPTION = "transcription";
29+
/** Feature: translated speech (voice). */
30+
public static final String FEATURE_TRANSLATED_SPEECH = "translated_speech";
31+
/** Feature: spoken terms (voice). */
32+
public static final String FEATURE_SPOKEN_TERMS = "spoken_terms";
33+
34+
private final String status;
35+
36+
/**
37+
* Initializes a new LanguageFeature object.
38+
*
39+
* @param status Support status of the feature, for example "stable" or "beta".
40+
*/
41+
public LanguageFeature(String status) {
42+
this.status = status;
43+
}
44+
45+
/** @return Support status of the feature, for example "stable" or "beta". */
46+
public String getStatus() {
47+
return status;
48+
}
49+
}
Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
// Copyright 2026 DeepL SE (https://www.deepl.com)
2+
// Use of this source code is governed by an MIT
3+
// license that can be found in the LICENSE file.
4+
package com.deepl.api;
5+
6+
import java.util.Collections;
7+
import java.util.Map;
8+
9+
/**
10+
* Information about a single DeepL resource and the features it supports, as returned by {@link
11+
* DeepLClient#getLanguageResources()}.
12+
*/
13+
public class LanguageResource {
14+
/** Resource value: text translation. */
15+
public static final String RESOURCE_TRANSLATE_TEXT = "translate_text";
16+
/** Resource value: document translation. */
17+
public static final String RESOURCE_TRANSLATE_DOCUMENT = "translate_document";
18+
/** Resource value: glossary. */
19+
public static final String RESOURCE_GLOSSARY = "glossary";
20+
/** Resource value: voice. */
21+
public static final String RESOURCE_VOICE = "voice";
22+
/** Resource value: write (rephrase). */
23+
public static final String RESOURCE_WRITE = "write";
24+
/** Resource value: style rules. */
25+
public static final String RESOURCE_STYLE_RULES = "style_rules";
26+
/** Resource value: translation memory. */
27+
public static final String RESOURCE_TRANSLATION_MEMORY = "translation_memory";
28+
29+
private final String resource;
30+
private final Map<String, ResourceFeature> features;
31+
32+
/**
33+
* Initializes a new LanguageResource object.
34+
*
35+
* @param resource Name of the resource, for example "translate_text".
36+
* @param features Map of feature name to {@link ResourceFeature}.
37+
*/
38+
public LanguageResource(String resource, Map<String, ResourceFeature> features) {
39+
this.resource = resource;
40+
this.features = features;
41+
}
42+
43+
/** @return Name of the resource, for example "translate_text". */
44+
public String getResource() {
45+
return resource;
46+
}
47+
48+
/**
49+
* @return Map of feature name to {@link ResourceFeature} for each feature the resource supports,
50+
* including whether it requires source and/or target language support.
51+
*/
52+
public Map<String, ResourceFeature> getFeatures() {
53+
return Collections.unmodifiableMap(features);
54+
}
55+
56+
/**
57+
* Checks whether this resource exposes the given feature.
58+
*
59+
* @param feature Feature name, for example {@link LanguageFeature#FEATURE_GLOSSARY}.
60+
* @return <code>true</code> if the feature is exposed by the resource.
61+
*/
62+
public boolean supports(String feature) {
63+
return features.containsKey(feature);
64+
}
65+
}
Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
// Copyright 2026 DeepL SE (https://www.deepl.com)
2+
// Use of this source code is governed by an MIT
3+
// license that can be found in the LICENSE file.
4+
package com.deepl.api;
5+
6+
import com.google.gson.annotations.SerializedName;
7+
import java.util.Collections;
8+
import java.util.Map;
9+
import org.jetbrains.annotations.Nullable;
10+
11+
/**
12+
* Information about a language supported by the DeepL API for a given resource, as returned by
13+
* {@link DeepLClient#getLanguagesForResource(String, java.util.List)}.
14+
*/
15+
public class LanguageSupport {
16+
/** Include value: also return beta languages and features. */
17+
public static final String INCLUDE_BETA = "beta";
18+
/** Include value: also return features that rely on third-party service providers. */
19+
public static final String INCLUDE_EXTERNAL = "external";
20+
21+
@SerializedName("lang")
22+
private final String code;
23+
24+
private final String name;
25+
26+
private final String status;
27+
28+
@SerializedName("usable_as_source")
29+
private final boolean usableAsSource;
30+
31+
@SerializedName("usable_as_target")
32+
private final boolean usableAsTarget;
33+
34+
@Nullable private final Map<String, LanguageFeature> features;
35+
36+
/**
37+
* Initializes a new LanguageSupport object.
38+
*
39+
* @param code BCP-47 language code, for example "de", "en-US" or "zh-Hans".
40+
* @param name Name of the language in English.
41+
* @param status Support status of the language, for example "stable" or "beta".
42+
* @param usableAsSource Whether the language can be used as a source language.
43+
* @param usableAsTarget Whether the language can be used as a target language.
44+
* @param features Map of feature name to {@link LanguageFeature}.
45+
*/
46+
public LanguageSupport(
47+
String code,
48+
String name,
49+
String status,
50+
boolean usableAsSource,
51+
boolean usableAsTarget,
52+
@Nullable Map<String, LanguageFeature> features) {
53+
this.code = code;
54+
this.name = name;
55+
this.status = status;
56+
this.usableAsSource = usableAsSource;
57+
this.usableAsTarget = usableAsTarget;
58+
this.features = features;
59+
}
60+
61+
/** @return BCP-47 language code, for example "de", "en-US", "pt-BR" or "zh-Hans". */
62+
public String getCode() {
63+
return code;
64+
}
65+
66+
/** @return Name of the language in English. */
67+
public String getName() {
68+
return name;
69+
}
70+
71+
/** @return Support status of the language, for example "stable" or "beta". */
72+
public String getStatus() {
73+
return status;
74+
}
75+
76+
/** @return <code>true</code> if the language can be used as a source language. */
77+
public boolean isUsableAsSource() {
78+
return usableAsSource;
79+
}
80+
81+
/** @return <code>true</code> if the language can be used as a target language. */
82+
public boolean isUsableAsTarget() {
83+
return usableAsTarget;
84+
}
85+
86+
/**
87+
* @return Map of feature name to {@link LanguageFeature} for the features this language supports
88+
* with the requested resource; empty if it supports no optional features.
89+
*/
90+
public Map<String, LanguageFeature> getFeatures() {
91+
return features == null ? Collections.emptyMap() : Collections.unmodifiableMap(features);
92+
}
93+
94+
/**
95+
* Checks whether this language supports the given feature for the requested resource.
96+
*
97+
* @param feature Feature name, for example {@link LanguageFeature#FEATURE_FORMALITY}.
98+
* @return <code>true</code> if the feature is supported.
99+
*/
100+
public boolean supports(String feature) {
101+
return features != null && features.containsKey(feature);
102+
}
103+
104+
@Override
105+
public String toString() {
106+
return name + " (" + code + ")";
107+
}
108+
}
Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// Copyright 2026 DeepL SE (https://www.deepl.com)
2+
// Use of this source code is governed by an MIT
3+
// license that can be found in the LICENSE file.
4+
package com.deepl.api;
5+
6+
import com.google.gson.annotations.SerializedName;
7+
import org.jetbrains.annotations.Nullable;
8+
9+
/**
10+
* A feature supported by a DeepL resource, as returned by {@link
11+
* DeepLClient#getLanguageResources()}.
12+
*/
13+
public class ResourceFeature {
14+
private final String name;
15+
16+
@SerializedName("needs_source_support")
17+
@Nullable
18+
private final Boolean needsSourceSupport;
19+
20+
@SerializedName("needs_target_support")
21+
@Nullable
22+
private final Boolean needsTargetSupport;
23+
24+
/**
25+
* Initializes a new ResourceFeature object.
26+
*
27+
* @param name Feature name, for example "glossary" or "formality".
28+
* @param needsSourceSupport Whether the source language must support the feature.
29+
* @param needsTargetSupport Whether the target language must support the feature.
30+
*/
31+
public ResourceFeature(
32+
String name, @Nullable Boolean needsSourceSupport, @Nullable Boolean needsTargetSupport) {
33+
this.name = name;
34+
this.needsSourceSupport = needsSourceSupport;
35+
this.needsTargetSupport = needsTargetSupport;
36+
}
37+
38+
/** @return Feature name, for example "glossary" or "formality". */
39+
public String getName() {
40+
return name;
41+
}
42+
43+
/**
44+
* @return <code>true</code> if the source language must support this feature, <code>false
45+
* </code> if not, or <code>null</code> if the API omitted the flag (the API treats this as
46+
* <code>false</code>).
47+
*/
48+
@Nullable
49+
public Boolean getNeedsSourceSupport() {
50+
return needsSourceSupport;
51+
}
52+
53+
/**
54+
* @return <code>true</code> if the target language must support this feature, <code>false
55+
* </code> if not, or <code>null</code> if the API omitted the flag (the API treats this as
56+
* <code>false</code>).
57+
*/
58+
@Nullable
59+
public Boolean getNeedsTargetSupport() {
60+
return needsTargetSupport;
61+
}
62+
}

‎deepl-java/src/main/java/com/deepl/api/parsing/Parser.java‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,27 @@ public List<Language> parseV3Languages(String json, LanguageType languageType) {
6262
return result;
6363
}
6464

65+
public List<LanguageSupport> parseLanguageSupportList(String json) {
66+
Type listType = new TypeToken<ArrayList<LanguageSupport>>() {}.getType();
67+
return gson.fromJson(json, listType);
68+
}
69+
70+
public List<LanguageResource> parseLanguageResourceList(String json) {
71+
Type listType = new TypeToken<ArrayList<V3LanguageResource>>() {}.getType();
72+
List<V3LanguageResource> entries = gson.fromJson(json, listType);
73+
List<LanguageResource> result = new ArrayList<>();
74+
for (V3LanguageResource entry : entries) {
75+
Map<String, ResourceFeature> features = new LinkedHashMap<>();
76+
if (entry.features != null) {
77+
for (ResourceFeature feature : entry.features) {
78+
features.put(feature.getName(), feature);
79+
}
80+
}
81+
result.add(new LanguageResource(entry.name, features));
82+
}
83+
return result;
84+
}
85+
6586
public List<GlossaryLanguagePair> parseV3GlossaryLanguagePairs(String json) {
6687
Type v3LanguageListType = new TypeToken<ArrayList<V3Language>>() {}.getType();
6788
List<V3Language> entries = gson.fromJson(json, v3LanguageListType);

0 commit comments

Comments
 (0)