deepl node
v1.15.0
Perpustakaan Klien Node.js Resmi untuk DeepL API.
DeepL API adalah API terjemahan bahasa yang memungkinkan program komputer lain mengirim teks dan dokumen ke server DeepL dan menerima terjemahan berkualitas tinggi. Hal ini membuka banyak peluang bagi pengembang: produk terjemahan apa pun yang dapat Anda bayangkan kini dapat dibangun di atas teknologi terjemahan DeepL yang terbaik di kelasnya.
Pustaka DeepL Node.js menawarkan cara mudah bagi aplikasi yang ditulis untuk Node.js untuk berinteraksi dengan API DeepL. Kami bermaksud untuk mendukung semua fungsi API dengan perpustakaan, meskipun dukungan untuk fitur baru dapat ditambahkan ke perpustakaan setelah ditambahkan ke API.
Untuk menggunakan paket ini, Anda memerlukan kunci autentikasi API. Untuk mendapatkan kunci, silakan buat akun di sini. Dengan akun DeepL API Gratis Anda dapat menerjemahkan hingga 500.000 karakter/bulan secara gratis.
npm install deepl-node
Paket ini secara resmi mendukung Node.js versi 12, 14, 16, 17, dan 18.
Mulai tahun 2024, kami akan menghentikan dukungan untuk versi Node lama yang telah mencapai akhir masa pakainya secara resmi. Anda dapat menemukan versi Node dan jadwal dukungan di sini. Untuk terus menggunakan perpustakaan ini, Anda harus memperbarui ke Node 18+.
Impor paket dan buat Translator . Argumen pertama adalah string yang berisi kunci autentikasi API Anda seperti yang ditemukan di Akun DeepL Pro Anda.
Berhati-hatilah untuk tidak mengekspos kunci Anda, misalnya saat berbagi kode sumber.
Contoh penggunaan Modul async / await dan 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 !
} ) ( ) ;Contoh ini hanya untuk tujuan demonstrasi. Dalam kode produksi, kunci autentikasi tidak boleh dikodekan secara permanen, melainkan diambil dari file konfigurasi atau variabel lingkungan.
Jika Anda menggunakan CommonJS, Anda seharusnya memerlukan paket:
const deepl = require ( 'deepl-node' ) ;
const translator = new deepl . Translator ( authKey ) ; Translator menerima opsi sebagai argumen kedua, lihat Konfigurasi untuk informasi selengkapnya.
Semua fungsi Translator mengembalikan janji, dan untuk singkatnya contoh dalam file ini menggunakan blok await dan try / catch , namun rangkaian janji juga dimungkinkan:
translator
. translateText ( 'Hello, world!' , null , 'fr' )
. then ( ( result ) => {
console . log ( result . text ) ; // Bonjour, le monde !
} )
. catch ( ( error ) => {
console . error ( error ) ;
} ) ;Paket ini juga mendukung 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 !
} ) ;
} ) ( ) ; Untuk menerjemahkan teks, panggil translateText() . Argumen pertama adalah string yang berisi teks yang ingin Anda terjemahkan, atau array string jika Anda ingin menerjemahkan banyak teks.
Argumen kedua dan ketiga adalah kode bahasa sumber dan target. Kode bahasa adalah string yang tidak peka huruf besar-kecil menurut ISO 639-1, misalnya 'de' , 'fr' , 'ja'' . Beberapa bahasa target juga menyertakan varian regional menurut ISO 3166-1, misalnya 'en-US' , atau 'pt-BR' . Bahasa sumber juga menerima null , untuk mengaktifkan deteksi otomatis bahasa sumber.
Argumen terakhir untuk translateText() bersifat opsional, dan menentukan opsi terjemahan tambahan, lihat Opsi terjemahan teks di bawah.
translateText() mengembalikan Promise yang dipenuhi dengan TextResult , atau array TextResult yang sesuai dengan teks masukan Anda. TextResult memiliki properti berikut:
text adalah teks terjemahan,detectedSourceLang adalah kode bahasa sumber yang terdeteksi,billedCharacters adalah jumlah karakter yang ditagih untuk teks.modelTypeUsed menunjukkan model terjemahan yang digunakan, tetapi undefined kecuali opsi modelType ditentukan. // 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 : tentukan bagaimana teks masukan harus dipecah menjadi kalimat, default: 'on' .'on' : teks masukan akan dipecah menjadi kalimat menggunakan baris baru dan tanda baca.'off' : teks masukan tidak akan dipecah menjadi kalimat. Gunakan ini untuk aplikasi yang setiap teks masukannya hanya berisi satu kalimat.'nonewlines' : teks masukan akan dipecah menjadi kalimat menggunakan tanda baca tetapi bukan baris baru.preserveFormatting : mengontrol koreksi pemformatan otomatis. Setel ke true untuk mencegah koreksi otomatis pemformatan, default: false .formality : mengontrol apakah terjemahan harus condong ke bahasa informal atau formal. Opsi ini hanya tersedia untuk beberapa bahasa target, lihat Mencantumkan bahasa yang tersedia. Gunakan opsi prefer_* untuk menerapkan formalitas jika tersedia untuk target'less' : menggunakan bahasa informal.'more' : menggunakan bahasa formal yang lebih sopan.'default' : gunakan formalitas default.'prefer_less' : gunakan bahasa informal jika tersedia, jika tidak maka default.'prefer_more' : gunakan bahasa yang formal dan lebih sopan jika tersedia, jika tidak maka akan default.glossary : menentukan glosarium yang akan digunakan dengan terjemahan, baik sebagai string yang berisi ID glosarium, atau GlossaryInfo yang dikembalikan oleh getGlossary() .context : menentukan konteks tambahan untuk mempengaruhi terjemahan, yang tidak diterjemahkan sendiri. Karakter dalam parameter context tidak dihitung dalam penagihan. Lihat dokumentasi API untuk informasi lebih lanjut dan contoh penggunaan.modelType : menentukan jenis model terjemahan yang akan digunakan, pilihannya adalah:'quality_optimized' : menggunakan model terjemahan yang memaksimalkan kualitas terjemahan, dengan mengorbankan waktu respons. Opsi ini mungkin tidak tersedia untuk beberapa pasangan bahasa.'prefer_quality_optimized' : gunakan model terjemahan kualitas tertinggi untuk pasangan bahasa tertentu.'latency_optimized' : menggunakan model terjemahan yang meminimalkan waktu respons, dengan mengorbankan kualitas terjemahan.tagHandling : jenis tag yang akan diurai sebelum terjemahan, pilihannya adalah 'html' dan 'xml' . Opsi berikut hanya digunakan jika tagHandling adalah 'xml' :
outlineDetection : tentukan false untuk menonaktifkan deteksi tag otomatis, defaultnya adalah true .splittingTags : daftar tag XML yang harus digunakan untuk membagi teks menjadi kalimat. Tag dapat ditentukan sebagai larik string ( ['tag1', 'tag2'] ), atau daftar string yang dipisahkan koma ( 'tag1,tag2' ). Standarnya adalah daftar kosong.nonSplittingTags : daftar tag XML yang tidak boleh digunakan untuk membagi teks menjadi kalimat. Format dan defaultnya sama dengan splittingTags .ignoreTags : daftar tag XML yang berisi konten yang tidak boleh diterjemahkan. Format dan defaultnya sama dengan splittingTags .extraRequestParameters : Parameter isi tambahan yang akan diteruskan bersama dengan permintaan HTTP. Hanya nilai string yang diizinkan. Misalnya: {'param': 'value', 'param2': 'value2'} Untuk menerjemahkan dokumen, panggil translateDocument() . Argumen pertama dan kedua adalah file input dan output. Argumen ini menerima string yang berisi jalur file, atau Streams atau FileHandles yang dibuka untuk membaca/menulis. File masukan juga dapat diberikan sebagai Buffer yang berisi data file. Perhatikan bahwa jika file masukan tidak diberikan sebagai jalur file, maka opsi filename diperlukan.
Argumen ketiga dan keempat adalah kode bahasa sumber dan target, dan cara kerjanya sama persis seperti saat menerjemahkan teks dengan translateText() .
Argumen terakhir untuk translateDocument() bersifat opsional, dan menentukan opsi terjemahan tambahan, lihat Opsi terjemahan dokumen di bawah.
// 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() menggabungkan beberapa panggilan API: pengunggahan, status polling hingga terjemahan selesai, dan pengunduhan. Jika aplikasi Anda perlu menjalankan langkah-langkah ini satu per satu, Anda dapat menggunakan fungsi berikut secara langsung:
uploadDocument() ,getDocumentStatus() (atau isDocumentTranslationComplete() ), dandownloadDocument()formality : sama seperti pada opsi terjemahan teks.glossary : sama seperti pada opsi terjemahan teks.filename : jika file masukan tidak disediakan sebagai jalur file, opsi ini diperlukan untuk menentukan ekstensi file.extraRequestParameters : sama seperti pada opsi terjemahan teks.Glosarium memungkinkan Anda menyesuaikan terjemahan menggunakan istilah yang ditentukan. Beberapa glosarium dapat disimpan dengan akun Anda, masing-masing dengan nama yang ditentukan pengguna dan ID yang ditetapkan secara unik.
Anda dapat membuat glosarium dengan istilah dan nama yang Anda inginkan menggunakan createGlossary() . Setiap glosarium berlaku untuk satu pasangan bahasa sumber-target. Catatan: glosarium hanya didukung untuk beberapa pasangan bahasa, periksa dokumentasi DeepL API untuk informasi lebih lanjut.
// 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 ) ; Anda juga dapat mengunggah glosarium yang diunduh dari situs web DeepL menggunakan createGlossaryWithCsv() . Daripada menyediakan entri sebagai kamus, berikan file CSV sebagai string yang berisi jalur file, atau Stream, Buffer, atau FileHandle yang berisi konten file CSV:
const csvFilePath = '/path/to/glossary_file.csv' ;
const glossaryEnToDe = await translator . createGlossaryWithCsv (
'My glossary' ,
'en' ,
'de' ,
csvFilePath ) ;Dokumentasi API menjelaskan format CSV yang diharapkan secara detail.
Fungsi untuk mendapatkan, membuat daftar, dan menghapus glosarium yang tersimpan juga disediakan.
// 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.` ,
) ; Untuk menggunakan glosarium saat menerjemahkan teks dan dokumen, sertakan ID (atau objek Glossary yang dikembalikan oleh listGlossaries() atau createGlossary() ) dalam pemanggilan fungsi. Bahasa sumber dan bahasa sasaran harus sesuai dengan glosarium.
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.' Untuk memeriksa penggunaan akun, gunakan fungsi getUsage() .
Objek Usage yang dikembalikan berisi hingga tiga subtipe penggunaan, bergantung pada jenis akun Anda: character , document dan teamDocument . Untuk akun API, character akan ditentukan, yang lainnya undefined .
Setiap subtipe penggunaan (jika ditentukan) memiliki properti count dan limit yang masing-masing memberikan jumlah yang digunakan dan jumlah maksimum, serta fungsi limitReached() yang memeriksa apakah penggunaan telah mencapai batas. Objek Usage tingkat atas memiliki fungsi anyLimitReached() untuk memeriksa semua subtipe penggunaan.
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 } ` ) ;
} Anda dapat meminta daftar bahasa yang didukung oleh DeepL Translator untuk teks dan dokumen menggunakan fungsi getSourceLanguages() dan getTargetLanguages() . Keduanya mengembalikan array objek Language .
Properti name memberikan nama bahasa dalam bahasa Inggris, dan properti code memberikan kode bahasa. Properti supportsFormality hanya muncul untuk bahasa target, dan merupakan Boolean yang menunjukkan apakah bahasa target mendukung parameter formality opsional.
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'
}
} Glosarium didukung untuk subkumpulan pasangan bahasa. Untuk mengambil bahasa tersebut gunakan fungsi getGlossaryLanguagePairs() , yang mengembalikan array objek GlossaryLanguagePair . Masing-masing memiliki properti sourceLang dan targetLang yang menunjukkan bahwa pasangan kode bahasa tersebut didukung untuk glosarium.
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.
} Jika Anda menggunakan pustaka ini dalam suatu aplikasi, harap identifikasikan aplikasi tersebut dengan bidang appInfo di TranslatorOptions , yang mengambil nama dan versi aplikasi:
const options = { appInfo : { appName : 'sampleNodeTranslationApp' , appVersion : '1.2.3' } , } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;Informasi ini diteruskan ketika perpustakaan melakukan panggilan ke DeepL API. Nama dan versi diperlukan.
Konstruktor Translator menerima opsi konfigurasi sebagai argumen kedua, misalnya:
const options = { maxRetries : 5 , minTimeout : 10000 } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ;Opsi yang tersedia adalah:
maxRetries : Number maksimum permintaan HTTP yang gagal untuk dicoba lagi, per panggilan fungsi. Secara default, 5 percobaan ulang dilakukan. Lihat Meminta percobaan ulang.minTimeout : Number milidetik yang digunakan sebagai batas waktu koneksi untuk setiap percobaan ulang permintaan HTTP. Nilai defaultnya adalah 10.000 (10 detik).serverUrl : string yang berisi URL DeepL API, dapat diganti misalnya untuk tujuan pengujian. Secara default, URL dipilih berdasarkan jenis akun pengguna (gratis atau berbayar).headers : header HTTP tambahan yang dilampirkan pada setiap permintaan HTTP. Secara default, tidak ada header tambahan yang digunakan. Perhatikan bahwa header Otorisasi dan Agen-Pengguna ditambahkan secara otomatis tetapi dapat ditimpa oleh opsi ini.proxy : menentukan nama host, dan port server proxy, dan secara opsional protokol, dan otorisasi (sebagai objek autentikasi dengan bidang nama pengguna dan kata sandi). deepl-node mencatat debug dan pesan info untuk setiap permintaan dan respons HTTP menggunakan modul loglevel , ke logger 'deepl' . Anda dapat mengkonfigurasi ulang level log sebagai berikut:
import log from 'loglevel' ;
log . getLogger ( 'deepl' ) . setLevel ( 'debug' ) ; // Or 'info' Paket loglevel juga mendukung plugin, lihat dokumentasi.
Anda dapat mengonfigurasi proksi dengan menentukan argumen proxy saat membuat deepl.Translator :
const options = { proxy : { host : 'localhost' , port : 3000 } } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ; Argumen proksi diteruskan ke permintaan axios yang mendasarinya, lihat dokumentasi untuk aksio.
Secara default, kami mengirimkan beberapa informasi dasar tentang platform tempat perpustakaan klien dijalankan dengan setiap permintaan, lihat di sini untuk penjelasannya. Data ini sepenuhnya anonim dan hanya digunakan untuk meningkatkan produk kami, bukan melacak pengguna individual mana pun. Jika Anda tidak ingin mengirim data ini, Anda dapat memilih untuk tidak ikut serta saat membuat objek Translator dengan menyetel tanda sendPlatformInfo di TranslatorOptions ke false seperti:
const options = { sendPlatformInfo : false } ;
const deepl = new deepl . Translator ( 'YOUR_AUTH_KEY' , options ) ; Permintaan ke DeepL API yang gagal karena kondisi sementara (misalnya, waktu tunggu jaringan habis atau beban server tinggi) akan dicoba ulang. Jumlah percobaan ulang maksimum dapat dikonfigurasi saat membuat objek Translator menggunakan opsi maxRetries . Batas waktu untuk setiap upaya permintaan dapat dikontrol menggunakan opsi minTimeout . Strategi kemunduran eksponensial digunakan, sehingga permintaan yang gagal beberapa kali akan mengalami penundaan.
Jika Anda mengalami masalah dalam menggunakan perpustakaan, atau ingin meminta fitur baru, silakan buka terbitan.
Kami menyambut Permintaan Tarik, harap baca pedoman berkontribusi.
Jalankan tes menggunakan npm test . Pengujian berkomunikasi dengan DeepL API menggunakan kunci autentikasi yang ditentukan oleh variabel lingkungan DEEPL_AUTH_KEY .
Ketahuilah bahwa pengujian ini membuat permintaan API DeepL yang berkontribusi terhadap penggunaan API Anda.
Rangkaian pengujian mungkin dikonfigurasi untuk berkomunikasi dengan server tiruan yang disediakan oleh deepl-mock. Meskipun sebagian besar kasus pengujian berfungsi untuk keduanya, beberapa kasus pengujian hanya berfungsi dengan API DeepL atau server tiruan dan jika tidak, akan dilewati. Kasus uji yang memerlukan server tiruan memicu kesalahan server dan menguji penanganan kesalahan klien. Untuk menjalankan pengujian menggunakan deepl-mock, jalankan di terminal lain saat menjalankan pengujian. Jalankan pengujian menggunakan npm test dengan variabel lingkungan DEEPL_MOCK_SERVER_PORT dan DEEPL_SERVER_URL yang ditentukan dengan mengacu pada server tiruan.
