Microsoft OfficeのDeepL APIアドインを1日で作る
DeepLでは月に一度、「ハックフライデー」と称して、日々の業務以外のプロジェクトに取り組む日を設けています。ハックフライデーは、DeepLのAPIをあれこれいじってみる良い機会で、成果をユーザーにお届けできる場合もあります。実際、最近リリースしたGoogle Sheetsのためのスクリプトはハックフライデーから生まれました。
2022年9月のハックフライデーに、DeepLで働くソフトエンジニアのMarvin BeckerとデベロッパーエバンジェリストのTim CadenbachがMicrosoft Wordで直接翻訳できるDeepL APIアドインのプロトタイプを作りました。
こちらで実際の動作をご覧ください。
開発の経緯
多言語を使うグローバルなチームが取り扱いに注意が必要なデータの安全性を確保しながら効率的に協力できるということで、DeepL翻訳はビジネスコミュニケーションの場で広く活用されています。DeepL APIを使って独自にOfficeアドインを作成したいけれど、リソースはどこにあるかという声をよく耳にして、皆さんから質問を受けた際により適切な回答ができるように、アドインで機能を追加するための要件は何か知りたいと考えたのがそもそものきっかけでした。
今回のブログでは、私たちの学びを共有したいと思います。また、皆さんのプロジェクトをスムーズに開始できるように、オープンソースのコードもご紹介します。
準備はいいですか？では、始めましょう！
キーポイント0：下調べ（任意）
Office APIを初めて使う場合は、MicrosoftのOffice JavaScript APIについてをご一読ください。すべてのOffice製品には共通APIと固有の各種APIがあります。
キーポイント1へ進む前に、こちらのチュートリアルにも目を通しておくとよいかもしれません。
キーポイント1：Script Labを使ってプロトタイプを構築（DeepLのScript Labも使用可能）
Script LabはMicrosoftのオープンソースプロジェクトです。Script LabがあればExcel、Outlook、Word、PowerPointを使いながらOffice JavaScript APIを試せます。Script LabのGitHubリポジトリでは、始め方に関するチュートリアルもあります。
DeepLではアドインのプロトタイプを作成するにあたり、まずScript Labを使いました。JavaScript、HTML、CSSファイルからのみ構成されるScript Labを使うと、コードを早く書けるだけでなく、動作もすぐに確認できます。
この最初のステップではチームで共有できるアドインはまだ作成できませんが、DeepL APIを使って何ができるか、またアドインで実現できるユーザー体験は何かをイメージできます。
キーポイントの説明に入る前に、オープンソースのコードもご紹介すると書きました。Script Labでは別の人が書いたコードの「スニペット」をインポートできることから、DeepL Wordのスニペットもオープンソースにして、誰にでも試していただけるようにしました。コードはこちらのGitHubに記載しています。
なお、作業を続けるにはDeepL APIの認証キーが必要です。まだアカウントをお持ちでない方はこちらからご登録ください。
こちらの説明を参考にしてGist YAMLをコピー＆ペーストし、DeepL APIの認証キーを32行目のプレースホルダに挿入すると、DeepLのスニペットを数クリックで実行できるようになります。
最大のメリットScript Labではアドインのテンプレートを準備できるため、スニペットを後で別の用途に簡単に転用できます。
キーポイント2：Yeoman GeneratorでOfficeアドインのプロジェクトを作成
Script Labのプロトタイプを作成し、Officeスクリプトの基本を理解できたところで、Yeomenを使って実際のアドインを作ってみましょう。Yeomanは、新規プロジェクトを比較的簡単に作成できるオープンソースのスキャフォールディングツールです。Officeアドイン向けには、通称”Yo Office”というMicrosoftの既存のテンプレートがあります。
手順はOffice Add-in Yeoman Generatorでご覧いただけます。
セットアップが終わったら、Script Labのコードを新しく作成したリポジトリにコピーします。細かな設定は他にもありますが、'npm run start’を実行するとすぐに作業を開始できます。実行するとWordが開き、アドインを自動でサイドロードします。
開発にはどんなIDEも使えますが、作成したテンプレートはMicrosoftのオリジナルのコードで最もスムーズに動作します。快適にコード作成とデバッグを行うには、Visual Studioを使うのががおすすめです。
キーポイント3：DeepL APIを実装
DeepLの実装は簡単です。JavaScript fetch scriptでテキスト翻訳のエンドポイントを呼び出せます。私たちが作成した簡単なプロトタイプでは、これで十分でした。アドインで用語集を使うには、もう少し作業が必要です。
プロジェクトではDeepL公式のNode.js client library を使用しませんでしたが、これはクライアント側のJavaScript code向けではないことが理由です。クライアント側のコードを呼び出す際にAPI認証キーが見える状態になり、セキュリティが確保できません。
上でご紹介したGIST fileの102行目以降に、私たちの採用した方法を記載しています。
キーポイント4：Macユーザーのためのデバッグ
近年、MicrosoftはMacユーザーをサポートできるように莫大な投資を行っています。Macでは.NET Coreの開発ができますが、Microsoft OfficeのアプリケーションなどWindowsの開発を十分に行うのはまだ難しいのが現状です。残念ながら、MicrosoftアプリケーションのMac版のデバッグは簡単ではありません。TimはMicrosoftの愛用者（Microsoft MVPにも認定されています！）なので問題はありませんでしたが、MacユーザーのMarvinは適切にデバッグを行うためにParallelsをダウンロードしなければなりませんでした。
ParallelsでMicrosoft OfficeとVisual Studio Codeを動かすと、アプリのデバッグやアドインを使った作業を適切に行えます。100％満足できる解決策ではありませんが、ひとまずこれでOKです。
キーポイント5：ユーザーとアドインを共有
OfficeアドインはOfficeアプリを実行するウェブビューに読み込まれ、iFrame（インラインフレーム）に表示されるので、アクセスできるウェブサーバーでご自身のアドインをホストしなければなりません。詳しくは、MicrosoftのOfficeアドインを展開し、発行するをご参照ください。
アドインを使用する準備ができたら、Officeの管理者は誰でもMicrosoft 365管理センターで組織内のユーザーやグループにアドインを展開できます。管理センターで展開したアドインは、すぐに使用できます。
おまけ：他のMicrosoftアプリにアドインを拡張
アドインは他のアプリにも簡単に拡張できます。Officeアドインの構成要素の多くは、Outlook、Word、Excel、PowerPoint、Visio、OneNoteなどすべてのOfficeアプリケーションで共通です。そのため、ひとつのアプリケーション用のアドインを使い回せます。
ただし、アプリケーションごとにイベントは異なります。例えば今回ご紹介したWordではOnTextSelectedを使っていますが、ExcelではOnColumnSelectedやRowが必要になります。
他のアプリケーションでもアドインを動作させるには、アドインを適用したいイベントやアクションを追加するだけでOKです。ほとんどのコードは異なるアプリケーションで再利用できます。
必要なアプリケーションの仕様を再利用したり呼び出したりできるように、固有のコードを関数化しておくと良いでしょう。こちらの関連記事もご参照ください。
Microsoftのトレーニングモジュールも便利です。
まとめ
ここまでの内容がお役に立てば幸いです。何か分からないことがあれば、GitHubのリポジトリでレポート（issue）を作成して、関連するScript Labのスニペットをお知らせください。
開発のご成功を祈ります！
