German post was automatically translated by DeepL API and manually reviewed
In March I tried SharePoint Premium Translation. SharePoint Premium cannot currently translate SharePoint Pages (like SharePoint News), and for operational topics, SharePoint Premium Translation is an unknown black box with no cost ceiling.
DeepL provides a similar feature via the DeepL API and can be linked to SharePoint via code. The documentation describes how translation is carried out via API.
It’s good to know that the API supports the translation of HTML text. The API leaves HTML tags as they are and only translates the text in the tags. The HTML structure and formatting should remain as they are.
- Images and hyperlinks are not translated, but their position is not changed.
- The API does not translate image descriptions for SharePoint pages.
- Depending on the hyperlink and text, the translation may move the hyperlink.
I wrote a translation bot for my blog via DeepL API, translating my German texts into English since March.
I wanted to know how to automatically translate a SharePoint page via the DeepL API. DeepL provides a Power Platform Connector. The connector also uses the API.
I wrote the PowerShell script Request-TASPOPageTranslation without any connector. After the initial setup, the script translates a SharePoint page into an alternative language in less than 15 seconds.
Below, you will find information and requirements about the script. I can provide support via email or LinkedIn if you have any questions.
Content
Requirements
DeepL API Key
An API key is required for translation with DeepL.
DeepL API provides three subscription packages. The free package includes 500,000 characters per month. If your organization already uses a Pro or Business package for other integrations, it only needs a new API key from the account.
A free account can be created quickly. To prevent misuse, DeepL requires a credit card to register. The card will not be charged.
After registration, DeepL has already created an API key. You can use it or create a new one. As usual with API keys, keep the key secret.
Compared to SharePoint Premium Translation, DeepL transparently and in real time shows how many characters the account has already used in the billing period. In the Pro package, you can also define a monthly cost limit.
PowerShell and PowerShell modules
I expect PowerShell 7 and three PowerShell modules for my script.
- PowerShell 7
The script was tested with PowerShell 7.4. It is not compatible with PowerShell 5.
- PnP.PowerShell
The script uses commands from the PnP.PowerShell module. The module must be installed from version 2.4.0.
- Az.KeyVault and Az.Accounts
In my script, I obtain the API key from an Azure KeyVault. To do this, the PowerShell module Az.KeyVault must be installed from version 5 and Az. Accounts from version 2.13.x. The modules are interdependent.
You should not save the API key in the script. As my script does not run in Azure, I use an Azure app in conjunction with KeyVault. Mahdi Tehrani describes how to set this up in his YouTube video. Alternatively, you can use a Managed Identity in Azure.
Further notes
- I have tested the script in multiple forms for sites in SharePoint Online and PowerShell 7.
- The script wants to know a SharePoint Online URL via the SiteUrl parameter. When executed, it asks for login data for the site collection. The account requires at least written access to the content or more. Alternatively, you can customize the script and link Connect-PnPOnline to an Azure app. This allows it to establish the connection automatically.
- I use my Get-TASPOPageLanguages command in the script to evaluate the languages per SharePoint page.
- I use my Build-TALanguageTable command in the script to merge the languages between SharePoint and DeepL API.
- The script translates the title, the short description, and the content of the page.
- The script supports German, English, Italian, French, and Spanish. You can easily add further languages in Build-TALanguageTable.
- In the standard configuration, the script uses the DeepL Free API. If you have a Pro or Business package, use the DeepLEdition parameter.
- In the standard configuration, the script does not publish a translation. The translated SharePoint page is left in draft form. With the PublishPage parameter, the script can publish the page at the end.
- In the standard configuration, the script inserts a note about the automatic translation at the beginning of the translated page. With the SkipTranslationNote parameter, the note is not inserted. The addition may not work as expected for all pages. Due to the page’s HTML structure, it may skip the note.
- Information about available parameters in my documentation.
Execute and translate
- Download the script Request-TASPOPageTranslation.ps1 from my GitHub repository.
- I load the Azure App and KeyVault variables in the script via an externally stored environment file. Customize the connection according to your needs.
$EnvVar = Get-Content ".\Env\SPOPageTranslation.env" | ConvertFrom-StringData- The script should now translate a SharePoint site.
.\Request-TASPOPageTranslation.ps1 -PageID 3 -TranslationLanguage EN -SiteUrl <SharePointSiteUrl>
Examples
I translated various pages for testing. None of the translations were modified manually.
