Как создать надстройку DeepL API для Microsoft Office (всего за один день)

Каждый месяц в нашей компании проходит мероприятие под названием Hack Friday: в этот день сотрудники DeepL могут посвятить время работе над проектами, выходящими за рамки их повседневных задач. Пятницы хакеров предоставляют отличную возможность поработать с нашим API, и иногда результаты этой работы становятся доступны пользователям. Наш недавно выпущенный скрипт Google Sheets-DeepL был разработан в рамках проекта Hack Friday. В рамках Hack Friday в сентябре 2022 года разработчик программного обеспечения DeepL Марвин Беккер и разработчик-евангелист Тим Каденбах создали прототип надстройки DeepL API для Microsoft Word, что позволило пользователям переводить с помощью DeepL непосредственно в документе Word.

Вот как это работает:

Почему мы заинтересовались этой интеграцией?

Деловая коммуникация является популярным случаем использования DeepL — переводы DeepL позволяют глобальному многоязычному персоналу эффективно сотрудничать, обеспечивая при этом безопасность конфиденциальных данных компании. , обеспечивая при этом безопасность конфиденциальных данных компании. Мы часто получаем запросы от клиентов, которые желают создать собственную надстройку для Of‡fice с помощью API от DeepL и ищут ресурсы для начала работы. Мы захотели на собственном опыте узнать, что именно требуется для создания интеграции, чтобы понять, как мы можем оптимальным образом помочь клиентам, работающим над собственными надстройками. 

В этом посте мы расскажем о том, что нам удалось узнать. Мы также предоставим открытый исходный код, который поможет вам быстрее запустить свой проект. Готовы к работе с ? Приступим! 

Перед началом работы: ознакомьтесь с теорией (опционально)  

Если вы только начинаете знакомиться с API Office, рекомендуем ознакомиться со статьей Разбираемся в Office JavaScript API в документации Microsoft. Вкратце, все продукты Office предоставляют общий API с специфичными для продукта API . Также может быть полезно ознакомиться с этот учебник , прежде чем переходить к совету 1. 

Совет 1: Создание прототипа с помощью Script Lab (или просто используйте наш прототип) 

Script Lab — это проект с открытым исходным кодом, поддерживаемый компанией Microsoft. С помощью Script Lab с API JavaScript для Office можно экспериментировать непосредственно в Excel, Outlook, Word и PowerPoint. Лаборатория сценариев Репозиторий GitHub содержит учебник, который поможет вам начать работу.

Мы создали прототип нашей надстройки именно в Script Lab, поскольку это очень удобный способ быстро написать код и сразу же увидеть его в действии. Код при этом состоит из одного файла JavaScript, HTML и CSS.

Таким прототипом надстройки рано делиться с командой, но он позволит вам получить общее представление о возможностях DeepL API и о том, насколько удобной ваша надстройка будет для конечных пользователей.

Как мы и обещали выше, теперь мы приведем пример открытого исходного кода. В Script Lab можно импортировать готовые фрагменты кода, и мы открыли доступ к коду DeepL-Word, чтобы все желающие могли попробовать с ним поработать. Он доступен на GitHub по этой ссылке.

На этом этапе вам также понадобится ключ авторизации DeepL API. Вы можете зарегистрироваться здесь.

Просто копировать и вставлять Gist YAML, как указано в инструкциях, вставлять свой ключ API от DeepL в местозаполнитель в строке 32, и вы сможете запустить наш фрагмент кода всего за несколько нажатий.

Самое интересное? Фрагмент кода Script Lab можно повторно использовать при настройке шаблона надстройки, поэтому вся работа, проделанная в Script Lab, пригодится позже.

Шаг 2: Создание проекта надстройки для Office с помощью генератора Yeoman

Мы создали несколько прототипов в Script Lab и ознакомились с основами создания сценариев Office, и теперь мы можем приступить к созданию собственной надстройки с помощью Yeoman. Yeoman – это инструмент для скаффолдинга с открытым исходным кодом, который позволяет относительно легко создавать новые проекты. Для надстроек Office существует готовый шаблон от Microsoft («Yo Office»). 

Процесс создания надстроек подробно описан здесь: Надстройка для Office Yeoman Generator.

Следуя инструкциям по настройке, скопируйте код из Script Lab в свой новый репозиторий. Вы также можете задать некоторые дополнительные настройки, но работу можно начать и сразу же, выполнив команду 'npm run start'. Это запустит Word и автоматически загрузит ваше дополнение. Для разработки можно использовать любую IDE, однако сгенерированный шаблон лучше всего работает с собственными редакторами кода Microsoft VS Code или Visual Studio. Для большего удобства при написании кода и отладке мы рекомендуем вам использовать Visual Studio.

Шаг 3: Реализация API от DeepL

Наша реализация DeepL проста – fetch-запрос JavaScript обращается к конечной точке для перевода текста. Для нашего простого прототипа этого было достаточно. Если вы хотите включить Глоссарии в вашій надстройці, вам потребується приложити додаткові зусилля.

Мы не использовали официальную библиотеку DeepL для Node.js. Node.js клиентская библиотека для проекта, поскольку она не предназначена для клиентского кода JavaScript. Причина заключается в безопасности — при вызове кода на стороне клиента вы раскрываете свой ключ API. Вы можете ознакомиться с файлом GIST, который мы предоставили выше, чтобы более подробно изучить наш подход (начиная со строки 102).

Шаг 4: Отладка для пользователей Mac 

За последние годы Microsoft сделала многие из своих приложений доступными и для пользователей Mac. Хотя система Mac вполне подходит для .NET-разработки, ее довольно сложно использовать для разработки под Windows – это относится и к приложениям Office. К сожалению, версии приложений Microsoft для Mac не настроены для легкой отладки. Тим – приверженец Microsoft (и MVP!), поэтому у него не возникло никаких проблем, но Марвину, пользователю Mac, пришлось использовать для отладки Parallels.  Запуск Microsoft Office и Visual Studio Code в Parallels позволяет отлаживать приложения и работать над надстройкой надлежащим образом. Это не самый очевидный вариант, но он работает!

Шаг 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 и сообщите нам.  

Желаем вам плодотворной работы!