feat: Add support for multilingual glossary endpoints

Author: BriannaDelgado

CHANGELOG.md

@@ -4,9 +4,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-
 ## [Unreleased]
 ### Added
+* Added support for the /v3 Multilingual Glossary APIs in the client library
+  while providing backwards compatability for the previous /v2 Glossary
+  endpoints. Please refer to the README or
+  [upgrading_to_multilingual_glossaries.md](upgrading_to_multilingual_glossaries.md)
+  for usage instructions.
 * Added Ukrainian language code
 
 

README.md

@@ -27,6 +27,7 @@ dependencies {
     implementation("org.jetbrains:annotations:20.1.0")
     testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
     testImplementation("org.mockito:mockito-inline:4.11.0")
+    implementation("org.apache.httpcomponents:httpclient:4.5.2") { because("java.net.HttpURLConnection does not support PATCH") }
 
 //    implementation("com.google.guava:guava:30.1.1-jre")
     implementation("com.google.code.gson:gson:2.10.1")

deepl-java/build.gradle.kts

@@ -43,7 +43,7 @@ public DocumentTranslationOptions setGlossaryId(String glossaryId) {
    * Sets the glossary to use with the translation. By default, this value is <code>null</code> and
    * no glossary is used.
    */
-  public DocumentTranslationOptions setGlossary(GlossaryInfo glossary) {
+  public DocumentTranslationOptions setGlossary(IGlossary glossary) {
     return setGlossary(glossary.getGlossaryId());
   }
 

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

@@ -8,7 +8,7 @@
 import org.jetbrains.annotations.*;
 
 /** Information about a glossary, excluding the entry list. */
-public class GlossaryInfo {
+public class GlossaryInfo implements IGlossary {
 
   @SerializedName(value = "glossary_id")
   private final String glossaryId;

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

@@ -9,6 +9,12 @@
 import java.net.*;
 import java.time.*;
 import java.util.*;
+import org.apache.http.client.config.RequestConfig;
+import org.apache.http.client.methods.HttpPatch;
+import org.apache.http.entity.ByteArrayEntity;
+import org.apache.http.impl.client.CloseableHttpClient;
+import org.apache.http.impl.client.HttpClients;
+import org.apache.http.util.EntityUtils;
 import org.jetbrains.annotations.*;
 
 /**
@@ -21,6 +27,7 @@ class HttpClientWrapper {
   private static final String GET = "GET";
   private static final String POST = "POST";
   private static final String DELETE = "DELETE";
+  private static final String PUT = "PUT";
   private final String serverUrl;
   private final Map<String, String> headers;
   private final Duration minTimeout;
@@ -45,9 +52,16 @@ public HttpResponse sendGetRequestWithBackoff(String relativeUrl)
     return sendRequestWithBackoff(GET, relativeUrl, null).toStringResponse();
   }
 
+  public HttpResponse sendDeleteRequestWithBackoff(
+      String relativeUrl, @Nullable Iterable<KeyValuePair<String, String>> params)
+      throws InterruptedException, DeepLException {
+    HttpContent content = HttpContent.buildFormURLEncodedContent(params);
+    return sendRequestWithBackoff(DELETE, relativeUrl, content).toStringResponse();
+  }
+
   public HttpResponse sendDeleteRequestWithBackoff(String relativeUrl)
       throws InterruptedException, DeepLException {
-    return sendRequestWithBackoff(DELETE, relativeUrl, null).toStringResponse();
+    return sendDeleteRequestWithBackoff(relativeUrl, null);
   }
 
   public HttpResponse sendRequestWithBackoff(String relativeUrl)
@@ -62,6 +76,56 @@ public HttpResponse sendRequestWithBackoff(
     return sendRequestWithBackoff(POST, relativeUrl, content).toStringResponse();
   }
 
+  public HttpResponse sendPutRequestWithBackoff(
+      String relativeUrl, @Nullable Iterable<KeyValuePair<String, String>> params)
+      throws InterruptedException, DeepLException {
+    HttpContent content = HttpContent.buildFormURLEncodedContent(params);
+    return sendRequestWithBackoff(PUT, relativeUrl, content).toStringResponse();
+  }
+
+  public HttpResponse sendPatchRequestWithBackoff(
+      String relativeUrl, @Nullable Iterable<KeyValuePair<String, String>> params)
+      throws DeepLException {
+    try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
+      HttpContent content = HttpContent.buildFormURLEncodedContent(params);
+      HttpPatch request = new HttpPatch(serverUrl + relativeUrl);
+
+      // Set timeouts
+      BackoffTimer backoffTimer = new BackoffTimer(this.minTimeout);
+      RequestConfig requestConfig =
+          RequestConfig.custom()
+              .setConnectTimeout((int) backoffTimer.getTimeoutMillis())
+              .setSocketTimeout((int) backoffTimer.getTimeoutMillis())
+              .build();
+      request.setConfig(requestConfig);
+
+      // Set headers
+      for (Map.Entry<String, String> entry : this.headers.entrySet()) {
+        request.setHeader(entry.getKey(), entry.getValue());
+      }
+
+      request.setHeader("Content-Type", content.getContentType());
+      request.setEntity(new ByteArrayEntity(content.getContent()));
+
+      // Execute the request
+      org.apache.http.HttpResponse response = httpClient.execute(request);
+
+      // Get the response stream
+      InputStream responseStream =
+          (response.getStatusLine().getStatusCode() >= 200
+                  && response.getStatusLine().getStatusCode() < 400)
+              ? response.getEntity().getContent()
+              : new ByteArrayInputStream(EntityUtils.toByteArray(response.getEntity()));
+
+      return new HttpResponseStream(response.getStatusLine().getStatusCode(), responseStream)
+          .toStringResponse();
+    } catch (SocketTimeoutException e) {
+      throw new ConnectionException(e.getMessage(), true, e);
+    } catch (RuntimeException | IOException e) {
+      throw new ConnectionException(e.getMessage(), false, e);
+    }
+  }
+
   public HttpResponseStream downloadWithBackoff(
       String relativeUrl, @Nullable Iterable<KeyValuePair<String, String>> params)
       throws InterruptedException, DeepLException {

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

@@ -0,0 +1,10 @@
+// Copyright 2025 DeepL SE (https://www.deepl.com)
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+package com.deepl.api;
+
+/** Interface representing a glossary. */
+public interface IGlossary {
+  /** @return Unique ID assigned to the glossary. */
+  String getGlossaryId();
+}

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

@@ -0,0 +1,41 @@
+// Copyright 2025 DeepL SE (https://www.deepl.com)
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+package com.deepl.api;
+
+/** Stores the entries of a glossary. */
+public class MultilingualGlossaryDictionaryEntries {
+  private final String sourceLanguageCode;
+  private final String targetLanguageCode;
+  private final GlossaryEntries entries;
+
+  /**
+   * Initializes a new {@link MultilingualGlossaryDictionaryInfo} containing information about a
+   * glossary dictionary.
+   *
+   * @param sourceLanguageCode the source language for this dictionary
+   * @param targetLanguageCode the target language for this dictionary
+   * @param entries the entries in this dictionary
+   */
+  public MultilingualGlossaryDictionaryEntries(
+      String sourceLanguageCode, String targetLanguageCode, GlossaryEntries entries) {
+    this.sourceLanguageCode = sourceLanguageCode;
+    this.targetLanguageCode = targetLanguageCode;
+    this.entries = entries;
+  }
+
+  /** @return the source language code */
+  public String getSourceLanguageCode() {
+    return this.sourceLanguageCode;
+  }
+
+  /** @return the target language code */
+  public String getTargetLanguageCode() {
+    return this.targetLanguageCode;
+  }
+
+  /** @return the entry count */
+  public GlossaryEntries getEntries() {
+    return this.entries;
+  }
+}

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

@@ -0,0 +1,48 @@
+// Copyright 2025 DeepL SE (https://www.deepl.com)
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+package com.deepl.api;
+
+import com.google.gson.annotations.SerializedName;
+
+/** Stores the entries of a glossary. */
+public class MultilingualGlossaryDictionaryInfo {
+  @SerializedName(value = "source_lang")
+  private final String sourceLanguageCode;
+
+  @SerializedName(value = "target_lang")
+  private final String targetLanguageCode;
+
+  @SerializedName(value = "entry_count")
+  private final long entryCount;
+
+  /**
+   * Initializes a new {@link MultilingualGlossaryDictionaryInfo} containing information about a
+   * glossary dictionary.
+   *
+   * @param sourceLanguageCode the source language for this dictionary
+   * @param targetLanguageCode the target language for this dictionary
+   * @param entryCount the number of entries in this dictionary
+   */
+  public MultilingualGlossaryDictionaryInfo(
+      String sourceLanguageCode, String targetLanguageCode, long entryCount) {
+    this.sourceLanguageCode = sourceLanguageCode;
+    this.targetLanguageCode = targetLanguageCode;
+    this.entryCount = entryCount;
+  }
+
+  /** @return the source language code */
+  public String getSourceLanguageCode() {
+    return this.sourceLanguageCode;
+  }
+
+  /** @return the target language code */
+  public String getTargetLanguageCode() {
+    return this.targetLanguageCode;
+  }
+
+  /** @return the entry count */
+  public long getEntryCount() {
+    return this.entryCount;
+  }
+}