feat: Add extra parameters to translation requests

Author: JanEbbing

CHANGELOG.md

@@ -6,6 +6,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 ## [Unreleased]
+### Added
+* Add possibility to add extra parameters to a translation request (both text and document).
+  DeepL engineers use this to test features in the API before they are released. Library users
+  who cannot update their DeepL library dependency could use these extra parameters to access
+  features in the API that are released in the future.
 ### Security
 * Increase `follow-redirects` locked-version due to security 
   [vulnerability in follow-redirects <1.15.5](https://github.com/advisories/GHSA-cxjh-pqwp-8mfp) 

README.md

@@ -192,6 +192,10 @@ 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 
+    HTTP request. Only string values are permitted.
+    For example: `{'param': 'value', 'param2': 'value2'}`
+
 
 ### Translating documents
 
@@ -246,6 +250,7 @@ directly:
 -   `glossary`: same as in [Text translation options](#text-translation-options).
 -   `filename`: if the input file is not provided as file path, this option is
     needed to specify the file extension.
+-   `extraRequestParameters`: same as in [Text translation options](#text-translation-options).
 
 ### Glossaries
 

src/index.ts

@@ -31,6 +31,7 @@ import {
     GlossaryInfo,
     LanguageCode,
     NonRegionalLanguageCode,
+    RequestParameters,
     SentenceSplittingMode,
     SourceGlossaryLanguageCode,
     SourceLanguageCode,
@@ -255,6 +256,7 @@ function buildURLSearchParams(
     targetLang: LanguageCode,
     formality: Formality | undefined,
     glossary: GlossaryId | GlossaryInfo | undefined,
+    extraRequestParameters: RequestParameters | undefined,
 ): URLSearchParams {
     targetLang = standardizeLanguageCode(targetLang);
     if (sourceLang !== null) {
@@ -305,6 +307,11 @@ function buildURLSearchParams(
         }
         searchParams.append('glossary_id', glossary);
     }
+    if (extraRequestParameters !== undefined) {
+        for (const paramName in extraRequestParameters) {
+            searchParams.append(paramName, extraRequestParameters[paramName]);
+        }
+    }
     return searchParams;
 }
 
@@ -567,6 +574,7 @@ export class Translator {
             targetLang,
             options?.formality,
             options?.glossary,
+            options?.extraRequestParameters,
         );
         const singular = appendTextsAndReturnIsSingular(data, texts);
         validateAndAppendTextOptions(data, options);
@@ -913,6 +921,7 @@ export class Translator {
             targetLang,
             options?.formality,
             options?.glossary,
+            options?.extraRequestParameters,
         );
         const { statusCode, content } = await this.httpClient.sendRequestWithBackoff<string>(
             'POST',

src/types.ts

@@ -144,6 +144,9 @@ 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;
 }
 
 /**
@@ -158,6 +161,9 @@ 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;
 }
 
 /**
@@ -246,3 +252,9 @@ export type SourceGlossaryLanguageCode =
  * API accept case-insensitive language codes.
  */
 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>;