deepl node
v1.15.0
Biblioteca cliente oficial Node.js para a API DeepL.
A API DeepL é uma API de tradução de idiomas que permite que outros programas de computador enviem textos e documentos para os servidores do DeepL e recebam traduções de alta qualidade. Isto abre todo um universo de oportunidades para os desenvolvedores: qualquer produto de tradução que você possa imaginar agora pode ser construído com base na melhor tecnologia de tradução do DeepL.
A biblioteca DeepL Node.js oferece uma maneira conveniente para aplicativos escritos para Node.js interagirem com a API DeepL. Pretendemos oferecer suporte a todas as funções da API com a biblioteca, embora o suporte para novos recursos possa ser adicionado à biblioteca após serem adicionados à API.
Para usar o pacote, você precisará de uma chave de autenticação API. Para obter uma chave, crie uma conta aqui. Com uma conta DeepL API Free você pode traduzir até 500.000 caracteres/mês gratuitamente.
npm install deepl-node
O pacote oferece suporte oficial ao Node.js versões 12, 14, 16, 17 e 18.
A partir de 2024, abandonaremos o suporte para versões mais antigas do Node que atingiram o fim de sua vida útil oficial. Você pode encontrar as versões do Node e os cronogramas de suporte aqui. Para continuar usando esta biblioteca, você deve atualizar para o Node 18+.
Importe o pacote e construa um Translator . O primeiro argumento é uma string que contém a sua chave de autenticação API, tal como se encontra na sua conta DeepL Pro.
Tenha cuidado para não expor sua chave, por exemplo, ao compartilhar o código-fonte.
Um exemplo usando módulos async / await e 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 exemplo é apenas para fins de demonstração. No código de produção, a chave de autenticação não deve ser codificada, mas sim obtida de um arquivo de configuração ou variável de ambiente.
Se você estiver usando CommonJS, você deverá solicitar o pacote:
const deepl = require ( 'deepl-node' ) ;
const translator = new deepl . Translator ( authKey ) ; Translator aceita opções como segundo argumento, consulte Configuração para obter mais informações.
Todas as funções Translator retornam promessas e, para resumir, os exemplos neste arquivo usam blocos await e try / catch , no entanto, o encadeamento de promessas também é possível:
translator
. translateText ( 'Hello, world!' , null , 'fr' )
. then ( ( result ) => {
console . log ( result . text ) ; // Bonjour, le monde !
} )
. catch ( ( error ) => {
console . error ( error ) ;
} ) ;O pacote também oferece suporte a 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 traduzir texto, chame translateText() . O primeiro argumento é uma string contendo o texto que você deseja traduzir, ou um array de strings se você deseja traduzir vários textos.
O segundo e terceiro argumentos são os códigos dos idiomas de origem e de destino. Os códigos de idioma são strings que não diferenciam maiúsculas de minúsculas de acordo com a ISO 639-1, por exemplo 'de' , 'fr' , 'ja'' . Alguns idiomas de destino também incluem a variante regional de acordo com a ISO 3166-1, por exemplo 'en-US' ou 'pt-BR' . O idioma de origem também aceita null , para permitir a detecção automática do idioma de origem.
O último argumento para translateText() é opcional e especifica opções extras de tradução, veja Opções de tradução de texto abaixo.
translateText() retorna uma Promise que cumpre com um TextResult , ou uma matriz de TextResult s correspondentes ao(s) seu(s) texto(s) de entrada. TextResult possui as seguintes propriedades:
text é o texto traduzido,detectedSourceLang é o código do idioma fonte detectado,billedCharacters é o número de caracteres cobrados pelo texto.modelTypeUsed indica o modelo de tradução usado, mas é undefined , a menos que a opção modelType seja especificada. // 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 : especifique como o texto de entrada deve ser dividido em sentenças, padrão: 'on' .'on' : o texto de entrada será dividido em frases usando novas linhas e pontuação.'off' : o texto de entrada não será dividido em frases. Use isto para aplicações onde cada texto de entrada contém apenas uma frase.'nonewlines' : o texto de entrada será dividido em frases usando pontuação, mas não novas linhas.preserveFormatting : controla a correção automática de formatação. Defina como true para evitar a correção automática da formatação, padrão: false .formality : controla se as traduções devem tender para uma linguagem informal ou formal. Esta opção está disponível apenas para alguns idiomas de destino; consulte Listando idiomas disponíveis. Use as opções prefer_* para aplicar formalidade se estiver disponível para o alvo'less' : use linguagem informal.'more' : use uma linguagem formal e mais educada.'default' : use a formalidade padrão.'prefer_less' : use linguagem informal se disponível, caso contrário, padrão.'prefer_more' : use linguagem formal e mais educada, se disponível, caso contrário, padrão.glossary : especifica um glossário para usar com tradução, seja como uma string contendo o ID do glossário ou um GlossaryInfo retornado por getGlossary() .context : especifica contexto adicional para influenciar as traduções, que não é traduzido em si. Os caracteres no parâmetro context não são contabilizados no faturamento. Consulte a documentação da API para obter mais informações e exemplos de uso.modelType : especifica o tipo de modelo de tradução a ser usado, as opções são:'quality_optimized' : use um modelo de tradução que maximize a qualidade da tradução, ao custo do tempo de resposta. Esta opção pode não estar disponível para alguns pares de idiomas.'prefer_quality_optimized' : use o modelo de tradução da mais alta qualidade para um determinado par de idiomas.'latency_optimized' : use um modelo de tradução que minimize o tempo de resposta, em detrimento da qualidade da tradução.tagHandling : tipo de tags a serem analisadas antes da tradução, as opções são 'html' e 'xml' . As opções a seguir serão usadas apenas se tagHandling for 'xml' :
outlineDetection : especifique false para desativar a detecção automática de tags, o padrão é true .splittingTags : lista de tags XML que devem ser usadas para dividir o texto em frases. As tags podem ser especificadas como uma matriz de strings ( ['tag1', 'tag2'] ) ou uma lista de strings separadas por vírgula ( 'tag1,tag2' ). O padrão é uma lista vazia.nonSplittingTags : lista de tags XML que não devem ser usadas para dividir texto em frases. O formato e o padrão são iguais aos de splittingTags .ignoreTags : lista de tags XML que contém conteúdo que não deve ser traduzido. O formato e o padrão são iguais aos de splittingTags .extraRequestParameters : parâmetros extras do corpo a serem passados junto com a solicitação HTTP. Somente valores de string são permitidos. Por exemplo: {'param': 'value', 'param2': 'value2'} Para traduzir documentos, chame translateDocument() . O primeiro e o segundo argumentos são os arquivos de entrada e saída. Esses argumentos aceitam strings contendo caminhos de arquivos ou Streams ou FileHandles abertos para leitura/gravação. O arquivo de entrada também pode ser fornecido como um Buffer contendo os dados do arquivo. Observe que se o arquivo de entrada não for fornecido como caminho de arquivo, a opção filename será necessária.
O terceiro e quarto argumentos são os códigos dos idiomas de origem e de destino e funcionam exatamente da mesma forma que ao traduzir texto com translateText() .
O último argumento para translateDocument() é opcional e especifica opções extras de tradução, veja Opções de tradução de documentos abaixo.
// 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() envolve várias chamadas de API: upload, status de pesquisa até que a tradução seja concluída e download. Se seu aplicativo precisar executar essas etapas individualmente, você poderá usar diretamente as seguintes funções:
uploadDocument() ,getDocumentStatus() (ou isDocumentTranslationComplete() ) edownloadDocument()formality : igual às opções de tradução de texto.glossary : igual às opções de tradução de texto.filename : se o arquivo de entrada não for fornecido como caminho do arquivo, esta opção será necessária para especificar a extensão do arquivo.extraRequestParameters : igual às opções de tradução de texto.Os glossários permitem que você personalize suas traduções usando termos definidos. Vários glossários podem ser armazenados em sua conta, cada um com um nome especificado pelo usuário e um ID atribuído exclusivamente.
Você pode criar um glossário com os termos e nome desejados usando createGlossary() . Cada glossário se aplica a um único par de idiomas de origem-destino. Nota: os glossários são suportados apenas para alguns pares de idiomas. Consulte a documentação da API do DeepL para obter mais informações.
// 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 ) ; Você também pode fazer upload de um glossário baixado do site do DeepL usando createGlossaryWithCsv() . Em vez de fornecer as entradas como um dicionário, forneça o arquivo CSV como uma string contendo o caminho do arquivo ou um Stream, Buffer ou FileHandle contendo o conteúdo do arquivo CSV:
const csvFilePath = '/path/to/glossary_file.csv' ;
const glossaryEnToDe = await translator . createGlossaryWithCsv (
'My glossary' ,
'en' ,
'de' ,
csvFilePath ) ;A documentação da API explica detalhadamente o formato CSV esperado.
Funções para obter, listar e excluir glossários armazenados também são fornecidas.
// 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 usar um glossário ao traduzir texto e documentos, inclua o ID (ou objeto Glossary retornado por listGlossaries() ou createGlossary() ) na chamada de função. Os idiomas de origem e de destino devem corresponder ao glossário.
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 o uso da conta, use a função getUsage() .
O objeto Usage retornado contém até três subtipos de uso, dependendo do tipo de conta: character , document e teamDocument . Para contas API character será definido, as demais undefined .
Cada subtipo de uso (se definido) possui propriedades count e limit que fornecem a quantidade usada e a quantidade máxima, respectivamente, e a função limitReached() que verifica se o uso atingiu o limite. O objeto Usage de nível superior possui a função anyLimitReached() para verificar todos os 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 } ` ) ;
} Você pode solicitar a lista de idiomas suportados pelo DeepL Translator para textos e documentos usando as funções getSourceLanguages() e getTargetLanguages() . Ambos retornam uma matriz de objetos Language .
A propriedade name fornece o nome do idioma em inglês e a propriedade code fornece o código do idioma. A propriedade supportsFormality aparece apenas para idiomas de destino e é um Boolean que indica se o idioma de destino oferece suporte ao parâmetro opcional 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'
}
} Glossários são suportados para um subconjunto de pares de idiomas. Para recuperar esses idiomas, use a função getGlossaryLanguagePairs() , que retorna uma matriz de objetos GlossaryLanguagePair . Cada um possui propriedades sourceLang e targetLang indicando que esse par de códigos de idioma é compatível com glossários.
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.
} Se você usar esta biblioteca em um aplicativo, identifique o aplicativo com o campo appInfo no TranslatorOptions , que leva o nome e a versão do aplicativo:
const options = { appInfo : { appName : 'sampleNodeTranslationApp' , appVersion : '1.2.3' } , } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;Esta informação é transmitida quando a biblioteca faz chamadas para a API do DeepL. O nome e a versão são obrigatórios.
O construtor Translator aceita opções de configuração como segundo argumento, por exemplo:
const options = { maxRetries : 5 , minTimeout : 10000 } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;As opções disponíveis são:
maxRetries : o Number máximo de solicitações HTTP com falha para tentar novamente, por chamada de função. Por padrão, são feitas 5 tentativas. Consulte Novas tentativas de solicitação.minTimeout : o Number de milissegundos usados como tempo limite de conexão para cada nova tentativa de solicitação HTTP. O valor padrão é 10.000 (10 segundos).serverUrl : string que contém o URL da API do DeepL, pode ser substituída, por exemplo, para fins de teste. Por padrão, o URL é selecionado com base no tipo de conta do usuário (gratuita ou paga).headers : cabeçalhos HTTP extras anexados a cada solicitação HTTP. Por padrão, nenhum cabeçalho extra é usado. Observe que os cabeçalhos Authorization e User-Agent são adicionados automaticamente, mas podem ser substituídos por esta opção.proxy : defina o nome do host e a porta do servidor proxy e, opcionalmente, o protocolo e a autorização (como um objeto de autenticação com campos de nome de usuário e senha). deepl-node registra mensagens de depuração e informações para cada solicitação e resposta HTTP usando o módulo loglevel , para o logger 'deepl' . Você pode reconfigurar o nível de log da seguinte maneira:
import log from 'loglevel' ;
log . getLogger ( 'deepl' ) . setLevel ( 'debug' ) ; // Or 'info' O pacote loglevel também suporta plugins, veja a documentação.
Você pode configurar um proxy especificando o argumento proxy ao construir um deepl.Translator :
const options = { proxy : { host : 'localhost' , port : 3000 } } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ; O argumento proxy é passado para a solicitação axios subjacente; consulte a documentação do axios.
Por padrão, enviamos algumas informações básicas sobre a plataforma em que a biblioteca cliente está sendo executada em cada solicitação. Veja aqui uma explicação. Esses dados são completamente anônimos e usados apenas para melhorar nosso produto e não para rastrear usuários individuais. Se você não deseja enviar esses dados, você pode cancelar ao criar seu objeto Translator definindo o sinalizador sendPlatformInfo em TranslatorOptions como false , assim:
const options = { sendPlatformInfo : false } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ; As solicitações à API do DeepL que falharem devido a condições transitórias (por exemplo, tempos limite de rede ou alta carga do servidor) serão repetidas. O número máximo de novas tentativas pode ser configurado ao construir o objeto Translator usando a opção maxRetries . O tempo limite para cada tentativa de solicitação pode ser controlado usando a opção minTimeout . Uma estratégia de espera exponencial é usada, portanto, solicitações que falharem diversas vezes incorrerão em atrasos.
Se você tiver problemas ao usar a biblioteca ou quiser solicitar um novo recurso, abra um problema.
Aceitamos solicitações pull, leia as diretrizes de contribuição.
Execute os testes usando npm test . Os testes comunicam-se com a API do DeepL usando a chave de autenticação definida pela variável de ambiente DEEPL_AUTH_KEY .
Esteja ciente de que os testes fazem solicitações à API do DeepL que contribuem para o uso da API.
Em vez disso, o conjunto de testes pode ser configurado para se comunicar com o servidor simulado fornecido pelo deepl-mock. Embora a maioria dos casos de teste funcione para ambos, alguns casos de teste funcionam apenas com a API do DeepL ou com o servidor simulado e, caso contrário, serão ignorados. Os casos de teste que exigem o servidor simulado acionam erros do servidor e testam o tratamento de erros do cliente. Para executar os testes usando deepl-mock, execute-o em outro terminal enquanto executa os testes. Execute os testes usando npm test com as variáveis de ambiente DEEPL_MOCK_SERVER_PORT e DEEPL_SERVER_URL definidas referentes ao mock-server.
