deepl node
v1.15.0
Offizielle Node.js-Clientbibliothek für die DeepL-API.
Die DeepL API ist eine Sprachübersetzungs-API, die es anderen Computerprogrammen ermöglicht, Texte und Dokumente an die Server von DeepL zu senden und hochwertige Übersetzungen zu empfangen. Dies eröffnet Entwicklern ein ganzes Universum an Möglichkeiten: Jedes Übersetzungsprodukt, das Sie sich vorstellen können, kann jetzt auf der erstklassigen Übersetzungstechnologie von DeepL basieren.
Die DeepL Node.js-Bibliothek bietet eine praktische Möglichkeit für für Node.js geschriebene Anwendungen, mit der DeepL-API zu interagieren. Wir beabsichtigen, alle API-Funktionen mit der Bibliothek zu unterstützen, allerdings kann die Unterstützung für neue Funktionen zur Bibliothek hinzugefügt werden, nachdem sie der API hinzugefügt wurden.
Um das Paket nutzen zu können, benötigen Sie einen API-Authentifizierungsschlüssel. Um einen Schlüssel zu erhalten, erstellen Sie bitte hier ein Konto. Mit einem DeepL API Free-Konto können Sie bis zu 500.000 Zeichen/Monat kostenlos übersetzen.
npm install deepl-node
Das Paket unterstützt offiziell Node.js Version 12, 14, 16, 17 und 18.
Ab 2024 werden wir den Support für ältere Node-Versionen einstellen, die das offizielle Ende ihrer Lebensdauer erreicht haben. Die Node-Versionen und Support-Zeitpläne finden Sie hier. Um diese Bibliothek weiterhin nutzen zu können, sollten Sie auf Node 18+ aktualisieren.
Importieren Sie das Paket und erstellen Sie einen Translator . Das erste Argument ist eine Zeichenfolge, die Ihren API-Authentifizierungsschlüssel enthält, wie er in Ihrem DeepL Pro-Konto zu finden ist.
Achten Sie darauf, Ihren Schlüssel nicht offenzulegen, beispielsweise wenn Sie Quellcode teilen.
Ein Beispiel mit async / await und ES-Modulen:
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 !
} ) ( ) ;Dieses Beispiel dient nur zu Demonstrationszwecken. Im Produktionscode sollte der Authentifizierungsschlüssel nicht fest codiert sein, sondern aus einer Konfigurationsdatei oder Umgebungsvariablen abgerufen werden.
Wenn Sie CommonJS verwenden, sollten Sie stattdessen das Paket benötigen:
const deepl = require ( 'deepl-node' ) ;
const translator = new deepl . Translator ( authKey ) ; Translator akzeptiert Optionen als zweites Argument. Weitere Informationen finden Sie unter Konfiguration.
Alle Translator geben Versprechen zurück, und der Kürze halber verwenden die Beispiele in dieser Datei die Blöcke await und try / catch . Eine Versprechensverkettung ist jedoch auch möglich:
translator
. translateText ( 'Hello, world!' , null , 'fr' )
. then ( ( result ) => {
console . log ( result . text ) ; // Bonjour, le monde !
} )
. catch ( ( error ) => {
console . error ( error ) ;
} ) ;Das Paket unterstützt auch 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 !
} ) ;
} ) ( ) ; Um Text zu übersetzen, rufen Sie translateText() auf. Das erste Argument ist eine Zeichenfolge, die den Text enthält, den Sie übersetzen möchten, oder ein Array von Zeichenfolgen, wenn Sie mehrere Texte übersetzen möchten.
Das zweite und dritte Argument sind die Quell- und Zielsprachencodes. Sprachcodes sind gemäß ISO 639-1 Zeichenfolgen ohne Berücksichtigung der Groß-/Kleinschreibung , zum Beispiel 'de' , 'fr' , 'ja'' . Einige Zielsprachen umfassen auch die regionale Variante nach ISO 3166-1, zum Beispiel 'en-US' oder 'pt-BR' . Die Quellsprache akzeptiert auch null , um die automatische Erkennung der Quellsprache zu ermöglichen.
Das letzte Argument von translateText() ist optional und gibt zusätzliche Übersetzungsoptionen an, siehe Textübersetzungsoptionen unten.
translateText() gibt ein Promise zurück, das mit einem TextResult oder einem Array von TextResult s erfüllt wird, die Ihren Eingabetexten entsprechen. TextResult hat die folgenden Eigenschaften:
text ist der übersetzte Text,detectedSourceLang ist der erkannte Quellsprachencode,billedCharacters ist die Anzahl der für den Text in Rechnung gestellten Zeichen.modelTypeUsed gibt das verwendete Übersetzungsmodell an, ist jedoch undefined , sofern nicht die Option modelType angegeben ist. // 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 : Geben Sie an, wie Eingabetext in Sätze aufgeteilt werden soll, Standard: 'on' .'on' : Der Eingabetext wird unter Verwendung von Zeilenumbrüchen und Satzzeichen in Sätze aufgeteilt.'off' : Eingabetext wird nicht in Sätze aufgeteilt. Verwenden Sie dies für Anwendungen, bei denen jeder Eingabetext nur einen Satz enthält.'nonewlines' : Der eingegebene Text wird mit Satzzeichen, aber ohne Zeilenumbrüche in Sätze aufgeteilt.preserveFormatting : Steuert die automatische Formatierungskorrektur. Auf true setzen, um eine automatische Formatierungskorrektur zu verhindern, Standard: false .formality : steuert, ob Übersetzungen eher informelle oder formelle Sprache bevorzugen sollen. Diese Option ist nur für einige Zielsprachen verfügbar, siehe Verfügbare Sprachen auflisten. Verwenden Sie die Optionen prefer_* , um die Formalität anzuwenden, wenn sie für das Ziel verfügbar ist'less' : informelle Sprache verwenden.'more' : formelle, höflichere Sprache verwenden.'default' : Standardformalität verwenden.'prefer_less' : informelle Sprache verwenden, falls verfügbar, andernfalls Standard.'prefer_more' : Verwenden Sie eine formelle, höflichere Sprache, falls verfügbar, andernfalls Standard.glossary : Gibt ein Glossar an, das bei der Übersetzung verwendet werden soll, entweder als String, der die Glossar-ID enthält, oder GlossaryInfo wie von getGlossary() zurückgegeben.context : Gibt zusätzlichen Kontext zur Beeinflussung von Übersetzungen an, der selbst nicht übersetzt wird. Zeichen im context werden nicht zur Abrechnung gezählt. Weitere Informationen und Anwendungsbeispiele finden Sie in der API-Dokumentation.modelType : Gibt den Typ des zu verwendenden Übersetzungsmodells an. Die Optionen sind:'quality_optimized' : Verwenden Sie ein Übersetzungsmodell, das die Übersetzungsqualität auf Kosten der Reaktionszeit maximiert. Diese Option ist für einige Sprachpaare möglicherweise nicht verfügbar.'prefer_quality_optimized' : Verwenden Sie das Übersetzungsmodell mit der höchsten Qualität für das angegebene Sprachpaar.'latency_optimized' : Verwenden Sie ein Übersetzungsmodell, das die Antwortzeit auf Kosten der Übersetzungsqualität minimiert.tagHandling : Typ der Tags, die vor der Übersetzung analysiert werden sollen. Optionen sind 'html' und 'xml' . Die folgenden Optionen werden nur verwendet, wenn tagHandling 'xml' ist:
outlineDetection : Geben Sie false an, um die automatische Tag-Erkennung zu deaktivieren. Der Standardwert ist true “.splittingTags : Liste der XML-Tags, die zum Aufteilen von Text in Sätze verwendet werden sollen. Tags können als Array von Zeichenfolgen ( ['tag1', 'tag2'] ) oder als durch Kommas getrennte Liste von Zeichenfolgen ( 'tag1,tag2' ) angegeben werden. Der Standardwert ist eine leere Liste.nonSplittingTags : Liste von XML-Tags, die nicht zum Aufteilen von Text in Sätze verwendet werden sollten. Format und Standard sind die gleichen wie für splittingTags .ignoreTags : Liste von XML-Tags, die Inhalte enthalten, die nicht übersetzt werden sollen. Format und Standard sind die gleichen wie für splittingTags .extraRequestParameters : Zusätzliche Body-Parameter, die zusammen mit der HTTP-Anfrage übergeben werden sollen. Es sind nur Zeichenfolgewerte zulässig. Zum Beispiel: {'param': 'value', 'param2': 'value2'} Um Dokumente zu übersetzen, rufen Sie translateDocument() auf. Das erste und zweite Argument sind die Eingabe- und Ausgabedateien. Diese Argumente akzeptieren Zeichenfolgen, die Dateipfade oder zum Lesen/Schreiben geöffnete Streams oder FileHandles enthalten. Die Eingabedatei kann auch als Puffer mit den Dateidaten angegeben werden. Beachten Sie, dass die Option filename erforderlich ist, wenn die Eingabedatei nicht als Dateipfad angegeben wird.
Das dritte und vierte Argument sind die Quell- und Zielsprachencodes und funktionieren genauso wie beim Übersetzen von Text mit translateText() .
Das letzte Argument für translateDocument() ist optional und gibt zusätzliche Übersetzungsoptionen an, siehe Dokumentübersetzungsoptionen unten.
// 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() umschließt mehrere API-Aufrufe: Hochladen, Abfragen des Status bis zum Abschluss der Übersetzung und Herunterladen. Wenn Ihre Anwendung diese Schritte einzeln ausführen muss, können Sie stattdessen direkt die folgenden Funktionen verwenden:
uploadDocument() ,getDocumentStatus() (oder isDocumentTranslationComplete() ) unddownloadDocument()formality : das Gleiche wie bei den Textübersetzungsoptionen.glossary : dasselbe wie in den Textübersetzungsoptionen.filename : Wenn die Eingabedatei nicht als Dateipfad angegeben ist, ist diese Option erforderlich, um die Dateierweiterung anzugeben.extraRequestParameters : dasselbe wie in den Textübersetzungsoptionen.Mit Glossaren können Sie Ihre Übersetzungen anhand definierter Begriffe anpassen. In Ihrem Konto können mehrere Glossare gespeichert werden, jedes mit einem vom Benutzer angegebenen Namen und einer eindeutig zugewiesenen ID.
Mit createGlossary() können Sie ein Glossar mit Ihren gewünschten Begriffen und Namen erstellen. Jedes Glossar bezieht sich auf ein einzelnes Quell-Zielsprachenpaar. Hinweis: Glossare werden nur für einige Sprachpaare unterstützt. Weitere Informationen finden Sie in der DeepL-API-Dokumentation.
// 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 ) ; Sie können mit createGlossaryWithCsv() auch ein von der DeepL-Website heruntergeladenes Glossar hochladen. Anstatt die Einträge als Wörterbuch bereitzustellen, stellen Sie die CSV-Datei als Zeichenfolge mit dem Dateipfad oder als Stream, Buffer oder FileHandle mit dem Inhalt der CSV-Datei bereit:
const csvFilePath = '/path/to/glossary_file.csv' ;
const glossaryEnToDe = await translator . createGlossaryWithCsv (
'My glossary' ,
'en' ,
'de' ,
csvFilePath ) ;In der API-Dokumentation wird das erwartete CSV-Format ausführlich erläutert.
Außerdem stehen Funktionen zum Abrufen, Auflisten und Löschen gespeicherter Glossare zur Verfügung.
// 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.` ,
) ; Um beim Übersetzen von Texten und Dokumenten ein Glossar zu verwenden, schließen Sie die ID (oder das von listGlossaries() oder createGlossary() zurückgegebene Glossary ) in den Funktionsaufruf ein. Die Ausgangs- und Zielsprache müssen mit dem Glossar übereinstimmen.
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.' Um die Kontonutzung zu überprüfen, verwenden Sie die Funktion getUsage() .
Das zurückgegebene Usage -Objekt enthält je nach Kontotyp bis zu drei Nutzungsuntertypen: character , document und teamDocument . Für API-Konten wird character definiert, die anderen undefined .
Jeder Nutzungsuntertyp (falls definiert) verfügt über die Eigenschaften count und limit die die verwendete Menge bzw. die maximale Menge angeben, sowie über die Funktion limitReached() , die prüft, ob die Nutzung das Limit erreicht hat. Das Usage Objekt der obersten Ebene verfügt über die Funktion anyLimitReached() um alle Verwendungsuntertypen zu überprüfen.
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 } ` ) ;
} Mit den Funktionen getSourceLanguages() und getTargetLanguages() können Sie die Liste der vom DeepL Translator unterstützten Sprachen für Texte und Dokumente anfordern. Beide geben ein Array von Language zurück.
Die name -Eigenschaft gibt den Namen der Sprache in Englisch an und die code Eigenschaft gibt den Sprachcode an. Die Eigenschaft supportsFormality wird nur für Zielsprachen angezeigt und ist ein Boolean , der angibt, ob die Zielsprache den optionalen formality unterstützt.
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'
}
} Glossare werden für eine Teilmenge von Sprachpaaren unterstützt. Um diese Sprachen abzurufen, verwenden Sie die Funktion getGlossaryLanguagePairs() , die ein Array von GlossaryLanguagePair Objekten zurückgibt. Jedes verfügt über die Eigenschaften sourceLang und targetLang die angeben, dass dieses Sprachcodepaar für Glossare unterstützt wird.
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.
} Wenn Sie diese Bibliothek in einer Anwendung verwenden, identifizieren Sie die Anwendung bitte mit dem appInfo Feld in TranslatorOptions , das den Namen und die Version der App annimmt:
const options = { appInfo : { appName : 'sampleNodeTranslationApp' , appVersion : '1.2.3' } , } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;Diese Informationen werden weitergegeben, wenn die Bibliothek Aufrufe an die DeepL-API durchführt. Sowohl Name als auch Version sind erforderlich.
Der Translator Konstruktor akzeptiert Konfigurationsoptionen als zweites Argument, zum Beispiel:
const options = { maxRetries : 5 , minTimeout : 10000 } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;Die verfügbaren Optionen sind:
maxRetries : die maximale Number fehlgeschlagener HTTP-Anfragen, die pro Funktionsaufruf wiederholt werden sollen. Standardmäßig werden 5 Wiederholungsversuche durchgeführt. Siehe Wiederholungsversuche anfordern.minTimeout : Die Number der Millisekunden, die als Verbindungszeitlimit für jeden Wiederholungsversuch einer HTTP-Anforderung verwendet werden. Der Standardwert ist 10000 (10 Sekunden).serverUrl : string , der die URL der DeepL-API enthält, kann beispielsweise zu Testzwecken überschrieben werden. Standardmäßig wird die URL basierend auf dem Benutzerkontotyp (kostenlos oder kostenpflichtig) ausgewählt.headers : Zusätzliche HTTP-Header, die an jede HTTP-Anfrage angehängt werden. Standardmäßig werden keine zusätzlichen Header verwendet. Beachten Sie, dass Autorisierungs- und User-Agent-Header automatisch hinzugefügt werden, aber durch diese Option möglicherweise überschrieben werden.proxy : Definieren Sie den Hostnamen und den Port des Proxyservers sowie optional das Protokoll und die Autorisierung (als Authentifizierungsobjekt mit Benutzernamen- und Passwortfeldern). deepl-node protokolliert Debug- und Infomeldungen für jede HTTP-Anfrage und -Antwort mithilfe des loglevel Moduls im 'deepl' -Logger. Sie können die Protokollebene wie folgt neu konfigurieren:
import log from 'loglevel' ;
log . getLogger ( 'deepl' ) . setLevel ( 'debug' ) ; // Or 'info' Das loglevel Paket unterstützt auch Plugins, siehe Dokumentation.
Sie können einen Proxy konfigurieren, indem Sie beim Erstellen eines deepl.Translator das proxy Argument angeben:
const options = { proxy : { host : 'localhost' , port : 3000 } } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ; Das Proxy-Argument wird an die zugrunde liegende axios -Anfrage übergeben, siehe Dokumentation für Axios.
Standardmäßig senden wir bei jeder Anfrage einige grundlegende Informationen über die Plattform, auf der die Clientbibliothek ausgeführt wird. Eine Erklärung finden Sie hier. Diese Daten sind völlig anonym und werden nur zur Verbesserung unseres Produkts verwendet, nicht zur Verfolgung einzelner Benutzer. Wenn Sie diese Daten nicht senden möchten, können Sie sich beim Erstellen Ihres Translator Objekts abmelden, indem Sie das Flag sendPlatformInfo in den TranslatorOptions wie folgt auf false setzen:
const options = { sendPlatformInfo : false } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ; Anfragen an die DeepL-API, die aufgrund vorübergehender Bedingungen (z. B. Netzwerk-Timeouts oder hohe Serverlast) fehlschlagen, werden erneut versucht. Die maximale Anzahl von Wiederholungen kann beim Erstellen des Translator Objekts mithilfe der Option maxRetries konfiguriert werden. Das Timeout für jeden Anforderungsversuch kann mit der Option minTimeout gesteuert werden. Es wird eine exponentielle Backoff-Strategie verwendet, sodass es bei Anfragen, die mehrmals fehlschlagen, zu Verzögerungen kommt.
Wenn Sie Probleme bei der Nutzung der Bibliothek haben oder eine neue Funktion anfordern möchten, öffnen Sie bitte ein Problem.
Wir freuen uns über Pull-Anfragen. Bitte lesen Sie die Beitragsrichtlinien.
Führen Sie die Tests mit npm test aus. Die Tests kommunizieren mit der DeepL-API über den Authentifizierungsschlüssel, der durch die Umgebungsvariable DEEPL_AUTH_KEY definiert ist.
Beachten Sie, dass die Tests DeepL-API-Anfragen stellen, die zu Ihrer API-Nutzung beitragen.
Die Testsuite kann stattdessen so konfiguriert werden, dass sie mit dem von deepl-mock bereitgestellten Mock-Server kommuniziert. Obwohl die meisten Testfälle für beides funktionieren, funktionieren einige Testfälle nur mit der DeepL-API oder dem Mock-Server und werden andernfalls übersprungen. Die Testfälle, die den Mock-Server erfordern, lösen Serverfehler aus und testen die Fehlerbehandlung des Clients. Um die Tests mit deepl-mock auszuführen, führen Sie es in einem anderen Terminal aus, während Sie die Tests ausführen. Führen Sie die Tests mit npm test aus, wobei die Umgebungsvariablen DEEPL_MOCK_SERVER_PORT und DEEPL_SERVER_URL in Bezug auf den Mock-Server definiert sind.
