fix: send options.filename for a file path document upload

translateDocumentUpload() (and so translateDocument()) sent the path's
base name and ignored the filename option when the input was a file path.
It now sends the filename option when set and falls back to the base name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: hive-bot

CHANGELOG.md

@@ -265,6 +265,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   major version.
 
 ### Fixed
+- `translateDocument()` and `translateDocumentUpload()` send the `filename`
+  option as the file name when the input is a file path, instead of always
+  sending the path's base name. The base name remains the default.
 - An `Authorization` header in the `headers` option, in any casing, no longer
   replaces the `DeepL-Auth-Key` authorization header; it is ignored. A
   `User-Agent` header in the `headers` option replaces the default User-Agent in

README.md

@@ -344,8 +344,10 @@ statuses this library does not know.
     `DocumentTranslationError` whose message contains `Style profile not found.`.
 -   `translationMemory`: same as in [Text translation options](#text-translation-options).
 -   `translationMemoryThreshold`: 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.
+-   `filename`: file name sent with the upload; its extension determines the
+    document type. Required if the input file is not provided as file path. For a
+    file path it defaults to the path's base name; set it when the path lacks the
+    right extension, for example `filename: 'report.docx'` for a temporary file.
 -   `outputFormat`: file extension of the desired format of the translated
     document, for example `'docx'`. If unspecified, the translated document has
     the same format as the input document.

src/translator.ts

@@ -303,7 +303,8 @@ export class Translator {
      * translation to complete, then downloads translated document to specified output path.
      * @param inputFile String containing file path of document to be translated, or a Stream,
      *     Buffer, or FileHandle containing file data. Note: unless file path is used, then
-     *     `options.filename` must be specified.
+     *     `options.filename` must be specified. For a file path, `options.filename` defaults to
+     *     the path's base name.
      * @param outputFile String containing file path to create translated document, or Stream or
      *     FileHandle to write translated document content.
      * @param sourceLang Language code of input document, or null to use auto-detection.
@@ -403,6 +404,7 @@ export class Translator {
      * Uploads specified document to DeepL to translate into target language, and returns handle associated with the document.
      * @param inputFile String containing file path, stream containing file data, or FileHandle.
      *     Note: if a Buffer, Stream, or FileHandle is used, then `options.filename` must be specified.
+     *     For a file path, `options.filename` defaults to the path's base name.
      * @param sourceLang Language code of input document, or null to use auto-detection.
      * @param targetLang Language code of language to translate into.
      * @param options Optional DocumentTranslateOptions object containing additional options controlling translation.
@@ -420,7 +422,7 @@ export class Translator {
                 buffer,
                 sourceLang,
                 targetLang,
-                path.basename(inputFile),
+                options?.filename ?? path.basename(inputFile),
                 options,
             );
         } else {

src/types.ts

@@ -319,7 +319,11 @@ export interface DocumentTranslateOptions extends BaseRequestOptions {
     /** Specifies the minimum similarity threshold (0 to 100) for translation memory matches. */
     translationMemoryThreshold?: number;
 
-    /** Filename including extension, only required when translating documents as streams. */
+    /**
+     * File name including extension, sent with the upload; the API uses its extension to
+     * detect the document type. Required unless the input is a file path, where it defaults
+     * to the path's base name.
+     */
     filename?: string;
 
     /**

tests/offline/translateDocument.test.ts

@@ -204,6 +204,18 @@ describe('Translator.translateDocumentUpload', () => {
         expect(upload.body()).toContain('name="target_lang"\r\n\r\nde\r\n');
         expect(upload.body()).toContain('filename="a.txt"');
     });
+
+    it('sends options.filename instead of the base name of a file path', async () => {
+        const upload = expectUpload();
+        const [exampleDocument] = createTextDocument();
+
+        await makeDeeplClient().translateDocumentUpload(exampleDocument, null, 'de', {
+            filename: 'report.docx',
+        });
+
+        expect(upload.body()).toContain('name="file"; filename="report.docx"');
+        expect(upload.body()).not.toContain('example_document.txt');
+    });
 });
 
 describe('Translator.translateDocumentGetStatus', () => {