feat: Add Document Minification feature

Author: leoncheng57

CHANGELOG.md

@@ -4,11 +4,12 @@ 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]
+## [1.17.0] - 2025-02-25
 ### Added
+* Added document minification as a feature before document translation, to 
+  allow translation of large docx or pptx files. For more info check the README.
 * Added .env.example file with `dotenv` library for environment variables management
 * Improve unit tests
-
 ### Changed
 * Upgrade cross-spawn library (see https://github.com/advisories/GHSA-3xgq-45jj-v275)
 
@@ -283,7 +284,7 @@ client library took over this package name. Thanks to
 ownership.
 
 
-[Unreleased]: https://github.com/DeepLcom/deepl-node/compare/v1.16.0...HEAD
+[1.17.0]: https://github.com/DeepLcom/deepl-node/compare/v1.16.0...v1.17.0
 [1.16.0]: https://github.com/DeepLcom/deepl-node/compare/v1.15.0...v1.16.0
 [1.15.0]: https://github.com/DeepLcom/deepl-node/compare/v1.14.0...v1.15.0
 [1.14.0]: https://github.com/DeepLcom/deepl-node/compare/v1.13.1...v1.14.0

README.md

@@ -15,7 +15,7 @@ DeepL's best-in-class translation technology.
 The DeepL Node.js library offers a convenient way for applications written for
 Node.js to interact with the DeepL API. We intend to support all API functions
 with the library, though support for new features may be added to the library
-after they’re added to the API.
+after they're added to the API.
 
 ## Getting an authentication key
 
@@ -264,6 +264,64 @@ directly:
 -   `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).
+-   `enableDocumentMinification`: A `bool` value. If set to `true`, the library will try to minify a document 
+before translating it through the API, sending a smaller document if the file contains a lot of media. This is 
+currently only supported for `pptx` and `docx` files. See also [Document minification](#document-minification). 
+
+#### Document minification
+In some contexts, one can end up with large document files (e.g. PowerPoint presentations
+or Word files with many contributors, especially in a larger organization). However, the
+DeepL API enforces a limit of 30 MB for most of these files (see Usage Limits in the docs).
+In the case that most of this size comes from media included in the documents (e.g. images,
+videos, animations), document minification can help.
+In this case, the library will create a temporary directory to extract the document into,
+replace the large media with tiny placeholders, create a minified document, translate that
+via the API, and re-insert the original media into the original file. Please note that this
+requires a bit of additional (temporary) disk space, we recommend at least 2x the file size
+of the document to be translated.
+
+To use document minification, simply pass the option to the `translateDocument()` function:
+```typescript
+await translator.translateDocument(
+    inFile, outFile, "en", "de", { enableDocumentMinification: true }
+);
+```
+In order to use document minification with the lower-level `uploadDocument()`,
+`isDocumentTranslationComplete()` and `downloadDocument()` methods as well as other details,
+see the `DocumentMinifier` class.
+
+
+Currently supported document types for minification:
+1. `pptx`
+2. `docx`
+
+Currently supported media types for minification:
+1. `png`
+2. `jpg`
+3. `jpeg`
+4. `emf`
+5. `bmp`
+6. `tiff`
+7. `wdp`
+8. `svg`
+9. `gif`
+10. `mp4`
+11. `asf`
+12. `avi`
+13. `m4v`
+14. `mpg`
+15. `mpeg`
+16. `wmv`
+17. `mov`
+18. `aiff`
+19. `au`
+20. `mid`
+21. `midi`
+22. `mp3`
+23. `m4a`
+24. `wav`
+25. `wma`
+
 
 ### Glossaries
 

package-lock.json

@@ -20,13 +20,17 @@
     ],
     "dependencies": {
         "@types/node": ">=12.0",
+        "adm-zip": "^0.5.16",
         "axios": "^1.7.4",
         "dotenv": "^16.4.7",
         "form-data": "^3.0.0",
-        "loglevel": ">=1.6.2"
+        "loglevel": ">=1.6.2",
+        "uuid": "^8.3.2"
     },
     "devDependencies": {
+        "@types/adm-zip": "^0.5.7",
         "@types/jest": "^27.0.3",
+        "@types/mock-fs": "^4.13.4",
         "@types/uuid": "^8.3.4",
         "@typescript-eslint/eslint-plugin": "^5.6.0",
         "@typescript-eslint/parser": "^5.6.0",
@@ -38,11 +42,11 @@
         "eslint-plugin-promise": "^6.0.0",
         "jest": "^27.4.3",
         "jest-junit": "^13.0.0",
+        "mock-fs": "^5.5.0",
         "nock": "^13.3.0",
         "prettier": "^2.5.1",
         "ts-jest": "^27.1.1",
-        "typescript": "^4.5.3",
-        "uuid": "^8.3.2"
+        "typescript": "^4.5.3"
     },
     "files": [
         "CHANGELOG.md",
@@ -62,6 +66,6 @@
         "format": "prettier --check .",
         "format:fix": "prettier --write .",
         "test": "jest",
-        "test:coverage": "jest --coverage --reporters=\"default\" --reporters=\"jest-junit\""
+        "test:coverage": "jest --coverage --reporters=\"default\" --reporters=\"jest-junit\" --maxWorkers=5"
     }
 }