SharePoint Premium Document Translation is an awesome new feature to allow staff to translate documents from SharePoint document libraries. This is done either on-demand by pressing a button to translate files or by SharePoint document library rules. I previously blogged & reviewed SharePoint Premium Document Translation (link) and I was very impressed! Today I will demonstrate how to automate Document Translation using the Microsoft Syntex API (REST) with Power Automate or PowerShell.

This opens up numerous automation possibilities by enabling the translation process to be invoked programmatically through workflows in Power AutomateLogic Apps, or any other software language capable of making a REST API call. Now build advanced conditional logic with approval, document movement, security trimming, customised notifications, reporting etc

Some Ideas

  • Build a document approval system and when approved translate the document into 10 different languages.
    • Where category equals “Manual” instead translate into 20 languages etc
    • Where a document is translated into Dutch notify Ronald Koeman who will review the translation before publishing to a different site etc
    • Security trim, place in specific locations so users only see documents in their native langauge.
  • Translate a document into many different languages at once. The UI for translate from the document library (on-demand) currently only allows one language translation at a time.
  • Allow a line of business system to produce documents & auto translate them using SharePoint Premium Document Translation service.
  • Migrate documents from a file share into SharePoint online. Then translate into 10 languages and move each copy to the the relevant language subfolder/site etc.

The API Call

The Document Translation feature of the Microsoft Syntex REST API is currently undocumented, which means it might undergo changes. However, I’ve analysed the network calls using the developer toolbar in my Edge browser. Interestingly, these calls are utilising the same endpoints as those used for creating file classification requests in document processing models. Additionally, the JSON body structure appears to be similar. Based on this observation, I believe that the endpoints and body patterns are unlikely to change significantly, especially since they align with the established Syntex REST APIs.

In order to perform Document Translation on a document it needs to be in a SharePoint library (& the site enabled for Document Translation). A request body in JSON then needs to be created with details of where (site, web, document) the document is located in URL or ID format. Along with the target language code (multiple can be entered seperate by a comma) for the translation i.e. FR.

Two sample request bodies are below:

Request Body (ID Format) – Multiple Languages Requested For Translation

This JSON body shows targeting a file with IDs i.e. SiteId, WebID, Doc UniqueID. We request the document to be translated into 5 languages by combining language codes separated by commas in the TargetLanguages part of the ExtraPropertyList section.

Request Body (URL Format) – Single Language Requested For Translation

This JSON body shows targeting a file with URL paths and requesting the document to be translated into a single language (mi = Māori language).

Request Headers

The following headers for your call are also required.

HeaderValue
Acceptapplication/json;odata=verbose
Content-Typeapplication/json;odata=verbose;charset=utf-8

Request URL

The Request Body (in JSON) and the Request Headers need to be included in a call to the following SharePoint Premium Rest API endpoint. This is then combined with your site url i.e. “https://leonarmston.sharepoint.com/_api/machinelearning/workItems

Bonus (Batching)

Document Translation also supports OData batch so multiple requests (for multiple documents) can be combined into a single call reducing web traffic and decreasing total processing time. (More Details Here)

The REST service of SharePoint Online supports the combining of multiple requests. Requests are combined into a single call to the service by using the OData $batch query option. This method can be used to enqueue classification work items for hundreds of documents at one time.

Quote from https://learn.microsoft.com/en-us/sharepoint/dev/apis/syntex/rest-createclassificationrequest

Automate Document Translation in Power Automate

In this section I will show you how we can use what we’ve learned to translate documents using Power Automate. I am not going to do a step by step guide but the the templated flow is available to download here. You can then install this in your Power Automate environment and configure to your heart’s content!

The templated Flow in Power Automate is designed to be manually triggered. When a user initiates the flow, they are prompted to input the Item ID of the file they want to translate, along with the language codes corresponding to the desired target language(s). There are also some hardcoded variables in the Flow to change for your tenant name, site URL and library name. There are no Premium Actions in the Flow and this can all be done under standard licencing (your tenant and site needs configuring for Syntex PAYG)

Obviously this could be made more integrated and not prompt users for IDs but I wanted to show the proof of concept.

The flow receives a Document ID and language code(s) to translate. Then through various SharePoint REST API calls gets the Document unique ID (GUID) & then the site and web ID. Then in the final action sends these details in a Request body (JSON) to the Document Translation API (see below for a screenshot of the last action).

Automate Document Translation in PowerShell

I will now show how Document Translation can be done using PnP PowerShell by building the Request Body in JSON for a document and then submitting the details for document to be then translated.

There are are two options for the Request body for the call ID format and URL format – I will show them both below:

Request Body (ID Format) – Multiple Languages Requested For Translation

This script requires lines 1-4 to be completed with details of the site, document, library title and the language code(s) for the translation. Then the rest of the script obtains the SiteID, WebID and DocumentUniqueID to add to the Request body and then submits using Invoke-PnPSPRestMethod.

Once submitted the script will report the following to indicate the Document has been queued for translation.

The document is then duplicated, then translated into five different copies in five different languages in the library.

Request Body (URL Format) – Single Language Requested For Translation

This script requires lines 1-4 to be completed with details of the document and the language code(s) for the translation. Then the rest of the script obtains the SiteUrl, WebServerRelativeUrl and DocumentUniqueID to add to the Request body and then submits using Invoke-PnPSPRestMethod.

Once submitted the script will report the following to indicate the Document has been queued for translation.

The document is then duplicated & translated into Māori in the library.

Summary

The ability to invoke the Document Translation API programmatically, either through Power Automate or custom code, is incredibly powerful for integrated solutions and automation. Consider a scenario where documents are added to SharePoint from various line-of-business systems. By automatically translating these documents, you can then trigger subsequent actions such as user notifications or task creation. Giving you much more options/control when/how to invoke document translation – the possibilities truly are endless.

With the translation quality being both excellent and affordable, it is exciting to see organisations utilising automated SharePoint Premium Document Translation. I hope this same translation functionality comes to SharePoint pages – I often hear this request from the community and customers!

Do let me know in the comments if you are using Document Translation and even better if you are using it in an automated approach like this blog. Let me know if you have any questions?

Leave a Reply