Automatic translation process for CP using Jenkins and GitHub

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-----------"