deepl node

ディープルノード

DeepL API の公式 Node.js クライアント ライブラリ。

DeepL API は、他のコンピューター プログラムがテキストやドキュメントを DeepL のサーバーに送信し、高品質の翻訳を受信できるようにする言語翻訳 API です。これにより、開発者にとってチャンスが広がります。想像できるあらゆる翻訳製品を、DeepL のクラス最高の翻訳テクノロジー上に構築できるようになります。

DeepL Node.js ライブラリは、Node.js 用に作成されたアプリケーションが DeepL API と対話するための便利な方法を提供します。新しい機能のサポートは、API に追加された後にライブラリに追加される可能性がありますが、ライブラリですべての API 関数をサポートする予定です。

認証キーの取得

パッケージを使用するには、API 認証キーが必要です。キーを取得するには、ここでアカウントを作成してください。 DeepL API Free アカウントを使用すると、毎月最大 500,000 文字を無料で翻訳できます。

インストール

npm install deepl-node

要件

このパッケージは、Node.js バージョン 12、14、16、17、および 18 を正式にサポートしています。

2024 年から、正式なサポートが終了した古い Node バージョンのサポートを終了します。 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 2 番目の引数としてオプションを受け入れます。詳細については、「構成」を参照してください。

すべての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()を呼び出します。最初の引数は、翻訳するテキストを含む文字列、または複数のテキストを翻訳する場合は文字列の配列です。

2 番目と 3 番目の引数は、ソース言語コードとターゲット言語コードです。言語コードは、ISO 639-1 に準拠した大文字と小文字を区別しない文字列です (例: 'de' 、 'fr' 、 'ja'' 。一部のターゲット言語には、 ISO 3166-1 に準拠した地域バリアント ( 'en-US'や'pt-BR'など) も含まれています。ソース言語はnullも受け入れて、ソース言語の自動検出を有効にします。

translateText()の最後の引数はオプションであり、追加の翻訳オプションを指定します。以下のテキスト翻訳オプションを参照してください。

translateText() TextResult 、または入力テキストに対応するTextResultの配列で満たされる Promise を返します。 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' : 入力テキストは文に分割されません。これは、各入力テキストに 1 つの文のみが含まれるアプリケーションに使用します。
  • '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()を呼び出します。最初と 2 番目の引数は入力ファイルと出力ファイルです。これらの引数は、ファイル パスを含む文字列、または読み取り/書き込み用に開かれたストリームまたはファイル ハンドルを受け入れます。入力ファイルは、ファイル データを含むバッファとして指定することもできます。入力ファイルがファイル パスとして指定されていない場合は、 filenameオプションが必要であることに注意してください。

3 番目と 4 番目の引数はソース言語コードとターゲット言語コードで、 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 Web サイトからダウンロードした用語集をアップロードすることもできます。エントリを辞書として提供する代わりに、ファイル パスを含む文字列として CSV ファイルを提供するか、CSV ファイルのコンテンツを含むストリーム、バッファ、またはファイル ハンドルを提供します。

 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という最大3つの使用サブタイプが含まれます。 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プロパティはターゲット言語にのみ表示され、ターゲット言語がオプションのformalityパラメーターをサポートするかどうかを示すBooleanです。

 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コンストラクターは、次のような構成オプションを 2 番目の引数として受け入れます。

 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 ヘッダー。デフォルトでは、追加のヘッダーは使用されません。 Authorization ヘッダーと User-Agent ヘッダーは自動的に追加されますが、このオプションによってオーバーライドされる可能性があることに注意してください。
• proxy : プロキシ サーバーのホスト名とポート、およびオプションでプロトコルと認可 (ユーザー名とパスワードのフィールドを持つ認証オブジェクトとして) を定義します。

ロギング

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 ) ;

プロキシ引数は基礎となるaxiosリクエストに渡されます。axios のドキュメントを参照してください。

匿名のプラットフォーム情報

デフォルトでは、クライアント ライブラリが実行されているプラ​​ットフォームに関する基本情報がリクエストごとに送信されます。説明については、ここを参照してください。このデータは完全に匿名であり、製品を改善するためにのみ使用され、個々のユーザーを追跡することはありません。このデータを送信したくない場合は、次のようにTranslatorOptionsのsendPlatformInfoフラグをfalseに設定することで、 Translatorオブジェクトの作成時にオプトアウトできます。

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

リクエストの再試行

一時的な状況 (ネットワーク タイムアウトやサーバー負荷の高さなど) が原因で失敗した DeepL API へのリクエストは再試行されます。再試行の最大数は、 Translatorオブジェクトを構築するときにmaxRetriesオプションを使用して構成できます。各リクエスト試行のタイムアウトは、 minTimeoutオプションを使用して制御できます。指数バックオフ戦略が使用されるため、リクエストが複数回失敗すると遅延が発生します。

問題

ライブラリの使用中に問題が発生した場合、または新しい機能をリクエストしたい場合は、問題を作成してください。

発達

プル リクエストは歓迎です。投稿ガイドラインをお読みください。

テスト

npm test使用してテストを実行します。テストは、 DEEPL_AUTH_KEY環境変数で定義された認証キーを使用して DeepL API と通信します。

テストでは、API の使用に寄与する DeepL API リクエストが作成されることに注意してください。

代わりに、テスト スイートは、deepl-mock によって提供されるモックサーバーと通信するように構成できます。ほとんどのテスト ケースはどちらでも機能しますが、一部のテスト ケースは DeepL API またはモックサーバーでのみ機能し、それ以外の場合はスキップされます。モックサーバーを必要とするテスト ケースは、サーバー エラーをトリガーし、クライアントのエラー処理をテストします。 deepl-mock を使用してテストを実行するには、テストの実行中に別のターミナルで実行します。モックサーバーを参照して定義されたDEEPL_MOCK_SERVER_PORTおよびDEEPL_SERVER_URL環境変数を使用して、 npm testを使用してテストを実行します。