feat: add support for extra request params

Author: Lucas Mathis

CHANGELOG.md

@@ -4,6 +4,11 @@ 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 `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.12.0] - 2025-04-25
 ### Added
 * Added support for the /v3 Multilingual Glossary APIs in the client library 

src/TranslateDocumentOptions.php

@@ -27,4 +27,11 @@ final class TranslateDocumentOptions
 
     /** Set to `true` in order to use Document Minification for translation, if available. */
     public const ENABLE_DOCUMENT_MINIFICATION = 'enable_document_minification';
+
+    /** Dictionary of extra 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 array will be added to the request body and can override existing keys.
+     * Values must be of string type.
+     */
+    public const EXTRA_BODY_PARAMETERS = 'extra_body_parameters';
 }

src/TranslateTextOptions.php

@@ -79,4 +79,11 @@ class TranslateTextOptions
      * - 'latency_optimized': Use translation models that have been optimized for translation speed.
      */
     public const MODEL_TYPE = 'model_type';
+
+    /** Dictionary of extra 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 array will be added to the request body and can override existing keys.
+     * Values must be of string type.
+     */
+    public const EXTRA_BODY_PARAMETERS = 'extra_body_parameters';
 }

src/Translator.php

@@ -272,6 +272,11 @@ public function uploadDocument(
             $options[TranslateDocumentOptions::GLOSSARY] ?? null
         );
 
+        $this->applyExtraBodyParameters(
+            $params,
+            $options[TranslateDocumentOptions::EXTRA_BODY_PARAMETERS] ?? null
+        );
+
         $response = $this->client->sendRequestWithBackoff(
             'POST',
             '/v2/document',
@@ -688,6 +693,23 @@ private function validateAndAppendTextOptions(array &$params, ?array $options):
             $params[TranslateTextOptions::IGNORE_TAGS] =
                 $this->joinTagList($options[TranslateTextOptions::IGNORE_TAGS]);
         }
+        $this->applyExtraBodyParameters(
+            $params,
+            $options[TranslateTextOptions::EXTRA_BODY_PARAMETERS] ?? null
+        );
+    }
+
+    /**
+     * Adds extra body parameters to the params array. Extra parameters can override existing keys.
+     * Values are converted to strings.
+     */
+    private function applyExtraBodyParameters(array &$params, ?array $extraParams): void
+    {
+        if ($extraParams !== null) {
+            foreach ($extraParams as $key => $value) {
+                $params[$key] = (string)$value;
+            }
+        }
     }
 
     /**

tests/TranslateTextTest.php

@@ -395,4 +395,24 @@ public function testTagHandlingHTML(?ClientInterface $httpClient)
         $this->assertStringContainsString('<h1>Meine erste Überschrift</h1>', $result->text);
         $this->assertStringContainsString('<p translate="no">My first paragraph.</p>', $result->text);
     }
+
+    /**
+     * @dataProvider provideHttpClient
+     */
+    public function testExtraBodyParams(?ClientInterface $httpClient)
+    {
+        $translator = $this->makeTranslator([TranslatorOptions::HTTP_CLIENT => $httpClient]);
+
+        $extra = ['target_lang' => 'FR', 'debug' => '1'];
+        $result = $translator->translateText(
+            DeepLTestBase::EXAMPLE_TEXT['en'],
+            null,
+            'de',
+            [TranslateTextOptions::EXTRA_BODY_PARAMETERS => $extra]
+        );
+
+        $this->assertEquals(DeepLTestBase::EXAMPLE_TEXT['fr'], $result->text);
+        $this->assertEquals('en', $result->detectedSourceLang);
+        $this->assertEquals(mb_strlen(DeepLTestBase::EXAMPLE_TEXT['en']), $result->billedCharacters);
+    }
 }