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環境變數。

展開