# Localization

The Platform provides for a powerful adaptive language management solution which provides users access to “best available” translations for information. For localization purposes, text within the application is classified into various types:

Site Text: Applies to the commonly available text for out-of-box user interface functions, such as access to application menus, basket functions, and request history menus related text.

Localized Text: Applies to base text and configured text for Form Elements, as well as additional application text. Base text includes content such as error messages and labels. Configured text includes text such as user lookup attribute labels.

Content Text: Applies to any unique content developed for an implementation of the application, particularly Categories and Services, including their titles, descriptions, keywords, and Forms.

Workflow Text: Text which is controlled by Workflow tasks, such as the subject and body fields defined in the properties of human actions.

Response Text: Configurable text for choice and task actions as well as response text for human actions, such as an approval action’s Approve and Reject responses.

# Languages

Each language to be supported must be enabled within the system by the System Administrator. System-supported languages are managed from the Languages page, which is accessible via the rollover drop-down menu navigation path ADMINISTRATION, System Management, Languages.

The table lists languages that may be enabled by the following fields:

Tag: Language tag for the LCID

LCID: Unique Locale ID as defined by Microsoft

Native Name: Locale as represented in the native language

English Name: Locale as represented in American English

Languages may be enabled or disabled by selecting or deselecting them via the Enabled checkbox. Once a language has been enabled on this screen, it will be made available for other functions within the application. Languages that have not been enabled will not appear in any translation administration menus.

Only one Locale ID is required to be enabled for a language which has a provided translation to be available for users. If no exact locale match is available, then the user will be presented with the closest translated language match. For example, if a user’s browser language preference is set to es-MX (“Spanish – Mexico”) and that Locale ID is not specifically enabled but es-ES (“Spanish – Spain”) is, then the user will see text presented based on the best available language match of “es”, or Spanish. Accordingly, if only one Spanish translation will be provided, then only the respective Locale ID for that translation should be selected.

If no locale or language match is available, then the user will be presented with the default language text.

# Site Text

The localization of application text, which includes text displayed for standard user interface functions, can be managed from the Site Text page, which is accessible via the rollover drop-down menu navigation path ADMINISTRATION, System Management, Site Text.

The default screen for site text administration is set to the system’s default language and locale and presents a table displaying:

Message ID: System ID for a given text field within the application

Value: Text value for each field, which may be provided as plain text or html

The values configured here for English (United States) will be used within the application as the default or used when no suitable localization is available for a user. To change any default text, the System Administrator can modify the Value field for its respective Message ID and click Save.

To review or provide translations for a language – country/region, select an enabled language from the drop-down select list.

For an enabled language other than the default, the Site Text screen will display:

Message ID: System ID for a given text field within the application

Default: Text value for each field, in plain text or html, in the system’s default language is provided here as a reference for translation

Value: Translated text value for each field, in plain text or html, for the respective enabled language

The text values for an enabled language will initially be set as the same as in the default language. Once the Value field has been modified with the appropriate translation, the System Administrator can click Save to keep the changes. To revert the text in the Value field for a specific Message ID back to the default text, the Reset button can be clicked.

# Localized Text

Localized Text is a library of localized text available for use throughout the application, including in Form Elements. Localized texts are managed on the Localized Text page, which is accessed via the rollover drop-down menu navigation path ADMINISTRATION, System Management, Localized Text.

Individual Localized Texts are added by providing a “Message ID” and a corresponding value in English. Once a message ID has been added, the text can be localized by selecting another language and setting the Value in the screen presented.

Form Element text is localized by referencing Message IDs for text values. Localized Texts are managed through the Localized Text administration screen. Form Elements which are coded to support localization may have several “internal” Message IDs, such as error messages and other labels, buttons, etc., which are standard for the Form Element. Configured Form Element text may also be localized through any available Localized Text Message IDs.

The syntax for using Localized Text is [@MESSAGEID@], where MESSAGEID is the Message ID from the Localized Text. For example, within the Active Directory Lookup Form Element, the AD user property, “given name” may be labeled as [@First Name@]. In this case, the Localized Text with the Message ID “First Name” will be used as the display text with the language in which the service is being shown. When a user requests to see a service in French and the service is available in French, then the French value for the “First Name” Message ID will be displayed. When installing or updating a Form Element, the related localized text data must be uploaded to the application.

Import and export of Localized Text languages is provided through the Import/Export function presented.

For a Form Element to use a specific language, the service which contains the Form Element must also have the language enabled. Form Elements which are downloaded from the support site which support this feature should also include an importable localized text XML document for import. Legacy or custom Configuration Modules may be updated to use the “GetSiteText” function for this feature.

# Content Localization

Individual Categories and Services support localization, and any given Category or Service may be configured with translations for any language – country/region that has been enabled within the system. Localization of Categories and Services can be done largely from their respective edit screens.

# Categories

To configure a language for a Category, the System Administrator must open the Category’s edit screen by clicking the pencil icon from the Category home page and then follow the Localization link near the top of the page.

A pop-up box will open presenting the following fields:

Language: A drop-down select list of languages that have been enabled for localization.

Enabled: This checkbox controls whether the provided translation will be available to end-users. The box must be checked to set the language as visible for end-user access.

Default – Title: Read only text displaying the default text value of the Category title as a reference for translation.

Default – Description: Read only text displaying the default text value of the Category description as a reference for translation.

Localized – Title: Input field for the translated title to be used for the selected language.

Localized – Description: Input field for the translated description to be used for the selected language.

To enter or edit localized text, the System Admin user can select a language from the drop-down list of available languages and provide the desired translations in the respective Localized text boxes. If a language is enabled and only some values are translated, then the translated values will be shown when defined, and default text will be shown when no translation is found but a user’s browser has been set to the given language. This function is intended to be used where languages are similar, and changes need not be made for all text.

Once the translated text has been entered or edited, the System Administrator can click the Close button to save the translations.

# Services

# Localization within the Platform

As a table providing inputs to translate the form element text labels as well as inputs to provide translations for localized values for section headers and single and multi-select values.

Services can be localized for enabled languages.

Configured for a language from the Edit Mode view of the Service details page by clicking the Localization link near the top of the page.

A pop-up screen will open presenting the following fields:

Language: A drop-down select list of languages that have been enabled for localization.

Enabled: This checkbox controls whether the provided translation will be available to end-users. The box must be checked to set the language as visible for end-user access.

Default – Title: Read only text displaying the default text value of the Service title as a reference for translation.

Default – Description: Read only text displaying the default text value of the Service description as a reference for translation.

Localized – Title: Input field for the translated title to be used for the selected language.

Localized – Description: Input field for the translated description to be used for the selected language.

Form Elements: The Service Form Elements that have been defined for the Service will be shown with their default labels as well as their default configured values. The fields for each defined Form Element are as follows:

Base Label: The default text for the original Form Element label. This text will be used if no translated alternative is provided.
Base Value: The default text for the original Form Element value. This text will be used if no translated alternative is provided.
Localized Label: The translated text to be used for the selected language.
Localized Value: The translated text to be used for the selected language.

For Form Element Types with comma separated values, such as radio sets and select lists, the localized value field should contain the same number of response options. For example, “red, green, blue” would be “roja, verde, azul” for Spanish localization.

Once the translated text has been entered or edited, the System Administrator can click the Close button to save the translations.

Default text will be shown to end users when no specific locales are matched in the user’s browser.

# Integrating Localized Text

Database driven values for form Elements which are to be localized must use SQL which can return localized text from the related database.

For example, the query must use the user session’s locale setting to control the display text for selected values. A simple example is as follows,

Select localizedcolortext from colors where locale = ‘__USER_LOCALE__’

The current display value for each available text item will be shown in the Value field. System admin users can modify those values as needed to customize the corresponding text or label in their front-end interface. Once the desired text values have been entered, clicking the Save button will save the values and update the front-end interface accordingly.

# Workflow Text

This function provides localized strings for use within Workflows. In situations where values require localization, such as human action subject and body messages, Workflow Text references can be used. Workflow Text provide a set of “names” which are referenced at the required location. Workflow Text names and their values are managed within the start step of the respective Workflow. To manage Workflow Text, open the designer for the given workflow. From the Workflow Start step properties, open the “Workflow Text” property. To create a new Text for use, click “Add New Text”. Specify a “Name” and “Value”. “Name” should typically be a brief string which represents the purpose of the text. Workflow Contents, Variables, XML, and XML iterators can be used within the Workflow Text be inserting the required fields into the value. As an example, the Workflow Text name “Approval1Subject” is below with the following “Value”:

PLEASE APPROVE REQUEST FOR R{{Product Name}} SUBMITTED BY V{{SubmittedBy.Name}}

Once a value is set, the Workflow Text name can be localized. Select a language from the provided Workflow Text management screen. By default, the default value for the Workflow Text name is shown for the selected language. The provided text will be used if no override is provided for the selected language. The provided text also acts as a template to use as a basis for the translated text. An example translation for Spanish would be:

Por favor apruebe la peticion de R{{Product Name}} solicitada por V{{SubmittedBy.Name}}

Workflow Texts are used by referencing the defined names within the workflow, just as other Contents, Variables, and XML as “Content.Text.NAME” where NAME is the defined name in the workflow start step.

For example, the Subject property for the action “Approval1” could be set as:

C{{Text.Approval1Subject}}

When the workflow executes, the language used will be based on the submitted language of the related service. For example, if a service is ordered in French, then the workflow text language used for the workflow will be French. The language which was submitted for the workflow can be seen in the respective workflow Content value under R.

When calling workflows, the parent’s workflow contents must be shared to the called workflow. This provides the R content value to the called workflow which enables a specific language to be used within the workflow.

# Response Localization

Most of the “fixed” localized text for the Web Work List is managed through the Site Text function. However, human actions vary by configuration. Human actions present choices (or outputs) presented to the user as valid choices for various human actions within the Web Work List. Like the fixed Web Work List localized text, the human action responses will be rendered in the language specified in the user’s browser as available. The approval action will present the “Approve” and “Reject” choices, and the choice and task step present outputs for responses based on configuration.

To manage translations for the human action responses, access the “Response Localization” menu choice from the workflow designer, under the menu item, “Settings”. Clicking this menu option will open a new Response Localization window where those localized button labels can be added and managed:

At the top left of the Response Localization management window is a Language drop-down menu, which will display all additional Languages that have been enabled for use in the system via the “Languages” utility found under Administration, System Management. For each enabled Language, you can declare any buttons that need to be localized, and provide the applicable translated value to display to end users with that language set as their browser language preference.

Use the “+ Add” button to add a new item to the list. Clicking this will open a new window where you can enter the English version of the output button label to be localized in the “Response” field. The value in this Response field will apply to any Human Actions that have output buttons with a matching label. So, for example, a value of “In Process” entered in the Response column would allow you to provide localized values for any Human Action (e.g., Choice step, Task step, etc.) that offered an “In Process” output button label in English.

From there, you may enter any corresponding translated value(s) to be displayed for each applicable Language enabled in the system accordingly in the “Localized response” field(s) on the right side of the window:

Once added and saved to the list of all localized response values, you can update the translated values for a given Language for any individual button as needed directly via the Response Localization management window. Or, you can use the trash can icon to reset any existing localization replacement value for a selected Language as needed. Clicking this trash can icon will remove the current localized value for the selected Language, and reset the response value to the current English version by default. Once the desired values have been entered, click “Save and Close” to save the current values and close the Response Localization management window.

In addition, you can use the “Export” and “Import” buttons at the bottom left of the Response Localization management window to migrate all the current localization values from one environment to another. Clicking “Export” will prompt you to save the existing localization values as an XML file (“ActionOutputText.xml”), which can then be imported into a different target environment. Clicking “Import” will prompt you to browse for the appropriate XML file (“ActionOutputText.xml”) to be imported into the current environment.

# “Dyna” Localization

“Dyna” Localization is an automatic feature for DynaForm and DynaGrid. No specific configuration is required to enable the feature. Localization keys are converted into the user’s browser language if the key has a corresponding value in that language in the localized text. If the key has no corresponding value in that language, the localization syntax is removed and the key is used as the value.

Use – Add Message Ids and Values to the localized text administrator page for the desired languages.

Adding Localized Text

Add a control type to DynaForm or DynaGrid that has a value/display option with the localization key as the value and the localized syntax around the key as the display.

The front-end should display the localized values.

English Result

French Result

Since the localization key remains constant between the languages (only the display value changes), the selected item can be identified by the key.

(The key/value is constant while the display is in French)

Same Select List HTML in English

← Price Management Work Management →