Localization with SAP Cloud Application Programming Model
Tl;dr: Use node package “@sap/textbundle” to provide localized custom messages.
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.
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.
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).
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’);
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”
Request with HTTP header key “accept-language” and value “de-DE”
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
@sap/textbundle – https://www.npmjs.com/package/@sap/textbundle
SAP Cloud Application Programming Model – localized data – https://cap.cloud.sap/docs/guides/localized-data
Great post, Pat!
Keep it going 🙂