deepl-node
Version:
deepl-node is the official DeepL Node.js client library
377 lines (376 loc) • 20.9 kB
JavaScript
;
// 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;