Reference: Localization and Globalization in Cireson Portal

Introduction

Localization is the technique and technology involved in displaying text and dates/times in a language and format that is familiar to the user.  The Cireson Portal is designed to be a single platform that can display and format content for users from different languages and regions.  This knowledge article describes the options available to administrators and users to configure the Cireson Portal for display languages and date/time formats.

Languages

Out of the box the Cireson Portal and System Center Service Manager are fully translated as follows:

Administrator Configuration of Language Options

During the installation of the the installing user can choose which languages will be available for users to choose from. 

The language chosen as the default language will be the language that all users see content in unless the user has a preference for a different language:

The installing user can also choose to add additional languages which users can choose from:

During these selections will be stored as a list in the SettingsItem table in the database.  You can view the languages chosen in the SettingsItem table by running a query like this:

SELECT [Key],Value FROM SettingsItem WHERE [Key] = 'LanguageCode'

After installation the LanguageCode setting can be changed in two ways:

• Updating the SettingsItem table in the database directly by following this KB article: KB1118 - Editing or Adding a Settings Item in ServiceManagement DB

• Logged in as an administrator, to Admin Settings in the upper right menu, clicking the Settings Items link.  Change the LanguageCode setting in the table and click Save.

Note: After changing the LanguageCode the should be restarted.

Languages can be added or removed by changing the list of language codes.  See the table above for the list of supported language codes.  Note: The first language code listed is the default language code.

User Selection of Preferred Language

Each user can choose a preferred language by going to User Settings in the upper right menu.

This choice is stored in the database in the UserPreferences table:

If desired, an administrator can pre-configure these user preferences for language or date/time format by creating a SQL script that creates a row in this table for each user.  The preferences are stored in JSON format.

Note: Any display string in the  Cireson Portal can be overridden in any language.  See How to Override a Localization Display String for more details.

Date/Time Format

Configuring the date/time format is essentially the same as choosing the language.  At install time, the administrator chooses which date/time format options to have including setting a default:

The administrator can also choose to have additional date/time format codes:

Below are the date/time formatting codes available:

Users can then choose a preferred date/time setting from the User Settings available in the upper right menu:

User preferences for date/time formatting are also stored in the UserPreferences table in the database similar to the user's language preference.

Service Catalog Language Code

When creating a service offering in the SCSM console you can choose a service offering language:

The default value is to not have a language code specified.

When the service catalog content is copied to the database by the Cireson Cache Builder the service offering language code is stored in the LanguageCode column on the ServiceOffering table.  Depending on the language selected the code will be either a two or a language code.  Here is an example:

When installing the Cireson Portal, the installing user can choose to specify a service catalog language code:

The default is an asterisk (*) which will match all service offerings regardless of language code.  If you want to only display service offerings (and their contained request offerings) of a certain language you can enter a different value in this textbox such as 'en-US'.  This value is stored in the SettingsItem table in the database.  Just as with the LanguageCodes setting, the ServiceCatalogLanguageCode can be set either in the SettingsItem table directly by following this KB article - Editing or Adding a Settings Item in ServiceManagement DB -  or in version 3.7 or higher you can use the Settings Item view in Admin Settings to change the value.  For a particular Cireson Portal instance, you can override the ServiceCatalogLanguageCode stored centrally in the SettingsItem table by creating an appSetting in the web.config for that web site instance.  For example:

Service Catalog Localization

In Service some things are localizable such as class names, property names, enumeration values, and much more.  Those items have a unique ID and a display string for each language that Service Manager supports.  Some things in Service Manager are not localizable and only have a single display string which is shown all languages.  Two examples of these things that are not localizable are service offerings and request offerings.  The service offering category enumeration is localizable though.  Thus, we have a taxonomy like this:

• Service Offering Category - an enumeration which is localizable

• Service Offering - not localizable

• Request Offering - not localizable
  

When an administrator is creating service offering categories in the Service Manager console the display strings that are created are created in the language that the SCSM console is currently running as.  For example, if a user opens the SCSM console using the English language and creates service offering category enumerations and provides a display string for each of those, whatever the user enters will be stored as the English display string value.  Whatever the user enters will be stored as the display string.  Thus, if the user is running the console in English and enters display string values in Finnish, the Finnish display string values will be stored as the English display string values.  If the administrator wants to create Finnish display string values, the administrator should open the SCSM console in the Finnish language and then create the enumerations and provide the Finnish display strings.  Unlike the service offering category enumerations, because service offerings and request offerings only have a single non-localizable display string value, it does not matter which language the administrator is running the SCSM console as.

Localizing Service Offering Category Enumerations

One common configuration issue that can happen is that the administrator has defined service offering category enumeration values in one language (normally English) and not others OR the administrator is running the SCSM console in English and enters display strings in a different language and doesn't realize that those display strings are being stored as the English display strings.  When the service catalog data is synchronized to the DB by the Cireson Cache Builder and then loaded into the Cireson Portal the English display string values exist, but the display strings for the other language do not.  If the user then changes his language code to the language that the display strings do not exist for, the user will see a blank service catalog.  In this situation, the user could look at the F12 developer panel on the Console tab and see an error like this: Uncaught TypeError: Cannot read property 'replace' of null.  This is an indication that the display strings for the service offering enumerations for the language the user chose do not exist.

You can check the display strings for your service offering enumerations and add display strings for other languages by doing the following.

If you already know which management pack your service offering category enumerations are in you can export that management pack from the SCSM console Administration\Management Packs view and skip to step #3.

Install SMLets on management server.  Open a PowerShell window and enter Import-Module SMLets.

• Run the following command:  Get-SCSMEnumeration | ?{$_.DisplayName -eq 'the display name of one of the service offering category enumerations'}.  Example: Get-SCSMEnumeration | ?{$_.DisplayName -eq 'Datacenter'}

• If you get back just one result then you can run this command to export the management pack that contains that enumeration: (Get-SCSMEnumeration | ?{$_.DisplayName -eq 'Datacenter'}).GetManagementPack() | Export-SCManagementPack -TargetDirectory C:\Temp

• Now open the management pack in a text editor and search for 'LanguagePacks'.  In this situation, you will likely see a single LanguagePack with the ID="ENU".  If this is the only LanguagePack element then you need to create a new LanguagePack for your desired language.  In this example, we will create one for Finnish.  

• Copy the element and everything that it contains down to and including the closing element.

• Paste the in immediately after the English closing element.
  

• Change the ID from "ENU" to "FIN" (or whatever language code you would like).  Change the IsDefault attribute to "false".  At this point, it should look like this:

• If needed, translate the DisplayString elements in your new language pack from English to Finnish (or your desired language).

• Increment the version number near the top of the pack file. Example:

• Save the file.

• Import the management pack back into SCSM.

• Restart the Cireson Cache Builder service.

More information can be found on the SCSM engineering team blog about localizing management pack content.

Service Catalog Content Selected by User's Preferred Language

You can choose to have the user's language preference be used to select service catalog content.  The user's preferred language is set by the user in User Settings (upper right menu).  The language preference will be a three letter code such as 'ENU', 'FRA', etc.  If the user has not specified a preference, then the first language code specified in the LanguageCode setting will be used.  The LanguageCode setting can be seen on the Admin Settings page > click on Setting Items at the bottom of the page > look for 'LanguageCode' in the list of settings.

The user's language code preference (or default) is used to get the service offering category enumeration display strings.  If there are no matching display strings for the user's preferred language then the service offering category display names will simply not be shown. 

The user's language code preference (or default) can also be used to filter the service offerings and their contained request offerings.  Because service offering language codes are either a 2 or 4 letter language code (ex. 'EN' or 'EN-US' and a user's language preference is a 3 letter language code (ex. 'ENU') there must be a mapping of 3 letter codes to 2 and 4 letter codes.  This is done by using the Language lookup table in the database.  It contains a default mapping of 3 letter codes to 4 letter codes as follows:

CHT > -TW
CHS > -CN
CSY > cs-CZ
DAN > da-DK
DEU > de-DE
ELL > el-GR
ENU > en-US
ESN > es-ES
FIN > fi-FI
FRA > fr-FR
HUN > hu-HU
ITA > it-IT
JPN > -JP
KOR > ko-KR
NLD > -NL
NOR > nb-NO
PLK > pl-PL
PTB > pt-BR
PTG > pt-PT
RUS > ru-RU
SVE > -SE
TRK > tr-TR
ZHH > -HK

You can optionally choose to insert additional language mappings into the table by running a query like this in the ServiceManagement DB:

INSERT INTO Language (ISO639x, CultureCode, DisplayName, LanguageCultureName) VALUES ('ENU', '', 'English-Any', 'EN')

The above example query will create a mapping of ENU > EN.

To change the configuration of the Cireson Portal to use the logged in user's language preference as a filter for the service catalog, you will need to change the ServiceCatalogLanguageCode setting to something besides '*'.  You can change this setting by logging in as administrator.  Then, navigate to the upper right menu, select Admin Settings, scroll to the bottom of the page and click the Setting Items button, and then find the ServiceCatalogLanguageCode.  You can change this to one of three options:

You can also make this change directly in the database by following the Editing or Adding a Settings Item in ServiceManagement DB KB article.

Note: you can make a given service offering and it's contained request offerings be displayed to any user regardless of the user's preferred language code by setting the ServiceOfferingLanguageCode setting to '!' and not specifying a language code for the service offering.

Overriding Display Strings

• A localization is translated content provided with the portal.

• A localization override is system-wide setting that will override a given translation.

For example, users of the system that have selected "English" as their language in their User Settings page, would see these buttons at the bottom of the page:

Whereas a user that has selected "Spanish" would see:

However, if you provide an override for the save button label, they would instead see:

To create an override, log in to your portal as an admin, and select "Localizations" from the menu at the upper right:

• Select the appropriate locale (e.g. language) that would like to provide the override for.

• Find the key you would like to override (hit Control + F and search the page).

• Click the cell in the Override column.

• Type in whatever you want the override to be.

• Click "Save" at the bottom of the page.

• Restart the web site.

As a best practice, use an override, instead of just changing the translation, because the translation could be changed by us at some point (as part of our normal development process), but you'll always keep your overrides.

Localizing Enumerations

When creating new enumerations or editing enumerations in the Enumeration Settings you can specify a display string for each enumeration.

• as an administrator.

• In the upper right menu choose Enumeration Settings.

• Select an enumeration list that you want to edit.

• In the editor choose an enumeration value and on the you can specify a value for each language.

• Click Save when you are done.

• Restart the web site.

Note: If you do not provide a display string for a given enumeration for a given language the display string will be set to 'undefined' as a default.

Updating the Localization Content Manually

When a new version of the Cireson Portal is released the localization strings are simultaneously included as part of the installer for that version.  In some cases, localization strings may be modified or added in between releases.  In this case, you may be instructed by Cireson Support to update your localization strings manually.  Here are the steps to do that:

• For version 4.1 and below, go to https://support.cireson.com/Localizations and save the file to your computer

• For version 4.2 and above, go to https://translations.cireson.com/api/legacy/1 and save the file to your computer

• Copy the file to C:\inetpub\CiresonPortal\bin (or wherever you installed the portal ) on the server where the Cache Builder service is running

• Restart the CacheBuilder service

Localizing Custom Navigation

If you add custom navigation nodes to the navigation, you may want to localize the display strings for those navigation nodes.  This can only be done through database updates for now.  The following steps describe the procedure:

First, you need to determine the ID of the navigation node that you want to localize.  You can do this using the following query: 

SELECT *FROM DisplayString
WHERE DisplayStringOverride='The Name of the Navigation Node'

Note: Replace the text 'The Name of the Navigation Node' with the name of the navigation node that you want to localize.

Copy the ElementID GUID value from the results.  You will use it in the following stored procedure call.

EXEC spAdd_DisplayString'7850848B-6C10-471A-9FDC-BF8F4BA045F4','FRA','French Display String Value',NULL

The first parameter is the GUID of the navigation node that you copied from the first query.  The second parameter is the language code that you want to create the display string value for.  See the language code list at the top of this article for the full list of language codes.  The third parameter is the localized display string value want to display in the navigation for that language.  The fourth parameter is the GUID ID of the user that is creating this display string.  You can pass NULL for convenience instead of spending time looking up the user ID.

If necessary, repeat the above steps for other language codes.

Once you have completed making the changes, they will be reflected the next time users log in to the Cireson Portal.