terminologies
.terminology
is a content-related vocabulary fitted to a certain industry or business scenario. With Version 1.77, UI5 has gained the capability of defining one or more terminologies
for an application, which can be activated during the start-up of your application component. Find more details on the new APIs here.*.properties
files as a way of providing a localized and translated version of your application. This practically meant you only had a single scenario "hard-coded" into your application. If you now wanted to adapt an application for a similar scenario or industry (as in our shop example above), this typically meant a lot of manual effort. You either had to copy the application or provide additional controller logic to switch between i18n resource models (or bundles for that matter).npm install --global @ui5/cli
cd "Shop Administration Tool"
npm install
ui5 serve
Open http://localhost:8080/index.html in your browser to launch the app. It should look like this:
webapp
folder. Open the webapp
folder and you'll see the localization folder called i18n
. It contains the *.properties
files, one for each language (i18n_de
and i18n_en)
, and a default bundle. We call these top-level *.properties
files in the following base bundles. These bundles contain the localized text variants for the application.terminologies
folder. In there, you find two more folders, named sports
and travel
. Each of these folders contain additional *.properties
files.*.properties
files you find in our project contain key-value pairs. The keys are arbitrary and will be used in binding paths inside the ResourceModel
that has been defined in the manifest.json
. The values are the localized strings which will end up in the UI.terminologies
is based on overdefining the keys. Take a look at the *.properties
files in the i18n/terminologies
folder, and you will see that all files (re-)use the same keys. Yet, not all keys are used there, but only the subset that differs from the base bundles. The terminology bundles only need to contain the delta to the base bundles. If you reuse a key in a terminology bundle, the values defined for the same keys in the base bundle are overwritten at runtime.To better understand the handling of*.properties
files, please also have a look at the dev guide entry and the sample app linked below. They illustrate the way UI5 resolves bundles and retrieves the values inside the*.properties
files:
manifest.json
.sap.ui5/models
section from the manifest.json
file to the following content. We're going to remove the existing definition of terminologies
, so we can rebuild them step by step:"models": {
"i18n": {
"type": "sap.ui.model.resource.ResourceModel",
"settings": {
"bundleUrl": "i18n/i18n.properties",
"async": true,
"fallbackLocale": "en",
"supportedLocales": ["en", "de"],
"enhanceWith": []
}
},
"side": {
"type": "sap.ui.model.json.JSONModel",
"uri": "model/sideContent.json"
},
"alerts": {
"type": "sap.ui.model.json.JSONModel",
"uri": "model/alerts.json"
},
"customer": {
"type": "sap.ui.model.json.JSONModel",
"uri": "model/customers.json"
}
}
terminology
to our projectmanifest.json
file and the sap.ui5/models
section where your ResourceModels
are defined, and do some modifications. In our walkthrough we will only pay attention to the i18n
model and ignore the other models.i18n/i18n.properties
with additional terminologies, we will add the new terminologies
property and certain terminology definitions to the configuration. A terminology definition includes a bundleName
or bundleUrl
, which points to some resource bundle containing different wording or vocabulary, and a list of supported locales. In our sample application, the supported locales are en
and de
. For every supported locale, a dedicated resource bundle must be available.travel
as our first additional terminology. After you're done with Step 3, the sap.ui5/models
section in your manifest.json
file should look like this:"models": {
"i18n": {
"type": "sap.ui.model.resource.ResourceModel",
"settings": {
"bundleUrl": "i18n/i18n.properties",
"async": true,
"fallbackLocale": "en",
"supportedLocales": ["en", "de"],
"terminologies": {
"travel": {
"bundleUrl": "i18n/terminologies/travel/i18n.terminologies.travel.properties",
"bundleUrlRelativeTo": "manifest",
"supportedLocales": ["en", "de"]
}
},
"enhanceWith": []
}
}
}
This configuration part inside the manifest will end up in the sap.base.i18n.ResourceBundle
, which will take care of requesting the correct resource bundle files. You can read more about the terminologies
property here, and about the terminology definition here.
travel
terminologymanifest.json
, we're going to activate the travel
terminology in our sample app. There are several ways how the available terminologies can be activated.sap-ui-activeTerminologies
URL parameter, which we'll use in this walkthrough. You can read about the other options in the Developer's Guide. To activate the travel
terminology we simply add the URL parameter with travel
as its argument, and run the app:sports
and travel
. This would probably be the first thing you'd do as an application developer if you wanted to introduce terminologies into your application.sports
as an additional terminology:"models": {
"i18n": {
"type": "sap.ui.model.resource.ResourceModel",
"settings": {
"bundleUrl": "i18n/i18n.properties",
"async": true,
"fallbackLocale": "en",
"supportedLocales": ["en", "de"],
"terminologies": {
"travel": {
"bundleUrl": "i18n/terminologies/travel/i18n.terminologies.travel.properties",
"bundleUrlRelativeTo": "manifest",
"supportedLocales": ["en", "de"]
},
"sports": {
"bundleUrl": "i18n/terminologies/sports/i18n.terminologies.sports.properties",
"bundleUrlRelativeTo": "manifest",
"supportedLocales": ["en", "de"]
}
},
"enhanceWith": []
}
}
}
Run your application with the URL parameter sap-ui-activeTerminologies=sports
, and you'll see a different result: http://localhost:8080/index.html?sap-ui-activeTerminologies=sports
enhanceWith
section, which is still empty. The enhanceWith
property is an array, that allows you to define additional bundle configurations. For the purpose of this demo we're going to add additional resource bundles, which will be layered on top of the original base bundle. The resource bundles we're going to add to the enhanceWith
section are inside a folder called reuse
. There, we find two additional folders, appvar1
and appvar2
, which contain the resource bundles we're going to use.appvar1
and add the terminology bundles for travel
and sports
. The definition of the terminology bundles looks much like the definition of the base bundle, except that we have different bundle URLs:"models": {
"i18n": {
"type": "sap.ui.model.resource.ResourceModel",
"settings": {
"bundleUrl": "i18n/i18n.properties",
"async": true,
"fallbackLocale": "en",
"supportedLocales": ["en", "de"],
"terminologies": {
"travel": {
"bundleUrl": "i18n/terminologies/travel/i18n.terminologies.travel.properties",
"bundleUrlRelativeTo": "manifest",
"supportedLocales": ["en", "de"]
},
"sports": {
"bundleUrl": "i18n/terminologies/sports/i18n.terminologies.sports.properties",
"bundleUrlRelativeTo": "manifest",
"supportedLocales": ["en", "de"]
}
},
"enhanceWith": [
{
"bundleUrl": "reuse/appvar1/i18n/i18n.properties",
"fallbackLocale": "en",
"supportedLocales": [
"en", "de"
],
"terminologies": {
"sports": {
"bundleUrl": "reuse/appvar1/i18n/terminologies/sports/i18n.terminologies.sports.properties",
"bundleUrlRelativeTo": "manifest",
"supportedLocales": [
"en", "de"
]
},
"travel": {
"bundleUrl": "reuse/appvar1/i18n/terminologies/travel/i18n.terminologies.travel.properties",
"bundleUrlRelativeTo": "manifest",
"supportedLocales": [
"en", "de"
]
}
}
}
]
}
}
}
If you now reload the page with the URL
http://localhost:8080/index.html?sap-ui-activeTerminologies=travel, you should see that the app has changed again, this time from a generic Travel Shop Administration Tool to an app for a specific branch of this industry, which in this example is a Vehicle Rental Administration Tool.
appvar2
to the enhanceWith
array, we'll see another change in the UI: The app has now changed from a Vehicle Rental Administration Tool to a Bike Rental Administration Tool.{
"bundleUrl": "reuse/appvar2/i18n/i18n.properties",
"fallbackLocale": "en",
"supportedLocales": [
"en", "de"
],
"terminologies": {
"travel": {
"bundleUrl": "reuse/appvar2/i18n/terminologies/travel/i18n.terminologies.travel.properties",
"bundleUrlRelativeTo": "manifest",
"supportedLocales": [
"en", "de"
]
}
}
}
As mentioned in the Short Primer on the .properties Files, the concept of terminologies is based on overdefining keys within the .properties
files. The terminology bundles will be applied in the order they appear in the enhanceWith
array. If a key is used on the UI, UI5 will first look at the last entry of the enhanceWith
array. In case the key is not found there, UI5 will look at the second-to-last entry and so on, until the base bundle is reached.
appvar1
. This happens because the key used in the tile is not defined in the bundle of appvar2
, so UI5 will behave as described and look up the text in the second-to-last enhanceWith
entry (which in our case is appvar1
).As far as the customer is concerned, the interface is the product. [1]
Thorsten & Tommy: We're colleagues in the UI5 Core Framework team, and we are always happy to contribute nice features to this great UI framework. The coolest part, however, is that we get the chance to share our stuff with you and help you build better applications. Until next time 🙂 |
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
User | Count |
---|---|
38 | |
25 | |
17 | |
13 | |
7 | |
7 | |
7 | |
7 | |
6 | |
6 |