Building Language Packages

This document will guide you through the process of building a package that adds a new language to Parallels H-Sphere interface. A package is built into one portable .hsp file and can be easily installed by a Parallels H- Sphere system administrator.

Please also refer to the collection of Parallels H-Sphere language packages: http://www.psoft.net/downloads/index.html#languages.

To build a language package, you should be familiar with the concept of language bundles and the way they are compiled.

Let us take Portuguese (Brazil) as a sample language to be added. We assume you have the language bundles already translated.

1. Log into the CP server as cpanel user.
2. Create a special location where you will assemble and build your packages, for example, ~cpanel/shiva/custom/Packages:

   mkdir ~cpanel/shiva/custom/Packages

3. Run package configurator:

   cd ~cpanel/shiva/custom/Packages

   java psoft.hsp.tools.PkgConfigurator --with-prefix=./pt_BR --with-properties --with-lang-bundle

4. Package configurator will create the pt_BR directory, which includes the following structure:

   src/_pkg.xml - package configuration file

   src/pkg_lang_bundle/ - directory where you will place new language files

   src/pkg_config/default.properties - custom package properties file (initially empty)

5. Set the package name, version, build, vendor, description in src/_pkg.xml:

   <pkg build="1" name="Language_PT_BR" description="Portuguese (Brazil) Language Package"

      info="Package for installation of the Portuguese (Brazil) language into Parallels H-Sphere"

      vendor="Sample Company Inc." version="0.0.1">

6. You don't need to edit other tags in _pkg.xml.
7. Copy the translated language files into pt_BR/src/pkg_lang_bundle/:

   Important: Starting with Parallels H-Sphere 3.0 RC 1, menu.properties and messages.properties become deprecated, and all labels are collected a single hsphere_lang.properties file for each language!

   cd src/pkg_lang_bundle/

   cp /some/location/hsphere_lang_pt_BR.properties .

8. Create the empty file hsphere_lang.properties in the pt_BR/src/pkg_lang_bundle/ directory:

   touch hsphere_lang.properties

9. These files are required for correct bundle compilation during the package installation.
10. Add the misc.langs.<LABEL>lang label with the name of the new language into hsphere_lang.properties. This text will appear as the new language option in the Change Language dropdown menus in Parallels H-Sphere.

    misc.langs.ptlang = Portugu\u00eas (Brasil)

    Notes:

    1) Default (English) language bundles are written in the ISO-8859-1 encoding. Special Latin and non-Latin characters must be converted into Unicode. Use the native2ascii JDK tool (http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/native2ascii.html) to convert these symbols into Unicode characters (\uxxxx notations, like "Portugu\u00eas" instead of "Portugues" in the example above).

    2) If the original language name significantly differs from that in English, (especially for non-Latin alphabets), we recommend adding its English transcription, e.g.:

    misc.langs.de_atlang = Deutch (\u00d6sterreich) - German (Austria)

11. Edit src/pkg_config/default.properties:
12. Add properties that specify location of language bundles implemented in this package. The format is:

    TEMPLATE_BUNDLE=packages.PackageName.hsphere_lang

    Here, PackageName is the value of the name attribute of the pkg tag in _pkg.xml.

    In our example, we add the following lines to default.properties:

    TEMPLATE_BUNDLE=packages.Language_PT_BR.hsphere_lang

13. Add the new language to the list of languages available in Parallels H-Sphere. Set the language and encoding of the translated language files in the LANG_LIST parameter. The format is:

    LANG_LIST = <language>_<COUNTRY>_<ENCODING>|<HTML_ENCODING>:misc.langs.<LABEL>lang

    Here:

    • <language>, <COUNTRY>, and <ENCODING> are Java locale identifiers. For detailed description and the tables of canonical identifiers, please refer to Understanding Language Bundles.
    • <HTML_ENCODING> is the HTML-compliant encoding (this parameter is deprecated since 2.4 and is not really used but must still be specified for the sake of compatibility);
    • misc.langs.<LABEL>lang is the previously set language label.
    • For Portuguese (Brazil):

      LANG_LIST = pt_BR_ISO-8859-15|ISO-8859-15:misc.langs.ptlang

      Notes:

    • Don't specify other languages into LANG_LIST in default.properties! During the package installation, the package properties will be customize the default properties in ~cpanel/shiva/psoft_config/hsphere.properties.
    • You must specify the correct encoding in which the language bundle files were created and saved. During the package installation, language bundle compiler will convert these files into UTF-8.
14. Return from the package directory and run package builder:

    cd ~cpanel/shiva/custom/Packages

    java psoft.hsp.tools.PkgBuilder --with-source=./pt_BR

    The package Language_PT_BR.0.0.1-1.hsp will be created in the pt_BR directory. It is ready to be installed on Parallels H-Sphere.