deepl node
v1.15.0
Biblioteca cliente oficial de Node.js para la API DeepL.
La API de DeepL es una API de traducción de idiomas que permite a otros programas informáticos enviar textos y documentos a los servidores de DeepL y recibir traducciones de alta calidad. Esto abre todo un universo de oportunidades para los desarrolladores: cualquier producto de traducción que pueda imaginar ahora puede crearse sobre la mejor tecnología de traducción de DeepL.
La biblioteca DeepL Node.js ofrece una forma conveniente para que las aplicaciones escritas para Node.js interactúen con la API de DeepL. Tenemos la intención de admitir todas las funciones de la API con la biblioteca, aunque se puede agregar compatibilidad con nuevas funciones a la biblioteca después de que se agreguen a la API.
Para utilizar el paquete, necesitará una clave de autenticación API. Para obtener una clave, cree una cuenta aquí. Con una cuenta DeepL API Free puedes traducir hasta 500.000 caracteres al mes de forma gratuita.
npm install deepl-node
El paquete es oficialmente compatible con las versiones 12, 14, 16, 17 y 18 de Node.js.
A partir de 2024, dejaremos de admitir versiones anteriores de Node que hayan llegado al final oficial de su vida útil. Puede encontrar las versiones de Node y los cronogramas de soporte aquí. Para continuar usando esta biblioteca, debe actualizar al Nodo 18+.
Importe el paquete y construya un Translator . El primer argumento es una cadena que contiene su clave de autenticación API tal como se encuentra en su cuenta DeepL Pro.
Tenga cuidado de no exponer su clave, por ejemplo, al compartir el código fuente.
Un ejemplo que utiliza módulos async / await y 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 !
} ) ( ) ;Este ejemplo es sólo para fines de demostración. En el código de producción, la clave de autenticación no debe estar codificada, sino que debe obtenerse de un archivo de configuración o de una variable de entorno.
Si está utilizando CommonJS, debería requerir el paquete:
const deepl = require ( 'deepl-node' ) ;
const translator = new deepl . Translator ( authKey ) ; Translator acepta opciones como segundo argumento; consulte Configuración para obtener más información.
Todas las funciones Translator devuelven promesas y, para abreviar, los ejemplos de este archivo utilizan los bloques await y try / catch ; sin embargo, el encadenamiento de promesas también es posible:
translator
. translateText ( 'Hello, world!' , null , 'fr' )
. then ( ( result ) => {
console . log ( result . text ) ; // Bonjour, le monde !
} )
. catch ( ( error ) => {
console . error ( error ) ;
} ) ;El paquete también admite 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 !
} ) ;
} ) ( ) ; Para traducir texto, llame translateText() . El primer argumento es una cadena que contiene el texto que desea traducir, o una serie de cadenas si desea traducir varios textos.
El segundo y tercer argumento son los códigos del idioma de origen y de destino. Los códigos de idioma son cadenas que no distinguen entre mayúsculas y minúsculas según ISO 639-1, por ejemplo 'de' , 'fr' , 'ja'' . Algunos idiomas de destino también incluyen la variante regional según ISO 3166-1, por ejemplo 'en-US' o 'pt-BR' . El idioma de origen también acepta null para permitir la detección automática del idioma de origen.
El último argumento para translateText() es opcional y especifica opciones de traducción adicionales; consulte Opciones de traducción de texto a continuación.
translateText() devuelve una Promesa que se cumple con un TextResult o una matriz de TextResult correspondientes a los textos de entrada. TextResult tiene las siguientes propiedades:
text es el texto traducido,detectedSourceLang es el código del idioma fuente detectado,billedCharacters es el número de caracteres facturados por el texto.modelTypeUsed indica el modelo de traducción utilizado, pero no está undefined a menos que se especifique la opción modelType . // 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 : especifica cómo se debe dividir el texto de entrada en oraciones, predeterminado: 'on' .'on' : el texto ingresado se dividirá en oraciones usando nuevas líneas y puntuación.'off' : el texto ingresado no se dividirá en oraciones. Úselo para aplicaciones donde cada texto de entrada contiene solo una oración.'nonewlines' : el texto ingresado se dividirá en oraciones usando puntuación pero no nuevas líneas.preserveFormatting : controla la corrección automática de formato. Establezca en true para evitar la corrección automática del formato; valor predeterminado: false .formality : controla si las traducciones deben inclinarse hacia un lenguaje informal o formal. Esta opción solo está disponible para algunos idiomas de destino; consulte Listado de idiomas disponibles. Utilice las opciones prefer_* para aplicar la formalidad si está disponible para el objetivo'less' : utiliza lenguaje informal.'more' : utilice un lenguaje formal y más educado.'default' : utiliza la formalidad predeterminada.'prefer_less' : utilice un lenguaje informal si está disponible; de lo contrario, será el predeterminado.'prefer_more' : utilice un lenguaje formal y más educado si está disponible; de lo contrario, será el predeterminado.glossary : especifica un glosario para usar con la traducción, ya sea como una cadena que contiene el ID del glosario o como un GlossaryInfo devuelto por getGlossary() .context : especifica contexto adicional para influir en las traducciones, que no se traduce en sí. Los caracteres en el parámetro context no se cuentan para la facturación. Consulte la documentación de la API para obtener más información y ejemplos de uso.modelType : especifica el tipo de modelo de traducción a utilizar, las opciones son:'quality_optimized' : utilice un modelo de traducción que maximice la calidad de la traducción, a costa del tiempo de respuesta. Es posible que esta opción no esté disponible para algunos pares de idiomas.'prefer_quality_optimized' : utiliza el modelo de traducción de mayor calidad para el par de idiomas determinado.'latency_optimized' : utiliza un modelo de traducción que minimiza el tiempo de respuesta, a costa de la calidad de la traducción.tagHandling : tipo de etiquetas para analizar antes de la traducción, las opciones son 'html' y 'xml' . Las siguientes opciones sólo se utilizan si tagHandling es 'xml' :
outlineDetection : especifique false para deshabilitar la detección automática de etiquetas, el valor predeterminado es true .splittingTags : lista de etiquetas XML que deben usarse para dividir texto en oraciones. Las etiquetas se pueden especificar como una matriz de cadenas ( ['tag1', 'tag2'] ) o una lista de cadenas separadas por comas ( 'tag1,tag2' ). El valor predeterminado es una lista vacía.nonSplittingTags : lista de etiquetas XML que no deben usarse para dividir texto en oraciones. El formato y el valor predeterminado son los mismos que para splittingTags .ignoreTags : lista de etiquetas XML que contienen contenido que no debe traducirse. El formato y el valor predeterminado son los mismos que para splittingTags .extraRequestParameters : parámetros de cuerpo adicionales que se pasarán junto con la solicitud HTTP. Sólo se permiten valores de cadena. Por ejemplo: {'param': 'value', 'param2': 'value2'} Para traducir documentos, llame translateDocument() . El primer y segundo argumento son los archivos de entrada y salida. Estos argumentos aceptan cadenas que contienen rutas de archivos, o Streams o FileHandles abiertos para lectura/escritura. El archivo de entrada también se puede proporcionar como un búfer que contiene los datos del archivo. Tenga en cuenta que si el archivo de entrada no se proporciona como ruta de archivo, entonces se requiere la opción de filename .
Los argumentos tercero y cuarto son los códigos del idioma de origen y de destino, y funcionan exactamente igual que cuando se traduce texto con translateText() .
El último argumento para translateDocument() es opcional y especifica opciones de traducción adicionales; consulte Opciones de traducción de documentos a continuación.
// 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() envuelve múltiples llamadas API: carga, estado de sondeo hasta que se completa la traducción y descarga. Si su aplicación necesita ejecutar estos pasos individualmente, puede utilizar las siguientes funciones directamente:
uploadDocument() ,getDocumentStatus() (o isDocumentTranslationComplete() ), ydownloadDocument()formality : igual que en las opciones de traducción de texto.glossary : igual que en las opciones de traducción de texto.filename : si el archivo de entrada no se proporciona como ruta de archivo, esta opción es necesaria para especificar la extensión del archivo.extraRequestParameters : igual que en las opciones de traducción de texto.Los glosarios le permiten personalizar sus traducciones utilizando términos definidos. Se pueden almacenar varios glosarios con su cuenta, cada uno con un nombre especificado por el usuario y una identificación asignada de forma única.
Puede crear un glosario con los términos y nombres que desee utilizando createGlossary() . Cada glosario se aplica a un único par de idiomas de origen y de destino. Nota: los glosarios solo son compatibles con algunos pares de idiomas; consulte la documentación de la API de DeepL para obtener más información.
// 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 ) ; También puede cargar un glosario descargado del sitio web de DeepL usando createGlossaryWithCsv() . En lugar de proporcionar las entradas como un diccionario, proporcione el archivo CSV como una cadena que contenga la ruta del archivo, o un Stream, Buffer o FileHandle que contenga el contenido del archivo CSV:
const csvFilePath = '/path/to/glossary_file.csv' ;
const glossaryEnToDe = await translator . createGlossaryWithCsv (
'My glossary' ,
'en' ,
'de' ,
csvFilePath ) ;La documentación de la API explica en detalle el formato CSV esperado.
También se proporcionan funciones para obtener, enumerar y eliminar glosarios almacenados.
// 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.` ,
) ; Para utilizar un glosario al traducir texto y documentos, incluya el ID (u objeto Glossary devuelto por listGlossaries() o createGlossary() ) en la llamada a la función. Los idiomas de origen y de destino deben coincidir con el glosario.
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.' Para verificar el uso de la cuenta, use la función getUsage() .
El objeto Usage devuelto contiene hasta tres subtipos de uso, según su tipo de cuenta: character , document y teamDocument . Para las cuentas API, character estará definido, las demás undefined .
Cada subtipo de uso (si está definido) tiene propiedades count y limit que indican la cantidad utilizada y la cantidad máxima respectivamente, y la función limitReached() que comprueba si el uso ha alcanzado el límite. El objeto Usage de nivel superior tiene la función anyLimitReached() para verificar todos los subtipos de uso.
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 } ` ) ;
} Puede solicitar la lista de idiomas admitidos por DeepL Translator para texto y documentos utilizando las funciones getSourceLanguages() y getTargetLanguages() . Ambos devuelven una serie de objetos Language .
La propiedad name proporciona el nombre del idioma en inglés y la propiedad code proporciona el código de idioma. La propiedad supportsFormality solo aparece para los idiomas de destino y es un Boolean que indica si el idioma de destino admite el parámetro formality opcional.
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'
}
} Se admiten glosarios para un subconjunto de pares de idiomas. Para recuperar esos idiomas, utilice la función getGlossaryLanguagePairs() , que devuelve una matriz de objetos GlossaryLanguagePair . Cada uno tiene propiedades sourceLang y targetLang que indican que ese par de códigos de idioma es compatible con los glosarios.
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 utiliza esta biblioteca en una aplicación, identifique la aplicación con el campo appInfo en TranslatorOptions , que toma el nombre y la versión de la aplicación:
const options = { appInfo : { appName : 'sampleNodeTranslationApp' , appVersion : '1.2.3' } , } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;Esta información se transmite cuando la biblioteca realiza llamadas a la API de DeepL. Se requieren tanto el nombre como la versión.
El constructor Translator acepta opciones de configuración como segundo argumento, por ejemplo:
const options = { maxRetries : 5 , minTimeout : 10000 } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;Las opciones disponibles son:
maxRetries : el Number máximo de solicitudes HTTP fallidas para reintentar, por llamada de función. De forma predeterminada, se realizan 5 reintentos. Consulte Solicitar reintentos.minTimeout : el Number de milisegundos utilizados como tiempo de espera de conexión para cada reintento de solicitud HTTP. El valor predeterminado es 10000 (10 segundos).serverUrl : string que contiene la URL de la API de DeepL; se puede anular, por ejemplo, con fines de prueba. De forma predeterminada, la URL se selecciona según el tipo de cuenta de usuario (gratuita o de pago).headers : encabezados HTTP adicionales adjuntos a cada solicitud HTTP. De forma predeterminada, no se utilizan encabezados adicionales. Tenga en cuenta que los encabezados Autorización y Agente de usuario se agregan automáticamente, pero esta opción puede anularlos.proxy : define el nombre de host y el puerto del servidor proxy y, opcionalmente, el protocolo y la autorización (como un objeto de autenticación con campos de nombre de usuario y contraseña). deepl-node registra mensajes de información y depuración para cada solicitud y respuesta HTTP utilizando el módulo loglevel , en el registrador 'deepl' . Puede reconfigurar el nivel de registro de la siguiente manera:
import log from 'loglevel' ;
log . getLogger ( 'deepl' ) . setLevel ( 'debug' ) ; // Or 'info' El paquete loglevel también admite complementos; consulte la documentación.
Puede configurar un proxy especificando el argumento proxy al construir un deepl.Translator :
const options = { proxy : { host : 'localhost' , port : 3000 } } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ; El argumento del proxy se pasa a la solicitud axios subyacente; consulte la documentación de axios.
De forma predeterminada, enviamos información básica sobre la plataforma en la que se ejecuta la biblioteca cliente con cada solicitud; consulte aquí para obtener una explicación. Estos datos son completamente anónimos y solo se utilizan para mejorar nuestro producto, no para rastrear a ningún usuario individual. Si no desea enviar estos datos, puede optar por no participar al crear su objeto Translator configurando el indicador sendPlatformInfo en TranslatorOptions en false de esta manera:
const options = { sendPlatformInfo : false } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ; Se volverán a intentar las solicitudes a la API de DeepL que fallen debido a condiciones transitorias (por ejemplo, tiempos de espera de red o alta carga del servidor). El número máximo de reintentos se puede configurar al construir el objeto Translator usando la opción maxRetries . El tiempo de espera para cada intento de solicitud se puede controlar mediante la opción minTimeout . Se utiliza una estrategia de retroceso exponencial, por lo que las solicitudes que fallan varias veces provocarán retrasos.
Si tiene problemas al utilizar la biblioteca o desea solicitar una nueva función, abra una incidencia.
Damos la bienvenida a las solicitudes de extracción; lea las pautas de contribución.
Ejecute las pruebas usando npm test . Las pruebas se comunican con la API de DeepL mediante la clave de autenticación definida por la variable de entorno DEEPL_AUTH_KEY .
Tenga en cuenta que las pruebas realizan solicitudes de API de DeepL que contribuyen a su uso de API.
En cambio, el conjunto de pruebas puede configurarse para comunicarse con el servidor simulado proporcionado por deepl-mock. Aunque la mayoría de los casos de prueba funcionan para cualquiera de los dos, algunos casos de prueba solo funcionan con la API de DeepL o el servidor simulado y, de lo contrario, se omitirán. Los casos de prueba que requieren el servidor simulado desencadenan errores del servidor y prueban el manejo de errores del cliente. Para ejecutar las pruebas usando deepl-mock, ejecútelo en otra terminal mientras ejecuta las pruebas. Ejecute las pruebas utilizando npm test con las variables de entorno DEEPL_MOCK_SERVER_PORT y DEEPL_SERVER_URL definidas haciendo referencia al servidor simulado.
