feat: add support for glossary creation using CSV format

Author: daniel-jones-dev

CHANGELOG.md

@@ -5,6 +5,12 @@ 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
+* Add `createGlossaryWithCsv()` allowing glossaries downloaded from website to
+  be easily uploaded to API.
+
+
 ## [1.3.2] - 2022-08-09
 ### Changed
 * Update contributing guidelines, we can now accept Pull Requests.
@@ -93,6 +99,7 @@ client library took over this package name. Thanks to
 ownership.
 
 
+[Unreleased]: https://github.com/DeepLcom/deepl-node/compare/v1.3.2..HEAD
 [1.3.2]: https://github.com/DeepLcom/deepl-node/compare/v1.3.1...v1.3.2
 [1.3.1]: https://github.com/DeepLcom/deepl-node/compare/v1.2.2...v1.3.1
 [1.3.0]: https://github.com/DeepLcom/deepl-node/releases/tag/v1.3.0

README.md

@@ -249,6 +249,23 @@ const entries = new deepl.GlossaryEntries({ entries: { artist: 'Maler', prize: '
 const glossaryEnToDe = await translator.createGlossary('My glossary', 'en', 'de', entries);
 ```
 
+You can also upload a glossary downloaded from the DeepL website using
+`createGlossaryFromCsv()`. Instead of supplying the entries as a dictionary,
+provide the CSV file as a string containing the file path, or a Stream, Buffer,
+or FileHandle containing the CSV file content:
+
+```javascript
+const csvFilePath = '/path/to/glossary_file.csv';
+const glossaryEnToDe = await translator.createGlossaryFromCsv(
+    'My glossary',
+    'en',
+    'de',
+    csvFilePath);
+```
+
+The [API documentation][api-docs-csv-format] explains the expected CSV format in
+detail.
+
 Functions to get, list, and delete stored glossaries are also provided.
 
 ```javascript
@@ -422,6 +439,7 @@ tests using `npm test` with the `DEEPL_MOCK_SERVER_PORT` and `DEEPL_SERVER_URL`
 environment variables defined referring to the mock-server.
 
 [api-docs]: https://www.deepl.com/docs-api?utm_source=github&utm_medium=github-nodejs-readme
+[api-docs-csv-format]: https://www.deepl.com/docs-api/managing-glossaries/supported-glossary-formats/?utm_source=github&utm_medium=github-nodejs-readme
 [create-account]: https://www.deepl.com/pro?utm_source=github&utm_medium=github-nodejs-readme#developer
 [deepl-mock]: https://www.github.com/DeepLcom/deepl-mock
 [issues]: https://www.github.com/DeepLcom/deepl-node/issues

src/index.ts

@@ -778,7 +778,7 @@ export class Translator {
     }
 
     /**
-     * Creates a new glossary on DeepL server with given name, languages, and entries.
+     * Creates a new glossary on the DeepL server with given name, languages, and entries.
      * @param name User-defined name to assign to the glossary.
      * @param sourceLang Language code of the glossary source terms.
      * @param targetLang Language code of the glossary target terms.
@@ -791,33 +791,43 @@ export class Translator {
         targetLang: LanguageCode,
         entries: GlossaryEntries,
     ): Promise<GlossaryInfo> {
-        // Glossaries are only supported for base language types
-        sourceLang = nonRegionalLanguageCode(sourceLang);
-        targetLang = nonRegionalLanguageCode(targetLang);
-
-        if (!isString(name) || name.length === 0) {
-            throw new DeepLError('glossary name must be a non-empty string');
-        } else if (Object.keys(entries.entries()).length === 0) {
+        if (Object.keys(entries.entries()).length === 0) {
             throw new DeepLError('glossary entries must not be empty');
         }
 
         const tsv = entries.toTsv();
+        return this.internalCreateGlossary(name, sourceLang, targetLang, 'tsv', tsv);
+    }
 
-        const data = new URLSearchParams({
-            name: name,
-            source_lang: sourceLang,
-            target_lang: targetLang,
-            entries_format: 'tsv',
-            entries: tsv,
-        });
+    /**
+     * Creates a new glossary on DeepL server with given name, languages, and CSV data.
+     * @param name User-defined name to assign to the glossary.
+     * @param sourceLang Language code of the glossary source terms.
+     * @param targetLang Language code of the glossary target terms.
+     * @param csvFile String containing the path of the CSV file to be translated, or a Stream,
+     *     Buffer, or a FileHandle containing CSV file content.
+     * @return Fulfills with a GlossaryInfo containing details about the created glossary.
+     */
+    async createGlossaryWithCsv(
+        name: string,
+        sourceLang: LanguageCode,
+        targetLang: LanguageCode,
+        csvFile: string | Buffer | fs.ReadStream | fs.promises.FileHandle,
+    ): Promise<GlossaryInfo> {
+        let csvContent;
+        if (isString(csvFile)) {
+            csvContent = (await fs.promises.readFile(csvFile)).toString();
+        } else if (csvFile instanceof fs.ReadStream) {
+            csvContent = (await streamToBuffer(csvFile)).toString();
+        } else if (csvFile instanceof Buffer) {
+            csvContent = csvFile.toString();
+        } else {
+            // FileHandle
+            csvContent = (await csvFile.readFile()).toString();
+            await csvFile.close();
+        }
 
-        const { statusCode, content } = await this.httpClient.sendRequestWithBackoff<string>(
-            'POST',
-            '/v2/glossaries',
-            { data },
-        );
-        await checkStatusCode(statusCode, content, true);
-        return parseGlossaryInfo(content);
+        return this.internalCreateGlossary(name, sourceLang, targetLang, 'csv', csvContent);
     }
 
     /**
@@ -932,6 +942,42 @@ export class Translator {
         });
     }
 
+    /**
+     * Create glossary with given details.
+     * @private
+     */
+    private async internalCreateGlossary(
+        name: string,
+        sourceLang: LanguageCode,
+        targetLang: LanguageCode,
+        entriesFormat: string,
+        entries: string,
+    ): Promise<GlossaryInfo> {
+        // Glossaries are only supported for base language types
+        sourceLang = nonRegionalLanguageCode(sourceLang);
+        targetLang = nonRegionalLanguageCode(targetLang);
+
+        if (!isString(name) || name.length === 0) {
+            throw new DeepLError('glossary name must be a non-empty string');
+        }
+
+        const data = new URLSearchParams({
+            name: name,
+            source_lang: sourceLang,
+            target_lang: targetLang,
+            entries_format: entriesFormat,
+            entries: entries,
+        });
+
+        const { statusCode, content } = await this.httpClient.sendRequestWithBackoff<string>(
+            'POST',
+            '/v2/glossaries',
+            { data },
+        );
+        await checkStatusCode(statusCode, content, true);
+        return parseGlossaryInfo(content);
+    }
+
     /**
      * HttpClient implements all HTTP requests and retries.
      * @private

tests/glossary.test.ts

@@ -80,6 +80,39 @@ describe('translate using glossaries', () => {
         }
     });
 
+    it('should create glossaries from CSV', async () => {
+        const translator = makeTranslator();
+        const glossaryName = getGlossaryName();
+        const sourceLang = 'en';
+        const targetLang = 'de';
+
+        const expectedEntries = new deepl.GlossaryEntries({
+            entries: {
+                sourceEntry1: 'targetEntry1',
+                'source"Entry': 'target,Entry',
+            },
+        });
+        const csvFile = Buffer.from(
+            'sourceEntry1,targetEntry1,en,de\n"source""Entry","target,Entry",en,de',
+        );
+        const glossary = await translator.createGlossaryWithCsv(
+            glossaryName,
+            sourceLang,
+            targetLang,
+            csvFile,
+        );
+        try {
+            const entries = await translator.getGlossaryEntries(glossary);
+            expect(entries.entries()).toStrictEqual(expectedEntries.entries());
+        } finally {
+            try {
+                await translator.deleteGlossary(glossary);
+            } catch (e) {
+                // Suppress errors
+            }
+        }
+    });
+
     it('should reject creating invalid glossaries', async () => {
         const translator = makeTranslator();
         const glossaryName = getGlossaryName();