The Localization tab provides a tool to support the translation of static text strings in the STEP user interfaces (STEP Workbench and Web UI), such as titles, labels, and dialog text. The tool enables administrators to generate a translation file that contains the texts that need translation. Translation files are in XML format and are intended to be sent to an outside agency for translation of the text strings in the file. Once the file is returned from the translation agency, it can be converted into system resource files that can be applied to the system so that users may view the STEP interfaces in the translated language(s).
This document is not intended to act as a standalone set of instructions for implementation of UI localization. Instead, it is strictly a guide to some basic localization concepts and instructions for using the localization tool.
STEP has both a key-based and an annotation-based framework for localization.
This section describes the legacy way of localizing static text strings in the Web UI. The framework for this is based on using localization keys as opposed to the annotation-based framework.
A localization key (sometimes referred to as 'i18n' keys) is basically a value-pair. The key ID always starts with 'i18n' and the value is the actual text string that will be presented in the Web UI (Portal).
For example, i18n.stibo.portal.server.components.value.ApproveActionServerComponent.default.button.Label = Save & Approve
In the above example, the localization key ID is 'i18n.stibo.portal.server.components.value.ApproveActionServerComponent.default.button.Label' and the value 'Save & Approve' is the text string that the end user will see in the Web UI.
The localization keys are stored in resource files that can either be part of the Web UI code or be placed on the file system on the application server. On a given STEP system, you will be able to see the list of localization keys via this URL: [system name]/webui/docs
For example, http://mysystem.acme.corp/webui/docs
This will provide a webpage with descriptions of the portal components available on the given system as well as a list of localization keys and values shown at the bottom.
In the Web UI designer tool you will be able to see the localization key used for a specific text.
The above example shows the Approve Action properties in the Web UI designer. The label on the button is defined by the localization key 'i18n.stibo.portal.server.components.value.ApproveActionServerComponent.default.button.Label.' The default English value for that localization key is 'Save & Approve' and the button will be rendered like this for the English locale:
In some cases you may want to overwrite the standard value for a localization key, thus changing the default text. This requires that you add the given translation key with the new value to a 'portalmessages' property file and place that file on the application server. The file can be placed on the file system in any directory as long as the directory is pointed out in the sharedconfig.properties file using the 'Portal.Localizer.Folder' property.
For example, Portal.Localizer.Folder = [STEPHOME]/PortalLocales (e.g., opt/stibo/step/PortalLocales)
Note: The naming convention for the 'portalmessages' file is: portalmessages_[ISO country code].properties. Example: portalmessages_en.properties. Also, region codes can be added as a postfix to the country code. Example: portalmessages_en_US.properties
For instance if you want to change the English default text on the SaveApproveButton to 'Verified', the following will have to be in place:
Localization of texts in STEP Workbench is based on a 'GUI bundle' system. A GUI bundle is a java .properties file which maps localization keys to text strings to be used in the UI. The developer provides a default English text in a file called 'something.properties.' Translations to other languages exist as files called 'something_language.properties.' The code retrieves the texts based on the keys and the framework takes care of first looking up the translated text in the 'something_language.properties' file and then in the 'something.properties' file. All the properties files involved are included in the jar files that make up the application and cannot be changed by the users.
The localization framework offers a bundle-based approach to localization of STEP code. Basically it means that user facing static text strings must be annotated as localizable in the code and a default (English) text is provided. This is valid for both STEP Workbench and Web UI.
A class annotated with @Localizable represents a string that can be localized with a Localizer. The annotated class makes up the ID of the string. The annotation contains the default source translation (in English).
The bundle translations can be overridden by custom translations placed as properties files on the STEP server. The STEP server is configured to look for localizable artifacts by setting the configuration property ‘Install.ExternalLocalizationDir’ to point to the folder where the files are stored.
The Localization tool supports system administrators in the process localization, using either the annotation-based localization, or key-based annotation in Web UI.
Important: The localization tool does not support key-based localization in STEP Workbench.
The localization tool assists administrators in translating static text strings in the UI, such as titles, labels, and dialog text as it generates a translation file that contains the texts that need translation. These generated files are in XML format and are intended to be sent to an outside agency for translation of the text strings in the file. Once the file is returned from the translation agency, it can be converted into system resource files that can be applied to the system so that users may view the STEP interfaces in the translated language(s).
The Localization tool is intended to be used by system administrators only, and the involvement of a Stibo Systems developer or partner may be required as part of the initial implementation of the functionality.
The Localization tab is split into two functional areas: file generation and file conversion.
The Localization tool is able to extract both the localization keys (often referred to as 'i18n keys') used by STEP Web UIs, as well as the text strings in the code base that are annotated as localizable. The latter is used by both Web UIs and STEP Workbench. In order to generate the translation file, the system administrator must first select the data to be included.
The target language the file should be generated for must be specified. The selected target language is added to the XML translation file so that the language indicator is available to the system when the translated file is returned.
For some languages it is possible to specify a country version of the language. Country should only be specified if the translation is specific to a particular regional dialect.
Translation status selections may be made to reduce the size of the translation XML file, if desired. This is especially useful on previously translated systems where only untranslated and/or changed (delta) content in the selected language should be submitted for translation.
Once the administrator has made the appropriate filtering selections, they must click Search to generate the list of bundles and translation status.
The data to be extracted can be further refined by selection / deselection of the particular component bundles to be included. Administrators may select all (as is defaulted) or may select only a subset for extraction. In the latter case, a Stibo Systems developer should be consulted to ensure that the correct bundles are extracted to meet the translation requirements. One example could be that only the texts related to matching should be translated, thus only the bundle related to matching needs to be selected.
Once all file generation selections have been made, the administrator clicks Download translation file. The file can then be submitted to a translation agency.
When a generated file has been translated, the conversion functionality in the localization tool must be used to convert the XML file into a system resource file.
First, the administrator must select the translated XML file from their local machine using the Choose File button.
The Merge with existing translations from STEP option may be checked if the resource files are intended to replace only a small subset of existing translations on the system.
The Convert to one Portal message file per bundle selection applies to Web UIs only. Check this option if the generated resource files will be placed on the STEP application server. This option should be left unchecked if the resource files should be placed within the code.
When the translation file and any additional options have been selected, the Convert and download button should be clicked to generate the resource files.
The resource files are delivered in a zipped file which contains a number of folders that are structured and named in a way that the STEP installation will be able to recognize. The entire file structure that is included in the zipped file must be added to the STEP installation.
Converted files may be delivered to STEP via addition to the code base or via placement on the application server.
Addition to the code base requires a Stibo Systems developer and is typically used when the translations are to be used as part of the standard STEP distribution.
Placement of the files on the STEP application server can be done by any STEP administrator with access to the application server and the sharedconfig.properties file. This option is typically used when the core translations of texts must be overwritten using the newly generated resource file content. Note that this option requires population of the 'Install.ExternalLocalizationDir' property in the sharedconfig.properties file with the path of the folder on the application server in which the localization files are stored. One file per locale per bundle may be stored in this location.
For the workbench and the WebUI, the following parameters must be set in the sharedconfig.properties:
For the workbench: Install.ExternalLocalizationDir=/workarea/localization
For the WebUI: Portal.Localizer.Folder= [STEPHOME]/PortalLocales
The system administrator must also verify the Webstart.Locales property in the sharedconfig.properties file. This property is populated with locales and their Start Page translations in the following format: [locale1]:[start page text];[locale2]:[start page text]
For example: Webstart.Locales=de:STEP Werkbank auf deutsch provides the following option on the Start Page.
Assuming that corresponding German (de) resource files are available, users logging in via this link will view a German-translated workbench.
Stibo Systems can provide translations of STEP Workbench and Web UI for the following languages:
Note: The STEP server must be restarted to clear the cache and allows the translations to become active.
Regardless of the framework used for the translation, end user access for translated interfaces is the same.
Translated STEP Web UIs are accessed via the Locale selector on the login page, as shown below. Note that the locales available to the end user are configurable via the Web UI designer. However, in the designer, the list of locales is determined by the portalmessages files available on the application server. So if 'portalmessages_en.properties' and 'portalmessages_es.properties' files are available on the application server, then the Portal Designer will only list English and Spanish.
Note: A property can be added to the sharedconfig.properties file to force a locale—even if the browser prefers a different language. For example, to force English, the property is WebUI.OverrideBrowserPreferredLocale=en. Setting the locale via the login screen's locale selector, as described above, will overrule this property.
Translated workbenches are accessed via the appropriate Start Page links. The available Start Page links are defined by the 'Webstart.Locales' property that can be specified in the sharedconfig.properties file.
Example: Webstart.Locales=de:STEP Werkbank auf deutsch;en: Launch STEP Workbench
2020, Stibo Systems – Confidential