Thanks for your feedback!
Need to tell us more? Click here or use the Feedback button.

Is this page helpful?

Contents

Overview of Localization in Business Intelligence
Preparing for Model Localization
Preparing for Folder Item Localization
Localizing the Strings

Performing Localization for Business Intelligence

This page describes how to localize strings in InterSystems IRIS® data platform Business Intelligence, as part of the Business Intelligence implementation process.

Overview of Localization in Business Intelligence

This section provides an overview of how InterSystems IRIS Business Intelligence supports localization of strings.

Model Localization

The system provides a simple mechanism for localizing the names of level, measures, and other model elements.

Every element in the Business Intelligence model has a logical value and a display value. You specify the logical value, the original display value, and alternative display values for use with other language locales. Then:

In MDX queries, you always use the logical value.
The user interfaces use the appropriate display value, if available. The user configures the browser to use a preferred language, and when the browser sends requests to a server, those requests indicate the preferred language to use, if available. The server sends a reply that includes the appropriate set of strings, based on that language preference.

Folder Item Localization

In a similar manner, you can localize a specific set of following strings within dashboards, pivot tables, and other folder items. For these strings, you specify the original display value and alternative display values for use with other language locales.

The User Portal and the dashboard viewer use the appropriate display value, if available. The user configures the browser to use a preferred language, and when the browser sends requests to a server, those requests indicate the preferred language to use, if available. The server sends a reply that includes the appropriate set of strings, based on that language preference.

Preparing for Model Localization

To prepare for localization of strings in the Business Intelligence models, do the following:

Specify the DOMAIN class parameter in each cube, subject area, and KPI class.
For example:
```
Parameter DOMAIN = "PATIENTSAMPLE";
```
The classes in the Patients sample all use the same value for DOMAIN, but this practice is not required. You can specify a different value for each class.
Specify a value for the displayName attribute for every Business Intelligence element.
In the Architect, when you specify a name, the system initializes the Display name field with the same value. When you work in an IDE, however, you must remember to specify the displayName attribute (which is optional), in addition to the name attribute (which is required).

When you compile the classes, the system adds values to the ^IRIS.Msg global in this namespace. These values may look like this:

The Management Portal, showing the ^IRIS.Msg global containing a set of strings localized for English.

This global (which is known as the Message Dictionary) contains the messages defined in this namespace; for Business Intelligence, each message corresponds to the name of a model element.

When you compile a cube, subject area, or KPI class that defines the DOMAIN parameter, the system updates this global to include the messages defined in that class, in your default language. Each message uses a numeric identifier and has a string value that applies to the default language.

If you do not see the expected set of strings, make sure that the class defines the DOMAIN parameter, that you have specified values for displayName, and that you have compiled the class.

Preparing for Folder Item Localization

This section describes how to prepare for localization of strings in the dashboards, pivot tables, and other folder items.

Default Domain

DeepSeeUser is the domain that the system uses by default when it looks for a localized string in a dashboard. For details, see the following sections.

Adding Strings to the Message Dictionary

Create a class that, when compiled, generates a set of entries in the Message Dictionary. In this class:

Extend %RegisteredObjectOpens in a new tab or any other class that provides access to the standard system macros.
Specify the DOMAIN class parameter. For example:
```
Parameter DOMAIN = "DeepSeeUser";
```
The DeepSeeUser domain is the most convenient choice, because this is the default domain.
Define a method that uses $$$Text(Localizable String) to refer to each string that the given domain should contain. Localizable String is an expression that evaluates to a string in this domain.
You can specify any name for the method. It does not need to take any arguments or return any values. The following shows an example:
```
ClassMethod DefineL18N()
{
   set x=$$$Text("Dashboard Title")
   set x=$$$Text("Dashboard Description")
   set x=$$$Text("KeywordA")
   set x=$$$Text("KeywordB")
   
   set x=$$$Text("Control Label")
   set x=$$$Text("Tooltip")
   set x=$$$Text("Widget Title")
   set x=$$$Text("Chart Title")
}
```
Or, instead of $$$Text(Localizable String}, use $$$Text(@MessageID@) where MessageID is a numeric ID that is unique within the given domain.

When you compile this class, the compiler finds each instance of the $$$Text macro and adds values to the ^IRIS.Msg global in this namespace.

Using Localizable Strings in a Dashboard, Pivot Table, or Other Folder Item

Wherever you would like to include a localized string as part of the definitions for your dashboards, pivot tables, or other folder items, provide a reference to one of the strings which you have defined as part of a Message Dictionary.

To localize a string in fields other than folder item names and pivot table descriptions (which require a different syntax), refer to the localized string using the following syntax:

// To use the value of a localizable string:
$$$LocalizableString/Domain1

// To use a message ID:
$$$@MessageID/Domain2

Where

LocalizableString is a localizable string which you have defined in a Message Dictionary.
MessageID is a numeric message ID, as defined in a Message Dictionary.
Domain1 and Domain2 are the respective domains within which you have defined the string or ID. Including the domain is optional; if you refer to a localizable string or a message ID without specifying a domain ($$$LocalizableString or $$$@MessageID), Business Intelligence looks for the string in the default domain.

For example:

Dashboard example, showing $$$Dashboard Description used as the Description and $$$KeywordA used as a Keyword.

Folder Item Names and Pivot Table Descriptions

To localize a folder item name or a pivot table description, use the following alternative syntax:

// To use the value of a localizable string:
$$$LocalizableString1#Domain1/$$$LocalizableString2#Domain2[/...]

// To use a message ID:
$$$@MessageID3#Domain3/$$$@MessageID4#Domain4[/...]

Where:

LocalizableString1 and LocalizableString2 are localizable strings which you have defined in a Message Dictionary.
MessageID3 and MessageID4 are numeric message IDs, as defined in a Message Dictionary.
Domain1, Domain2, Domain3 and Domain4 are the respective domains within which you have defined the string or ID. As with other fields, the domain is optional; if omitted, Business Intelligence looks for the string in the default domain.
[/...] represents the repetition of this pattern, as needed.

Note:

Unlike other fields, Business Intelligence localizes folder item names and pivot table descriptions on an all-or-nothing basis: it attempts to resolve the content of one of these fields for localization if and only if the content string begins with the string "$$$", and it evaluates the whole, undivided content string according to the preceding syntax. If the content string does not begin with "$$$", Business Intelligence ignores occurrences of “$$$” elsewhere in the string, and no localization occurs.

Localizing the Strings

To localize the strings:

Export the Message Dictionary to one or more XML files. To do so, do the following in the Terminal:
1. Change to the namespace in which you are using Business Intelligence.
2. Identify the output file and its location:
```
 SET file="C:\myLocation\Messages.xml"
```
  The specified directory must already exist; the system does not create it.
3. Run the export command:
  - It may be practical to export only those messages in a particular domain:
```
 DO ##class(%Library.MessageDictionary).ExportDomainList(file,"myDomain")
```
    The domain names are case-sensitive.
  - Or, to export all the messages in the namespace:
```
 DO ##class(%Library.MessageDictionary).Export(file)
```
For each desired language, make a copy of the message file.
Edit each message file as follows:
1. Edit the Language attribute of the root element:
```
<MsgFile Language="en">
```
  Change this to the language name of the desired language.
  This must be an all-lowercase language tag that conforms to RFC1766Opens in a new tab (so that a user can choose the preferred language in the browser from the standard set). This tag consists of one or more parts: a primary language tag (such as en or ja) optionally followed by a hyphen (-) and a secondary language tag (so that the result has the form en-gb or ja-jp).
  For example:
```
<MsgFile Language="es">
```
2. Scan the file to find the <MsgDomain> element that corresponds to the appropriate domain:
```
<MsgDomain Domain="myDomain">
```
  If you exported only one domain, the file contains only one <MsgDomain> element.
3. Within this section, edit the value of each message. For example, change this:
```
     <Message Id="2372513034">City</Message>
```
  To this:
```
     <Message Id="2372513034">Ciudad</Message>
```

Import the edited message file or files. To do so:

To import a single file:

 SET file="C:\myLocation\myfile.xml"
 DO ##class(%Library.MessageDictionary).Import(file)

To import all the files in the same directory:

 SET myFiles="C:\myLocation"
 DO ##class(%Library.MessageDictionary).ImportDir(myFiles,"d")

Optionally use the Management Portal to verify that the message dictionary has been updated. To do so, switch to the appropriate namespace, select System Explorer > Globals, and then click View Globals for the ^IRIS.Msg global.
Within this global, you should see a new set of subscripts that correspond to the language you have added.
In your browser, find the setting that controls the language that it requests for use on localized pages. Change this setting to the language that you specified in the edited message file.
Depending on the browser, you might need to clear the browser cache, restart the browser, or both.
Access the Analyzer and validate that you see translated strings.

For more information on the utility methods in %Library.MessageDictionaryOpens in a new tab, see the class reference for that class or see String Localization and Message Dictionaries.

Packaging Business Intelligence Elements into Classes

Executing Business Intelligence Queries Programmatically