377 lines
20 KiB
JavaScript
377 lines
20 KiB
JavaScript
"use strict";
|
|
// Copyright 2025 DeepL SE (https://www.deepl.com)
|
|
// Use of this source code is governed by an MIT
|
|
// license that can be found in the LICENSE file.
|
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
exports.DeepLClient = exports.WritingTone = exports.WritingStyle = void 0;
|
|
const translator_1 = require("./translator");
|
|
const parsing_1 = require("./parsing");
|
|
const utils_1 = require("./utils");
|
|
const errors_1 = require("./errors");
|
|
var WritingStyle;
|
|
(function (WritingStyle) {
|
|
WritingStyle["ACADEMIC"] = "academic";
|
|
WritingStyle["BUSINESS"] = "business";
|
|
WritingStyle["CASUAL"] = "casual";
|
|
WritingStyle["DEFAULT"] = "default";
|
|
WritingStyle["PREFER_ACADEMIC"] = "prefer_academic";
|
|
WritingStyle["PREFER_BUSINESS"] = "prefer_business";
|
|
WritingStyle["PREFER_CASUAL"] = "prefer_casual";
|
|
WritingStyle["PREFER_SIMPLE"] = "prefer_simple";
|
|
WritingStyle["SIMPLE"] = "simple";
|
|
})(WritingStyle = exports.WritingStyle || (exports.WritingStyle = {}));
|
|
var WritingTone;
|
|
(function (WritingTone) {
|
|
WritingTone["CONFIDENT"] = "confident";
|
|
WritingTone["DEFAULT"] = "default";
|
|
WritingTone["DIPLOMATIC"] = "diplomatic";
|
|
WritingTone["ENTHUSIASTIC"] = "enthusiastic";
|
|
WritingTone["FRIENDLY"] = "friendly";
|
|
WritingTone["PREFER_CONFIDENT"] = "prefer_confident";
|
|
WritingTone["PREFER_DIPLOMATIC"] = "prefer_diplomatic";
|
|
WritingTone["PREFER_ENTHUSIASTIC"] = "prefer_enthusiastic";
|
|
WritingTone["PREFER_FRIENDLY"] = "prefer_friendly";
|
|
})(WritingTone = exports.WritingTone || (exports.WritingTone = {}));
|
|
class DeepLClient extends translator_1.Translator {
|
|
constructor(authKey, options = {}) {
|
|
super(authKey, options);
|
|
}
|
|
async rephraseText(texts, targetLang, writingStyle, tone) {
|
|
const data = new URLSearchParams();
|
|
if (targetLang) {
|
|
data.append('target_lang', targetLang);
|
|
}
|
|
if (writingStyle) {
|
|
data.append('writing_style', writingStyle);
|
|
}
|
|
if (tone) {
|
|
data.append('tone', tone);
|
|
}
|
|
const singular = (0, utils_1.appendTextsAndReturnIsSingular)(data, texts);
|
|
const { statusCode, content } = await this.httpClient.sendRequestWithBackoff('POST', '/v2/write/rephrase', { data });
|
|
await (0, translator_1.checkStatusCode)(statusCode, content);
|
|
const writeResults = (0, parsing_1.parseWriteResultArray)(content);
|
|
return (singular ? writeResults[0] : writeResults);
|
|
}
|
|
/**
|
|
* Creates a glossary with given name with all of the specified
|
|
* dictionaries, each with their own language pair and entries. The
|
|
* glossary may be used in the translateText functions.
|
|
*
|
|
* Only certain language pairs are supported. The available language pairs
|
|
* can be queried using getGlossaryLanguages(). Glossaries are not
|
|
* regional specific: a glossary with target language EN may be used to
|
|
* translate texts into both EN-US and EN-GB.
|
|
*
|
|
* This function requires the glossary entries for each dictionary to be
|
|
* provided as a dictionary of source-target terms. To create a glossary
|
|
* from a CSV file downloaded from the DeepL website, see
|
|
* {@link createMultilingualGlossaryWithCsv}.
|
|
*
|
|
* @param name user-defined name to attach to glossary.
|
|
* @param glossaryDicts the dictionaries of the glossary, see {@link MultilingualGlossaryDictionaryEntries}.
|
|
* @return {Promise<MultilingualGlossaryInfo>} object with details about the newly created glossary.
|
|
*
|
|
* @throws {ArgumentError} If any argument is invalid.
|
|
* @throws {DeepLError} If any error occurs while communicating with the DeepL API
|
|
*/
|
|
async createMultilingualGlossary(name, glossaryDicts) {
|
|
if (!name) {
|
|
throw new errors_1.ArgumentError('glossary name must not be empty');
|
|
}
|
|
const data = new URLSearchParams();
|
|
data.append('name', name);
|
|
(0, utils_1.appendDictionaryEntries)(data, glossaryDicts);
|
|
const { statusCode, content } = await this.httpClient.sendRequestWithBackoff('POST', '/v3/glossaries', { data: data });
|
|
await (0, translator_1.checkStatusCode)(statusCode, content);
|
|
return (0, parsing_1.parseMultilingualGlossaryInfo)(content);
|
|
}
|
|
/**
|
|
* Creates a multilingual glossary with the given name using entries from a CSV file.
|
|
* The CSV file must contain two columns: source terms and target terms.
|
|
* The glossary may be used in the translateText() functions.
|
|
*
|
|
* Only certain language pairs are supported. The available language pairs
|
|
* can be queried using getGlossaryLanguages(). Glossaries are not
|
|
* regional specific: a glossary with target language EN may be used to
|
|
* translate texts into both EN-US and EN-GB.
|
|
*
|
|
* @param name User-defined name to attach to the glossary.
|
|
* @param sourceLanguageCode Source language code for the glossary.
|
|
* @param targetLanguageCode Target language code for the glossary.
|
|
* @param csvContent String in CSV format containing the entries.
|
|
* @returns {Promise<MultilingualGlossaryInfo>} Object with details about the newly created glossary.
|
|
*
|
|
* @throws {ArgumentError} If any argument is invalid.
|
|
* @throws {DeepLError} If any error occurs while communicating with the DeepL API.
|
|
*/
|
|
async createMultilingualGlossaryWithCsv(name, sourceLanguageCode, targetLanguageCode, csvContent) {
|
|
if (!name) {
|
|
throw new errors_1.ArgumentError('Parameter "name" must not be empty');
|
|
}
|
|
if (!sourceLanguageCode) {
|
|
throw new errors_1.ArgumentError('Parameter "sourceLanguageCode" must not be empty');
|
|
}
|
|
if (!targetLanguageCode) {
|
|
throw new errors_1.ArgumentError('Parameter "targetLanguageCode" must not be empty');
|
|
}
|
|
if (!csvContent) {
|
|
throw new errors_1.ArgumentError('Parameter "csvContent" must not be empty');
|
|
}
|
|
const data = new URLSearchParams();
|
|
data.append('name', name);
|
|
(0, utils_1.appendCsvDictionaryEntries)(data, sourceLanguageCode, targetLanguageCode, csvContent);
|
|
const { statusCode, content } = await this.httpClient.sendRequestWithBackoff('POST', '/v3/glossaries', { data: data });
|
|
await (0, translator_1.checkStatusCode)(statusCode, content);
|
|
return (0, parsing_1.parseMultilingualGlossaryInfo)(content);
|
|
}
|
|
/**
|
|
* Retrieves information about the glossary with the specified ID.
|
|
* This does not retrieve the glossary entries.
|
|
* @param glossaryId ID of glossary to retrieve.
|
|
* @returns {Promise<MultilingualGlossaryInfo>} object with details about the specified glossary.
|
|
* @throws {DeepLError} If any error occurs while communicating with the DeepL API.
|
|
*/
|
|
async getMultilingualGlossary(glossaryId) {
|
|
if (!glossaryId) {
|
|
throw new errors_1.ArgumentError('glossaryId must not be empty');
|
|
}
|
|
const { statusCode, content } = await this.httpClient.sendRequestWithBackoff('GET', `/v3/glossaries/${glossaryId}`);
|
|
await (0, translator_1.checkStatusCode)(statusCode, content, true /* usingGlossary */);
|
|
return (0, parsing_1.parseMultilingualGlossaryInfo)(content);
|
|
}
|
|
/**
|
|
* Retrieves the dictionary entries for a specific glossary and language pair.
|
|
*
|
|
* If the source and target language codes are specified, there should be at most one dictionary returned.
|
|
*
|
|
* @param glossary The ID of the glossary or MultilingualGlossaryInfo object to query.
|
|
* @param sourceLanguageCode Source language code of the dictionary.
|
|
* @param targetLanguageCode Target language code of the dictionary.
|
|
* @returns {Promise<MultilingualGlossaryDictionaryEntries>} Object containing the dictionary entries.
|
|
*
|
|
* @throws {ArgumentError} If any argument is invalid.
|
|
* @throws {DeepLError} If any error occurs while communicating with the DeepL API.
|
|
* @throws {GlossaryNotFoundError} If no dictionary is found for the given source and target language codes.
|
|
*/
|
|
async getMultilingualGlossaryDictionaryEntries(glossary, sourceLanguageCode, targetLanguageCode) {
|
|
if (!glossary) {
|
|
throw new errors_1.ArgumentError('Parameter "glossary" must not be empty/null');
|
|
}
|
|
if (!sourceLanguageCode) {
|
|
throw new errors_1.ArgumentError('Parameter "sourceLanguageCode" must not be empty');
|
|
}
|
|
if (!targetLanguageCode) {
|
|
throw new errors_1.ArgumentError('Parameter "targetLanguageCode" must not be empty');
|
|
}
|
|
const glossaryId = (0, utils_1.extractGlossaryId)(glossary);
|
|
const queryParams = new URLSearchParams();
|
|
queryParams.append('source_lang', sourceLanguageCode);
|
|
queryParams.append('target_lang', targetLanguageCode);
|
|
const { statusCode, content } = await this.httpClient.sendRequestWithBackoff('GET', `/v3/glossaries/${glossaryId}/entries`, { data: queryParams });
|
|
await (0, translator_1.checkStatusCode)(statusCode, content, true /* usingGlossary */);
|
|
const response = JSON.parse(content);
|
|
const dictionaryEntriesList = (0, parsing_1.parseMultilingualGlossaryDictionaryEntries)(response);
|
|
if (!dictionaryEntriesList || dictionaryEntriesList.length === 0) {
|
|
throw new errors_1.GlossaryNotFoundError('Glossary dictionary not found');
|
|
}
|
|
return dictionaryEntriesList[0];
|
|
}
|
|
/**
|
|
* Retrieves a list of all multilingual glossaries available for the authenticated user.
|
|
*
|
|
* @returns {Promise<MultilingualGlossaryInfo[]>} An array of objects containing details about each glossary.
|
|
*
|
|
* @throws {DeepLError} If any error occurs while communicating with the DeepL API.
|
|
*/
|
|
async listMultilingualGlossaries() {
|
|
const { statusCode, content } = await this.httpClient.sendRequestWithBackoff('GET', '/v3/glossaries');
|
|
await (0, translator_1.checkStatusCode)(statusCode, content);
|
|
const response = JSON.parse(content);
|
|
return (0, parsing_1.parseListMultilingualGlossaries)(response);
|
|
}
|
|
/**
|
|
* Deletes the glossary with the specified ID or MultilingualGlossaryInfo object.
|
|
* @param glossary The ID of the glossary or MultilingualGlossaryInfo object to delete.
|
|
* @throws {Error} If the glossaryId is empty.
|
|
* @throws {DeepLError} If the glossary could not be deleted.
|
|
*/
|
|
async deleteMultilingualGlossary(glossary) {
|
|
const glossaryId = (0, utils_1.extractGlossaryId)(glossary);
|
|
if (!glossaryId) {
|
|
throw new Error('glossaryId must not be empty');
|
|
}
|
|
const { statusCode, content } = await this.httpClient.sendRequestWithBackoff('DELETE', `/v3/glossaries/${glossaryId}`);
|
|
await (0, translator_1.checkStatusCode)(statusCode, content, true /* usingGlossary */);
|
|
}
|
|
/**
|
|
* Deletes a specific dictionary from a multilingual glossary based on the source and target language codes.
|
|
*
|
|
* @param glossary ID of the glossary or MultilingualGlossaryInfo object from which the dictionary will be deleted.
|
|
* @param sourceLanguageCode Source language code of the dictionary to delete.
|
|
* @param targetLanguageCode Target language code of the dictionary to delete.
|
|
* @throws {ArgumentError} If any argument is invalid.
|
|
* @throws {DeepLError} If any error occurs while communicating with the DeepL API.
|
|
*/
|
|
async deleteMultilingualGlossaryDictionary(glossary, sourceLanguageCode, targetLanguageCode) {
|
|
if (!glossary) {
|
|
throw new errors_1.ArgumentError('Parameter "glossary" must not be empty/null');
|
|
}
|
|
if (!sourceLanguageCode) {
|
|
throw new errors_1.ArgumentError('Parameter "sourceLanguageCode" must not be empty');
|
|
}
|
|
if (!targetLanguageCode) {
|
|
throw new errors_1.ArgumentError('Parameter "targetLanguageCode" must not be empty');
|
|
}
|
|
const glossaryId = (0, utils_1.extractGlossaryId)(glossary);
|
|
const { statusCode, content } = await this.httpClient.sendRequestWithBackoff('DELETE', `/v3/glossaries/${glossaryId}/dictionaries?source_lang=${sourceLanguageCode}&target_lang=${targetLanguageCode}`);
|
|
await (0, translator_1.checkStatusCode)(statusCode, content, true /* usingGlossary */);
|
|
}
|
|
/**
|
|
* Replaces the dictionary entries for a specific source and target language pair in a multilingual glossary.
|
|
*
|
|
* @param glossary ID of the glossary or MultilingualGlossaryInfo object from which the dictionary will be deleted.
|
|
* @param sourceLanguageCode Source language code of the dictionary to replace.
|
|
* @param targetLanguageCode Target language code of the dictionary to replace.
|
|
* @param entries Dictionary entries to replace, formatted as a string in TSV format.
|
|
* @returns {Promise<MultilingualGlossaryDictionaryInfo>} Object containing details about the updated dictionary.
|
|
*
|
|
* @throws {ArgumentError} If any argument is invalid.
|
|
* @throws {DeepLError} If any error occurs while communicating with the DeepL API.
|
|
*/
|
|
async replaceMultilingualGlossaryDictionary(glossary, glossaryDict) {
|
|
if (!glossary) {
|
|
throw new errors_1.ArgumentError('Parameter "glossary" must not be empty/null');
|
|
}
|
|
if (!glossaryDict) {
|
|
throw new errors_1.ArgumentError('Parameter "glossaryDict" must not be null');
|
|
}
|
|
const glossaryId = (0, utils_1.extractGlossaryId)(glossary);
|
|
const data = new URLSearchParams();
|
|
data.append('source_lang', glossaryDict.sourceLangCode);
|
|
data.append('target_lang', glossaryDict.targetLangCode);
|
|
data.append('entries', glossaryDict.entries.toTsv());
|
|
data.append('entries_format', 'tsv');
|
|
const { statusCode, content } = await this.httpClient.sendRequestWithBackoff('PUT', `/v3/glossaries/${glossaryId}/dictionaries`, { data: data });
|
|
await (0, translator_1.checkStatusCode)(statusCode, content, true /* usingGlossary */);
|
|
const response = JSON.parse(content);
|
|
return (0, parsing_1.parseMultilingualGlossaryDictionaryInfo)(response);
|
|
}
|
|
/**
|
|
* Replaces the dictionary entries for a specific source and target language pair in a multilingual glossary
|
|
* using entries from a CSV file.
|
|
*
|
|
* @param glossary ID of the glossary or MultilingualGlossaryInfo object from which the dictionary will be deleted.
|
|
* @param sourceLanguageCode Source language code of the dictionary to replace.
|
|
* @param targetLanguageCode Target language code of the dictionary to replace.
|
|
* @param csvContent String in CSV format containing the new entries.
|
|
* @returns {Promise<MultilingualGlossaryDictionaryInfo>} Object containing details about the updated dictionary.
|
|
*
|
|
* @throws {ArgumentError} If any argument is invalid.
|
|
* @throws {DeepLError} If any error occurs while communicating with the DeepL API.
|
|
*/
|
|
async replaceMultilingualGlossaryDictionaryWithCsv(glossary, sourceLanguageCode, targetLanguageCode, csvContent) {
|
|
if (!glossary) {
|
|
throw new errors_1.ArgumentError('Parameter "glossary" must not be empty/null');
|
|
}
|
|
if (!sourceLanguageCode) {
|
|
throw new errors_1.ArgumentError('Parameter "sourceLanguageCode" must not be empty');
|
|
}
|
|
if (!targetLanguageCode) {
|
|
throw new errors_1.ArgumentError('Parameter "targetLanguageCode" must not be empty');
|
|
}
|
|
if (!csvContent) {
|
|
throw new errors_1.ArgumentError('Parameter "csvContent" must not be empty');
|
|
}
|
|
const glossaryId = (0, utils_1.extractGlossaryId)(glossary);
|
|
const data = new URLSearchParams();
|
|
data.append('source_lang', sourceLanguageCode);
|
|
data.append('target_lang', targetLanguageCode);
|
|
data.append('entries', csvContent);
|
|
data.append('entries_format', 'csv');
|
|
const { statusCode, content } = await this.httpClient.sendRequestWithBackoff('PUT', `/v3/glossaries/${glossaryId}/dictionaries`, { data: data });
|
|
await (0, translator_1.checkStatusCode)(statusCode, content, true /* usingGlossary */);
|
|
const response = JSON.parse(content);
|
|
return (0, parsing_1.parseMultilingualGlossaryDictionaryInfo)(response);
|
|
}
|
|
/**
|
|
* Updates the name of a multilingual glossary.
|
|
*
|
|
* @param glossary ID of the glossary or MultilingualGlossaryInfo object from which the dictionary will be deleted.
|
|
* @param name New name for the glossary.
|
|
* @returns {Promise<MultilingualGlossaryInfo>} Object containing details about the updated glossary.
|
|
*
|
|
* @throws {ArgumentError} If the name is invalid.
|
|
* @throws {DeepLError} If any error occurs while communicating with the DeepL API.
|
|
*/
|
|
async updateMultilingualGlossaryName(glossary, name) {
|
|
if (!name) {
|
|
throw new errors_1.ArgumentError('Parameter "name" must not be empty');
|
|
}
|
|
const glossaryId = (0, utils_1.extractGlossaryId)(glossary);
|
|
const data = new URLSearchParams();
|
|
data.append('name', name);
|
|
const { statusCode, content } = await this.httpClient.sendRequestWithBackoff('PATCH', `/v3/glossaries/${glossaryId}`, { data: data });
|
|
await (0, translator_1.checkStatusCode)(statusCode, content, true /* usingGlossary */);
|
|
return (0, parsing_1.parseMultilingualGlossaryInfo)(content);
|
|
}
|
|
/**
|
|
* Updates the dictionary entries for a specific source and target language pair in a multilingual glossary.
|
|
*
|
|
* @param glossary ID of the glossary or MultilingualGlossaryInfo object to update.
|
|
* @param glossaryDict The new or updated glossary dictionary.
|
|
* @returns {Promise<MultilingualGlossaryInfo>} Object containing details about the updated glossary.
|
|
*
|
|
* @throws {ArgumentError} If any argument is invalid.
|
|
* @throws {DeepLError} If any error occurs while communicating with the DeepL API.
|
|
*/
|
|
async updateMultilingualGlossaryDictionary(glossary, glossaryDict) {
|
|
if (!glossary) {
|
|
throw new errors_1.ArgumentError('Parameter "glossary" must not be empty/null');
|
|
}
|
|
if (!glossaryDict) {
|
|
throw new errors_1.ArgumentError('Parameter "glossaryDict" must not be null');
|
|
}
|
|
const glossaryId = (0, utils_1.extractGlossaryId)(glossary);
|
|
const data = new URLSearchParams();
|
|
(0, utils_1.appendDictionaryEntries)(data, [glossaryDict]);
|
|
const { statusCode, content } = await this.httpClient.sendRequestWithBackoff('PATCH', `/v3/glossaries/${glossaryId}`, { data: data });
|
|
await (0, translator_1.checkStatusCode)(statusCode, content, true /* usingGlossary */);
|
|
return (0, parsing_1.parseMultilingualGlossaryInfo)(content);
|
|
}
|
|
/**
|
|
* Updates the dictionary entries for a specific source and target language pair in a multilingual glossary
|
|
* using entries from a CSV file.
|
|
*
|
|
* @param glossary ID of the glossary or MultilingualGlossaryInfo object to update.
|
|
* @param sourceLanguageCode Source language code of the dictionary to update.
|
|
* @param targetLanguageCode Target language code of the dictionary to update.
|
|
* @param csvContent String in CSV format containing the new entries.
|
|
* @returns {Promise<MultilingualGlossaryInfo>} Object containing details about the updated glossary.
|
|
*
|
|
* @throws {ArgumentError} If any argument is invalid.
|
|
* @throws {DeepLError} If any error occurs while communicating with the DeepL API.
|
|
*/
|
|
async updateMultilingualGlossaryDictionaryWithCsv(glossary, sourceLanguageCode, targetLanguageCode, csvContent) {
|
|
if (!glossary) {
|
|
throw new errors_1.ArgumentError('Parameter "glossary" must not be empty/null');
|
|
}
|
|
if (!sourceLanguageCode) {
|
|
throw new errors_1.ArgumentError('Parameter "sourceLanguageCode" must not be empty');
|
|
}
|
|
if (!targetLanguageCode) {
|
|
throw new errors_1.ArgumentError('Parameter "targetLanguageCode" must not be empty');
|
|
}
|
|
if (!csvContent) {
|
|
throw new errors_1.ArgumentError('Parameter "csvContent" must not be empty');
|
|
}
|
|
const glossaryId = (0, utils_1.extractGlossaryId)(glossary);
|
|
const data = new URLSearchParams();
|
|
(0, utils_1.appendCsvDictionaryEntries)(data, sourceLanguageCode, targetLanguageCode, csvContent);
|
|
const { statusCode, content } = await this.httpClient.sendRequestWithBackoff('PATCH', `/v3/glossaries/${glossaryId}`, { data: data });
|
|
await (0, translator_1.checkStatusCode)(statusCode, content, true /* usingGlossary */);
|
|
return (0, parsing_1.parseMultilingualGlossaryInfo)(content);
|
|
}
|
|
}
|
|
exports.DeepLClient = DeepLClient;
|