Skip to Content
Previous

Localizing your SAPUI5 app

By akula86

Learn how to support multiple languages in your app using the SAP Translation Hub, and how to manually add a language-locale combination.

You will learn

In the fourth tutorial of Mobile Guide #2, you extracted strings from the application into the internationalization (i18n) bundle of UI5. In subsequent tutorials, you continued this practice by placing all strings in the messageBundle.properties file.

Details

Using a single file not only makes it easy to update strings in the future, but it makes it trivial to localize the UI to different languages and locales. If you want to support multiple languages (English, Spanish, German, French, etc.) or multiple locale settings for a given language (e.g. UK vs US English, or German vs Swiss German) you can create separate files to store the localized strings.

In this tutorial, you will add implement language support for Dutch (nl) Spanish (es), German (de), with the base file covering English (en) via the HANA Cloud Platform Translation Hub. Additionally, strings are provided for Swiss German (de_CH) to demonstrate language and locale support. After running the app, you will test that the runtime loads the correct files by setting the language/locale in your browser.

Background on i18n:

When loading an app, SAPUI5 will check the container’s (in this case your browser’s) language/local settings, then attempt to load the most specific locale resource bundle file, with graceful degradation down to a “catch-all” case. For example, with a Swiss German-based browser, and no explicit language-related URL parameters, the SAPUI5 runtime will attempt to load the following files in this order:

  1. messageBundle_de_CH.properties
  2. messageBundle_de.properties
  3. messageBundle.properties (catchall)

Strings in more specific resource bundles (loaded earlier) will take precedence over strings for the same translation keys in less specific resource bundles (loaded later).

>An important point: Before you begin, make sure you have deployed the current version of your app to SAP HANA Cloud Platform. This ensures that your latest code is checked into your Git Repository and is available to the Translation Hub service.


  1. Log into your HCP account, click on the Account tab and confirm that the Enable beta features check box is selected. If not, click the Edit button, check the box, and click Save.

    This step is required because the SAP Translation Hub service is currently in beta release.
    Accounts tab

  2. Click on the Services tab, scroll down until you see SAP Translation Hub, then click on the SAP Translation Hub tile.

    Open Translation Hub page

  3. Click on the Enable button. The status will change to Processing, then Enabled. Click on the Go To Service link to open the Translation Hub service page.

    Enable Translation Hub

    Open Translation Hub page

  4. Click the + icon to create a new translation project and enter the following information in the Create Translation Project page. You will see a toast notification at the bottom of the screen with the selected languages. Click Save after entering all information. A toast notification is a non-modal UI element used to display brief alerts to a user.

    • Field: Value
    • Application Name: northwind (See note below)
    • Branch: Master
    • Path to Properties File: i18n/messageBundle.properties
    • Target Languages: Click on the menu and check: Dutch, French, German, Spanish
    • Domain: Basis

    Note: The application name must be lower case, and match the HTML5 Application name in your git repository. To check your app name, go to your HCP Cockpit and click on Git Repositories in the left navigation bar.)

    Translation project fields

  5. The Translation Hub will display the Project Details. Click Get Translations in the lower right corner of the window, enter your password and click Submit when prompted.

    The Translation Hub service will create the appropriate messageBundle_xx.properties files and add them to your Git repository (but they will not be visible in your project folder until you complete the next two steps).

    Get Translations

    git password

  6. To review and optionally edit the translated text, click the Edit icon, and then select the desired language to review from the pull down menu.

    Edit translations

  7. To change the suggested text for any of the fields (for instance use the German word Ort instead of Stadt for the label_City string) simply edit the field under Translated Text. Once your review and your edits are complete, click Save. If you don’t make any edits, you can simply click Cancel.

    changing strings

  8. If you have made changes you will need to click the Get Translations button again, and enter your git password for them to be saved to your repository.

  9. Switch to your Web IDE tab, select the Git Pane on the right hand side of the window. Notice that:

    • The northwind repository and the master branch are selected
    • The new messageBundle_xx.properties files are not yet in your project.
    Git pane showing only one messageBundle.properties file
  10. To download the new language files, click on the Pull button.

    Git pane pull button

    Login in with your HCP credentials when prompted. You will see a progress indicator on the Pull button as the new messageBundle_xx.properties files are added to your project folder.

    Git pane

    The green dot next to the files indicates that the version in your project is identical to the version in your Git repository.

    The files added to your Web IDE northwind > i18n folder are:
    * messageBundle_de.properties
    * messageBundle_es.properties
    * messageBundle_fr.properties
    * messageBundle_nl.properties

    Files added to project

  11. Double-click on the new files and you will see each has the same 31 entries as messageBundle.properties.

  12. Mobile web, hybrid and native applications have the ability to support both language and locale (for example de_CH for Swiss German).

    The SAP Translation Hub does not yet support Swiss German, so to add that language to your app, you will create a file with the appropriate name and copy in the strings provided below.

    Right-click on the i18n folder and select New > File. Name the file messageBundle_de_CH.properties.

    Create de_CH file

  13. Copy and paste the text below (these are Swiss German strings) into the new file and save your changes.

    masterTitle=Produkt
    detailTitle=Produktdetails
    notFoundTitle=Nöd gfunde
    notFoundText=Die agfordereti Ressource isch nöd gfunde worde
    masterListNoDataText=Kei Iträg
    masterSearchPlaceholder=Sueche nach Produktname
    masterSearchTooltip=Produktname i geh
    currencySymbol=€
    label_ProductID=Produktschlüssel
    label_UnitsInStock=Lagerbestand
    label_UnitsOnOrder=Bstellti Stückazahl
    label_CategoryID=Kategorieschlüssel
    label_ReorderLevel=Mindestbestand
    label_Discontinued=Uslaufstatus
    label_SupplierID=Lieferanteschlüssel
    label_CompanyName=Unternehmensname
    label_ContactName=Kontaktname
    label_ContactTitle=Kontakttitel
    label_Address=Addresse
    label_City=Stadt
    label_PostalCode=Postleitzahl
    label_Country=Land
    label_Region=Region
    label_Phone=Telefon
    label_Fax=Fax
    label_HomePage=Startsiite
    tab_supplier_short_title=Lieferant
    tab_supplier_sub_title=Lieferantedetails
    tab_product_short_title=Produkt
    tab_product_sub_title=Produktdetail
    label_CurrentInventoryValue=Aktuelle Lagerbestand
    

    Your new file should look like this. Note that the messageBundle_de_CH.properties file does not have a green dot because it hasn’t been committed and pushed to your Git repository yet.

    de_CH strings

  14. Commit your new file to Git (following the same procedure as in the previous tutorial.

  15. Deploy your app to HCP (following the same procedure as in an earlier tutorial and open the new, active version of the app.

  16. To test the language support in the deployed app, we can utilize the SAPUI5 sap-ui-language URL parameter. To do so, just append ?sap-ui-language=xx_YY to your application URL

    • If your standard application URL looks like this:
      • https://northwind-p12345678trial.dispatcher.hanatrial.ondemand.com/
    • You can view the German strings by specifying:
      • https://northwind-p12345678trial.dispatcher.hanatrial.ondemand.com/?sap-ui-language=de
    • Swiss German strings by specifying:
      • https://northwind-p12345678trial.dispatcher.hanatrial.ondemand.com/?sap-ui-language=de_CH
    • Spanish strings by specifying:
      • https://northwind-p12345678trial.dispatcher.hanatrial.ondemand.com/?sap-ui-language=es
  17. As described in the introduction for this tutorial, when a user opens your app URL, the app will check the language and locale settings on the device, then load the appropriate strings file.

Next Steps

Updated 06/27/2016

Time to Complete

20 min

Intermediate
Next
Back to top