DeepL Logo

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

Каждый месяц в нашей компании проходит мероприятие под названием Hack Friday: в этот день сотрудники DeepL могут посвятить время работе над проектами, выходящими за рамки их повседневных задач. Для многих сотрудников это отличная возможность поработать с нашим API, и иногда результаты такой работы доходят и до наших пользователей. Например, недавно опубликованный скрипт DeepL для Google Sheets как раз был создан в рамках одного из проектов Hack Friday!

В сентябре 2022 года разработчик Марвин Беккер и технологический евангелист Тим Каденбах создали прототип надстройки DeepL API для Microsoft Word, с помощью которого переводы с DeepL можно выполнять непосредственно в документах Word.

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

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

Бизнес-коммуникации – одна из основных сфер применения DeepL. Технология перевода от DeepL может упростить процессы коммуникации в международных и многоязычных компаниях, обеспечивая конфиденциальность корпоративной информации при переводе. Мы часто получаем сообщения от клиентов, которые хотят создать свои собственные надстройки для Office с использованием API от DeepL и ищут ресурсы для начала работы. Мы захотели на собственном опыте узнать, что именно требуется для создания интеграции, чтобы понять, как мы можем оптимальным образом помочь клиентам, работающим над собственными надстройками. 

В этом посте мы расскажем о том, что нам удалось узнать. Мы также поделимся примером кода, чтобы вам было проще начать работу над собственным проектом.

Готовы? Приступим! 

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

Если вы никогда не работали с API Office, мы советуем вам ознакомиться с материалом Общие сведения об API JavaScript для Office в документации Microsoft. Для всех продуктов Office доступен ряд как общих API, так и API для конкретных продуктов.

Также может быть полезно просмотреть этот учебник

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

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

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

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

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

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

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

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

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

Мы создали несколько прототипов в 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: Реализация API от DeepL

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

В этом проекте мы не стали использовать официальную клиентскую библиотеку DeepL для Node.js, потому что эта библиотека не предназначена для кода клиентской части на JavaScript. Это связано с вопросами безопасности: при вызове кода клиентской части ваш ключ API был бы раскрыт.

Чтобы ознакомиться с нашим подходом, просмотрите этот файл GIST (начиная со строки 102).

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

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

Запустив Microsoft Office и Visual Studio Сode в 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, с которым вам нужна помощь.  

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