feat: add support for extra request params

Author: Lucas Mathis

CHANGELOG.md

@@ -5,11 +5,9 @@ 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
-<!-- * add to here -->
-### Changed
-<!-- * add to here -->
 
+### Added
+* Added `extraRequestParameters` option to text and document translation methods to pass arbitrary parameters in the request body. This can be used to access beta features or override built-in parameters (such as `target_lang`, `source_lang`, etc.).
 
 ## [1.10.3] - 2025-08-22
 ### Security

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

@@ -0,0 +1,29 @@
+// 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 java.util.Map;
+
+/** Base class for request options providing common functionality for all endpoints. */
+public abstract class BaseRequestOptions {
+  private Map<String, String> extraBodyParameters;
+
+  /**
+   * Sets additional parameters to pass in the body of the HTTP request. Can be used to access beta
+   * features, override built-in parameters, or for testing purposes. Keys in this map will be added
+   * to the request body and can override existing keys.
+   *
+   * @param extraBodyParameters Map of additional parameters to include in the request.
+   * @return This options object for method chaining.
+   */
+  public BaseRequestOptions setExtraBodyParameters(Map<String, String> extraBodyParameters) {
+    this.extraBodyParameters = extraBodyParameters;
+    return this;
+  }
+
+  /** Gets the current extra body parameters. */
+  public Map<String, String> getExtraBodyParameters() {
+    return extraBodyParameters;
+  }
+}

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

@@ -13,7 +13,7 @@
  *          .setFormality(Formality.Less).setGlossaryId("f63c02c5-f056-..");
  * </code>
  */
-public class DocumentTranslationOptions {
+public class DocumentTranslationOptions extends BaseRequestOptions {
   private Formality formality;
   private String glossaryId;
 

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

@@ -13,7 +13,7 @@
  *          .setFormality(Formality.Less).setGlossaryId("f63c02c5-f056-..");
  * </code>
  */
-public class TextTranslationOptions {
+public class TextTranslationOptions extends BaseRequestOptions {
   private Formality formality;
   private String glossaryId;
   private SentenceSplittingMode sentenceSplittingMode;

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

@@ -846,6 +846,7 @@ private static ArrayList<KeyValuePair<String, String>> createHttpParams(
       if (options.getIgnoreTags() != null) {
         params.add(new KeyValuePair<>("ignore_tags", joinTags(options.getIgnoreTags())));
       }
+      addExtraBodyParameters(params, options.getExtraBodyParameters());
     }
     return params;
   }
@@ -862,11 +863,16 @@ private static ArrayList<KeyValuePair<String, String>> createHttpParams(
    */
   protected static ArrayList<KeyValuePair<String, String>> createHttpParams(
       String sourceLang, String targetLang, DocumentTranslationOptions options) {
-    return createHttpParamsCommon(
-        sourceLang,
-        targetLang,
-        options != null ? options.getFormality() : null,
-        options != null ? options.getGlossaryId() : null);
+    ArrayList<KeyValuePair<String, String>> params =
+        createHttpParamsCommon(
+            sourceLang,
+            targetLang,
+            options != null ? options.getFormality() : null,
+            options != null ? options.getGlossaryId() : null);
+
+    addExtraBodyParameters(params, options != null ? options.getExtraBodyParameters() : null);
+
+    return params;
   }
 
   /**
@@ -931,6 +937,23 @@ private static String joinTags(Iterable<String> tags) {
     return String.join(",", tags);
   }
 
+  /**
+   * Adds extra body parameters to the HTTP request parameters. Extra parameters can override
+   * existing parameters.
+   *
+   * @param params List of HTTP parameters to add to.
+   * @param extraBodyParameters Map of extra parameters to add (can be null).
+   */
+  private static void addExtraBodyParameters(
+      ArrayList<KeyValuePair<String, String>> params, Map<String, String> extraBodyParameters) {
+    if (extraBodyParameters != null) {
+      params.removeIf(pair -> extraBodyParameters.containsKey(pair.getKey()));
+      for (Map.Entry<String, String> entry : extraBodyParameters.entrySet()) {
+        params.add(new KeyValuePair<>(entry.getKey(), entry.getValue()));
+      }
+    }
+  }
+
   /**
    * Checks the specified source and target language are valid.
    *

deepl-java/src/test/java/com/deepl/api/TranslateTextTest.java

@@ -330,4 +330,23 @@ void testMixedCaseLanguages() throws DeepLException, InterruptedException {
     Assertions.assertEquals(exampleText.get("en-US"), result.getText().toLowerCase(Locale.ENGLISH));
     Assertions.assertEquals("de", result.getDetectedSourceLanguage());
   }
+
+  @Test
+  void testExtraBodyParams() throws DeepLException, InterruptedException {
+    Translator translator = createTranslator();
+
+    // Verifies that extra_body_parameters can override standard parameters like target_lang
+    Map<String, String> extraParams = new HashMap<>();
+    extraParams.put("target_lang", "FR");
+    extraParams.put("debug", "1");
+
+    TextTranslationOptions options = new TextTranslationOptions();
+    options.setExtraBodyParameters(extraParams);
+
+    TextResult result = translator.translateText(exampleText.get("en"), null, "DE", options);
+
+    Assertions.assertEquals(exampleText.get("fr"), result.getText());
+    Assertions.assertEquals("en", result.getDetectedSourceLanguage());
+    Assertions.assertEquals(exampleText.get("en").length(), result.getBilledCharacters());
+  }
 }