Intellicus Enterprise Reporting and Business Insights 18.1

Localizing Intellicus

0 views June 28, 2020 0

Localization enables to meet the language requirements of a particular country or region for users spread across geographical locations.

By using localization features of Intellicus, you can get information like date, time and currency in your localized formats; date and time as per your time zones. You can access Intellicus portal and also get report outputs in a language supported by corresponding locale.

Scope of localization

Localization of Intellicus includes the following tasks:

  • Specify Locale to select date and time formats
  • Select Time zones for report server, database and user
  • Localize Portal
  • Localize Report data
Locale selection

Locale identifies a specific language and geographic region. In Intellicus, locales affect portal language (if configured), sorting, date/time formats, number and currency formats.

Localization options
Figure 1: Localization options on User Preferences page

Locale can be set from multiple places in Intellicus.  It will be applied in the following order:

  1. User Preferences: User can specify locale in user’s personal preferences under Navigate > Personalization > Preferences.
  2. Organization Preferences: If Default Locale is not set in personal preferences, then, Default Locale set for the organization (to which user belongs) under Navigate > Administration > Manage Users > Organization will be applied.
  3. Report Server Properties: If Default Locale is not set for the organization, then, locale set on Navigate > Administration > Configure > Server page will be applied.
  4. Machine Locale: If Default Locale is set as “Default” under the Server Properties, then locale set on the machine where report server is running will be applied.
Time zones for report server, database and user

Value of ‘Time Zone’ affects all the time dependent activities like report output (data of date type), scheduling and life of repository objects (for example, published reports).

There are three types of time zones:

  • Database time zone: Configured on Navigate > Administration > Configure > Databases page.
  • Server time zone: Set on Navigate > Administration > Configure > Server page.
  • User time zone: Set on various places on portal.

User time zone can be set at multiple pages in Intellicus. It will be applied in the following order:

  • User Preferences: The Time zone specified in user’s personal preferences under Navigate > Personalization > Preferences will be applied.
  • Organization Preferences: If Default Time zone is not set in personal preferences, then, Default Time Zone set for the organization (to which user belongs) under Navigate > Administration > Manage Users > Organization will be applied.
  • Report Server Properties: If Default Time Zone is not set for the organization, then, time zone set on Navigate > Administration > Configure > Server page will be applied.
  • Machine Locale: If Default Time Zone is set as “Default” under Server Properties, then time set on the machine where report server is running will be applied.
Portal

Portal components may not just be set to appear in any of the set language, but users can provide inputs on some of the portal pages in respective language. All the static portal text and validation messages appear in respective language.

Portal
Figure 2: Portal running in Japanese

Users would be able to provide following details in respective language on portal:

  • Name of Report
  • Name of Category (Folder)
  • Name of the Query Object
  • Field caption (being set at the time of creating a query object)
  • Dashboard name
  • Dashboard Widget name
  • Job name being setup from report list page (Quick job)
  • Published Report name

Report and Folder name in specified language
Figure 3: Report and Folder name across portal appears in the language they were specified in

Report data

Data values as well as labels placed on a report can be made to appear in the selected language. You can choose to receive output of selected reports in selected language and all the reports deployed in a selected category.

During ad hoc-report’s design, user Query Object (Data source) list can have localized entries. Field captions as well as values can also be provided in local language.

report data
Figure 4: Report title (report name) and field titles appear in language other than English

What will continue to appear in English

Even after configuring, some of the items will continue to appear in English.

Report Server and third party messages

Intellicus users interact with Intellicus portal, which in turn communicates with Intellicus Report Server.  Due to any reasons (generally beyond control of Intellicus) if Report Server is not able to serve a request, it responds with an error message.

Error message in english
Figure 5: Error message appearing in English

Such messages coming from report server and third party components will continue to appear in English.

Property values

During report design, user needs to set various properties of report components. For example, component name, chart type, its data source and other options for chart component, etc. These values are stored along with report layout (IRL file).

Property values in English
Figure 6: Property values that go in IRL appear in English

These property values appearing on web studio as well as other portal pages like Ad hoc Report Wizard will continue to appear in English.

Numeric values

All the numeric values will continue to appear in English. For example, calendar, serial numbers on portal pages and default values on various dialog boxes.

Calendar in English
Figure 7: Calendar having numbers in English

Customizing locale dependent items

During data input (like Input Parameter Form), Intellicus expects input in default format of corresponding locale that is effective at that time. Similarly, for output, it formats data in default format of corresponding locale that is effective at that time.

If you want Intellicus to use other than default formats, you can provide your preferred formats in localeconfigurations.xls file. This file is available on Report Server at path:

<Intellicus installation path>

localeconfigurations.xls
Figure 8: Partial contents of localeconfigurations.xls file (‘localedata’ sheet)
\Intellicus\ReportEngine\Config\i18n

HELP sheet of the file contains instructions that will guide you in creating the file.

Note: You need to restart the Report Server after making changes and saving the file.

Character encoding of certain locale (that are not covered under UTF-8 encoding) is also required in this .xls file so that our web portal can understand which character set is to be used to display a particular locale.

Encoding details for languages
Figure 9: Encoding details for languages

Configuring Intellicus Portal

To get multiple language support in Intellicus you need to make sure Intellicus portal and Intellicus server runs in UTF-8 mode. This mode ensures the programs are able to load, process and display multi-byte language characters.

Configuring Locales appearing on Intellicus Portal

The list of Locales, which users can select a locale from, is controlled by DEFAULT_LOCALE options tag in the XML configuration file:  “ReportServerProperties.xml”. This file is placed at the path:

<Intellicus installation path>\Intellicus\ReportEngine\Config

For example, when you want to add “Chinese (Simplified)” as a new locale, then under the XML tag <OPTIONS NAME=”DEFAULT_LOCALE”> in the above-mentioned file enter the OPTION tag with OPTION entry.

<OPTIONS NAME=”DEFAULT_LOCALE” TYPE=”2″ VALIDATEFOR=”0″ DISPLAY_TEXT=”DEFAULT LOCALE” REFRESH=”0″ IS_HIDDEN=”false”>

<OPTION DISPLAY_TEXT=”Default”>

<VALUE><![CDATA[]]></VALUE>

</OPTION>

<OPTION DISPLAY_TEXT=”Chinese (Simplified)”>

<VALUE><![CDATA[zh_CN]]></VALUE>

</OPTION>

<OPTION DISPLAY_TEXT=”Chinese (Traditional)”>

<VALUE><![CDATA[zh_TW]]></VALUE>

</OPTION>

</OPTIONS>

Note: You need to restart the Portal and Server after making any configuration changes.

If you want to remove any existing locale then you can remove the respective OPTION tag for that locale in the same file.

By default, English (US) is the available language. The list of languages supported in Intellicus that are license-controlled is given below:

  • Chinese Simplified
  • Chinese Traditional
  • Czech
  • Danish
  • Dutch
  • German
  • Finnish
  • French
  • Hindi
  • Hungarian
  • Indonesian
  • Italian
  • Japanese
  • Malay
  • Norwegian
  • Polish
  • Portuguese
  • Romanian
  • Russian
  • Slovak
  • Spanish
  • Swedish
  • Swahili
  • Turkish
  • Vietnamese
  • Thai
  • Bulgarian
  • Croatian
  • Estonian
  • Greek
  • Korean
  • Irish
  • Serbian
  • Ukrainian
Running Intellicus Portal in UTF-8 mode

An important prerequisite for Intellicus portal web server to serve language data is that it needs to run in UTF-8 mode.

Intellicus Portal’s running-mode is specified in run.bat startup file. This file is placed at path:

<Intellicus installation path>\Intellicus\Jakarta\bin

If the file has following entry, it means Intellicus Portal is running in UTF-8 mode.

set FILE_ENCODING=-Dfile.encoding=utf-8

This FILE_ENCODING variable is appended to the java launching parameters.

Note: If you don’t want Intellicus Portal to run in UTF-8 mode, comment out the above entry in the run.bat with REM.

Running Intellicus Report Server in UTF-8 mode

To support multi-byte language characters, Intellicus Report Server also needs to run in UTF-8 mode.

Intellicus Report Server’s running-mode is specified in run.bat file. This file is placed at path:

<Intellicus installation path>\Intellicus\ReportEngine\bin

If the file has following entry, it means Intellicus Report Server is running in UTF-8 mode.

set FILE_ENCODING=-Dfile.encoding=utf-8

This FILE_ENCODING variable is appended to the java launching parameters.

Note: If you don’t want Intellicus Report Server to run in UTF-8 mode, prefix the above entry in the run.bat with REM.

Important: Intellicus metadata is stored in database (known as repository database). To get multiple language support for Intellicus, make sure repository database is configured to support UTF-8-character set (example: locale-specific collation in MS SQL). Also make sure ‘Charset Encoding’ is set to UTF-8 under Navigate > Administration > Configure > Databases.

Important: Make sure, fonts that support Unicode fonts, like Arial Unicode MS are installed on machine where Intellicus server is running and the portal is being browsed.

Pre-configured items on Portal

Intellicus portal is pre-configured to accept following items in any language:

  • Folder name (Category name)
  • Report name
  • Report title
  • Report description
  • Published Report name
  • Published Report description
  • Query name
  • In a query, Caption name for selected field
  • OLAP Report name, Cube Object name
  • Quick Schedule name
  • Job name (Schedule Job page)
  • Dashboard name
  • Dashboard Widget name
  • Organization/User/Role name, Organization/User/Role description
  • Notification name

After a respective item is entered and saved in a selected language, it will appear in that language across portal pages without any configuration needs.

Field Caption name if specified in a local language will appear in local language on Ad hoc reports.

Note: When you import a Query Object from within Intellicus Desktop Studio, you receive only SQL part of the Query Object. So, Field captions specified in a local language are not available for use on Standard Reports.

Important: These items will appear in the language they were entered and saved regardless of the language you select.

Portal in Chinese
Figure 10: Portal in Chinese language

Portal can be localized to make all the portal-text appear in the selected language. To do this, you need to:

Create language bundle file having key-value pair for all possible values that appear on portal.

Note: You need to restart the portal after making configuration related changes.  Changed configuration will be effective only after server-restart.

Language Bundle file on Portal

The text of portal components comes from respective language bundle file. This file has one “key–value pair” for each piece of information appearing on portal – like caption names, options appearing in combo boxes, error messages, numbers, dates and months.

Intellicus identifies these files through their file names. For example, en_US.xls is the language bundle file for Key-value in English.

To localize a portal in a language, you need to create such a file for that language.

Portal bundle file has content in two sheets. One sheet needs to have name as “meta”. There is no name related requirement for other sheet of the file.

The sheet having name ‘meta’ contains the language name (that should be displayed in the drop-down) and the associated locale.


Figure 11: “meta” sheet of Portal’s language bundle file

Note: Don’t use the first row of the ‘meta’ sheet.

The other sheet (generally Sheet1) contains key-value pairs of text used on Intellicus Portal. When a key is found on the portal page, a corresponding value is searched from this sheet and displayed on the portal.

Sheet1 on portal
Figure 12: Sheet1 of a bundle file on Portal

Column A of this sheet contains all the keys. Column B of the same row contains respective values of that key-value pair.

Best way to create a language bundle file is:

  1. Copy en_US.xls as the new file.
  2. Change values in Column B of meta
  3. Replace contents of Column B (of sheet having key-value pairs) with translated content.
  4. Save the file (with the right file name).
File Name

<locale name>.xls

For example,

  • For English to be used in United States, the file name should be xls
  • For Spanish to be used in United States, the file name should be xls
  • For Japanese to be used in Japan, the file name should be xls
Location

Language Bundle files are placed on machine running portal at path:

<Intellicus installation path>

\Intellicus\Jakarta\webapps\intellicus\client\lang

Note: Information in language bundle file is cached at report-server start up time.  Restart the report server when you add a language resource bundle file on the report server.

Points to remember while creating a language bundle file
  • Whichever version of MS Excel you use to create the language bundle file, remember to save the file as .xls file.
  • Each entry is a key-value combination. Key is used inside the program and value is displayed on screen. So, translate the values (entries in column B).
  • Generally, values are same as keys. The only difference is, for value, “_” is replaced by a space. In some cases (like 24hh-mm-ss), key is different than value (24hh:mm:ss).
  • If you encounter single-quote or a double-quote anywhere in the value, prefix it with a \.
  • %1, %2, etc. needs to be kept as it is. These are the values that will be replaced by actual values at run time.
  • \n in a value, means “next line”. If you notice two sentences separated by a \n, keep them that way, in order to carry the next sentence in the next line. Removing \n will make the next sentence continue on the same line.
  • Some of the keys like DaysOfMonth, DaysOfWeek, CalendarMonths, InitialMonthsOfYear and InitialDaysOfWeek have multiple values separated by comma. The translated values should be placed the same way as that in English bundle file. Use comma in English text to separate two values. Avoid space between two values.

Configuring Intellicus Server

To get multiple language support in Intellicus you need to make sure Intellicus (server and portal) runs in UTF-8 mode.

You can run Intellicus server and portal in UTF-8 mode as per instructions provided in the previous chapter.

This chapter explains configurations required on Intellicus Server for localization.

Language Bundle file on Report Server

Intellicus Report Server refers to this language bundle file for conversion information when source data of the report is in English, but the report output is required in a selected local language.

Report Server treats every piece of data coming from database as “key” and tries to find matching “value” (key-value pair) in the language bundle file. So, the language bundle file on Report Server needs to have all the possible keys (data values that may come from database) and values to be used for the selected language.

Tabs on language bundle
Figure 13: Tabs on language bundle file on Report Server

Information in the report server language bundle file is spread across multiple sheets:

  • Base: This sheet (necessarily called Base) contains translation information (key-value pair) that needs to be applied to all the reports deployed in all the categories.
  • CategoryName (the actual category name): This sheet contains translation information (key-value pair) that needs to be applied to the category (folder) identified by the sheet having respective category name. For example to translate reports deployed in “EmpReps” category, specify sheet name as “EmpReps” and specify key-value pairs on that sheet.
  • CategoryName_ReportName (the actual category name+underscore+actual report name): This sheet contains translation information (key-value pair) that needs to be applied to the “ReportName” deployed under “CategoryName”. For example, to translate “SalaryRep” deployed under “Finance” category, create a sheet with name “Finance_SalaryRep” and specify key-value pairs on that sheet.

For all the above sheets, key is specified in column A and value is specified in Column B. Key is the phrase that will be found on report. As specified above, value is the string with which the phrase will be replaced with.

Location

This file is placed on machine running Report Server at path:

<Intellicus installation path>

\Intellicus\ReportEngine\resourcebundles

Intellicus identifies these files by their file names. For example, ja_JP.xls is the language bundle file for key-value in Japanese.

Note: Information in language bundle file is cached at report-server start up time.  Restart the report server when you add a language resource bundle file on the report server.

Setting value of Report Server Property “Text Output Encoding”

When Intellicus is run in multi-language mode, Intellicus Server needs to run in UTF-8 file encoding (by setting FILE_ENCODING in run.bat file. This file is used to launch Intellicus report server).

Intellicus supports output generation in various formats including CSV, Text and Raw-Text.

Programs that may be used to open such files may not support UTF-8 encoding. If that is the case and you are aware that encoding those programs are configured to read, you can override the value set by FILE_ENCODING in run.bat file.

To change encoding for report generated in any of the text-based output types (Text, CSV or RAWTEXT) set value of Report Server property Text Output Encoding (Navigate > Administration > Configure > Server > Rendering) to the one you need.

Text Output Encoding
Figure 14: Setting value of Text Output Encoding

This property is hot deployed. You need not re-start the Report Server to get the effect of new value specified for this property.

Important: To keep these configurations intact across versions during an upgrade, you need to make sure:
1) The configuration files are not overwritten during version upgrade or any patch application.
2) You keep a backup of the configuration files, in case the upgrade instructions require you to overwrite the files, and then you can ensure that you merge your entries into the new files.

Report output localization
Report getting localized data from database

Report data comes from the database. If this database already has localized content (content in script other than English), then you need to do following to make sure Intellicus Report Server generates such reports in that language.

If text-editor you use to open a report generated in text-based output types like (Text, CSV or RAW-TEXT) uses an encoding other than UTF-8, specify the required encoding by setting value of Report Server property Text Output Encoding (Navigate > Administration > Configure > Server > Rendering).

During report design, use fonts that support Unicode fonts, like Arial Unicode MS.  For ad hoc reports, make sure all the templates use fonts that support Unicode fonts, like Arial Unicode MS.

In this case, you will not need report server language bundle file.

To localize labels on report

Label is a static text control appearing on a report. Value of such a control does not come from a database.  It is typed in during report design.  To localize such static text controls, you need to follow the below steps.

If text-editor you use to open a report generated in text-based output types like (Text, CSV or RAW-TEXT) uses an encoding other than UTF-8, specify the required encoding by setting value of Report Server property Text Output Encoding (Navigate > Administration > Configure > Server > Rendering).

During report design, use fonts that support Unicode fonts, like Arial Unicode MS.  For ad hoc reports, make sure all the templates use fonts that support Unicode fonts, like Arial Unicode MS.

In this case, you also need to create language bundle file having key-value pair for all static text controls used in the report. This file will be placed on Report Server.

Note: You need to restart report server and portal after making configuration related changes. Changed configuration will be effective only after server-restart.

Report data is English, but report output needed to be localized

When a report-data comes from database having values in English, Intellicus report server can generate output of such a report in any of the language configured in Intellicus.

To localize output of such a report, you need to follow the below steps.

If text-editor you use to open a report generated in text-based output types like (Text, CSV or RAW-TEXT) uses an encoding other than UTF-8, specify the required encoding by setting value of Report Server property Text Output Encoding (Navigate > Administration > Configure > Server > Rendering).

During report design, use fonts that support Unicode fonts, like Arial Unicode MS. For ad hoc reports, make sure all the templates use fonts that support Unicode fonts, like Arial Unicode MS.

Applyi18forDataFields – Report level property in Studio. Set value of this property to True.  By default this property is set to FALSE.

  • True: Based on the language user has selected at the time of login, Report server translate report data from English to respective language and that way generates the report output in selected language. For translation it uses the language bundle file placed on Report Server machine.
  • False: Report Server does not translate report data before generating report output.

You also need to create language bundle file having key-value pair for all possible values that may appear on report. This file will be placed on Report Server.

Note: You need to restart report server and portal after making configuration related changes. Changed configuration will be effective only after server restart.

Note: You can translate Report title, Report name, Report header, Grouping details and Report output. Apart from these, Label captions that appear on various controls like chart, matrix etc. can also be translated.

To localize email messages

Email message notifications in Intellicus can be localized by placing a folder with the locale name, example: folder name zh_CN (Chinese Simplified) under:

<Intellicus installation path>\Intellicus\ReportEngine\Config\messages\mails

Keep the translated messages text files under the above folder saved using UTF-8 Encoding.