feat: add support for extra request params

Author: Lucas Mathis

CHANGELOG.md

@@ -6,6 +6,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [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.20.0] - 2025-10-08
 ### Added
 * Official support for Node.js versions 20, 22 and 24

README.md

@@ -202,9 +202,12 @@ The following options are only used if `tagHandling` is `'xml'`:
     into sentences. Format and default are the same as for `splittingTags`.
 -   `ignoreTags`: list of XML tags that containing content that should not be
     translated. Format and default are the same as for `splittingTags`.
--   `extraRequestParameters`: Extra body parameters to be passed along with the 
+-   `extraRequestParameters`: Extra body parameters to be passed along with the
     HTTP request. Only string values are permitted.
     For example: `{'param': 'value', 'param2': 'value2'}`
+    Note: Extra request parameters can override parameters explicitly set by the library
+    (such as `target_lang`, `source_lang`, etc.). This is primarily useful for testing or
+    accessing beta features.
 
 
 ### Translating documents

src/types.ts

@@ -88,6 +88,23 @@ export type ModelType = 'quality_optimized' | 'latency_optimized' | 'prefer_qual
 export type GlossaryId = string;
 export type TagList = string | string[];
 
+/**
+ * Extra request parameters to be passed with translation requests.
+ */
+export type RequestParameters = Record<string, string>;
+
+/**
+ * Base options that apply to all translation endpoints. Planned to be extended to other endpoints in future.
+ */
+export interface BaseRequestOptions {
+    /**
+     * Extra parameters to be added to the request body.
+     * Keys in this object will be added to the request body, and can override built-in parameters.
+     * This is mostly used by DeepL employees to test functionality, or for beta programs.
+     */
+    extraRequestParameters?: RequestParameters;
+}
+
 /**
  * Information about a glossary, excluding the entry list. {@link GlossaryInfo} is compatible with the
  * /v2 glossary endpoints and can only support mono-lingual glossaries (e.g. a glossary with only one source and
@@ -113,7 +130,7 @@ export interface GlossaryInfo {
 /**
  * Options that can be specified when translating text.
  */
-export interface TranslateTextOptions {
+export interface TranslateTextOptions extends BaseRequestOptions {
     /**
      * Specifies how input translation text should be split into sentences.
      * - 'on': Input translation text will be split into sentences using both newlines and
@@ -161,17 +178,14 @@ export interface TranslateTextOptions {
     /** List of XML tags containing content that should not be translated. */
     ignoreTags?: TagList;
 
-    /** Extra parameters to be added to a text translation request. */
-    extraRequestParameters?: RequestParameters;
-
     /** (internal only) Override path to send translate request to. */
     __path?: string;
 }
 
 /**
  * Options that can be specified when translating documents.
  */
-export interface DocumentTranslateOptions {
+export interface DocumentTranslateOptions extends BaseRequestOptions {
     /** Controls whether translations should lean toward formal or informal language. */
     formality?: Formality;
 
@@ -183,9 +197,6 @@ export interface DocumentTranslateOptions {
     /** Filename including extension, only required when translating documents as streams. */
     filename?: string;
 
-    /** Extra parameters to be added to a text translation request. */
-    extraRequestParameters?: RequestParameters;
-
     /** Controls whether to use Document Minification for translation, if available. */
     enableDocumentMinification?: boolean;
 }
@@ -308,12 +319,6 @@ export type SourceGlossaryLanguageCode =
  */
 export type TargetGlossaryLanguageCode = SourceGlossaryLanguageCode;
 
-/**
- * Extra request parameters to be passed with translation requests.
- * They are stored as an object where each field represents a request parameter.
- */
-export type RequestParameters = Record<string, string>;
-
 /**
  * Information about the API usage: how much has been translated in this billing period, and the
  * maximum allowable amount.

src/utils.ts

@@ -185,7 +185,7 @@ export function buildURLSearchParams(
     }
     if (extraRequestParameters !== undefined) {
         for (const paramName in extraRequestParameters) {
-            searchParams.append(paramName, extraRequestParameters[paramName]);
+            searchParams.set(paramName, extraRequestParameters[paramName]);
         }
     }
     return searchParams;

tests/translateText.test.ts

@@ -270,6 +270,17 @@ describe('translate text', () => {
         expect(result.text).toContain('<p translate="no">My first paragraph.</p>');
     });
 
+    it('allows extra parameters to override standard parameters', async () => {
+        const translator = makeTranslator();
+        const options: TranslateTextOptions = {
+            extraRequestParameters: { target_lang: 'fr', example_extra_param: 'true' },
+        };
+        const result = await translator.translateText(exampleText.en, null, 'de', options);
+        expect(result.text).toBe(exampleText.fr);
+        expect(result.detectedSourceLang).toBe('en');
+        expect(result.billedCharacters).toBe(exampleText.en.length);
+    });
+
     describe('request parameter tests', () => {
         beforeAll(() => {
             nock.disableNetConnect();