deepl node
v1.15.0
Bibliothèque client officielle Node.js pour l'API DeepL.
L'API DeepL est une API de traduction linguistique qui permet à d'autres programmes informatiques d'envoyer des textes et des documents aux serveurs de DeepL et de recevoir des traductions de haute qualité. Cela ouvre tout un univers d'opportunités pour les développeurs : tout produit de traduction que vous pouvez imaginer peut désormais être construit sur la meilleure technologie de traduction de DeepL.
La bibliothèque DeepL Node.js offre un moyen pratique pour les applications écrites pour Node.js d'interagir avec l'API DeepL. Nous avons l'intention de prendre en charge toutes les fonctions de l'API avec la bibliothèque, bien que la prise en charge de nouvelles fonctionnalités puisse être ajoutée à la bibliothèque après leur ajout à l'API.
Pour utiliser le package, vous aurez besoin d'une clé d'authentification API. Pour obtenir une clé, veuillez créer un compte ici. Avec un compte DeepL API Free, vous pouvez traduire gratuitement jusqu'à 500 000 caractères/mois.
npm install deepl-node
Le package prend officiellement en charge les versions 12, 14, 16, 17 et 18 de Node.js.
À partir de 2024, nous abandonnerons la prise en charge des anciennes versions de Node qui ont atteint officiellement leur fin de vie. Vous pouvez trouver les versions de Node et les calendriers de support ici. Pour continuer à utiliser cette bibliothèque, vous devez mettre à jour vers Node 18+.
Importez le package et construisez un Translator . Le premier argument est une chaîne contenant votre clé d'authentification API telle que trouvée dans votre compte DeepL Pro.
Faites attention à ne pas exposer votre clé, par exemple lors du partage du code source.
Un exemple utilisant async / await et ES Modules :
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 !
} ) ( ) ;Cet exemple est uniquement destiné à des fins de démonstration. Dans le code de production, la clé d'authentification ne doit pas être codée en dur, mais plutôt extraite d'un fichier de configuration ou d'une variable d'environnement.
Si vous utilisez CommonJS, vous devriez plutôt exiger le package :
const deepl = require ( 'deepl-node' ) ;
const translator = new deepl . Translator ( authKey ) ; Translator accepte les options comme deuxième argument, voir Configuration pour plus d'informations.
Toutes les fonctions Translator renvoient des promesses, et par souci de concision, les exemples de ce fichier utilisent des blocs await et try / catch , mais le chaînage de promesses est également possible :
translator
. translateText ( 'Hello, world!' , null , 'fr' )
. then ( ( result ) => {
console . log ( result . text ) ; // Bonjour, le monde !
} )
. catch ( ( error ) => {
console . error ( error ) ;
} ) ;Le package prend également en charge 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 !
} ) ;
} ) ( ) ; Pour traduire du texte, appelez translateText() . Le premier argument est une chaîne contenant le texte que vous souhaitez traduire, ou un tableau de chaînes si vous souhaitez traduire plusieurs textes.
Les deuxième et troisième arguments sont les codes des langues source et cible. Les codes de langue sont des chaînes insensibles à la casse selon la norme ISO 639-1, par exemple 'de' , 'fr' , 'ja'' . Certaines langues cibles incluent également la variante régionale selon ISO 3166-1, par exemple 'en-US' ou 'pt-BR' . La langue source accepte également null , pour activer la détection automatique de la langue source.
Le dernier argument de translateText() est facultatif et spécifie des options de traduction supplémentaires, voir Options de traduction de texte ci-dessous.
translateText() renvoie une Promise qui se remplit avec un TextResult ou un tableau de TextResult correspondant à votre(vos) texte(s) d'entrée. TextResult a les propriétés suivantes :
text est le texte traduit,detectedSourceLang est le code de langue source détecté,billedCharacters est le nombre de caractères facturés pour le texte.modelTypeUsed indique le modèle de traduction utilisé, mais undefined sauf si l'option modelType est spécifiée. // 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 : spécifiez comment le texte saisi doit être divisé en phrases, par défaut : 'on' .'on' : le texte saisi sera divisé en phrases en utilisant à la fois les sauts de ligne et la ponctuation.'off' : le texte saisi ne sera pas divisé en phrases. Utilisez-le pour les applications où chaque texte saisi ne contient qu'une seule phrase.'nonewlines' : le texte saisi sera divisé en phrases en utilisant la ponctuation mais pas les nouvelles lignes.preserveFormatting : contrôle la correction automatique du formatage. Défini sur true pour empêcher la correction automatique du formatage, par défaut : false .formality : contrôle si les traductions doivent pencher vers un langage informel ou formel. Cette option n'est disponible que pour certaines langues cibles, voir Liste des langues disponibles. Utilisez les options prefer_* pour appliquer la formalité si elle est disponible pour la cible'less' : utilisez un langage informel.'more' : utilisez un langage formel et plus poli.'default' : utilise la formalité par défaut.'prefer_less' : utilise un langage informel si disponible, sinon par défaut.'prefer_more' : utilisez un langage formel et plus poli si disponible, sinon par défaut.glossary : spécifie un glossaire à utiliser avec la traduction, soit sous la forme d'une chaîne contenant l'ID du glossaire, soit sous la forme d'un GlossaryInfo renvoyé par getGlossary() .context : spécifie un contexte supplémentaire pour influencer les traductions, qui n'est pas lui-même traduit. Les caractères du paramètre context ne sont pas pris en compte dans la facturation. Consultez la documentation de l'API pour plus d'informations et des exemples d'utilisation.modelType : spécifie le type de modèle de traduction à utiliser, les options sont :'quality_optimized' : utilisez un modèle de traduction qui maximise la qualité de la traduction, au détriment du temps de réponse. Cette option peut ne pas être disponible pour certaines paires de langues.'prefer_quality_optimized' : utilise le modèle de traduction de la plus haute qualité pour la paire de langues donnée.'latency_optimized' : utilise un modèle de traduction qui minimise le temps de réponse, au détriment de la qualité de la traduction.tagHandling : type de balises à analyser avant la traduction, les options sont 'html' et 'xml' . Les options suivantes ne sont utilisées que si tagHandling vaut 'xml' :
outlineDetection : spécifiez false pour désactiver la détection automatique des balises, la valeur par défaut est true .splittingTags : liste de balises XML qui doivent être utilisées pour diviser le texte en phrases. Les balises peuvent être spécifiées sous la forme d'un tableau de chaînes ( ['tag1', 'tag2'] ) ou d'une liste de chaînes séparées par des virgules ( 'tag1,tag2' ). La valeur par défaut est une liste vide.nonSplittingTags : liste de balises XML qui ne doivent pas être utilisées pour diviser du texte en phrases. Le format et la valeur par défaut sont les mêmes que pour splittingTags .ignoreTags : liste de balises XML contenant du contenu qui ne doit pas être traduit. Le format et la valeur par défaut sont les mêmes que pour splittingTags .extraRequestParameters : paramètres de corps supplémentaires à transmettre avec la requête HTTP. Seules les valeurs de chaîne sont autorisées. Par exemple : {'param': 'value', 'param2': 'value2'} Pour traduire des documents, appelez translateDocument() . Les premier et deuxième arguments sont les fichiers d'entrée et de sortie. Ces arguments acceptent des chaînes contenant des chemins de fichiers, ou des Streams ou FileHandles ouverts en lecture/écriture. Le fichier d'entrée peut également être donné sous forme de tampon contenant les données du fichier. Notez que si le fichier d'entrée n'est pas donné comme chemin de fichier, alors l'option filename est requise.
Les troisième et quatrième arguments sont les codes des langues source et cible, et ils fonctionnent exactement de la même manière que lors de la traduction de texte avec translateText() .
Le dernier argument de translateDocument() est facultatif et spécifie des options de traduction supplémentaires, voir Options de traduction de document ci-dessous.
// 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() encapsule plusieurs appels d'API : téléchargement, interrogation de l'état jusqu'à ce que la traduction soit terminée et téléchargement. Si votre application doit exécuter ces étapes individuellement, vous pouvez utiliser directement les fonctions suivantes :
uploadDocument() ,getDocumentStatus() (ou isDocumentTranslationComplete() ), etdownloadDocument()formality : idem que dans les options de traduction de texte.glossary : idem que dans les options de traduction de texte.filename : si le fichier d'entrée n'est pas fourni comme chemin de fichier, cette option est nécessaire pour spécifier l'extension du fichier.extraRequestParameters : identique à celui des options de traduction de texte.Les glossaires vous permettent de personnaliser vos traductions à l'aide de termes définis. Plusieurs glossaires peuvent être stockés avec votre compte, chacun avec un nom spécifié par l'utilisateur et un identifiant attribué de manière unique.
Vous pouvez créer un glossaire avec les termes et le nom souhaités en utilisant createGlossary() . Chaque glossaire s'applique à une seule paire de langues source-cible. Remarque : les glossaires ne sont pris en charge que pour certaines paires de langues. Consultez la documentation de l'API DeepL pour plus d'informations.
// 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 ) ; Vous pouvez également télécharger un glossaire téléchargé depuis le site Web DeepL à l'aide de createGlossaryWithCsv() . Au lieu de fournir les entrées sous forme de dictionnaire, fournissez le fichier CSV sous forme de chaîne contenant le chemin du fichier, ou sous forme de Stream, Buffer ou FileHandle contenant le contenu du fichier CSV :
const csvFilePath = '/path/to/glossary_file.csv' ;
const glossaryEnToDe = await translator . createGlossaryWithCsv (
'My glossary' ,
'en' ,
'de' ,
csvFilePath ) ;La documentation de l'API explique en détail le format CSV attendu.
Des fonctions permettant d'obtenir, de répertorier et de supprimer les glossaires stockés sont également fournies.
// 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.` ,
) ; Pour utiliser un glossaire lors de la traduction de texte et de documents, incluez l'ID (ou l'objet Glossary renvoyé par listGlossaries() ou createGlossary() ) dans l'appel de fonction. Les langues source et cible doivent correspondre au glossaire.
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.' Pour vérifier l'utilisation du compte, utilisez la fonction getUsage() .
L'objet Usage renvoyé contient jusqu'à trois sous-types d'utilisation, en fonction de votre type de compte : character , document et teamDocument . Pour les comptes API, character sera défini, les autres undefined .
Chaque sous-type d'utilisation (s'il est défini) a des propriétés count et limit donnant respectivement la quantité utilisée et la quantité maximale, ainsi que la fonction limitReached() qui vérifie si l'utilisation a atteint la limite. L'objet Usage de niveau supérieur possède la fonction anyLimitReached() pour vérifier tous les sous-types d'utilisation.
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 } ` ) ;
} Vous pouvez demander la liste des langues prises en charge par DeepL Translator pour le texte et les documents à l'aide des fonctions getSourceLanguages() et getTargetLanguages() . Ils renvoient tous deux un tableau d’objets Language .
La propriété name donne le nom de la langue en anglais et la propriété code donne le code de la langue. La propriété supportsFormality apparaît uniquement pour les langues cibles et est une Boolean indiquant si la langue cible prend en charge le paramètre formality facultatif.
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'
}
} Les glossaires sont pris en charge pour un sous-ensemble de paires de langues. Pour récupérer ces langues, utilisez la fonction getGlossaryLanguagePairs() , qui renvoie un tableau d'objets GlossaryLanguagePair . Chacun possède des propriétés sourceLang et targetLang indiquant que cette paire de codes de langue est prise en charge pour les glossaires.
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.
} Si vous utilisez cette bibliothèque dans une application, veuillez identifier l'application avec le champ appInfo dans TranslatorOptions , qui prend le nom et la version de l'application :
const options = { appInfo : { appName : 'sampleNodeTranslationApp' , appVersion : '1.2.3' } , } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;Ces informations sont transmises lorsque la bibliothèque appelle l'API DeepL. Le nom et la version sont requis.
Le constructeur Translator accepte les options de configuration comme deuxième argument, par exemple :
const options = { maxRetries : 5 , minTimeout : 10000 } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;Les options disponibles sont :
maxRetries : le Number maximum de requêtes HTTP ayant échoué à réessayer, par appel de fonction. Par défaut, 5 tentatives sont effectuées. Voir Demander de nouvelles tentatives.minTimeout : le Number de millisecondes utilisées comme délai d'expiration de connexion pour chaque nouvelle tentative de requête HTTP. La valeur par défaut est 10 000 (10 secondes).serverUrl : string contenant l'URL de l'API DeepL, peut être surchargée par exemple à des fins de tests. Par défaut, l'URL est sélectionnée en fonction du type de compte utilisateur (gratuit ou payant).headers : en-têtes HTTP supplémentaires attachés à chaque requête HTTP. Par défaut, aucun en-tête supplémentaire n'est utilisé. Notez que les en-têtes Authorization et User-Agent sont ajoutés automatiquement mais peuvent être remplacés par cette option.proxy : définissez le nom d'hôte et le port du serveur proxy, et éventuellement le protocole et l'autorisation (en tant qu'objet d'authentification avec les champs nom d'utilisateur et mot de passe). deepl-node enregistre les messages de débogage et d'information pour chaque requête et réponse HTTP à l'aide du module loglevel , dans l'enregistreur 'deepl' . Vous pouvez reconfigurer le niveau de journalisation comme suit :
import log from 'loglevel' ;
log . getLogger ( 'deepl' ) . setLevel ( 'debug' ) ; // Or 'info' Le package loglevel prend également en charge les plugins, voir la documentation.
Vous pouvez configurer un proxy en spécifiant l'argument proxy lors de la construction d'un deepl.Translator :
const options = { proxy : { host : 'localhost' , port : 3000 } } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ; L'argument proxy est transmis à la requête axios sous-jacente, voir la documentation d'axios.
Par défaut, nous envoyons des informations de base sur la plate-forme sur laquelle la bibliothèque cliente s'exécute avec chaque requête, voir ici pour une explication. Ces données sont totalement anonymes et utilisées uniquement pour améliorer notre produit, et non pour suivre des utilisateurs individuels. Si vous ne souhaitez pas envoyer ces données, vous pouvez vous désinscrire lors de la création de votre objet Translator en définissant l'indicateur sendPlatformInfo dans TranslatorOptions sur false comme ceci :
const options = { sendPlatformInfo : false } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ; Les requêtes adressées à l'API DeepL qui échouent en raison de conditions transitoires (par exemple, des délais d'attente du réseau ou une charge élevée du serveur) seront réessayées. Le nombre maximum de tentatives peut être configuré lors de la construction de l'objet Translator à l'aide de l'option maxRetries . Le délai d'attente pour chaque tentative de demande peut être contrôlé à l'aide de l'option minTimeout . Une stratégie d'attente exponentielle est utilisée, de sorte que les demandes qui échouent plusieurs fois entraîneront des retards.
Si vous rencontrez des problèmes lors de l'utilisation de la bibliothèque ou si vous souhaitez demander une nouvelle fonctionnalité, veuillez ouvrir un ticket.
Nous accueillons les Pull Requests, veuillez lire les directives de contribution.
Exécutez les tests en utilisant npm test . Les tests communiquent avec l'API DeepL à l'aide de la clé d'authentification définie par la variable d'environnement DEEPL_AUTH_KEY .
Sachez que les tests effectuent des requêtes API DeepL qui contribuent à votre utilisation de l'API.
La suite de tests peut plutôt être configurée pour communiquer avec le serveur fictif fourni par deepl-mock. Bien que la plupart des cas de test fonctionnent pour l'un ou l'autre, certains cas de test ne fonctionnent qu'avec l'API DeepL ou le serveur fictif et seront sinon ignorés. Les cas de test qui nécessitent le serveur fictif déclenchent des erreurs de serveur et testent la gestion des erreurs du client. Pour exécuter les tests à l'aide de deepl-mock, exécutez-le dans un autre terminal lors de l'exécution des tests. Exécutez les tests à l'aide npm test avec les variables d'environnement DEEPL_MOCK_SERVER_PORT et DEEPL_SERVER_URL définies en référence au serveur fictif.
