إنشاء وظيفة إضافية من DeepL API لبرنامج Microsoft Office (في يوم واحد فقط)

مرة واحدة في الشهر، يشارك موظفو DeepL في فعالية Hack Friday على مستوى الشركة، حيث يتولون مشاريع خارج نطاق عملهم اليومي. تعد أيام الجمعة المخصصة للقرصنة فرصة رائعة للتجريب مع API الخاص بنا، وأحيانًا تصل النتائج إلى المستخدمين. في الواقع، كان البرنامج النصي Google Sheets-DeepL الذي أطلقناه مؤخرًا نتيجة لمشروع Hack Friday! في Hack Friday في سبتمبر 2022، قام مطور برامج DeepL مارفن بيكر ومطور البرامج تيم كادنباخ ببناء نموذج أولي لبرنامج DeepL وظيفة إضافية لبرنامج Microsoft Word، مما يتيح للمستخدمين الترجمة باستخدام DeepL مباشرة في مستند Word.

يمكنك مشاهدته أثناء العمل هنا:

لماذا اهتممنا بهذا التكامل؟

تعد الاتصالات التجارية من الحالات الشائعة لاستخدام DeepL — حيث تتيح ترجمات DeepL للقوى العاملة العالمية متعددة اللغات التعاون بكفاءة مع الحفاظ على أمان البيانات الحساسة للشركة. كثيرًا ما نتلقى طلبات من عملاء يرغبون في إنشاء وظيفة إضافية خاصة بهم في Office باستخدام واجهة برمجة تطبيقات DeepL API ويبحثون عن موارد للبدء في ذلك. أردنا أن نتعلم بشكل مباشر ما يتطلبه التكامل حتى نتمكن من تقديم إجابات أفضل عندما يطرح عملاؤنا أسئلة علينا. 

في هذا المنشور، سنشارككم ما تعلمناه. سنوفر أيضًا كود مفتوح المصدر لمساعدتك في بدء مشروعك بسرعة أكبر. جاهز؟ لنبني! 

نصيحة 0 (اختيارية): قم ببعض الواجبات المنزلية  

إذا كنت جديدًا تمامًا في مجال API لبرمجة تطبيقات Office، نقترح عليك قراءة فهم واجهة برمجة تطبيقات JavaScript لـ Office API في وثائق Microsoft. باختصار، توفر جميع منتجات Office واجهة برمجة API مشتركة مع واجهات برمجة تطبيقات خاصة بالمنتج في الأعلى. قد يكون من المفيد أيضًا الاطلاع على هذا البرنامج التعليمي قبل الانتقال إلى النصيحة 1. 

نصيحة 1: بناء نموذج أولي باستخدام Script Lab (أو استخدم نموذجنا) 

Script Lab هو مشروع مفتوح المصدر تديره شركة Microsoft. يتيح Script Lab إمكانية تجربة Office JavaScript API دون مغادرة Excel أو Outlook أو Word أو PowerPoint. مختبر البرمجة النصية مستودع GitHub يتضمن درسًا تعليميًا لمساعدتك على البدء.

استخدمنا Script Lab لإنشاء نموذج أولي لإضافة البرنامج المساعد لأنها طريقة مثالية لكتابة التعليمات البرمجية بسرعة ومشاهدتها أثناء العمل — وهي تتكون من ملف JavaScript و HTML و CSS واحد فقط.

على الرغم من أن هذه الخطوة الأولية ليست الوظيفة الإضافية التي يمكنك مشاركتها مع أعضاء الفريق في الوقت الحالي، إلا أنها تعطيك فكرة عما يمكن تحقيقه باستخدام DeepL API ونوع تجربة المستخدم التي ستتمكن من توفيرها باستخدام الوظيفة الإضافية.

في بداية هذا المنشور، وعدناكم برمز مفتوح المصدر! يوفر Script Lab عرضًا لاستيراد "مقتطفات" الآخرين، لذا قمنا بفتح مصدر مقتطفات DeepL-Word التي أنشأناها حتى يتمكن أي شخص من تجربتها. يمكنك العثور عليه في GitHub هنا.

ستحتاج أيضًا إلى مفتاح API DeepL إذا كنت ترغب في متابعة هذه الخطوة. يمكنك التسجيل حساب هنا.

ما عليك سوى نسخ ولصق Gist YAML كما هو موضح في التعليمات، وإدخال مفتاح DeepL API الخاص بك في العنصر النائب في السطر 32، وستتمكن من تشغيل المقتطف الخاص بنا ببضع نقرات فقط.

أفضل جزء؟ يمكن إعادة استخدام مقتطف Script Lab أثناء إعداد قالب وظيفة إضافية، بحيث تصبح جميع الأعمال التي تقوم بها في Script Lab مفيدة لاحقًا.

النصيحة 2: إنشاء مشروع وظيفة إضافية لبرنامج Office باستخدام Yeoman Generator

الآن بعد أن قمنا بعمل بعض النماذج الأولية في Script Lab وتعرفنا على أساسيات البرمجة النصية في Office، يمكننا البدء في إنشاء وظيفة إضافية فعلية باستخدام Yeoman. Yeoman هي أداة سقالات مفتوحة المصدر تجعل إنشاء المشاريع الجديدة أمراً سهلاً نسبياً. بالنسبة لإضافات Office، هناك قالب جاهز من Microsoft يمكنك استخدامه، ويُشار إليه غالبًا باسم "Yo Office". 

يتم تغطية هذه العملية هنا: وظيفة إضافية Office Yeoman إنشائي.

بعد اتباع تعليمات الإعداد، نسخ الرمز من Script Lab إلى المستودع الذي أنشأته حديثًا. هناك المزيد من الإعدادات التي يمكنك تكوينها، ولكن يمكنك البدء على الفور بتنفيذ 'npm run start'. سيؤدي ذلك إلى تشغيل Word وتحميل الوظيفة الإضافية تلقائياً. يمكنك استخدام أي IDE للتطوير، على الرغم من أن القالب الذي تم إنشاؤه يعمل بشكل أفضل مع محررات الأكواد الخاصة بـ Microsoft VS Code أو Visual Studio. للحصول على تجربة أفضل في البرمجة وتصحيح الأخطاء، نوصي باستخدام Visual Studio.

النصيحة 3: تنفيذ DeepL API

تطبيقنا لـ DeepL بسيط للغاية — حيث يستدعي برنامج جافا سكريبت نصي نقطة نهاية ترجمة النصوص. بالنسبة لنموذجنا البسيط، كان ذلك كافياً. إذا كنت ترغب في تمكين مسارد المصطلحات في الوظيفة الإضافية الخاصة بك، فستحتاج إلى بذل المزيد من الجهد.

لم نستخدم مكتبة عميل Node.js الرسمية من DeepL مكتبة العميل Node.js للمشروع لأن المكتبة غير مخصصة لرموز JavaScript من جانب العميل. والسبب هنا هو الأمان — فأنت ستكشف مفتاح API الخاص بك عند استدعاء كود جانب العميل. يمكنك الاطلاع على ملف GIST الذي شاركناه أعلاه لمعرفة نهجنا بمزيد من التفصيل (بدءًا من السطر 102).

النصيحة 4: تصحيح الأخطاء لمستخدمي Mac 

في السنوات الأخيرة، قامت Microsoft باستثمارات كبيرة لتقديم فريق المساعدة لمستخدمي Mac. على الرغم من أن فريق المساعدة على Mac جيد جدًا لتطوير .NET Core، إلا أنه لا يزال غير كافٍ لتطوير Windows الأساسي، بما في ذلك تطبيقات Microsoft Office. لسوء الحظ، إصدارات تطبيقات Microsoft لمستخدمي Mac غير مهيأة لتسهيل عملية تصحيح الأخطاء. تيم من الموالين لشركة Microsoft (وMVP!)، لذا لم يواجه أي مشاكل، لكن مستخدم Mac مارفن احتاج إلى تنزيل Parallels لتصحيح الأخطاء بشكل صحيح.  تشغيل Microsoft Office و Visual Studio code في Parallels سيتيح لك تصحيح أخطاء التطبيقات والعمل على الوظيفة الإضافية بشكل صحيح. إنها ليست حلاً مثالياً بنسبة 100٪، ولكنها تؤدي الغرض المطلوب!

النصيحة 5: مشاركة الوظيفة الإضافية مع المستخدمين

يتم تحميل الوظائف الإضافية لـ Office في عرض الويب الذي يعمل في تطبيقات Office ويتم عرضها باستخدام iFrames، لذا ستحتاج إلى استضافتها على خادم الشبكة الذي يمكنك الوصول إليه. يمكنك قراءة المزيد حول كيفية نشر وإصدار وظائف Office الإضافية في وثائق Microsoft. 

بمجرد تثبيت الوظيفة الإضافية وتشغيلها، يمكن لأي مسؤول Office نشرها للمستخدمين والمجموعات في مؤسستهم عبر مركز إدارة Microsoft 365. يمكن استخدام الوظائف الإضافية التي تم نشرها عبر مركز الإدارة على الفور.

المكافأة: توسيع نطاق الوظيفة الإضافية لتشمل تطبيقات Microsoft الأخرى 

من السهل توسيع نطاق الوظيفة الإضافية لتشمل تطبيقات أخرى. تشترك الوظائف الإضافية لبرنامج Office في العديد من المكونات، وينبغي أن تعمل الوظيفة الإضافية لأحد التطبيقات في جميع التطبيقات المدعومة (Outlook وWord وExcel وPowerPoint وVisio وOneNote).

ومع ذلك، فإن جميع التطبيقات لها أحداث مختلفة. في مثال Word الخاص بنا، استخدمنا OnTextSelected، بينما في Excel من المحتمل أن تستخدم شيئًا مثل OnColumnSelected أو Row. لجعل الوظيفة الإضافية تعمل في تطبيقات أخرى، إضافة الأحداث أو الإجراءات المقابلة التي تريد أن تستجيب لها الوظيفة الإضافية — الأمر بهذه البساطة. يمكن إعادة استخدام معظم الكود الخاص بك عبر التطبيقات.  

يُنصح عمومًا بتحويل الكود الخاص بك إلى دالة يمكنك إعادة استخدامها واستدعائها مرة أخرى مع خصائص تطبيقك التي تحتاجها. نقترح قراءة المقالات المتوفرة هنا.

كما أن هناك وحدة تعلم من MS Learn يمكن أن تساعدك.

الختام

نأمل أن تكون هذه النظرة العامة مفيدة لك! إذا كان لديك أي أسئلة، فلا تتردد في إنشاء مشكلة في مستودع GitHub مع مقتطف Script Lab وإبلاغنا بها.  

نتمنى لكم كل التوفيق في رحلتكم مع DeepL API-Microsoft Office.