Building Language Packages

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)

   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 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:

      TEMPLATE_BUNDLE=packages.PackageName.hsphere_lang
      MENU_BUNDLE=packages.PackageName.menu
      USER_BUNDLE=packages.PackageName.messages

      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
      MENU_BUNDLE=packages.Language_PT_BR.menu
      USER_BUNDLE=packages.Language_PT_BR.messages

   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

      Here:

      • <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

      Notes:

      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.