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 sextas-feiras de hack são uma excelente oportunidade para experimentar a nossa API e, por vezes, os resultados chegam aos utilizadores. De facto, o nosso script Google Sheets-DeepL, lançado recentemente, foi o resultado de um projeto Hack Friday. Num Hack Friday em setembro de 2022, o programador de software da DeepL, Marvin Becker, e o evangelista de desenvolvimento, Tim Cadenbach, criaram um protótipo de complemento da API do DeepL para o Microsoft Word, possibilitando aos utilizadores traduzir com o DeepL diretamente 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 uso popular do DeepL — as traduções do DeepL podem permitir que uma força de trabalho internacional e multilingue colabore de forma eficiente , mantendo a segurança de dados confidenciais da empresa. Frequentemente recebemos solicitações de clientes que desejam desenvolver o seu próprio complemento do Office com a API do DeepL e estão à procura de 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. Também forneceremos código aberto para auxiliá-lo a iniciar o seu projeto mais rapidamente. Pronto? Mãos à obra! 

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

Se você é novo nas APIs do Office, sugerimos a leitura de Compreender a API JavaScript do Office na documentação da Microsoft. Em resumo, todos os produtos Office oferecem uma API comum com APIs específicas do produto adicionais. Também pode ser útil dar uma vista de olhos neste tutorial este tutorial antes de passar para a Dica 1. 

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

O Script Lab é um projeto de código aberto 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 Laboratório de Roteiros Repositório GitHub inclui um tutorial para auxiliá-lo 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 registar-se numa conta aqui.

Basta copiar e colar o Gist YAML conforme descrito nas instruções, inserir a sua chave de API do DeepL no espaço reservado na linha 32 e poderá executar o nosso snippet com apenas alguns cliques.

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: Suplemento do Office Yeoman Gerador.

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". Isso iniciará o Word e carregará automaticamente o seu suplemento. É possível utilizar qualquer IDE para desenvolvimento, embora o modelo gerado funcione melhor com os editores de código da Microsoft, VS Code ou Visual Studio. 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. Caso deseje ativar Glossários no seu suplemento, será necessário um pouco mais de trabalho.

Não utilizámos a biblioteca cliente oficial do DeepL para Node.js. para o projeto, pois a biblioteca de cliente não se destina a código JavaScript do lado do cliente. para o projeto, pois a biblioteca não se destina a código JavaScript do lado do cliente. A razão para isso é a segurança — você exporia a sua chave de API ao chamar o código do lado do cliente. Você pode consultar o ficheiro GIST que partilhamos acima para ver a nossa abordagem com mais detalhes (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.  Executando o Microsoft Office e o Visual Studio Code no Parallels permitirá que você depure aplicações e trabalhe no suplemento corretamente. 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. Pode ler mais sobre como implementar e publicar suplementos do Office na documentação da Microsoft. 

Após ter o suplemento instalado e em funcionamento, qualquer administrador do Office poderá implementar-lo para utilizadores e grupos na sua 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, utilizamos OnTextSelected, enquanto que no Excel provavelmente utilizaria algo como OnColumnSelected ou Row. Para que o seu suplemento funcione em outras aplicações, adicione os eventos ou ações correspondentes aos quais deseja que o seu suplemento reaja — é simples assim. 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 leitura dos artigos disponíveis aqui.

Além disso, existe um excelente módulo do MS aprender que pode ser útil.

Nota final

Esperamos que esta descrição geral lhe tenha sido útil! Caso tenha alguma dúvida, sinta-se à vontade para criar uma questão no repositório GitHub com o trecho do Script Lab e nos informar.  

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