VMTN
Blogs
Twitter
Facebook
YoutubeOVF Localization
The OVF specification includes an internationalization section that describes how to localize an OVF descriptor. This lets you address the issue of translating all the human readable metadata in the OVF descriptor without having to keep multiple copies of the descriptor, each localized to a specific language. Obviously it does not make sense to localize everything in an OVF descriptor, since some information is only intended to be read by a machine. A rule of thumb is that you can localize all the elements that carry some kind of metadata which are useful to the deployer of the OVF package but not needed by the deployment platform. For a full list of elements that can be localized please see the list at the end of this blog post.
Example
Let us take a look at how the user experiences an OVF package that has been localized:
OVF deployment using default language.
OVF deployment using German localization.
The vSphere Client attempts to use the localized messages from the OVF package which matches the locale of the users Windows installation. If a matching localization is not found, the default language of the OVF descriptor (English in the example) is used.
Localizing the OVF Descriptor
Let’s look at how to write an OVF descriptor that is localized to multiple language including both English and German as in the above example, but also Danish and Swahili:
<Envelope xml:lang="en-US">
...
<VirtualSystem ovf:id="MyVM">
...
<ProductSection>
<Info>Information about the installed software</Info>
<Property ovf:key="num_connections" ovf:type="string"
ovf:userConfigurable="true">
<Label ovf:msgid="num_connections.label">
Number of connections
</Label>
</Property>
<Property ovf:key="admin_address" ovf:type="string"
ovf:userConfigurable="true">
<Label ovf:msgid="admin_address.label">Administrator address</Label>
<Description ovf:msgid="admin_address.description">
Email address of the systems administrator
</Description>
</Property>
</ProductSection>
...
</VirtualSystem>
<!-- German localized messages -->
<Strings xml:lang="de-DE">
<Msg ovf:msgid="num_connections.label">Zahl der Anschlüsse</Msg>
<Msg ovf:msgid="admin_address.label">Verwalteradresse</Msg>
<Msg ovf:msgid="admin_address.description">
Email address des Systemverwalters
</Msg>
</Strings>
<!-- Danish localized messages -->
<Strings xml:lang="da-DK">
<Msg ovf:msgid="num_connections.label">Antal forbindelser</Msg>
<Msg ovf:msgid="admin_address.label">Administrator adresse</Msg>
<Msg ovf:msgid="admin_address.description">
System administratorens email-adresse
</Msg>
</Strings>
<!-- Swahili localized messages -->
<Strings xml:lang="sw">
<Msg ovf:msgid="num_connections.label">Idadi ya connections</Msg>
<Msg ovf:msgid="admin_address.label">Administrator anwani</Msg>
<Msg ovf:msgid="admin_address.description">
Barua pepe ya system administrator
</Msg>
</Strings>
</Envelope>
In this example, we are localizing the label of the "num_connections" property and the label and description of the "admin_address" property.
As you can see, it is pretty straight forward to localize an OVF descriptor to support multiple languages:
- First prepare the OVF descriptor for localization by adding an ovf:msgid attribute to each of the elements you want to be localized (see the list of possible elements in the last section of this blog entry) and give the ovf:msgid a unique value;
- Next you add a Strings section for each of the locales you
want to support and specify the locale by using the xml:lang attribute;
- For each ovf:msgid attribute in the OVF descriptor create a Msg element in the Strings section with the same ovf:msgid value.
The human readable messages in the example ProductSection element are used as the default language and will be used if no appropriate locale is available in the descriptor. To specify the default language of the OVF descriptor (the language used in the default messages), set the xml:lang attribute on the top Envelope element level. In our example we have set it to US English (en-US).
The format of the locale is standard and is written as [language]-[country]-[variant]. It is not necessary to specify the full locale for a string bundle. For example, if we simply specify the German locale in the example as de it can then be used for several German speaking countries such as Austria (de-AT), Germany (de-DE), Luxembourg (de-LU) and parts of Switzerland (de-CH). If a user uses locale X on his computer, we select the locale in the OVF descriptor which matches the beginning or all of X. If two locales match X we chose the one that gives the longest match. This is why changing the locale from de-DE to de means that the localization can be used on the locales de-AT, de-DE, de-LU and de-CH, since de is a prefix of those.
External String Bundles
Often when managing multiple locales it is impractical to keep them in the same file. For this purpose the OVF specification allows you to extract all the Strings elements and put them in separate files. From the example OVF descriptor we have used, we can take all the three different localizations and put them in separate files (we will call these files string bundles):
<References>
<File ovf:href="MyVM-de-DE.msg" ovf:id="msgs1"/>
<File ovf:href="MyVM-da-dk.msg" ovf:id="msgs2"/>
<File ovf:href="MyVM-sw.msg" ovf:id="msgs3"/>
<File ovf:href="MyVM-disk1.vmdk" ovf:id="file2" ovf:size="9580544"/>
...
</References>
...
</Envelope>
The files are then referenced in the beginning of the Reference section in the OVF descriptor (important: String bundles must be listed first in the reference section):
File: MyVM-de-DE.msg
<!-- German localized messages -->
<Strings xml:lang="de-DE">
<Msg ovf:msgid="num_connections.label">Zahl der Anschlüsse</Msg>
<Msg ovf:msgid="admin_address.label">Verwalteradresse</Msg>
<Msg ovf:msgid="admin_address.description">
Email address des Systemverwalters
</Msg>
</Strings>
File: MyVM-da-DK.msg
<!-- Danish localized messages -->
<Strings xml:lang="da-DK">
<Msg ovf:msgid="num_connections.label">Antal forbindelser</Msg>
<Msg ovf:msgid="admin_address.label">Administrator adresse</Msg>
<Msg ovf:msgid="admin_address.description">
System administratorens email-adresse
</Msg>
</Strings>
File: MyVM-sw.msg
<!-- Swahili localized messages -->
<Strings xml:lang="sw">
<Msg ovf:msgid="num_connections.label">Idadi ya connections</Msg>
<Msg ovf:msgid="admin_address.label">Administrator anwani</Msg>
<Msg ovf:msgid="admin_address.description">
Barua pepe ya system administrator
</Msg>
</Strings>
In the above example we created three files, one for each locale. The OVF specification allows multiple Strings elements in the same file next to the OVF descriptor, so it is not necessary to create a file per locale as we did. However, by keeping the locales in separate string bundles it become easy to extend the supported locales simply by adding more string bundle files.
Further Reading
To learn more about localization, check out section in the OVF 1.0.0 specification: http://www.dmtf.org/standards/published_documents/DSP0243_1.0.0.pdf.
List of Localizable Elements
- Info element on VirtualSystem and VirtualSystemCollection
- Name element on VirtualSystem and VirtualSystemCollection
- Info element on AnnotationSection, DeploymentOptionSection, DiskSection, EulaSection, InstallSection, NetworkSection, OperatingSystemSection, ProductSection, ResourceAllocationSection, StartupSection and VirtualHardwareSection.
- Annotation element on AnnotationSection
- License element on EulaSection
- Description element on NetworkSection
- Description element on OperatingSystemSection
- Description, Product, Vendor, Label, and Category elements on ProductSection
- Description and Label elements on DeploymentOptionSection
- ElementName, Caption and Description sub-elements on the System element in VirtualHardwareSection
- ElementName, Caption and Description sub-elements on Item elements in VirtualHardwareSection
- ElementName, Caption and Description sub-elements on Item elements in ResourceAllocationSection
Comments