deepl node

깊은 노드

DeepL API용 공식 Node.js 클라이언트 라이브러리.

DeepL API는 다른 컴퓨터 프로그램이 텍스트와 문서를 DeepL의 서버로 보내고 고품질 번역을 받을 수 있도록 하는 언어 번역 API입니다. 이는 개발자에게 무한한 기회의 세계를 열어줍니다. 이제 DeepL의 동급 최고의 번역 기술을 기반으로 상상할 수 있는 모든 번역 제품을 구축할 수 있습니다.

DeepL Node.js 라이브러리는 Node.js용으로 작성된 애플리케이션이 DeepL API와 상호 작용할 수 있는 편리한 방법을 제공합니다. 새로운 기능에 대한 지원은 API에 추가된 후 라이브러리에 추가될 수 있지만 라이브러리를 통해 모든 API 기능을 지원할 계획입니다.

인증키 받기

패키지를 사용하려면 API 인증키가 필요합니다. 키를 받으려면 여기에서 계정을 만드세요. DeepL API 무료 계정을 사용하면 월 최대 500,000자를 무료로 번역할 수 있습니다.

설치

npm install deepl-node

요구사항

이 패키지는 공식적으로 Node.js 버전 12, 14, 16, 17 및 18을 지원합니다.

2024년부터 공식적으로 수명이 종료된 이전 Node 버전에 대한 지원이 중단됩니다. 여기에서 Node 버전과 지원 타임라인을 확인할 수 있습니다. 이 라이브러리를 계속 사용하려면 Node 18+로 업데이트해야 합니다.

용법

패키지를 가져오고 Translator 구성합니다. 첫 번째 인수는 DeepL Pro 계정에 있는 API 인증 키가 포함된 문자열입니다.

예를 들어 소스 코드를 공유할 때 키가 노출되지 않도록 주의하세요.

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() TextResult 또는 입력 텍스트에 해당하는 TextResult 배열을 충족하는 Promise를 반환합니다. TextResult 에는 다음과 같은 속성이 있습니다.

• text 번역된 텍스트입니다.
• detectedSourceLang 은 감지된 소스 언어 코드입니다.
• billedCharacters 텍스트에 대해 청구되는 문자 수입니다.
• modelTypeUsed 사용된 번역 모델을 나타내지만 modelType 옵션이 지정되지 않으면 undefined .

 // 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 : 용어집 ID가 포함된 문자열 또는 getGlossary() 에서 반환된 GlossaryInfo 로 번역에 사용할 용어집을 지정합니다.
• 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() 호출하세요. 첫 번째 및 두 번째 인수는 입력 및 출력 파일입니다. 이러한 인수는 파일 경로 또는 읽기/쓰기를 위해 열린 스트림 또는 FileHandle을 포함하는 문자열을 허용합니다. 입력 파일은 파일 데이터를 포함하는 버퍼로 제공될 수도 있습니다. 입력 파일이 파일 경로로 제공되지 않으면 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 : 텍스트 번역 옵션과 동일합니다.

용어집

용어집을 사용하면 정의된 용어를 사용하여 번역을 사용자 정의할 수 있습니다. 여러 개의 용어집을 귀하의 계정에 저장할 수 있으며 각 용어집에는 사용자가 지정한 이름과 고유하게 할당된 ID가 있습니다.

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 ) ;

createGlossaryWithCsv() 사용하여 DeepL 웹사이트에서 다운로드한 용어집을 업로드할 수도 있습니다. 항목을 사전으로 제공하는 대신 CSV 파일을 파일 경로가 포함된 문자열로 제공하거나 CSV 파일 콘텐츠가 포함된 스트림, 버퍼 또는 FileHandle로 제공하세요.

 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.` ,
) ;

텍스트와 문서를 번역할 때 용어집을 사용하려면 함수 호출에 ID(또는 listGlossaries() 또는 createGlossary() 에서 반환된 Glossary 객체)를 포함하세요. 소스 및 대상 언어는 용어집과 일치해야 합니다.

 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 객체에는 계정 유형에 따라 최대 3개의 사용 하위 유형( 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 } ` ) ;
}

사용 가능한 언어 나열

getSourceLanguages() 및 getTargetLanguages() 함수를 사용하여 텍스트 및 문서에 대해 DeepL Translator에서 지원하는 언어 목록을 요청할 수 있습니다. 둘 다 Language 객체의 배열을 반환합니다.

name 속성은 영어로 된 언어 이름을 제공하고, code 속성은 언어 코드를 제공합니다. supportsFormality 속성은 대상 언어에만 표시되며 대상 언어가 선택적 formality 매개변수를 지원하는지 여부를 나타내는 Boolean 입니다.

 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'
    }
}

용어집은 언어 쌍의 하위 집합에 대해 지원됩니다. 해당 언어를 검색하려면 GlossaryLanguagePair 객체 배열을 반환하는 getGlossaryLanguagePairs() 함수를 사용하세요. 각각에는 해당 언어 코드 쌍이 용어집에 지원됨을 나타내는 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.
}

플러그인 작성

애플리케이션에서 이 라이브러리를 사용하는 경우 앱의 이름과 버전을 사용하는 TranslatorOptions 의 appInfo 필드로 애플리케이션을 식별하세요.

 const options = { appInfo : { appName : 'sampleNodeTranslationApp' , appVersion : '1.2.3' } , } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;

이 정보는 라이브러리가 DeepL API를 호출할 때 전달됩니다. 이름과 버전이 모두 필요합니다.

구성

Translator 생성자는 구성 옵션을 두 번째 인수로 허용합니다. 예를 들면 다음과 같습니다.

 const options = { maxRetries : 5 , minTimeout : 10000 } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;

사용 가능한 옵션은 다음과 같습니다.

• maxRetries : 함수 호출당 실패한 HTTP 요청의 최대 재시도 Number . 기본적으로 5번의 재시도가 이루어집니다. 재시도 요청을 참조하세요.
• minTimeout : 각 HTTP 요청 재시도에 대한 연결 시간 초과로 사용되는 밀리초 Number 입니다. 기본값은 10000(10초)입니다.
• serverUrl : DeepL API의 URL이 포함된 string 로, 예를 들어 테스트 목적으로 재정의될 수 있습니다. 기본적으로 URL은 사용자 계정 유형(무료 또는 유료)에 따라 선택됩니다.
• headers : 모든 HTTP 요청에 첨부되는 추가 HTTP 헤더입니다. 기본적으로 추가 헤더는 사용되지 않습니다. Authorization 및 User-Agent 헤더는 자동으로 추가되지만 이 옵션으로 재정의될 수 있습니다.
• proxy : 프록시 서버의 호스트 이름과 포트를 정의하고, 선택적으로 프로토콜과 인증(사용자 이름과 비밀번호 필드가 있는 인증 개체로)을 정의합니다.

벌채 반출

deepl-node loglevel 모듈을 사용하여 모든 HTTP 요청 및 응답에 대한 디버그 및 정보 메시지를 'deepl' 로거에 기록합니다. 다음과 같이 로그 수준을 재구성할 수 있습니다.

 import log from 'loglevel' ;

log . getLogger ( 'deepl' ) . setLevel ( 'debug' ) ; // Or 'info'

loglevel 패키지는 플러그인도 지원합니다. 설명서를 참조하세요.

프록시 구성

deepl.Translator 를 생성할 때 proxy 인수를 지정하여 프록시를 구성할 수 있습니다.

 const options = { proxy : { host : 'localhost' , port : 3000 } } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;

프록시 인수는 기본 axios 요청에 전달됩니다. axios 설명서를 참조하세요.

익명 플랫폼 정보

기본적으로 우리는 각 요청과 함께 클라이언트 라이브러리가 실행 중인 플랫폼에 대한 몇 가지 기본 정보를 보냅니다. 자세한 내용은 여기를 참조하세요. 이 데이터는 완전히 익명이며 제품 개선을 위해서만 사용되며 개별 사용자를 추적하지 않습니다. 이 데이터를 보내지 않으려면 Translator 개체를 생성할 때 다음과 같이 TranslatorOptions 의 sendPlatformInfo 플래그를 false 로 설정하여 선택 해제할 수 있습니다.

 const options = { sendPlatformInfo : false } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;

재시도 요청

일시적인 조건(예: 네트워크 시간 초과 또는 높은 서버 로드)으로 인해 실패한 DeepL API 요청은 다시 시도됩니다. maxRetries 옵션을 사용하여 Translator 개체를 생성할 때 최대 재시도 횟수를 구성할 수 있습니다. 각 요청 시도에 대한 시간 초과는 minTimeout 옵션을 사용하여 제어할 수 있습니다. 지수 백오프 전략이 사용되므로 여러 번 실패하는 요청은 지연이 발생합니다.

문제

라이브러리 사용에 문제가 있거나 새로운 기능을 요청하려면 이슈를 열어주세요.

개발

Pull Request를 환영합니다. 기여 가이드라인을 읽어보세요.

테스트

npm test 사용하여 테스트를 실행합니다. 테스트는 DEEPL_AUTH_KEY 환경 변수에 정의된 인증 키를 사용하여 DeepL API와 통신합니다.

테스트에서는 API 사용에 기여하는 DeepL API 요청을 수행한다는 점에 유의하세요.

대신 테스트 스위트는 deepl-mock에서 제공하는 모의 서버와 통신하도록 구성될 수 있습니다. 대부분의 테스트 사례는 둘 중 하나에서 작동하지만 일부 테스트 사례는 DeepL API 또는 모의 서버에서만 작동하므로 건너뛰게 됩니다. 모의 서버가 필요한 테스트 사례는 서버 오류를 트리거하고 클라이언트 오류 처리를 테스트합니다. deepl-mock을 사용하여 테스트를 실행하려면 테스트를 실행하는 동안 다른 터미널에서 실행하세요. 모의 서버를 참조하여 정의된 DEEPL_MOCK_SERVER_PORT 및 DEEPL_SERVER_URL 환경 변수와 함께 npm test 를 사용하여 테스트를 실행합니다.