Document Translation Service
Using Document Translation service in SAP Cloud Foundry, the service translates documents of varying lengths into multiple languages using a repository of SAP approved translations and 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.
There are several blogs and videos in SAP learning Journeys on this topic to gain a better understanding and to transform us from the beginner to an expert on this topic.
Environment
The document translation service is available in Neo as well as 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 subaccount 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 10th 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.
- 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.
- 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.
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.
- 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.
Click on the “Create” a new instance and provide appropriate information in the dialog that appears. Confirm the details and create the 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.
- 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.
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.
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” }
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 file format limitations has to be considered here. Take a look at the support file format.
Calling the API via form Data
Example –
Request URI [POST] – /api/v1/translation
File Upload Parameters –
file (formData) – uploaded source file
sourceLanguage – “en-US”
targetLanguage – “de-DE”
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.
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.”
}
Status Retrieval of Job 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
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
File Upload Parameters –
file (formData) – uploaded source file
sourceLanguage – “en-US”
targetLanguage – “de-DE”
Status Retrieval of Job 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
To download the file use below request
Request URI [GET] – /api/v1/translation/jobs/<JobID>/results?$value
