Automatic translation process for CP using Jenkins and GitHub

[yaron_ganor]

This topic is divided into 2 parts:

1. A public API for downloading and uploading translation files to portal service sites.


2. An example of how to automate the process using Jenkins, Shell script and GitHub.

You can use this API in any way you like, the example is just to give you an idea of the possibilities.

Manage Translation Interface (MTI)

• A new public API is now available for handling site translation.
  The API includes two methods to allow users to download the master_language.zip file and to also upload their translations zip files back to the system.


• The API is protected by HCP's OAuth service and can only be used by OAuth authenticated users.


• The authenticated users do not have to be recognized by any IDP, but they must possess the relevant OAuth tokens.
  For each method of the API (also known as "scope") there is a different token type:
  
  
  
  • Download master language (GET) requires a "read" token.
  
  
  • Upload translations (POST) requires a "write" token.
  
  
  
  


• The API is exposed in the following paths:
  
  
  
  • Download  - fiori/api/oauth2/v1/services/translations/download/<siteId>
  
  
  • Upload  - fiori/api/oauth2/v1/services/translations/upload/<siteId>
  
  
  
  

Related Documentation

• Manual translation process in portal service sites: help.sap - Managing Translations.


• Translation API implementation: API HUB - ManageTranslationInterface.


• HCP OAuth configuration: Enabling OAuth 2.0 Client Credentials Grant.

IMPORTANT:

The steps below are only for quick reference. It is recommended to use the documentation links above to fully understand the process.

OAuth Configuration

The provider application has to declare the supported OAuth scopes

In the Portal Service, this will be pre-configured for customers on the productive landscape by the Cloud Operations team.

Configurations in the subscriber account

(This should be done by any customer that wants to use OAuth protected API's)

1. In the HCP cockpit, login to your account.


2. Go to Security > OAuth > Clients
   Register a new client and enter a Secret value.
   


3. Encode the following key pair using BASE64 encoding:
   <client ID>:<secret> (Example -  a04e5576-d757-4bfd-953a-7f3643f87373:myTinySecret)
   Example encoder: https://www.base64encode.org


4. Copy and save the encoded result you get – <encoded_secret>.


5. For each scope you want to use, generate a Bearer token using HCP OAuth service
   Send a POST to the following REST API:
   https://oauthasservices-<;account>.hana.ondemand.com/oauth2/api/v1/token?grant_type=client_credentials&scope=<scope>
   _{(hana.ondemand.com - is for the productive landscape)}
   With this header:
   Authorization:Basic <encoded_secret>


6. Copy and save the Bearer tokens you get - <read_token> & <write_token>

Translations API usage

Download master language zip file

Send a GET request to the following REST API:
https://<;FLP_Landscape>/fiori/api/oauth2/v1/services/translations/download/<siteId>
With this header:

• Authorization:Bearer <read_token>

Upload translations zip file

Send a POST to the following REST API:
https://<;FLP_Landscape>/fiori/api/oauth2/v1/services/translations/upload/<siteId>

With these headers:

• Authorization:Bearer <write_token>


• Content-Type:multipart/form-data

And with these form fields:

• sap.ushell.designer.apps.manageTranslationEditor.fileUploader.name = <zip_file_name>


• Content-Type = application/x-zip-compressed

 

Example of how to use the API with Jenkins and GitHub

Prerequisites:

1. You have a repository in GitHub that you can fetch from and submit to.


2. You created an OAuth <read_token> & <write_token> .


3. You have a Jenkins server that is configured with the Git plugin to connect to your repository.

(This script just uses shell commands and can be run manually in any command line interpreter)

Download

1. Download master language from site


2. Unzip


3. Push to Git

Input parameters are:

• $read_token - Your client's OAuth read token


• $FLP_Landscape - The full <protocol>://<host> of your FLP. (same as when typing window.location.origin in console)


• $siteId - the site ID that will be translated


• $github_authenticated_url - The URL to your GitHub repository with a master branch in the form of:
  https://{user}:{pass}@github.com/{path_to_repository}

echo "-----start download process-------------"   



    



    echo "-----make sure you have unzip installed-------------"   



    sudo apt-get install unzip



    



    echo "-----sync from git and clean workspace-------------"   



    git checkout master



    git pull



    rm -rf source_properties_file



  



    echo "-----create a folder structure for the files-------------"   



    mkdir -p source_properties_file



    



    echo "------get the master language from site------------"



    curl -H "Authorization:Bearer $read_token" $FLP_Landscape/fiori/api/oauth2/v1/services/translations/download/$siteId -o source_properties_file/master_language.zip



    



    echo "-----extract the properties file to the dedicated folder---------"



    unzip -u source_properties_file/master_language.zip -d source_properties_file



    



    echo "-------push everything to git-----------"



    git add source_properties_file/*.*



    git commit -m "master language files"



    sudo git push --repo $github_authenticated_url



    



	echo "-------finished download process-----------"

 

Upload

_{(In this example I assume you have pushed your translated properties files to GitHub under a directory called target_properties_file)}

1. Fetch translation files from Git


2. Zip


3. Upload to site

Input parameters are:

• $write_token - Your client's OAuth read token


• $FLP_Landscape - The full <protocol>://<host> of your FLP. (same as when typing window.location.origin in console)


• $siteId - the site ID that will be translated

echo "--------start upload process-------------"   



	    



		echo "--------make sure you have zip installed-------------"   



		sudo apt-get install zip



	    



		echo "--------sync from git-------------"   



		git checkout master



		git pull



	    



		echo "--------zip the properties files into one archive-------------"   



		zip -r -j translations_for_upload.zip target_properties_file/*.properties



	    



		echo "--------upload the translations to site-------------"   



		curl -i -X POST -H "Content-Type:multipart/form-data" -H "Authorization:Bearer $write_token" --form "Translation-File=@translations_for_upload.zip" --form "Content-Type=application/x-zip-compressed" $FLP_Landscape/fiori/api/oauth2/v1/services/translations/upload/$siteId



	    



		echo "----------finished upload process-----------"