Foglight 5 - Topology Localization

Motivation

Topology type- and property-names have to adhere to Java naming standards (no whitespace, Umlauts, etc.). This means that names deployed through topology-type.xml as well as those generated dynamically from script agents often don't look as good in the UI as one might wish:

This post describes how to deploy language modules that localize these type- and property-names ultimately shown in the UI.

Developing a language module

Prerequisite: Foglight 5.5.4+, Ant

A language module is a simple text file that contains key/value pairs describing the localization value for a topology type- or property-name. Assuming there's a type define like so:

  <type name='Robot' extends='TopologyObject'>
    <property name='serial' type='String' is-many='false' is-containment='false' is-identity='true'/>
    <property name='name' type='String' is-many='false' is-containment='false' is-identity='false'/>
    <property name='model' type='String' is-many='false' is-containment='false' is-identity='false'/>
  </type>

The naming for the resource file follows the standard Java naming policy prefix[_lang].properties. Here's an example that defines the translation for the type above into english proper in topology_en.properties

  type.Robot.description=A Robot
  type.Robot.name=Robot
  type.Robot.property.serial.description=The serial number engraved on construction
  type.Robot.property.serial.name=Serial Number
  type.Robot.property.name.description=The name the robot is called by
  type.Robot.property.name.name=Name
  type.Robot.property.model.description=The robot's model
  type.Robot.property.model.name=Model

For german the international two letter code is de as usual. The following example defines the translation of the type and its properties above in topology_de.properties

  type.Robot.description=Ein Roboter
  type.Robot.name=Roboter
  type.Robot.property.serial.description=Die bei der Konstruktion eingeschlagene Seriennummer
  type.Robot.property.serial.name=Seriennummer
  type.Robot.property.name.description=Der Name des Roboters
  type.Robot.property.name.name=Name
  type.Robot.property.model.description=Die Modellnummer des Roboters
  type.Robot.property.model.name=Modell

The cartridge builder ant-task is used to package cartridges. We're going to build two, one for english, one for german localization (simplified). The task's commands are:

<car destdir="build">
   <cartridge name="Robot_en">
      <localizations name="topology-localizations" cartridge="Robot" basename="topology">
        <fileset file="src/topology_en.properties"/>
      </localizations>
   </cartridge>
</car>

<car destdir="build">
   <cartridge name="Robot_de">
      <localizations name="topology-localizations" cartridge="Robot" basename="topology">
        <fileset file="src/topology_de.properties"/>
      </localizations>
   </cartridge>
</car>

Essential parameters:

• cartridge name - the localization cartridge to be built: Robot_de/Robot_en
• localization component w/name - the cartridge component containing localization resources for topology: must be topology-localizations
• the cartridge that the localization is for: Robot
• the basename and fileset of resource files: src/topology_de.properties
  (the basename identifies the filename prefix for resource files and has to match the included files)

To build this example use the attached source, edit build.xml to have fglhome point to the Foglight installation folder and run ant in the main folder. The output generated should roughly say:

[car] creating cartridge archive: Robot-1_0_0.car
[cartridge] creating cartridge: Robot-1.0.0
      [car] adding Cartridge: Robot-1.0.0
      [car] adding Component: topology-types-1.0.0
      [car] adding Item: topology.xml
      [car] adding Component: Post-Install-1.0.0
      [car] adding Item: instantiate.groovy
      [car] adding Component: wcf-1.0.0
      [wcf] prefixing wcf to each item: wcf
      [car] Cartridge Archive Creation Successful
[cartridge] creating cartridge: Robot_en-1.0.0
      [car] adding Component: topology-localizations-1.0.0
      [car] adding Item: topology_en.properties
[cartridge] creating cartridge: Robot_de-1.0.0
      [car] adding Component: topology-localizations-1.0.0
      [car] adding Item: topology_de.properties

The build artifacts are:

• Robot-1_0_0.car
• Robot_de-1_0_0.car
• Robot_en-1_0_0.car

Note that the main cartridge not only contains the type definition we're translating but also a bit of groovy to generate a couple of sample-robots as well as a UI query to make it easier to find them for Drag'n'Drop ops.

Testing the language modules

Prerequisites: Foglight 5.5.4+

Before Foglight 5.5.8 only one localization cartridge is effective at a given time. The last enabled localization cartridge's resource are the only ones available regardless of the user's language settings.

Test steps (5.5.5+)

1. Install the main Robot-1_0_0.car cartridge - it defines the Robot type, generates two sample robots and adds a WCF query to easily find the instances in the UI.
2. Create a custom dashboard, navigate to Data|Robots|All Robots and drag'n'drop each robot to the dashboard (You will be asked for the properties to render, select model, name and serial)
3. Confirm default java-naming conform names showing up in the dashboard
4. Install the english localization Robot_en-1_0_0.car cartridge - it defines the english resources
5. Ensure current user settings are english (see How to change the user's language below)
6. Check the dashboard for english (proper) type-related texts
7. Install the german localization Robot_de-1_0_0.car cartridge - it defines the german resources
8. Switch the current user's settings to german(see How to change the user's language below)
9. Check the dashboard for german type-related texts

(5.5.4 in the older version of Foglight properties cannot be dragged to a custom dashboard easily - instead go to Configuration|Data and drill down to All Robots selecting a Property Viewer view)

Tthe following shows how the dashboard changes for different localizations:

Appendix: How to change the current user's language

There are two ways for a user to change the language of the UI and therefore decide which available (if any) language module is being used:

1. Change the Browsers preferred language settings
2. Change the language setting in the users' preferences from within the Foglight console

Note: check the testing the language modules notes above for caveats (support for languages has to be specifically enabled in the server before localizations are utilized)

(Please visit the site to view this file)