Parallels H-Sphere Documentation Developer Guide


Building Language Packages


Related Docs:   Adding New Languages (Customization Guide) Building Packages Package Installation Package Downloads Page

Last modified: 28 Dec 2007


WARNING: This documentation covers Parallels H-Sphere versions up to 3.1. For the latest up-to-date Parallels H-Sphere documentation, please proceed to the official Parallels site.

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

Please also refer to PSoft collection of language packages.

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 --with-prefix=./pt_BR --with-properties --with-lang-bundle

    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/ - custom package properties file (initially empty)
  4. 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 H-Sphere"    vendor="Sample Company Inc." version="0.0.1">

    You don't need to edit other tags in _pkg.xml.

  5. Copy the translated language files into pt_BR/src/pkg_lang_bundle/:

    Important: Starting with H-Sphere 3.0 RC 1, and become deprecated, and all labels are merged into a single for each language!

    cd src/pkg_lang_bundle/
    cp /some/location/ .
    cp /some/location/ .
    cp /some/location/ .

  6. Create empty files,, and in the pt_BR/src/pkg_lang_bundle/ directory:


    These files are required for correct bundle compilation during the package installation.

  7. Add the misc.langs.<LABEL>lang label with the name of the new language into This text will appear as the new language option in the Change Language dropdown menus in H-Sphere.

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


    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 to convert these symbols into Unicode characters (\uxxxx notations, like "Portugu\u00eas" instead of "Português" 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)

  8. Edit src/pkg_config/

    1. Add properties that specify location of language bundles implemented in this package. The format is:


      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


    2. Add the new language to the list of languages available in 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


      • <language>, <COUNTRY>, and <ENCODING> are Java locale identifiers. For detailed description and the tables of canonical identifiers, please refer to Understanding Language Bundles in Customization Guide.
      • <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


      1) Don't specify other languages into LANG_LIST in! During the package installation, the package properties will be customize the default properties in ~cpanel/shiva/psoft_config/

      2) 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.

  9. Return from the package directory and run package builder:

    cd ~cpanel/shiva/custom/Packages
    java --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 H-Sphere.

Related Docs:   Adding New Languages (Customization Guide) Building Packages Package Installation Package Downloads Page

© Copyright 2018. Parallels Holdings. All rights reserved.