Criar um suplemento da API do DeepL para o Microsoft Office (em apenas um dia)

Todos os meses, os funcionários da DeepL participam num evento empresarial denominado "Hack Friday", no qual desenvolvem projetos fora do seu trabalho habitual. As "Hack Fridays" são excelentes oportunidades para realizar experiências na nossa API. Por vezes, o resultado desses trabalhos é disponibilizado aos utilizadores finais. Na verdade, o nosso script Google Sheets-DeepL foi o resultado de um projeto da Hack Friday!

Numa Hack Friday em setembro de 2022, o programador de software da DeepL Marvin Becker e o evangelista de programação Tim Cadenbach criaram um protótipo de suplemento da API do DeepL para o Microsoft Word, permitindo que os utilizadores traduzam diretamente com o DeepL num documento do Word.

Pode vê-lo em ação aqui:

Porque é que esta integração é do nosso interesse?

A comunicação empresarial é um caso de utilização popular no DeepL. Com as suas traduções, o DeepL possibilita a colaboração eficiente entre equipas multilingues globais, protegendo simultaneamente os dados confidenciais das empresas. Recebemos frequentemente pedidos de clientes que desejam criar o seu próprio suplemento do Office com a API do DeepL e que procuram recursos para começar. Queríamos conhecer em primeira mão os requisitos da integração, para podermos fornecer respostas mais pormenorizadas quando os nossos clientes nos colocassem questões. 

Neste artigo, iremos partilhar o que aprendemos. Forneceremos também código aberto, para o ajudar a iniciar o seu projeto mais depressa.

Tudo a postos? Mãos à obra! 

Passo 0 (opcional): Faça algum trabalho de investigação  

Se estiver a utilizar as APIs do Office pela primeira vez, sugerimos que consulte o artigo Understanding the Office JavaScript API na documentação da Microsoft. Em resumo, todos os produto do Office fornecem uma API comum com uma camada sobreposta de APIs específicas de cada produto.

Sugerimos também uma breve consulta deste tutorial antes de avançar para o passo 1 

Passo 1: Crie um protótipo com o Script Lab (ou utilizar o nosso) 

O Script Lab é um projeto open-source mantido pela Microsoft. O Script Lab permite-lhe realizar experiências na Office JavaScript API, sem ter de sair do Excel, Outlook, Word ou PowerPoint. O repositório do GitHub do Script Lab inclui um tutorial para o ajudar a começar.

Utilizámos o Script Lab para criar um protótipo inicial do nosso suplemento, porque é um método ideal de escrever código rapidamente e de ver a sua aplicação prática, consistindo apenas num único ficheiro JavaScript, HTML e CSS.

Este passo inicial não é o suplemento em si que poderá partilhar com os membro da equipa, mas irá dar-lhe uma ideia do que é possível alcançar com a API do DeepL e o tipo de experiência de utilizador que conseguirá disponibilizar com o seu suplemento.

No início deste artigo, prometemos-lhe o acesso a código aberto! O Script Lab oferece uma forma de importar o "snippet" de outra pessoa, pelo que disponibilizámos o snippet do DeepL-Word em regime de open-source, para que qualquer pessoa possa experimentar. Poderá encontrá-lo no GitHub aqui.

Também irá precisar de uma chave da API do DeepL, se quiser acompanhar este passo. Pode assinar um plano da API do DeepL aqui.

Para executar o nosso snippet com apenas alguns cliques, basta copiar e colar o ficheiro Gist YAML, tal como descrito nas instruções e inserir a sua chave da API do DeepL no marcador de posição que se encontra na linha 32.

E o melhor de tudo? O snippet do Script Lab pode ser reaproveitado enquanto configura o modelo do suplemento, pelo que todo o trabalho que realizar no Script Lab ser-lhe-á útil no futuro.

Passo 2: Crie um projeto do suplemento do Office com o Yeoman Generator

Agora que já desenvolveu algum trabalho de prototipagem no Script Lab e conhece os aspetos fundamentais da criação de scripts do Office, pode começar a criar o suplemento em si no Yeoman. O Yeoman é uma ferramenta de scaffolding em código aberto que permite criar novos projetos com relativa facilidade. No caso dos suplementos do Office, existe um modelo pré-concebido que pode utilizar, e que é frequentemente designado por “Yo Office”. 

O processo é descrito aqui: Create Office Add-in projects using the Yeoman Generator.

Após seguir as instruções de configuração, copie o código do Script Lab para o seu repositório recentemente criado. Há mais configurações para fazer, mas pode começar de imediato, ao executar o comando "npm run start". Esta ação irá iniciar o Word automaticamente e colocará o seu suplemento em sideload.

Pode utilizar qualquer IDE para a programação. Contudo, o modelo gerado funciona melhor com os editores de código VS Code ou Visual Studio da Microsoft. Para uma melhor experiência de programação e depuração recomendamos a utilização do Visual Studio.

Passo 3: Implemente a API do DeepL

A nossa implementação do DeepL é simples e direta: um script JavaScript de obtenção de dados faz uma chama ao ponto final de tradução de texto. Isto foi suficiente para o nosso protótipo simples. Se quiser ativar glossários no seu suplemento, terá de investir mais algum tempo.

Neste projeto, não utilizámos a biblioteca de cliente Node.js oficial do DeepL, uma vez que a biblioteca não se destina a código JavaScript do lado do cliente. O motivo, neste caso, prende-se com questões de segurança. Se fizesse uma chamada ao código do lado do cliente, estaria a expor a sua chave da API.

Pode dar uma vista de olhos pelo ficheiro GIST que partilhámos acima, para compreender a nossa abordagem em mais detalhe (a partir da linha 102).

Passo 4: Depuração para utilizadores de Mac 

Nos últimos anos, a Microsoft tem feito investimentos significativos para disponibilizar suporte a utilizadores de Mac. Embora o suporte para Mac seja bastante bom em programação .NET Core, ainda não está suficientemente desenvolvido na programação dos componentes essenciais do Windows, incluindo as aplicações do Microsoft Office. Infelizmente, as versões das aplicações da Microsoft para utilizadores de Mac não estão configuradas para uma depuração fácil. O Tim, que é especialista (e MVP!) em tudo o que diga respeito à Microsoft, não teve quaisquer problemas, mas o Marvin, que utiliza Mac, necessitou de transferir o Parallels para conseguir depurar em condições. 

Executar código do Microsoft Office e Visual Studio no Parallels irá permitir-lhe depurar aplicações e trabalhar adequadamente no suplemento. Não é uma solução 100% perfeita, mas funciona!

Passo 5: Partilhe o seu suplemento com os utilizadores

Os suplementos do Office são carregados na vista web que é executada nas aplicações do Office e são apresentados através de iFrames, pelo que terá de alojar o seu suplemento num servidor web ao qual tenha acesso. Consulte a documentação da Microsoft para saber como implementar e publicar suplementos do Office. 

Quando o seu suplemento estiver funcional, qualquer administrador do Office o poderá implementar para os utilizadores e grupos na respetiva organização através do centro de administração do Microsoft 365. Os suplementos implementados através do centro de administração estão disponíveis para utilização imediata.

Dica extra: Alargue o seu suplemento a outras aplicações Microsoft 

É fácil alargar o seu suplemento a outras aplicações. Os suplementos do Office partilham imensos componentes, pelo que o suplemento de uma aplicação deverá funcionar em todas as aplicações suportadas (Outlook, Word, Excel, PowerPoint, Visio e OneNote).

Contudo, todas as aplicações têm eventos diferentes. No nosso exemplo do Word, temos estado a utilizar "OnTextSelected". Se quiser trabalhar no Excel, terá provavelmente de utilizar algo como "OnColumnSelected" ou "Row".

Para que o seu suplemento funcione noutras aplicações, adicione os eventos ou ações correspondentes que deverão desencadear uma reação por parte do suplemento. Nada mais simples! A maior parte do seu código poderá ser reaproveitado entre as várias aplicações.  

É geralmente aconselhável converter o seu código específico numa função, que poderá reutilizar e chamar novamente, juntamente com os elementos específicos da aplicação que são necessários. Recomendamos a consulta dos artigos disponíveis aqui.

Este excelente módulo do Microsoft Learn também poderá ajudar.

Nota final

Esperamos que esta descrição geral lhe tenha sido útil! Caso tenha alguma questão, crie um pedido de suporte no repositório do GitHub com o snippet do Script Lab e descreva-nos a sua situação.  

Desejamos-lhe um ótimo trabalho no seu percurso de integração da API do DeepL com o Microsoft Office.