DeepSee Implementation Guide
Performing Localization
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter describes how to localize strings in DeepSee. It discusses the following topics:

Overview of Localization in DeepSee
This section provides an overview of how DeepSee supports localization of strings.
Model Localization
DeepSee provides a simple mechanism for localizing the names of level, measures, and other model elements.
Every element in the DeepSee 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:
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 DeepSee models, do the following:
When you compile the classes, the system adds values to the ^CacheMsg global in this namespace. These values may look like this:
This global (which is known as the Message Dictionary) contains the messages defined in this namespace; for DeepSee, 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 DeepSee 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:
When you compile this class, the compiler finds each instance of the $$$Text macro and adds values to the ^CacheMsg global in this namespace.
Using Localizable Strings in a Dashboard, Pivot Table, or Other Folder Item
In the definition of a dashboard, pivot table, or other folder item, use one of the following values instead of the exact string that you want to see:
Use these values for any of the following strings in the folder item definition:
Localizing the Strings
To localize the strings:
  1. 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 DeepSee.
    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)
        Tip:
        To generate a sample message file, use this command in the SAMPLES namespace.
  2. For each desired language, make a copy of the message file.
  3. 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 RFC1766 (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>
  4. Import the edited message file or files. To do so:
  5. 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 ^CacheMsg global.
    Within this global, you should see a new set of subscripts that correspond to the language you have added.
  6. 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.
  7. Access the Analyzer and validate that you see translated strings.
For more information on the utility methods in %Library.MessageDictionary, see the class reference for that class or see the chapter Localizing Text in a CSP Application in Using Caché Server Pages (CSP).