173 lines
10 KiB
TypeScript
173 lines
10 KiB
TypeScript
/// <reference types="node" />
|
|
/// <reference types="node" />
|
|
/// <reference types="node" />
|
|
/// <reference types="node" />
|
|
import { HttpClient } from './client';
|
|
import { GlossaryEntries } from './glossaryEntries';
|
|
import { Usage } from './index';
|
|
import { DocumentStatus, DocumentHandle, DocumentTranslateOptions, GlossaryId, GlossaryInfo, GlossaryLanguagePair, Language, LanguageCode, SourceLanguageCode, TargetLanguageCode, TranslateTextOptions, TranslatorOptions, TextResult } from './types';
|
|
import * as fs from 'fs';
|
|
import { IncomingMessage } from 'http';
|
|
/**
|
|
* Checks the HTTP status code, and in case of failure, throws an exception with diagnostic information.
|
|
* @private
|
|
*/
|
|
export declare function checkStatusCode(statusCode: number, content: string | IncomingMessage, usingGlossary?: boolean, inDocumentDownload?: boolean): Promise<void>;
|
|
/**
|
|
* Wrapper for the DeepL API for language translation.
|
|
* Create an instance of Translator to use the DeepL API.
|
|
*/
|
|
export declare class Translator {
|
|
/**
|
|
* Construct a Translator object wrapping the DeepL API using your authentication key.
|
|
* This does not connect to the API, and returns immediately.
|
|
* @param authKey Authentication key as specified in your account.
|
|
* @param options Additional options controlling Translator behavior.
|
|
*/
|
|
constructor(authKey: string, options?: TranslatorOptions);
|
|
/**
|
|
* Queries character and document usage during the current billing period.
|
|
* @return Fulfills with Usage object on success.
|
|
*/
|
|
getUsage(): Promise<Usage>;
|
|
/**
|
|
* Queries source languages supported by DeepL API.
|
|
* @return Fulfills with array of Language objects containing available source languages.
|
|
*/
|
|
getSourceLanguages(): Promise<readonly Language[]>;
|
|
/**
|
|
* Queries target languages supported by DeepL API.
|
|
* @return Fulfills with array of Language objects containing available target languages.
|
|
*/
|
|
getTargetLanguages(): Promise<readonly Language[]>;
|
|
/**
|
|
* Queries language pairs supported for glossaries by DeepL API.
|
|
* @return Fulfills with an array of GlossaryLanguagePair objects containing languages supported for glossaries.
|
|
*/
|
|
getGlossaryLanguagePairs(): Promise<readonly GlossaryLanguagePair[]>;
|
|
/**
|
|
* Translates specified text string or array of text strings into the target language.
|
|
* @param texts Text string or array of strings containing input text(s) to translate.
|
|
* @param sourceLang Language code of input text language, or null to use auto-detection.
|
|
* @param targetLang Language code of language to translate into.
|
|
* @param options Optional TranslateTextOptions object containing additional options controlling translation.
|
|
* @return Fulfills with a TextResult object or an array of TextResult objects corresponding to input texts; use the `TextResult.text` property to access the translated text.
|
|
*/
|
|
translateText<T extends string | string[]>(texts: T, sourceLang: SourceLanguageCode | null, targetLang: TargetLanguageCode, options?: TranslateTextOptions): Promise<T extends string ? TextResult : TextResult[]>;
|
|
/**
|
|
* Uploads specified document to DeepL to translate into given target language, waits for
|
|
* translation to complete, then downloads translated document to specified output path.
|
|
* @param inputFile String containing file path of document to be translated, or a Stream,
|
|
* Buffer, or FileHandle containing file data. Note: unless file path is used, then
|
|
* `options.filename` must be specified.
|
|
* @param outputFile String containing file path to create translated document, or Stream or
|
|
* FileHandle to write translated document content.
|
|
* @param sourceLang Language code of input document, or null to use auto-detection.
|
|
* @param targetLang Language code of language to translate into.
|
|
* @param options Optional DocumentTranslateOptions object containing additional options controlling translation.
|
|
* @return Fulfills with a DocumentStatus object for the completed translation. You can use the
|
|
* billedCharacters property to check how many characters were billed for the document.
|
|
* @throws {Error} If no file exists at the input file path, or a file already exists at the output file path.
|
|
* @throws {DocumentTranslationError} If any error occurs during document upload, translation or
|
|
* download. The `documentHandle` property of the error may be used to recover the document.
|
|
*/
|
|
translateDocument(inputFile: string | Buffer | fs.ReadStream | fs.promises.FileHandle, outputFile: string | fs.WriteStream | fs.promises.FileHandle, sourceLang: SourceLanguageCode | null, targetLang: TargetLanguageCode, options?: DocumentTranslateOptions): Promise<DocumentStatus>;
|
|
/**
|
|
* Uploads specified document to DeepL to translate into target language, and returns handle associated with the document.
|
|
* @param inputFile String containing file path, stream containing file data, or FileHandle.
|
|
* Note: if a Buffer, Stream, or FileHandle is used, then `options.filename` must be specified.
|
|
* @param sourceLang Language code of input document, or null to use auto-detection.
|
|
* @param targetLang Language code of language to translate into.
|
|
* @param options Optional DocumentTranslateOptions object containing additional options controlling translation.
|
|
* @return Fulfills with DocumentHandle associated with the in-progress translation.
|
|
*/
|
|
uploadDocument(inputFile: string | Buffer | fs.ReadStream | fs.promises.FileHandle, sourceLang: SourceLanguageCode | null, targetLang: TargetLanguageCode, options?: DocumentTranslateOptions): Promise<DocumentHandle>;
|
|
/**
|
|
* Retrieves the status of the document translation associated with the given document handle.
|
|
* @param handle Document handle associated with document.
|
|
* @return Fulfills with a DocumentStatus giving the document translation status.
|
|
*/
|
|
getDocumentStatus(handle: DocumentHandle): Promise<DocumentStatus>;
|
|
/**
|
|
* Downloads the translated document associated with the given document handle to the specified output file path or stream.handle.
|
|
* @param handle Document handle associated with document.
|
|
* @param outputFile String containing output file path, or Stream or FileHandle to store file data.
|
|
* @return Fulfills with undefined, or rejects if the document translation has not been completed.
|
|
*/
|
|
downloadDocument(handle: DocumentHandle, outputFile: string | fs.WriteStream | fs.promises.FileHandle): Promise<void>;
|
|
/**
|
|
* Returns a promise that resolves when the given document translation completes, or rejects if
|
|
* there was an error communicating with the DeepL API or the document translation failed.
|
|
* @param handle {DocumentHandle} Handle to the document translation.
|
|
* @return Fulfills with input DocumentHandle and DocumentStatus when the document translation
|
|
* completes successfully, rejects if translation fails or a communication error occurs.
|
|
*/
|
|
isDocumentTranslationComplete(handle: DocumentHandle): Promise<{
|
|
handle: DocumentHandle;
|
|
status: DocumentStatus;
|
|
}>;
|
|
/**
|
|
* 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.
|
|
* @param entries The source- & target-term pairs to add to the glossary.
|
|
* @return Fulfills with a GlossaryInfo containing details about the created glossary.
|
|
*/
|
|
createGlossary(name: string, sourceLang: LanguageCode, targetLang: LanguageCode, entries: GlossaryEntries): Promise<GlossaryInfo>;
|
|
/**
|
|
* 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.
|
|
*/
|
|
createGlossaryWithCsv(name: string, sourceLang: LanguageCode, targetLang: LanguageCode, csvFile: string | Buffer | fs.ReadStream | fs.promises.FileHandle): Promise<GlossaryInfo>;
|
|
/**
|
|
* Gets information about an existing glossary.
|
|
* @param glossaryId Glossary ID of the glossary.
|
|
* @return Fulfills with a GlossaryInfo containing details about the glossary.
|
|
*/
|
|
getGlossary(glossaryId: GlossaryId): Promise<GlossaryInfo>;
|
|
/**
|
|
* Gets information about all existing glossaries.
|
|
* @return Fulfills with an array of GlossaryInfos containing details about all existing glossaries.
|
|
*/
|
|
listGlossaries(): Promise<GlossaryInfo[]>;
|
|
/**
|
|
* Retrieves the entries stored with the glossary with the given glossary ID or GlossaryInfo.
|
|
* @param glossary Glossary ID or GlossaryInfo of glossary to retrieve entries of.
|
|
* @return Fulfills with GlossaryEntries holding the glossary entries.
|
|
*/
|
|
getGlossaryEntries(glossary: GlossaryId | GlossaryInfo): Promise<GlossaryEntries>;
|
|
/**
|
|
* Deletes the glossary with the given glossary ID or GlossaryInfo.
|
|
* @param glossary Glossary ID or GlossaryInfo of glossary to be deleted.
|
|
* @return Fulfills with undefined when the glossary is deleted.
|
|
*/
|
|
deleteGlossary(glossary: GlossaryId | GlossaryInfo): Promise<void>;
|
|
/**
|
|
* Upload given stream for document translation and returns document handle.
|
|
* @private
|
|
*/
|
|
private internalUploadDocument;
|
|
/**
|
|
* Download translated document associated with specified handle to given stream.
|
|
* @private
|
|
*/
|
|
private internalDownloadDocument;
|
|
/**
|
|
* Create glossary with given details.
|
|
* @private
|
|
*/
|
|
private internalCreateGlossary;
|
|
private constructUserAgentString;
|
|
/**
|
|
* HttpClient implements all HTTP requests and retries.
|
|
* @protected
|
|
*/
|
|
protected readonly httpClient: HttpClient;
|
|
}
|