Localization with SAP Cloud Application Programming Model

Tl;dr: Use node package “@sap/textbundle” to provide localized custom messages.

Introduction

SAP introduced the SAP Cloud Application Programming Model as the standard framework for cloud applications on the SAP Cloud Platform. It utilizes many technologies, framework and best practices defined by SAP to provide enterprise level features and experiences.

Different aspects and features ensure the value creation and the quality of a software application. Users should experience the highest possible accessibility while using those. Besides the visual design, language is another factor with high impact on the accessibility and user acceptance of an application. Therefor the feature of language localization can’t be ignored. With this in mind, SAP included this feature in the SAP Cloud Application Programming Model. This blog will cover the aspect of localized messages in the SAP Cloud Application Programming Model (Node.js / JavaScript based). The documentation of the SAP Cloud Application Programming Model currently covers the possibility to provide localized database data, therefor won’t be part of this blog, since this has already been covered.

An application should provide plausible and reasonable feedback through messages to its users to create an understanding of the current process step and user interaction. In the framework there are two sources of messages, provided by custom coding or the framework itself. If the business process flow deviates from the designed standard flow in an unexpected way (e.g. error – “amount if ordered items exceeds the capacity of stored item”), the application would provide a respective message to the user to adapt his behavior. Let’s call these kind of messages custom messages.

SAP provides a JavaScript-based package named “textbundle”, which provides the handy feature of providing localized custom messages. Like the i18n-approach of localized messages / strings with SAP UI5, the package uses the i18n.properties file in accordance of the requested language to provide the translated value to the user.

Implementation steps

Install the package via npm with the following command in the root folder of the project:

npm install @sap/textbundle

This will install the package for the current project. The installation can be verified by checking the package.json file. It should include a new entry in the section of “dependencies” and should look like the entry in the screenshot.

After the successful installation. The corresponding files needs to be created. Since the files are used within the OData service, the files should be located within the srv folder. As best practice the files should be in a folder with clear purpose. In this case, the folder was named i18n as stated in the following figure. Since the approach follows the same approach with SAP UI5, files are named with the respective language code (e.g. i18n_de.properties or i18n_es.properties) and also provide the fallback option of default properties file (i18n.properties).

Usage

The process to use these files looks as followed:

– read the user locale (provided as property “Accept-Language” in the http request header)
The locale can be acquired through the req.user object as the property locale. The req object has been processed by the framework and provided to the service.

const locale = req.user.locale;

– create instance of the TextBundle class with the path to the i18n properties file and user locale
The class requires two input parameters. The first parameter is the path to the i18n properties in relation to the position where the class instantiation is called. The second parameter is the user locale, which was acquired in the previous step.

const bundle = new TextBundle(‘../i18n/i18n’, locale);

– Use method getText of the TextBundle instance and property name as input parameter of the method to acquire the desired string.

const messageString = bundle.getText(‘exceedOrderLimit’);

Example

The following screenshots display examples from a project, which includes a custom service handler. This handler checks before the creation of an order, if the ordered count exceeds the limit of 10. If so, a localized message will be returned. First the user locale is read from the req.user object and passed to the method getTextBundle to request the correct i18n bundle. In case that of a met condition, the localized string is requested from the text bundle and returned as the message.

Request with HTTP header key “accept-language” and value “en-En”

Response

Request with HTTP header key “accept-language” and value “de-DE”

Response

Conclusion

With the javascript package @sap/textbundle, it is easy to provide localized messages within a SAP Cloud Application Programming application with low effort. Since it follows the same approach for localization as in SAPUI5.

Feel free to add comments to my blog post or follow my community profil for more interesting content. If you have questions regarding this post, please use the Q&A platform https://answers.sap.com/tags/9f13aee1-834c-4105-8e43-ee442775e5ce

Additional links:

@sap/textbundle – https://www.npmjs.com/package/@sap/textbundle

SAP Cloud Application Programming Model – localized data – https://cap.cloud.sap/docs/guides/localized-data