H-Sphere Documentation Developer Guide


Building Language Packages

(version 2.4 and higher)


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

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 psoft.hsp.tools.PkgConfigurator --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/default.properties - 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/:

    cd src/pkg_lang_bundle/
    cp /some/location/hsphere_lang_pt_BR.properties .
    cp /some/location/menu_pt_BR.properties .
    cp /some/location/messages_pt_BR.properties .

  6. Create empty files hsphere_lang.properties, menu.properties, and messages.properties in the pt_BR/src/pkg_lang_bundle/ directory:

    touch hsphere_lang.properties menu.properties messages.properties

    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 hsphere_lang.properties. 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/default.properties:

    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 default.properties:


    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 default.properties! During the package installation, the package properties will be customize the default properties in ~cpanel/shiva/psoft_config/hsphere.properties.

      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 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 any H-Sphere 2.4 and up.

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

User comments
No comments for this page.
Add comment

Home   Products   Services   Partners   Support   News   Contact   Forum
© 2020 psoft.net.
All rights reserved.