feat: Add support for v3 glossary endpoints

Author: leoncheng57

CHANGELOG.md

@@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 <!-- * add to here... -->
 * Include `x-trace-id` response headers in debug logs
+* Added support for the /v3 Glossary APIs in the client library while providing backwards
+  compatibility for the previous /v2 Glossary endpoints. Please refer to the README for
+  usage instructions.
 ### Changed
 <!-- * add to here... -->
 

README.md

@@ -13,7 +13,7 @@ import { ProxyConfig } from './types';
 import * as https from 'https';
 import * as http from 'http';
 
-type HttpMethod = 'GET' | 'DELETE' | 'POST';
+type HttpMethod = 'GET' | 'DELETE' | 'POST' | 'PUT' | 'PATCH';
 
 const axiosInstance = axios.create({
     httpAgent: new http.Agent({ keepAlive: true }),

src/client.ts

@@ -53,3 +53,5 @@ export class DocumentMinificationError extends DeepLError {}
  * @see DocumentMinifier.deminifyDocument
  */
 export class DocumentDeminificationError extends DeepLError {}
+
+export class ArgumentError extends DeepLError {}

src/deeplClient.ts

@@ -2,6 +2,7 @@
 // Use of this source code is governed by an MIT
 // license that can be found in the LICENSE file.
 
+import { GlossaryEntries } from './glossaryEntries';
 import { DeepLError } from './errors';
 import {
     DocumentHandle,
@@ -17,6 +18,12 @@ import {
     GlossaryInfo,
     SourceLanguageCode,
     WriteResult,
+    MultilingualGlossaryInfo,
+    MultilingualGlossaryDictionaryInfo,
+    MultilingualGlossaryDictionaryEntries,
+    MultilingualGlossaryDictionaryApiResponse,
+    MultilingualGlossaryDictionaryEntriesApiResponse,
+    ListMultilingualGlossaryApiResponse,
 } from './types';
 import { standardizeLanguageCode } from './utils';
 
@@ -34,6 +41,17 @@ interface GlossaryInfoApiResponse {
     entry_count: number;
 }
 
+/**
+ * Type used during JSON parsing of API response for multilingual glossary info.
+ * @private
+ */
+interface MultilingualGlossaryInfoApiResponse {
+    glossary_id: string;
+    name: string;
+    dictionaries: MultilingualGlossaryDictionaryApiResponse[];
+    creation_time: string;
+}
+
 /**
  * Type used during JSON parsing of API response for lists of glossary infos.
  * @private
@@ -119,6 +137,17 @@ interface GlossaryLanguagePairArrayApiResponse {
     supported_languages: GlossaryInfoApiResponse[];
 }
 
+/**
+ * Type used during JSON parsing of API response for multilingual glossary info.
+ * @private
+ */
+interface MultilingualGlossaryInfoApiResponse {
+    glossary_id: string;
+    name: string;
+    dictionaries: MultilingualGlossaryDictionaryApiResponse[];
+    creation_time: string;
+}
+
 /**
  * Type used during JSON parsing of API response for document translation statuses.
  * @private
@@ -242,6 +271,66 @@ function parseRawGlossaryInfo(obj: GlossaryInfoApiResponse): GlossaryInfo {
     };
 }
 
+/**
+ * Parses the given multilingual glossary info API response to a GlossaryInfo object.
+ * @private
+ */
+export function parseMultilingualGlossaryDictionaryInfo(
+    obj: MultilingualGlossaryDictionaryApiResponse,
+): MultilingualGlossaryDictionaryInfo {
+    return {
+        sourceLangCode: obj.source_lang as SourceGlossaryLanguageCode,
+        targetLangCode: obj.target_lang as TargetGlossaryLanguageCode,
+        entryCount: obj.entry_count,
+    };
+}
+
+/**
+ * Parses the given multilingual glossary info API response to a GlossaryInfo object.
+ * @private
+ */
+function parseRawMultilingualGlossaryInfo(
+    obj: MultilingualGlossaryInfoApiResponse,
+): MultilingualGlossaryInfo {
+    return {
+        glossaryId: obj.glossary_id,
+        name: obj.name,
+        creationTime: new Date(obj.creation_time),
+        dictionaries: obj.dictionaries.map((dict) => parseMultilingualGlossaryDictionaryInfo(dict)),
+    };
+}
+
+/**
+ * Parses the given multilingual glossary entries API response to a GlossaryDictionaryEntries object.
+ * @private
+ */
+export function parseMultilingualGlossaryDictionaryEntries(
+    obj: MultilingualGlossaryDictionaryEntriesApiResponse,
+): MultilingualGlossaryDictionaryEntries[] {
+    return obj.dictionaries.map((dict) => ({
+        sourceLangCode: dict.source_lang as SourceGlossaryLanguageCode,
+        targetLangCode: dict.target_lang as TargetGlossaryLanguageCode,
+        entries: new GlossaryEntries({ tsv: dict.entries }),
+    }));
+}
+
+/**
+ * Parses the given list multilingual glossaries API response.
+ * @private
+ */
+export function parseListMultilingualGlossaries(
+    obj: ListMultilingualGlossaryApiResponse,
+): MultilingualGlossaryInfo[] {
+    return obj.glossaries.map((glossary) => ({
+        glossaryId: glossary.glossary_id,
+        name: glossary.name,
+        dictionaries: glossary.dictionaries.map((dict) =>
+            parseMultilingualGlossaryDictionaryInfo(dict),
+        ),
+        creationTime: new Date(glossary.creation_time),
+    }));
+}
+
 /**
  * Parses the given JSON string to a GlossaryInfo object.
  * @private
@@ -255,6 +344,19 @@ export function parseGlossaryInfo(json: string): GlossaryInfo {
     }
 }
 
+/**
+ * Parses the given JSON string to a MultilingualGlossaryInfo object.
+ * @private
+ */
+export function parseMultilingualGlossaryInfo(json: string): MultilingualGlossaryInfo {
+    try {
+        const obj = JSON.parse(json) as MultilingualGlossaryInfoApiResponse;
+        return parseRawMultilingualGlossaryInfo(obj);
+    } catch (error) {
+        throw new DeepLError(`Error parsing response JSON: ${error}`);
+    }
+}
+
 /**
  * Parses the given JSON string to an array of GlossaryInfo objects.
  * @private

src/errors.ts

@@ -2,6 +2,8 @@
 // Use of this source code is governed by an MIT
 // license that can be found in the LICENSE file.
 
+import { GlossaryEntries } from './glossaryEntries';
+
 /**
  * Optional proxy configuration, may be specified as proxy in TranslatorOptions.
  * @see TranslatorOptions.proxy
@@ -87,7 +89,9 @@ export type GlossaryId = string;
 export type TagList = string | string[];
 
 /**
- * Information about a glossary, excluding the entry list.
+ * 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
+ * target language defined).
  */
 export interface GlossaryInfo {
     /** Unique ID assigned to the glossary. */
@@ -128,8 +132,10 @@ export interface TranslateTextOptions {
     /** Controls whether translations should lean toward formal or informal language. */
     formality?: Formality;
 
-    /** Specifies the ID of a glossary to use with translation. */
-    glossary?: GlossaryId | GlossaryInfo;
+    /** Specifies the ID of a glossary to use with translation. Or
+     * using the given v2 glossary or given multilingual glossary.
+     */
+    glossary?: GlossaryId | GlossaryInfo | MultilingualGlossaryInfo;
 
     /** Type of tags to parse before translation, options are 'html' and 'xml'. */
     tagHandling?: TagHandlingMode;
@@ -169,8 +175,10 @@ export interface DocumentTranslateOptions {
     /** Controls whether translations should lean toward formal or informal language. */
     formality?: Formality;
 
-    /** Specifies the ID of a glossary to use with translation. */
-    glossary?: GlossaryId | GlossaryInfo;
+    /** Specifies the ID of a glossary to use with translation. Or
+     * using the given v2 glossary or given multilingual glossary.
+     */
+    glossary?: GlossaryId | GlossaryInfo | MultilingualGlossaryInfo;
 
     /** Filename including extension, only required when translating documents as streams. */
     filename?: string;
@@ -341,6 +349,47 @@ export interface Language {
     readonly supportsFormality?: boolean;
 }
 
+/**
+ * Information about a glossary dictionary, excluding the entry list. Is compatible with
+ * the /v3 glossary endpoints and supports multi-lingual glossaries compared to the v2 version.
+ * Glossaries now have multiple glossary dictionaries each with their own source language, target
+ * language and entries.
+ */
+export interface MultilingualGlossaryDictionaryInfo {
+    /** Language code of the glossary dictionary source terms. */
+    readonly sourceLangCode: string;
+    /** Language code of the glossary dictionary target terms. */
+    readonly targetLangCode: string;
+    /** The number of entries contained in the glossary dictionary. */
+    readonly entryCount: number;
+}
+
+/**
+ * Information about a multilingual glossary, excluding the entry list.
+ */
+export interface MultilingualGlossaryInfo {
+    /** ID of the associated glossary. */
+    readonly glossaryId: string;
+    /** Name of the glossary chosen during creation. */
+    readonly name: string;
+    /** The dictionaries of the glossary. */
+    readonly dictionaries: MultilingualGlossaryDictionaryInfo[];
+    /** Time when the glossary was created. */
+    readonly creationTime: Date;
+}
+
+/**
+ * Information about a glossary dictionary, including the entry list
+ */
+export interface MultilingualGlossaryDictionaryEntries {
+    /** Language code of the glossary dictionary source terms. */
+    readonly sourceLangCode: string;
+    /** Language code of the glossary dictionary target terms. */
+    readonly targetLangCode: string;
+    /** The entries in the glossary dictionary. */
+    readonly entries: GlossaryEntries;
+}
+
 /**
  * Information about a pair of languages supported for DeepL glossaries.
  */
@@ -455,3 +504,42 @@ export interface WriteResult {
      */
     readonly targetLang: string;
 }
+
+/**
+ * Type used during JSON parsing of API response for getting multilingual glossary dictionary entries.
+ * @private
+ */
+export interface MultilingualGlossaryDictionaryEntriesApiResponse {
+    dictionaries: [
+        {
+            source_lang: string;
+            target_lang: string;
+            entries: string;
+        },
+    ];
+}
+
+/**
+ * Type used during JSON parsing of API response for multilingual glossary dictionaries.
+ * @private
+ */
+export interface MultilingualGlossaryDictionaryApiResponse {
+    source_lang: string;
+    target_lang: string;
+    entry_count: number;
+}
+
+/**
+ * Type used during JSON parsing of API response for listing multilingual glossaries.
+ * @private
+ */
+export interface ListMultilingualGlossaryApiResponse {
+    glossaries: [
+        {
+            glossary_id: string;
+            name: string;
+            dictionaries: MultilingualGlossaryDictionaryApiResponse[];
+            creation_time: string;
+        },
+    ];
+}

src/parsing.ts

@@ -14,6 +14,8 @@ import {
     SentenceSplittingMode,
     TagList,
     TranslateTextOptions,
+    MultilingualGlossaryInfo,
+    MultilingualGlossaryDictionaryEntries,
 } from './types';
 
 const logger = loglevel.getLogger('deepl');
@@ -138,7 +140,7 @@ export function buildURLSearchParams(
     sourceLang: LanguageCode | null,
     targetLang: LanguageCode,
     formality: Formality | undefined,
-    glossary: GlossaryId | GlossaryInfo | undefined,
+    glossary: GlossaryId | GlossaryInfo | MultilingualGlossaryInfo | undefined,
     extraRequestParameters: RequestParameters | undefined,
 ): URLSearchParams {
     targetLang = standardizeLanguageCode(targetLang);
@@ -150,15 +152,6 @@ export function buildURLSearchParams(
         throw new DeepLError('sourceLang is required if using a glossary');
     }
 
-    if (glossary !== undefined && !isString(glossary)) {
-        if (
-            nonRegionalLanguageCode(targetLang) !== glossary.targetLang ||
-            sourceLang !== glossary.sourceLang
-        ) {
-            throw new DeepLError('sourceLang and targetLang must match glossary');
-        }
-    }
-
     if (targetLang === 'en') {
         throw new DeepLError(
             "targetLang='en' is deprecated, please use 'en-GB' or 'en-US' instead.",
@@ -281,3 +274,49 @@ export function validateAndAppendTextOptions(
         data.append('ignore_tags', joinTagList(options.ignoreTags));
     }
 }
+
+/**
+ * Appends glossary dictionaries to HTTP request parameters.
+ * @param data URL-encoded parameters for a HTTP request.
+ * @param dictionaries Glossary dictionaries to append.
+ * @private
+ */
+export function appendDictionaryEntries(
+    data: URLSearchParams,
+    dictionaries: MultilingualGlossaryDictionaryEntries[],
+): void {
+    dictionaries.forEach((dict, index) => {
+        data.append(`dictionaries[${index}].source_lang`, dict.sourceLangCode);
+        data.append(`dictionaries[${index}].target_lang`, dict.targetLangCode);
+        data.append(`dictionaries[${index}].entries`, dict.entries.toTsv());
+        data.append(`dictionaries[${index}].entries_format`, 'tsv');
+    });
+}
+/**
+ * Appends a glossary dictionary with CSV entries to HTTP request parameters.
+ * @param data URL-encoded parameters for a HTTP request.
+ * @param sourceLanguageCode Source language code of the dictionary.
+ * @param targetLanguageCode Target language code of the dictionary.
+ * @param csvContent CSV-formatted string containing the dictionary entries.
+ * @private
+ */
+export function appendCsvDictionaryEntries(
+    data: URLSearchParams,
+    sourceLanguageCode: string,
+    targetLanguageCode: string,
+    csvContent: string,
+): void {
+    data.append('dictionaries[0].source_lang', sourceLanguageCode);
+    data.append('dictionaries[0].target_lang', targetLanguageCode);
+    data.append('dictionaries[0].entries', csvContent);
+    data.append('dictionaries[0].entries_format', 'csv');
+}
+
+/**
+ * Extract the glossary ID from the argument.
+ * @param glossary The glossary as a string, GlossaryInfo, or MultilingualGlossaryInfo.
+ * @private
+ */
+export function extractGlossaryId(glossary: GlossaryId | GlossaryInfo | MultilingualGlossaryInfo) {
+    return typeof glossary === 'string' ? glossary : glossary.glossaryId;
+}