With today’s global market, a software vendor has to consider the internationalization (I18N) issue to better serve users in different areas and maximize the return on the product investment. This article introduces the I18N basics of vSphere. Much of the content is based on my book VMware VI and vSphere SDK by Prentice Hall.
There are two basic meanings. First, you have to design your software so that it is localizable. In other words, you have to use the right APIs that can handle double byte characters. Sometimes people call this globalization (G11N).
Bothered by SLOW Web UI to manage vSphere? Want to manage ALL your VMware vCenters, AWS, Azure, Openstack, container behind a SINGLE pane of glass? Want to search, analyze, report, visualize VMs, hosts, networks, datastores, events as easily as Google the Web? Find out more about vSearch 3.0: the search engine for all your private and public clouds.
Second, you should provide localized versions of your software so that users can read and use their native languages. Sometimes people call this localization.
In most cases, you externalize all the text strings that are visible to end users from the code to the resource files and translate them into different languages. Then localizing the software is as easy as combining the code and localized resource files. This is the way VirtualCenter server is localized. Depending on the programming language and platform, the resource files can be organized differently and might have another format. For example, Java uses properties files, yet C++ on Windows uses resource dlls.
That said, I18N is a broad topic that does much more than what is briefly covered here. Further discussion is beyond the scope of this book, but you can find more detailed information online.
As discussed, the VI SDK is essentially a set of Web Services interfaces. The WS-I18N summarizes four internationalization patterns that can be applied with Web Services when deployed.
- Locale neutral. Most aspects of most services are not particularly locale affected. For example, a service that adds two integers is locale neutral.
- Data driven. Aspects of the data determine how it is processed, rather than the configuration of either the requester or the provider.
- Service determined. The service has a particular setting built into it. For example, this service always runs in the French for France locale. Or, commonly, the service will run in the host’s default locale. It may even be a deployment decision that controls which locale or preferences are applied to the service’s operation.
- Client influenced. The service’s operation can use a locale preference provided by the end user to affect its processing. This is called “influenced” because not every request may be honored by the service. (The service may only implement behavior for certain locales or international preference combinations.)
If the VI SDK has to be categorized, it’s client influenced because the service provider tracks the client locale and responds accordingly. The VI SDK is indeed complicated, and most of the services and properties of managed objects are locale neutral.
When you first log into the system using the SessionManager, you can provide your locale so that the server knows your locale and responds in successive requests/responses. Your locale is held in the currentSession.locale of SessionManager.
The locale mainly affects the properties in some managed objects, such as the description properties of TaskManager, AlarmManager, AuthorizationManager, EventManager, PerformanceManager, and ScheduledTaskManager. Although they are all named description, they are different data object types inherited from the Description data object that includes two string properties: label and summary. These two properties can be displayed as they are at the client side, therefore, they should be localized.
Besides the subtypes, the Description data object can be included in other data objects. For example, the DiagnosticManagerLogDescriptor data object, which is a return type of the queryDescriptions() method of DiagnosticManager, includes Description as a localized description.
If your applications need to display any description about the task, alarm, and so on, you should always get it from the description properties. This not only saves you the time to write the descriptions, but it saves you the time to translate them when localized. The only exception is when you want to localize your application to a locale that the VirtualCenter Server does not support.
From the SessionManager, you can find out the server default locale and a list of locales for which the server has localized the messages. You can tell easily whether the server supports your locale.
Beyond these messages, the error message can be localized. The LocalizedMethodFault is a wrapper around MethodFault that provides a localized message for the wrapped fault. As already emphasized, LocalizedMethodFault is not a fault type, but a data object type.
So far, the discussion has mainly focused on the localized information from the server side. You can also send localized text from the client to the server side. For example, you can change the virtual machine name through the VI SDK. Even if you are working with an English-only version of VirtualCenter/ESX server, you can set a virtual machine’s name as a double-byte character string. On the English-only VI Client, you might see just rectangles because they don’t render well. If you open MOB to the virtual machine page, you might see the name show up correctly. That means the double-byte name has been saved correctly and your application can retrieve it using the VI SDK.
In general, you should be a little conservative with sending non-English text to the server from the API. Unless necessary, try to restrict to ASCII characters only. Some of the text should never be localized. For example, the keys in the system that identify certain resources should never be localized. Most of the time, they are not visible anyway.
The VI SDK is only part of your I18N story. To have a truly localized VI SDK application, make sure your client-side language, Web Services stub, and application are ready to handle the double-byte character. If you are using a language such as Java, it’s less of a problem because it’s built from the ground up to handle a double-byte string.