مكتبة عملاء Node.js الرسمية لواجهة برمجة تطبيقات DeepL.
DeepL API عبارة عن واجهة برمجة تطبيقات لترجمة اللغات تسمح لبرامج الكمبيوتر الأخرى بإرسال النصوص والمستندات إلى خوادم DeepL وتلقي ترجمات عالية الجودة. وهذا يفتح عالمًا كاملاً من الفرص للمطورين: يمكن الآن إنشاء أي منتج ترجمة يمكنك تخيله استنادًا إلى تقنية الترجمة الأفضل في فئتها من DeepL.
توفر مكتبة DeepL Node.js طريقة ملائمة للتطبيقات المكتوبة لـ Node.js للتفاعل مع DeepL API. نعتزم دعم جميع وظائف واجهة برمجة التطبيقات (API) مع المكتبة، على الرغم من إمكانية إضافة دعم الميزات الجديدة إلى المكتبة بعد إضافتها إلى واجهة برمجة التطبيقات (API).
لاستخدام الحزمة، ستحتاج إلى مفتاح مصادقة API. للحصول على المفتاح، يرجى إنشاء حساب هنا. باستخدام حساب DeepL API Free، يمكنك ترجمة ما يصل إلى 500000 حرف شهريًا مجانًا.
npm install deepl-node
تدعم الحزمة رسميًا الإصدار 12 و14 و16 و17 و18 من Node.js.
بدءًا من عام 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()
وعدًا يفي باستخدام 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()
استدعاءات واجهة برمجة التطبيقات المتعددة: التحميل، وحالة الاستقصاء حتى اكتمال الترجمة، والتنزيل. إذا كان تطبيقك يحتاج إلى تنفيذ هذه الخطوات بشكل فردي، فيمكنك بدلاً من ذلك استخدام الوظائف التالية مباشرةً:
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 ) ;
يتم تمرير هذه المعلومات عندما تقوم المكتبة بإجراء مكالمات إلى DeepL API. مطلوب كل من الاسم والإصدار.
يقبل منشئ 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 على سبيل المثال لأغراض الاختبار. افتراضيًا، يتم تحديد عنوان 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 ) ;
يتم تمرير وسيطة الوكيل إلى طلب 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
. تتواصل الاختبارات مع DeepL API باستخدام مفتاح المصادقة المحدد بواسطة متغير البيئة DEEPL_AUTH_KEY
.
انتبه إلى أن الاختبارات تقدم طلبات DeepL API التي تساهم في استخدام واجهة برمجة التطبيقات (API) الخاصة بك.
قد يتم بدلاً من ذلك تكوين مجموعة الاختبار للتواصل مع الخادم الوهمي الذي يوفره Deepl-mock. على الرغم من أن معظم حالات الاختبار تعمل مع أي منهما، إلا أن بعض حالات الاختبار تعمل فقط مع DeepL API أو الخادم الوهمي وسيتم تخطيها. تؤدي حالات الاختبار التي تتطلب خادمًا وهميًا إلى تشغيل أخطاء الخادم واختبار معالجة أخطاء العميل. لتنفيذ الاختبارات باستخدام Deepl-mock، قم بتشغيله في محطة أخرى أثناء تنفيذ الاختبارات. قم بتنفيذ الاختبارات باستخدام npm test
مع متغيرات البيئة DEEPL_MOCK_SERVER_PORT
و DEEPL_SERVER_URL
المحددة بالإشارة إلى الخادم الوهمي.