diff --git a/src/index.ts b/src/index.ts index b9dac80..8b5a068 100644 --- a/src/index.ts +++ b/src/index.ts @@ -22,24 +22,29 @@ import { parseLanguageArray, parseTextResultArray, parseUsage, + standardizeLanguageCode, } from './parsing'; import { AppInfo, + DocumentHandle, + DocumentStatus, DocumentTranslateOptions, Formality, GlossaryId, GlossaryInfo, + GlossaryLanguagePair, + Language, LanguageCode, NonRegionalLanguageCode, RequestParameters, SentenceSplittingMode, - SourceGlossaryLanguageCode, SourceLanguageCode, TagList, - TargetGlossaryLanguageCode, TargetLanguageCode, + TextResult, TranslateTextOptions, TranslatorOptions, + Usage, } from './types'; import { isString, logInfo, streamToBuffer, streamToString, timeout, toBoolString } from './utils'; @@ -54,149 +59,6 @@ export * from './errors'; export * from './glossaryEntries'; export * from './types'; -/** - * Stores the count and limit for one usage type. - */ -export interface UsageDetail { - /** The amount used of this usage type. */ - readonly count: number; - /** The maximum allowable amount for this usage type. */ - readonly limit: number; - - /** - * Returns true if the amount used has already reached or passed the allowable amount. - */ - limitReached(): boolean; -} - -/** - * Information about the API usage: how much has been translated in this billing period, and the - * maximum allowable amount. - * - * Depending on the account type, different usage types are included: the character, document and - * teamDocument fields provide details about each corresponding usage type, allowing each usage type - * to be checked individually. The anyLimitReached() function checks if any usage type is exceeded. - */ -export interface Usage { - /** Usage details for characters, for example due to the translateText() function. */ - readonly character?: UsageDetail; - /** Usage details for documents. */ - readonly document?: UsageDetail; - /** Usage details for documents shared among your team. */ - readonly teamDocument?: UsageDetail; - - /** Returns true if any usage type limit has been reached or passed, otherwise false. */ - anyLimitReached(): boolean; - - /** Converts the usage details to a human-readable string. */ - toString(): string; -} - -/** - * Information about a language supported by DeepL translator. - */ -export interface Language { - /** Name of the language in English. */ - readonly name: string; - /** - * Language code according to ISO 639-1, for example 'en'. Some target languages also include - * the regional variant according to ISO 3166-1, for example 'en-US'. - */ - readonly code: LanguageCode; - /** - * Only defined for target languages. If defined, specifies whether the formality option is - * available for this target language. - */ - readonly supportsFormality?: boolean; -} - -/** - * Information about a pair of languages supported for DeepL glossaries. - */ -export interface GlossaryLanguagePair { - /** - * The code of the source language. - */ - readonly sourceLang: SourceGlossaryLanguageCode; - /** - * The code of the target language. - */ - readonly targetLang: TargetGlossaryLanguageCode; -} - -/** - * Handle to an in-progress document translation. - */ -export interface DocumentHandle { - /** - * ID of associated document request. - */ - readonly documentId: string; - - /** - * Key of associated document request. - */ - readonly documentKey: string; -} - -export type DocumentStatusCode = 'queued' | 'translating' | 'error' | 'done'; - -/** - * Status of a document translation request. - */ -export interface DocumentStatus { - /** - * One of the status values defined in DocumentStatusCode. - * @see DocumentStatusCode - */ - readonly status: DocumentStatusCode; - - /** - * Estimated time until document translation completes in seconds, otherwise undefined if - * unknown. - */ - readonly secondsRemaining?: number; - - /** - * Number of characters billed for this document, or undefined if unknown or before translation - * is complete. - */ - readonly billedCharacters?: number; - - /** - * A short description of the error, or undefined if no error has occurred. - */ - readonly errorMessage?: string; - - /** - * True if no error has occurred, otherwise false. Note that while the document translation is - * in progress, this returns true. - */ - ok(): boolean; - - /** - * True if the document translation completed successfully, otherwise false. - */ - done(): boolean; -} - -/** - * Changes the upper- and lower-casing of the given language code to match ISO 639-1 with an - * optional regional code from ISO 3166-1. - * For example, input 'EN-US' returns 'en-US'. - * @param langCode String containing language code to standardize. - * @return Standardized language code. - */ -export function standardizeLanguageCode(langCode: string): LanguageCode { - if (!isString(langCode) || langCode.length === 0) { - throw new DeepLError('langCode must be a non-empty string'); - } - const [lang, region] = langCode.split('-', 2); - return ( - region === undefined ? lang.toLowerCase() : `${lang.toLowerCase()}-${region.toUpperCase()}` - ) as LanguageCode; -} - /** * Removes the regional variant from a language, for example inputs 'en' and 'en-US' both return * 'en'. @@ -210,21 +72,6 @@ export function nonRegionalLanguageCode(langCode: string): NonRegionalLanguageCo return langCode.split('-', 2)[0].toLowerCase() as NonRegionalLanguageCode; } -/** - * Holds the result of a text translation request. - */ -export interface TextResult { - /** - * String containing the translated text. - */ - readonly text: string; - - /** - * Language code of the detected source language. - */ - readonly detectedSourceLang: SourceLanguageCode; -} - /** * Returns true if the specified DeepL Authentication Key is associated with a free account, * otherwise false. diff --git a/src/parsing.ts b/src/parsing.ts index 78e4ecd..c154404 100644 --- a/src/parsing.ts +++ b/src/parsing.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 { isString } from './utils'; import { DeepLError } from './errors'; import { DocumentHandle, @@ -10,13 +11,31 @@ import { GlossaryLanguagePair, Language, SourceGlossaryLanguageCode, - standardizeLanguageCode, TextResult, TargetGlossaryLanguageCode, UsageDetail, Usage, -} from './index'; -import { GlossaryInfo, SourceLanguageCode } from './types'; + GlossaryInfo, + SourceLanguageCode, + LanguageCode, +} from './types'; + +/** + * Changes the upper- and lower-casing of the given language code to match ISO 639-1 with an + * optional regional code from ISO 3166-1. + * For example, input 'EN-US' returns 'en-US'. + * @param langCode String containing language code to standardize. + * @return Standardized language code. + */ +export function standardizeLanguageCode(langCode: string): LanguageCode { + if (!isString(langCode) || langCode.length === 0) { + throw new DeepLError('langCode must be a non-empty string'); + } + const [lang, region] = langCode.split('-', 2); + return ( + region === undefined ? lang.toLowerCase() : `${lang.toLowerCase()}-${region.toUpperCase()}` + ) as LanguageCode; +} /** * Type used during JSON parsing of API response for glossary info. diff --git a/src/types.ts b/src/types.ts index 03f8596..ef87d78 100644 --- a/src/types.ts +++ b/src/types.ts @@ -2,6 +2,154 @@ // Use of this source code is governed by an MIT // license that can be found in the LICENSE file. +/** + * Information about the API usage: how much has been translated in this billing period, and the + * maximum allowable amount. + * + * Depending on the account type, different usage types are included: the character, document and + * teamDocument fields provide details about each corresponding usage type, allowing each usage type + * to be checked individually. The anyLimitReached() function checks if any usage type is exceeded. + */ +export interface Usage { + /** Usage details for characters, for example due to the translateText() function. */ + readonly character?: UsageDetail; + /** Usage details for documents. */ + readonly document?: UsageDetail; + /** Usage details for documents shared among your team. */ + readonly teamDocument?: UsageDetail; + + /** Returns true if any usage type limit has been reached or passed, otherwise false. */ + anyLimitReached(): boolean; + + /** Converts the usage details to a human-readable string. */ + toString(): string; +} + +/** + * Holds the result of a text translation request. + */ +export interface TextResult { + /** + * String containing the translated text. + */ + readonly text: string; + + /** + * Language code of the detected source language. + */ + readonly detectedSourceLang: SourceLanguageCode; +} + +/** + * Language codes that may be used as a target language for glossaries. + * Note: although the language code type definitions are case-sensitive, this package and the DeepL + * API accept case-insensitive language codes. + */ +export type TargetGlossaryLanguageCode = SourceGlossaryLanguageCode; + +/** + * Stores the count and limit for one usage type. + */ +export interface UsageDetail { + /** The amount used of this usage type. */ + readonly count: number; + /** The maximum allowable amount for this usage type. */ + readonly limit: number; + + /** + * Returns true if the amount used has already reached or passed the allowable amount. + */ + limitReached(): boolean; +} + +/** + * Information about a language supported by DeepL translator. + */ +export interface Language { + /** Name of the language in English. */ + readonly name: string; + /** + * Language code according to ISO 639-1, for example 'en'. Some target languages also include + * the regional variant according to ISO 3166-1, for example 'en-US'. + */ + readonly code: LanguageCode; + /** + * Only defined for target languages. If defined, specifies whether the formality option is + * available for this target language. + */ + readonly supportsFormality?: boolean; +} + +/** + * Information about a pair of languages supported for DeepL glossaries. + */ +export interface GlossaryLanguagePair { + /** + * The code of the source language. + */ + readonly sourceLang: SourceGlossaryLanguageCode; + /** + * The code of the target language. + */ + readonly targetLang: TargetGlossaryLanguageCode; +} + +export type DocumentStatusCode = 'queued' | 'translating' | 'error' | 'done'; + +/** + * Status of a document translation request. + */ +export interface DocumentStatus { + /** + * One of the status values defined in DocumentStatusCode. + * @see DocumentStatusCode + */ + readonly status: DocumentStatusCode; + + /** + * Estimated time until document translation completes in seconds, otherwise undefined if + * unknown. + */ + readonly secondsRemaining?: number; + + /** + * Number of characters billed for this document, or undefined if unknown or before translation + * is complete. + */ + readonly billedCharacters?: number; + + /** + * A short description of the error, or undefined if no error has occurred. + */ + readonly errorMessage?: string; + + /** + * True if no error has occurred, otherwise false. Note that while the document translation is + * in progress, this returns true. + */ + ok(): boolean; + + /** + * True if the document translation completed successfully, otherwise false. + */ + done(): boolean; +} + +/** + * Handle to an in-progress document translation. + */ +export interface DocumentHandle { + /** + * ID of associated document request. + */ + readonly documentId: string; + + /** + * Key of associated document request. + */ + readonly documentKey: string; +} + /** * Optional proxy configuration, may be specified as proxy in TranslatorOptions. * @see TranslatorOptions.proxy @@ -246,13 +394,6 @@ export type SourceGlossaryLanguageCode = | 'ru' | 'zh'; -/** - * Language codes that may be used as a target language for glossaries. - * Note: although the language code type definitions are case-sensitive, this package and the DeepL - * API accept case-insensitive language codes. - */ -export type TargetGlossaryLanguageCode = SourceGlossaryLanguageCode; - /** * Extra request parameters to be passed with translation requests. * They are stored as an object where each field represents a request parameter.