Handling Locales

The default locale is the locale that is set by the Web browser of the user, or the English (United States) locale if the vSphere Client does not support the set locale.

In the vSphere Client locales are usually handled on the user interface layer. In some cases, the HTML plug-in must return text from the Java service layer such as the properties of a vSphere object adm error messages.

Handling Resources in the plugin.xml Manifest File

The localized resources for your plug-in are located in the locales directory of the WAR file. The plugin.xml manifest file contains the <resources> element that you must use to specify the location of plug-in resources such as images and localization data. The defaultBundle attribute of the <plugin> element specifies the name of the main .properties file of the plug-in and is added automatically by the Ant build scripts.

To instruct the vSphere Client to use the locale that your Web browser specifies at runtime, set {locale} as a value to the locale attribute of the <resource> element in the plugin.xml manifest file. You must avoid hard-coding a specific locale as a value to the locale attribute.

The plugin.xml manifest file contains the names of views, dialogs, action menus, icons, and other localizable objects. These strings and icons must be localized and not hard-coded in a particular language. If the string or icon is defined in the main properties file specified with the defaultBundle attribute, you must use the #{RESOURCE_KEY} syntax for the element and attribute values. If the string or icon is defined in a different .properties file, use the #{BUNDLE_NAME:RESOURCE_KEY} syntax for the element and attribute values.

Localizing Strings and Icons in the plugin.xml Manifest File

The following code snippet demonstrates how you can specify the values for strings and icons that must be localized in the vSphere Client depending on the settings of the Web browser. The main properties file of the plug-in is locale/en_US/com_vmware_samples_chassisa.properties which is reflected with the value of the defaultBundle attribute.

<plugin id="com.vmware.samples.chassisa"
   defaultBundle="com_vmware_samples_chassisa">

   <resources>
      <resource locale="{locale}">
         <module uri="locales/chassisa-{locale}.swf"/>
      </resource>
   </resources>
  ...
   <templateInstance id="com.vmware.samples.lists.allChassis">
      <templateId>vsphere.core.inventorylist.objectCollectionTemplate</templateId>
      <variable name="namespace" value="com.vmware.samples.chassisa_collection"/>
      <variable name="title" value="#{chassisLabel}"/>
      <variable name="icon" value="#{chassis}"/>
  ...

The English locales for the chassisLabel string and the chassis icon are defined in the com_vmware_samples_chassisa.properties file in the following way:

# ------- String properties --------

chassisLabel = ChassisA
summary.title = Chassis main info
...

# ------------- Images -------------

chassis = Embed("../../assets/images/chassis.png")
localizedImage.url = assets/images/localizedImage-en_US.png
...

Handling Resources in the HTML and JavaScript Code

You can retrieve the current client locale by using the app.getClientLocale() method from the JavaScript API. You can use the locale information to localize your plug-in UI with a framework of your choice. For an example of localizing a plug-in UI, see the HTML sample plug-in included with the SDK.

Handling Resources at the Service Layer

In some cases your plug-in might return strings from the service layer that must be displayed in the vSphere Client. For example, the service layer can return the properties of a vSphere object that must be displayed in a human-readable format, or an error message that comes from the back end. You must retrieve the current locale of the user and return the translated text for that locale in your Java code.

In case of error messages, your back end server might have the messages localized. In other cases, you can use the standard Java localization APIs and add .properties files inside your JAR files. These properties files are used to load the correct strings based on the locale.

Following is an example of how to use the UserSession class to access the locale of the current client session.

   // see the vsphere-wssdk-service sample for injecting  _userSessionService in your class
   UserSession userSession = _userSessionService.getUserSession();
   String locale = userSession.locale;
   ...