deepl node
v1.15.0
Официальная клиентская библиотека Node.js для API DeepL.
DeepL API — это API языкового перевода, который позволяет другим компьютерным программам отправлять тексты и документы на серверы DeepL и получать высококачественные переводы. Это открывает целую вселенную возможностей для разработчиков: любой продукт перевода, который вы только можете себе представить, теперь может быть создан на основе лучшей в своем классе технологии перевода DeepL.
Библиотека DeepL Node.js предлагает удобный способ взаимодействия приложений, написанных для Node.js, с API DeepL. Мы намерены поддерживать все функции API с помощью библиотеки, хотя поддержка новых функций может быть добавлена в библиотеку после их добавления в API.
Чтобы использовать пакет, вам понадобится ключ аутентификации API. Чтобы получить ключ, пожалуйста, создайте учетную запись здесь. С бесплатной учетной записью DeepL API вы можете бесплатно переводить до 500 000 символов в месяц.
npm install deepl-node
Пакет официально поддерживает Node.js версий 12, 14, 16, 17 и 18.
Начиная с 2024 года мы прекратим поддержку старых версий Node, срок эксплуатации которых официально истек. Версии Node и сроки поддержки можно найти здесь. Чтобы продолжить использование этой библиотеки, вам следует обновить ее до Node 18+.
Импортируйте пакет и создайте Translator . Первый аргумент — это строка, содержащая ваш ключ аутентификации API, который находится в вашей учетной записи DeepL Pro.
Будьте осторожны, чтобы не раскрыть свой ключ, например, при обмене исходным кодом.
Пример использования модулей 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 принимает параметры в качестве второго аргумента, дополнительную информацию см. в разделе «Конфигурация».
Все функции Translator возвращают обещания, и для краткости примеры в этом файле используют блоки await и try / catch , однако также возможно объединение обещаний:
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() . Первый аргумент — это строка, содержащая текст, который вы хотите перевести, или массив строк, если вы хотите перевести несколько текстов.
Второй и третий аргументы — это коды исходного и целевого языков. Коды языков представляют собой строки без учета регистра согласно ISO 639-1, например 'de' , 'fr' , 'ja'' . Некоторые целевые языки также включают региональный вариант в соответствии с ISO 3166-1, например 'en-US' или 'pt-BR' . Исходный язык также принимает значение null , чтобы включить автоматическое определение исходного языка.
Последний аргумент translateText() является необязательным и указывает дополнительные параметры перевода, см. раздел «Параметры перевода текста» ниже.
translateText() возвращает Promise, который выполняется с TextResult или массивом TextResult , соответствующим вашему входному тексту(ам). TextResult имеет следующие свойства:
text — это переведенный текст,detectedSourceLang — обнаруженный код исходного языка,billedCharacters — количество символов, оплачиваемых за текст.modelTypeUsed указывает используемую модель перевода, но undefined , если не указан параметр 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 : укажите, как входной текст должен быть разделен на предложения, по умолчанию: 'on' .'on' : входной текст будет разделен на предложения с использованием символов новой строки и знаков препинания.'off' : входной текст не будет разбит на предложения. Используйте это для приложений, где каждый входной текст содержит только одно предложение.'nonewlines' : входной текст будет разделен на предложения с использованием знаков препинания, но не символов новой строки.preserveFormatting : управляет автоматической коррекцией форматирования. Установите значение true , чтобы предотвратить автоматическое исправление форматирования, по умолчанию: false .formality : определяет, должны ли переводы опираться на неформальный или формальный язык. Эта опция доступна только для некоторых целевых языков. См. список доступных языков. Используйте параметры prefer_* , чтобы применить формальность, если она доступна для цели.'less' : используйте неформальный язык.'more' : используйте формальный, более вежливый язык.'default' : использовать формальность по умолчанию.'prefer_less' : используйте неофициальный язык, если он доступен, в противном случае – по умолчанию.'prefer_more' : используйте формальный, более вежливый язык, если таковой имеется, в противном случае используется значение по умолчанию.glossary : указывает глоссарий, который будет использоваться при переводе, либо в виде строки, содержащей идентификатор глоссария, либо в виде GlossaryInfo , возвращаемого getGlossary() .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() . Первый и второй аргументы — это входные и выходные файлы. Эти аргументы принимают строки, содержащие пути к файлам, а также потоки или FileHandles, открытые для чтения/записи. Входной файл также может быть представлен как буфер, содержащий данные файла. Обратите внимание: если входной файл не указан в виде пути к файлу, то требуется опция filename .
Третий и четвертый аргументы — это коды исходного и целевого языков, и они работают точно так же, как и при переводе текста с помощью 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 : то же, что и в параметрах перевода текста.Глоссарии позволяют персонализировать переводы, используя определенные термины. В вашей учетной записи можно хранить несколько глоссариев, каждый из которых имеет имя, указанное пользователем, и уникальный идентификатор.
Вы можете создать глоссарий с нужными вам терминами и названием, используя 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 ) ; Вы также можете загрузить глоссарий, загруженный с веб-сайта DeepL, с помощью createGlossaryWithCsv() . Вместо предоставления записей в виде словаря укажите CSV-файл в виде строки, содержащей путь к файлу, или Stream, Buffer или FileHandle, содержащий содержимое 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.` ,
) ; Чтобы использовать глоссарий при переводе текста и документов, включите идентификатор (или объект Glossary возвращаемый listGlossaries() или createGlossary() ) в вызов функции. Исходный и целевой языки должны соответствовать глоссарию.
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 . Для учетных записей 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 } ` ) ;
} Вы можете запросить список языков, поддерживаемых DeepL Translator для текста и документов, с помощью функций getSourceLanguages() и getTargetLanguages() . Оба они возвращают массив объектов Language .
Свойство name дает название языка на английском языке, а свойство code — код языка. Свойство supportsFormality отображается только для целевых языков и является Boolean , указывающим, поддерживает ли целевой язык необязательный параметр 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'
}
} Глоссарии поддерживаются для некоторых языковых пар. Чтобы получить эти языки, используйте функцию 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.
} Если вы используете эту библиотеку в приложении, укажите приложение с помощью поля appInfo в TranslatorOptions , которое принимает имя и версию приложения:
const options = { appInfo : { appName : 'sampleNodeTranslationApp' , appVersion : '1.2.3' } , } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;Эта информация передается, когда библиотека выполняет вызовы API DeepL. Укажите имя и версию.
Конструктор Translator принимает параметры конфигурации в качестве второго аргумента, например:
const options = { maxRetries : 5 , minTimeout : 10000 } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;Доступные варианты:
maxRetries : максимальное Number неудачных HTTP-запросов для повтора на вызов функции. По умолчанию делается 5 повторных попыток. См. Повторные попытки запроса.minTimeout : Number миллисекунд, используемых в качестве тайм-аута соединения для каждой повторной попытки HTTP-запроса. Значение по умолчанию — 10000 (10 секунд).serverUrl : string , содержащая URL-адрес DeepL API, может быть переопределена, например, в целях тестирования. По умолчанию URL-адрес выбирается в зависимости от типа учетной записи пользователя (бесплатная или платная).headers : дополнительные HTTP-заголовки, прикрепленные к каждому HTTP-запросу. По умолчанию дополнительные заголовки не используются. Обратите внимание, что заголовки Authorization и User-Agent добавляются автоматически, но могут быть переопределены этой опцией.proxy : определите имя хоста и порт прокси-сервера, а также, при необходимости, протокол и авторизацию (в виде объекта аутентификации с полями имени пользователя и пароля). deepl-node регистрирует отладочные и информационные сообщения для каждого HTTP-запроса и ответа с помощью модуля loglevel в регистраторе 'deepl' . Вы можете перенастроить уровень журнала следующим образом:
import log from 'loglevel' ;
log . getLogger ( 'deepl' ) . setLevel ( 'debug' ) ; // Or 'info' Пакет loglevel также поддерживает плагины, см. документацию.
Вы можете настроить прокси, указав аргумент proxy при создании deepl.Translator :
const options = { proxy : { host : 'localhost' , port : 3000 } } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ; Аргумент proxy передается базовому запросу axios , см. документацию по axios.
По умолчанию мы отправляем некоторую базовую информацию о платформе, на которой работает клиентская библиотека, с каждым запросом, см. здесь объяснение. Эти данные полностью анонимны и используются только для улучшения нашего продукта, а не для отслеживания отдельных пользователей. Если вы не хотите отправлять эти данные, вы можете отказаться при создании объекта Translator , установив для флага sendPlatformInfo в TranslatorOptions значение false например:
const options = { sendPlatformInfo : false } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ; Запросы к DeepL API, которые не выполняются из-за временных условий (например, тайм-аутов сети или высокой нагрузки на сервер), будут повторены. Максимальное количество повторов можно настроить при создании объекта Translator с помощью параметра maxRetries . Таймаут для каждой попытки запроса можно контролировать с помощью опции minTimeout . Используется стратегия экспоненциальной отсрочки, поэтому запросы, которые завершаются неудачно несколько раз, вызывают задержки.
Если у вас возникли проблемы с использованием библиотеки или вы хотите запросить новую функцию, откройте проблему.
Мы приветствуем запросы на включение. Пожалуйста, прочтите правила участия.
Выполните тесты с помощью npm test . Тесты взаимодействуют с API DeepL, используя ключ аутентификации, определенный переменной среды DEEPL_AUTH_KEY .
Имейте в виду, что тесты отправляют запросы DeepL API, которые способствуют использованию вами API.
Вместо этого набор тестов можно настроить для взаимодействия с макетным сервером, предоставляемым deepl-mock. Хотя большинство тестовых примеров подходят для обоих вариантов, некоторые тестовые примеры работают только с DeepL API или макетным сервером и в противном случае будут пропущены. Тестовые случаи, требующие использования макетного сервера, вызывают ошибки сервера и проверяют обработку ошибок клиента. Чтобы выполнить тесты с использованием deepl-mock, запустите его в другом терминале во время выполнения тестов. Выполните тесты с помощью npm test с переменными среды DEEPL_MOCK_SERVER_PORT и DEEPL_SERVER_URL , определенными для макетного сервера.
