Integrate Document Translation service in SAPUI5 Application

[ratish_rao]

Document Translation Service

Using Document Translation service in SAP Cloud Foundry, the service translates documents of varying lengths into multiple languages using machine translation. The machine translation service is especially suitable for SAP related content. Document translation services improves the accuracy of translation and saves time. It also allows to translate texts from the supported file formats through the APIs.

It provides the range of API methods which can be used to access the translated resources. The APIs can be used based on the source content size like, synchronous translation API for short documents and asynchronous translation API for long documents. Document translation service instance has to be created in order to use them effectively.

Environment

The document translation service is available in SAP Cloud Foundry environment. But we are using the free service plan of the Multi environment with Cloud Foundry capabilities enabled for this use case. The sub-account used here has Amazon Web Services (AWS) as the provider and Region US East (VA). Document translation service is offered in SAP Cloud foundry environment for free trial version as of 10^th Jan 2021 for non-productive use.

Objective

We will use the free service plan to understand and experience the capability of document translation service. We will see how we can enable them and integrate the APIs in an application and test the range of translations API methods to cover translation of a text and file form data in synchronous and asynchronous mode.

Initial Setup

• An account in SAP Business Technology Platform

An account in SAP Business Technology Platform is required. To try the basic functionalities of document translation service for non-productive purpose we can signup for a trial account.

Use the link to signup for SAP BTP.

 

• Subscription to use SAP Business Application Studio (SAP BAS)

We used SAP Business Application Studio for build and deployment of a custom application to SAP Cloud Foundry environment. To check if the Business Application Studio is enabled or not in the account, we can search for Business Application Studio in the Service Marketplace and check if the instance of the BAS is created. If not, we can create them by using the option and launch the BAS.

SAP Business Application Studio - Service Marketplace

• Dev space in SAP BAS

We need a workspace or Dev space in BAS for developing the applications. We can create dev space using the option below, but we can select the SAP Fiori dev space which provides best practice templates of Fiori or Free-style template to assist with the development.

Dev space selection

The Dev Space will be created and will take a while to change the state to RUNNING state. The Dev space can be launched by clicking on the dev space name once it is in the RUNNING state.

Dev space state

• Enable Document translation services and create service key

To access the Document Translation, go to the Service Marketplace and search for the Document translation in the search bar, click on the tile to access them.

Document translation service - Service Marketplace

Click on the “Create” a new instance and provide appropriate information in the dialog that appears. Confirm the details and create the instance.

Create Service Instance

After create, click on View Instance button in the confirmation dialog to look at the new instance that has been created and also it is the place where we have to create service key to generate credentials. These credentials are then used by the apps to communicate with the instance that is created.

Information - Service Instance created

Steps to Create Service key

Service Key Inputs

Download Credentials - Service key

Service key Details

• Destination configuration in Subaccount

We will create destinations to define the outbound communication from the apps to our cloud environment. Using this destination we can configure the necessary Authentication type and client credentials which are required for the authorization. To access the destination we need to click on the Cloud Foundry or Multi environment subaccount and under the connectivity we can need to click on Destinations to open the destinations form.

Click on New Destination button and enter the following as shown below. Use the downloaded credentials of the Document translation service instance to fill the form. Refer the mapping of the Service Key credentials form with the New destination form. No Additional properties are required in the destination configuration.

Note: Token Service URL should have /oauth/token in the service URL. Token service user and password are not mandatory for the destination configuration.

Field Name	Value
Name	documentservice
URL	<url in document translation service instance service key>
Authentication	OAuth2ClientCredentials
Client ID	<clientid in document translation service instance service key>
Client Secret	<clientsecret in document translation service instance service key>
Token URL	https://<subdomain>.authentication.us10.hana.ondemand.com/oauth/token

 

Implementation Approach

To demonstrate the capability of Document Translation service, we will consume the API in an application. The application will have the capability to trigger the document translation service API and show the response of the API. The document translation service is configured as a destination in the SAP cloud foundry subaccount.

Create Multi Target Application

We will require a Basic Multi Target application. In this MTA, we will add a Fiori module and the application router configuration.

We will use a basic free style template to develop a SAPUI5 application as the whole purpose of using the Fiori module is to consume the translation API and perform all the translations through a simple user interface. SAPUI5 application will have basic controls to take the user inputs for translation API.

You can also follow the initial project setup performed and create a project in your workspace. For information about the development of SAPUI5 app, clone the git repo in your workspace for more details.

Follow below steps to add modules to MTA.

Again use the shortcut keys to add Fiori module

We will add a resource for the destination services in the MTA descriptor file. The destination service will also be used as a route in xs-app.json to call the API through the destination with destination name as configured in destinations subaccount.

mta.yaml descriptor file

xs-app.json routes

Testing Translations API

To test the translations APIs from the SAP Business Hub, follow the procedure mentioned here. Here we integration the API in the SAPUI5 application and test the behavior. More details in demonstration section.

Demonstration

Here we have created an option to select the synchronous and asynchronous mode for testing the APIs. We will see the behavior of both the APIs below.

API selection

Synchronous API

Translates documents of up to 100 MB in size or up to 40,000 characters. The characters length are language dependent. In sync mode, the translated documents or texts are available immediately on completion of translation.

Usage of synchronous mode is recommended where the demand of translation is required in interactive scenarios.

TEXT Translation

Translating a simple text using Synchronous API. The API is triggered with the source and target language and the text for translation. The API responds immediately with the response. The length of the text that can be translated is dependent on the source language selected.

There are few limitations on the source language and target language pair and also with the length of the text provided for translation. For details related to the length of the texts supported, refer here.

Calling the API with a JSON request

 

Example -

Request URI [POST] - /api/v1/translation

Request Body –

{

    "sourceLanguage": "en-US",

    "targetLanguage": "de-DE",

    "contentType": "text/html",

    "data": "Hello World. Document Translations Services are here."

}

We can also encode the data if the input is binary { “encoding”: “base64” }

Synchronous API triggered - TEXT

Synchronous API - Request body

Synchronous API - Response body

FILE Translation

Here, the file/document is provided as a form submission for translation with multipart/form-data as the Content-Type in the HTTP Header. The HTTP response provides the translated document/file. The target language is mandatory however the source language is optional, the system will infer the source language from the text if not provided.

The support mime-types limitations has to be considered here. Take a look at the supported mime-types.

Calling the  API via form Data

 

Example -

Request URI [POST] - /api/v1/translation

Parameters –

Parameter Name	Type	Parameter value
file (formData)	file	<Uploaded file>
sourceLanguage (query)	string	en-US
targetLanguage (query)	string	de-DE

 

Synchronous API - File formData

Asynchronous API

Translates documents of up to 100 MB in size or up to 25,00,000 characters. In async mode, the user can retrieve the translations at any time within 3 days after the translations is performed.

Usage of asynchronous mode is recommended where the batch-translation are required or when the translation has to run in background for larger files.

The asynchronous request API when triggered, the system creates a new Job ID with the Job Status as Pending and initiates the translation process in the background.

Important to note here is that the translation results that is texts or files are stored for three days only. The translated results for the created Job ID will be deleted and the un-retrieved results will be lost.

TEXT Translation Job

Here we submit the text to be translated which will be done in background once the Job is created. The source and the target language is mandatory along with the data.

Example -

Request URI [POST] - /api/v1/translation/jobs

Request Body –

{

    "sourceLanguage": "en-US",

    "targetLanguage": "de-DE",

    "contentType": "text/html",

    "data": "Testing document translation services.\nI want to translate this to a different language."

}

Asynchronous API - Request Body

Asynchronous API - Response Body

 

Retrieval of Job Result for TEXT Translation

The API is called with the Job ID that is created for a translation Job, the system returns the translated text.

Request URI [GET] - /api/v1/translation/jobs/<JobID>/results

Results Retrieval - Request

Results Retrieval - Response

FILE Translation Job

Here we upload the file for translation which will be translated in the background once the job is created.

Example –

Request URI [POST] - /api/v1/translation/jobs

Parameters –

Parameter Name	Type	Parameter Value
file (formData)	file	<Uploaded file>
sourceLanguage (query)	string	en-US
targetLanguage (query)	string	de-DE

Asynchronous API - formData

Asynchronous API - Response

 

Retrieval of Job Result for FILE Translation

The API is called with the Job ID that is created for a translation Job, the system returns the translated document.

Request URI [GET] - /api/v1/translation/jobs/<JobID>/results

 

Results Retrieval - Request

 

Results Retrieval - Response

 

Request for Download

Summary

The article has covered the following

• Introduction to Document Translation Service


• Procedure to activate the Document Translation Service in SAP Cloud Foundry environment and creating credentials for them


• Different APIs provided by Document Translation Service with its limitations


• Testing the APIs through Integration of Document Translation Service with SAPUI5 application as one of the use-case.

References

SAP Help Document

Create Document Translation Service Instance – Developers community

Further Details

• More questions related to Document translations can be found here.


• Follow the BAS community for more details on SAP Business Application Studio.


• Follow the SAP Fiori community for the latest details on the topic.

 

I welcome the feedback from the others on this topic and looking forward to know if you have done something similar on this topic, but with a different approach and a different use-case. Leave your comments below.