deepl node下载 - deepl node源码下载

深度节点

DeepL API 的官方 Node.js 客户端库。

DeepL API 是一种语言翻译 API，允许其他计算机程序将文本和文档发送到 DeepL 的服务器并接收高质量的翻译。这为开发人员带来了巨大的机遇：您能想象到的任何翻译产品现在都可以构建在 DeepL 一流的翻译技术之上。

DeepL Node.js 库为为 Node.js 编写的应用程序提供了一种与 DeepL API 交互的便捷方式。我们打算通过该库支持所有 API 函数，尽管对新功能的支持可能会在添加到 API 后添加到库中。

获取身份验证密钥

要使用该包，您需要一个 API 身份验证密钥。要获取密钥，请在此处创建一个帐户。使用 DeepL API 免费帐户，您每月可以免费翻译多达 500,000 个字符。

安装

npm install deepl-node

要求

该包正式支持 Node.js 版本 12、14、16、17 和 18。

从 2024 年开始，我们将放弃对已正式终止生命周期的旧 Node 版本的支持。您可以在此处找到节点版本和支持时间表。要继续使用此库，您应该更新到 Node 18+。

用法

导入包并构造一个Translator 。第一个参数是一个字符串，其中包含您在 DeepL Pro 帐户中找到的 API 身份验证密钥。

请小心不要暴露您的密钥，例如在共享源代码时。

使用async / await和 ES 模块的示例：

 import * as deepl from 'deepl-node' ;

const authKey = "f63c02c5-f056-..." ; // Replace with your key
const translator = new deepl . Translator ( authKey ) ;

( async ( ) => {
    const result = await translator . translateText ( 'Hello, world!' , null , 'fr' ) ;
    console . log ( result . text ) ; // Bonjour, le monde !
} ) ( ) ;

此示例仅用于演示目的。在生产代码中，身份验证密钥不应进行硬编码，而应从配置文件或环境变量中获取。

如果您使用 CommonJS，则应该需要该包：

 const deepl = require ( 'deepl-node' ) ;
const translator = new deepl . Translator ( authKey ) ;

Translator接受选项作为第二个参数，请参阅配置以获取更多信息。

所有Translator函数都返回 Promise，为了简洁起见，此文件中的示例使用await和try / catch块，但是 Promise 链接也是可能的：

 translator
    . translateText ( 'Hello, world!' , null , 'fr' )
    . then ( ( result ) => {
        console . log ( result . text ) ; // Bonjour, le monde !
    } )
    . catch ( ( error ) => {
        console . error ( error ) ;
    } ) ;

该包还支持 TypeScript：

 import * as deepl from 'deepl-node' ;

( async ( ) => {
    const targetLang : deepl . TargetLanguageCode = 'fr' ;
    const results = await translator . translateText (
        [ 'Hello, world!' , 'How are you?' ] ,
        null ,
        targetLang ,
    ) ;
    results . map ( ( result : deepl . TextResult ) => {
        console . log ( result . text ) ; // Bonjour, le monde !
    } ) ;
} ) ( ) ;

翻译文本

要翻译文本，请调用translateText() 。第一个参数是包含要翻译的文本的字符串，如果要翻译多个文本，则第一个参数是字符串数组。

第二个和第三个参数是源语言代码和目标语言代码。根据 ISO 639-1，语言代码是不区分大小写的字符串，例如'de' 、 'fr' 、 'ja'' 。某些目标语言还包括根据 ISO 3166-1 的区域变体，例如'en-US'或'pt-BR' 。源语言还接受null ，以启用源语言的自动检测。

translateText()的最后一个参数是可选的，并指定额外的翻译选项，请参阅下面的文本翻译选项。

translateText()返回一个 Promise，该 Promise 满足TextResult或与您的输入文本相对应的TextResult数组。 TextResult具有以下属性：

text是翻译后的文本，
detectedSourceLang是检测到的源语言代码，
billedCharacters是为文本计费的字符数。
modelTypeUsed指示使用的转换模型，但除非指定modelType选项，否则undefined 。

 // Translate text into a target language, in this case, French:
const translationResult = await translator . translateText ( 'Hello, world!' , 'en' , 'fr' ) ;
console . log ( translationResult . text ) ; // 'Bonjour, le monde !'

// Translate multiple texts into British English:
const translations = await translator . translateText (
    [ 'お元気ですか？' , '¿Cómo estás?' ] ,
    null ,
    'en-GB' ,
) ;
console . log ( translations [ 0 ] . text ) ; // 'How are you?'
console . log ( translations [ 0 ] . detectedSourceLang ) ; // 'ja'
console . log ( translations [ 0 ] . billedCharacters ) ; // 7 - the number of characters in the source text "お元気ですか？"
console . log ( translations [ 1 ] . text ) ; // 'How are you?'
console . log ( translations [ 1 ] . detectedSourceLang ) ; // 'es'
console . log ( translations [ 1 ] . billedCharacters ) ; // 12 - the number of characters in the source text "¿Cómo estás?"

// Translate into German with less and more Formality:
console . log ( await translator . translateText ( 'How are you?' , null , 'de' , { formality : 'less' } ) ) ; // 'Wie geht es dir?'
console . log ( await translator . translateText ( 'How are you?' , null , 'de' , { formality : 'more' } ) ) ; // 'Wie geht es Ihnen?'

文本翻译选项

splitSentences ：指定如何将输入文本拆分为句子，默认值： 'on' 。
- 'on' ：输入文本将使用换行符和标点符号分割成句子。
- 'off' ：输入文本不会被分割成句子。将此用于每个输入文本仅包含一个句子的应用程序。
- 'nonewlines' ：输入文本将使用标点符号分割成句子，但不使用换行符。
preserveFormatting ：控制自动格式更正。设置为true以防止自动更正格式，默认值： false 。
formality ：控制翻译是否应该倾向于非正式语言或正式语言。此选项仅适用于某些目标语言，请参阅列出可用语言。如果目标可用，请使用prefer_*选项来应用形式
语言，或以其他方式回退到默认值。
- 'less' ：使用非正式语言。
- 'more' ：使用正式、更礼貌的语言。
- 'default' ：使用默认形式。
- 'prefer_less' ：如果可用，则使用非正式语言，否则使用默认语言。
- 'prefer_more' ：如果有的话，使用正式、更礼貌的语言，否则使用默认语言。
glossary ：指定用于翻译的词汇表，可以是包含词汇表 ID 的字符串，也可以是getGlossary()返回的GlossaryInfo 。
context ：指定影响翻译的附加上下文，而不是翻译本身。 context参数中的字符不计入计费。有关更多信息和示例用法，请参阅 API 文档。
modelType ：指定要使用的翻译模型的类型，选项有：
- 'quality_optimized' ：使用以响应时间为代价最大化翻译质量的翻译模型。此选项对于某些语言对可能不可用。
- 'prefer_quality_optimized' ：对给定语言对使用最高质量的翻译模型。
- 'latency_optimized' ：使用可最大限度缩短响应时间的翻译模型，但会牺牲翻译质量。
tagHandling ：翻译前解析的标签类型，选项为'html'和'xml' 。

仅当tagHandling为'xml'时才使用以下选项：

outlineDetection ：指定false禁用自动标签检测，默认为true 。
splittingTags ：用于将文本拆分为句子的 XML 标签列表。标签可以指定为字符串数组 ( ['tag1', 'tag2'] ) 或以逗号分隔的字符串列表 ( 'tag1,tag2' )。默认是一个空列表。
nonSplittingTags ：不应用于将文本拆分为句子的 XML 标记列表。格式和默认值与splittingTags相同。
ignoreTags ：包含不应翻译的内容的 XML 标签列表。格式和默认值与splittingTags相同。
extraRequestParameters ：与 HTTP 请求一起传递的额外主体参数。仅允许字符串值。例如： {'param': 'value', 'param2': 'value2'}

翻译文件

要翻译文档，请调用translateDocument() 。第一个和第二个参数是输入和输出文件。这些参数接受包含文件路径的字符串，或者为读/写而打开的 Streams 或 FileHandles。输入文件也可以作为包含文件数据的缓冲区给出。请注意，如果输入文件未作为文件路径给出，则需要filename选项。

第三个和第四个参数是源语言代码和目标语言代码，它们的工作方式与使用translateText()翻译文本时完全相同。

translateDocument()的最后一个参数是可选的，并指定额外的翻译选项，请参阅下面的文档翻译选项。

 // Translate a formal document from English to German:
try {
    await translator . translateDocument (
        'Instruction Manual.docx' ,
        'Bedienungsanleitung.docx' ,
        'en' ,
        'de' ,
        { formality : 'more' } ,
    ) ;
} catch ( error ) {
    // If the error occurs after the document was already uploaded,
    // documentHandle will contain the document ID and key
    if ( error . documentHandle ) {
        const handle = error . documentHandle ;
        console . log ( `Document ID: ${ handle . documentId } , ` + `Document key: ${ handle . documentKey } ` ) ;
    } else {
        console . log ( `Error occurred during document upload: ${ error } ` ) ;
    }
}

translateDocument()包装了多个 API 调用：上传、轮询状态直至翻译完成以及下载。如果您的应用程序需要单独执行这些步骤，您可以直接使用以下函数：

uploadDocument() ,
getDocumentStatus() （或isDocumentTranslationComplete() ），以及
downloadDocument()

文档翻译选项

formality ：与文本翻译选项中的相同。
glossary ：与文本翻译选项中的相同。
filename ：如果输入文件未作为文件路径提供，则需要此选项来指定文件扩展名。
extraRequestParameters ：与文本翻译选项中的相同。

词汇表

词汇表允许您使用定义的术语自定义翻译。您的帐户可以存储多个词汇表，每个词汇表都有用户指定的名称和唯一分配的 ID。

您可以使用createGlossary()创建包含所需术语和名称的术语表。每个术语表适用于单个源-目标语言对。注意：仅某些语言对支持术语表，请查看 DeepL API 文档以获取更多信息。

 // Create an English to German glossary with two terms:
const entries = new deepl . GlossaryEntries ( { entries : { artist : 'Maler' , prize : 'Gewinn' } } ) ;
const glossaryEnToDe = await translator . createGlossary ( 'My glossary' , 'en' , 'de' , entries ) ;

您还可以使用createGlossaryWithCsv()上传从 DeepL 网站下载的术语表。不要将条目作为字典提供，而是以包含文件路径的字符串形式提供 CSV 文件，或者包含 CSV 文件内容的 Stream、Buffer 或 FileHandle：

 const csvFilePath = '/path/to/glossary_file.csv' ;
const glossaryEnToDe = await translator . createGlossaryWithCsv (
    'My glossary' ,
    'en' ,
    'de' ,
    csvFilePath ) ;

API 文档详细解释了预期的 CSV 格式。

还提供获取、列出和删除存储的词汇表的功能。

 // Find details about the glossary named 'My glossary'
const glossaries = await translator . listGlossaries ( ) ;
const glossary = glossaries . find ( ( glossary ) => glossary . name == 'My glossary' ) ;
console . log (
    `Glossary ID: ${ glossary . glossaryId } , source: ${ glossary . sourceLang } , ` +
        `target: ${ glossary . targetLang } , contains ${ glossary . entryCount } entries.` ,
) ;

要在翻译文本和文档时使用术语表，请在函数调用中包含 ID（或listGlossaries()或createGlossary() ) 返回的Glossary对象）。源语言和目标语言必须与术语表匹配。

 const resultWithGlossary = await translator . translateText (
    'The artist was awarded a prize.' ,
    'en' ,
    'de' ,
    { glossary } ,
) ;
console . log ( resultWithGlossary . text ) ; // 'Der Maler wurde mit einem Gewinn ausgezeichnet.'
// Without using a glossary would give:  'Der Künstler wurde mit einem Preis ausgezeichnet.'

检查帐户使用情况

要检查帐户使用情况，请使用getUsage()函数。

返回的Usage对象最多包含三个使用子类型，具体取决于您的帐户类型： character 、 document和teamDocument 。对于API帐户character将被定义，其他undefined 。

每个使用子类型（如果已定义）都有count和limit属性，分别给出使用量和最大量，以及检查使用量是否已达到限制的limitReached()函数。顶级Usage对象具有anyLimitReached()函数来检查所有使用子类型。

 const usage = await translator . getUsage ( ) ;
if ( usage . anyLimitReached ( ) ) {
    console . log ( 'Translation limit exceeded.' ) ;
}
if ( usage . character ) {
    console . log ( `Characters: ${ usage . character . count } of ${ usage . character . limit } ` ) ;
}
if ( usage . document ) {
    console . log ( `Documents: ${ usage . document . count } of ${ usage . document . limit } ` ) ;
}

列出可用语言

您可以使用getSourceLanguages()和getTargetLanguages()函数请求 DeepL Translator 支持的文本和文档语言列表。它们都返回一个Language对象数组。

name属性给出英语语言的名称， code属性给出语言代码。 supportsFormality属性仅针对目标语言出现，并且是一个Boolean指示目标语言是否支持可选的formality参数。

 const sourceLanguages = await translator . getSourceLanguages ( ) ;
for ( let i = 0 ; i < sourceLanguages . length ; i ++ ) {
    const lang = sourceLanguages [ i ] ;
    console . log ( ` ${ lang . name } ( ${ lang . code } )` ) ; // Example: 'English (en)'
}

const targetLanguages = await translator . getTargetLanguages ( ) ;
for ( let i = 0 ; i < targetLanguages . length ; i ++ ) {
    const lang = targetLanguages [ i ] ;
    if ( lang . supportsFormality ) {
        console . log ( ` ${ lang . name } ( ${ lang . code } ) supports formality` ) ;
        // Example: 'German (DE) supports formality'
    }
}

一部分语言对支持术语表。要检索这些语言，请使用getGlossaryLanguagePairs()函数，该函数返回GlossaryLanguagePair对象的数组。每个都有sourceLang和targetLang属性，指示术语表支持该对语言代码。

 const glossaryLanguages = await translator . getGlossaryLanguagePairs ( ) ;
for ( let i = 0 ; i < glossaryLanguages . length ; i ++ ) {
    const languagePair = glossaryLanguages [ i ] ;
    console . log ( ` ${ languagePair . sourceLang } to ${ languagePair . targetLang } ` ) ;
    // Example: 'en to de', 'de to en', etc.
}

编写插件

如果您在应用程序中使用此库，请使用TranslatorOptions中的appInfo字段标识该应用程序，该字段采用应用程序的名称和版本：

 const options = { appInfo : { appName : 'sampleNodeTranslationApp' , appVersion : '1.2.3' } , } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;

当库调用 DeepL API 时，会传递此信息。名称和版本都是必需的。

配置

Translator构造函数接受配置选项作为第二个参数，例如：

 const options = { maxRetries : 5 , minTimeout : 10000 } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;

可用的选项有：

maxRetries ：每个函数调用重试失败的 HTTP 请求的最大Number 。默认情况下重试 5 次。请参阅请求重试。
minTimeout ：用作每个 HTTP 请求重试的连接超时的毫秒Number 。默认值为 10000（10 秒）。
serverUrl ：包含 DeepL API 的 URL 的string ，可以被覆盖，例如用于测试目的。默认情况下，根据用户帐户类型（免费或付费）选择 URL。
headers ：附加到每个 HTTP 请求的额外 HTTP 标头。默认情况下，不使用额外的标头。请注意，授权和用户代理标头会自动添加，但可能会被此选项覆盖。
proxy ：定义代理服务器的主机名和端口，以及可选的协议和授权（作为带有用户名和密码字段的 auth 对象）。

记录

deepl-node使用loglevel模块将每个 HTTP 请求和响应的调试和信息消息记录到'deepl'记录器。您可以按如下方式重新配置日志级别：

 import log from 'loglevel' ;

log . getLogger ( 'deepl' ) . setLevel ( 'debug' ) ; // Or 'info'

loglevel包还支持插件，请参阅文档。

代理配置

您可以通过在构造deepl.Translator时指定proxy参数来配置代理：

 const options = { proxy : { host : 'localhost' , port : 3000 } } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;

proxy 参数传递给底层的axios请求，请参阅 axios 文档。

匿名平台信息

默认情况下，我们会在每个请求中发送有关客户端库运行平台的一些基本信息，请参阅此处了解说明。这些数据是完全匿名的，仅用于改进我们的产品，不会跟踪任何个人用户。如果您不想发送此数据，则可以在创建Translator对象时通过将TranslatorOptions中的sendPlatformInfo标志设置为false来选择退出，如下所示：

 const options = { sendPlatformInfo : false } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;

请求重试

由于瞬态条件（例如网络超时或高服务器负载）而失败的 DeepL API 请求将被重试。使用maxRetries选项构造Translator对象时可以配置最大重试次数。每个请求尝试的超时可以使用minTimeout选项来控制。采用指数退避策略，因此多次失败的请求会产生延迟。

问题

如果您在使用该库时遇到问题，或者想要请求新功能，请提出问题。

发展

我们欢迎 Pull Request，请阅读贡献指南。

测试

使用npm test执行测试。测试使用DEEPL_AUTH_KEY环境变量定义的身份验证密钥与 DeepL API 进行通信。

请注意，测试发出的 DeepL API 请求有助于您的 API 使用。

测试套件可以配置为与 deepl-mock 提供的模拟服务器进行通信。尽管大多数测试用例都适用于其中任何一个，但某些测试用例仅适用于 DeepL API 或模拟服务器，否则将被跳过。需要模拟服务器的测试用例触发服务器错误并测试客户端错误处理。要使用 deepl-mock 执行测试，请在执行测试时在另一个终端中运行它。使用npm test执行测试，并引用模拟服务器定义的DEEPL_MOCK_SERVER_PORT和DEEPL_SERVER_URL环境变量。

展开