Parallels H-Sphere Documentation Customization Guide


Adding New Languages To H-Sphere


Related Docs:   Understanding Templates Understanding Bundles Interface Text Customization Updating Translation of H-Sphere Interface

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 introduces methods of adding languages to H-Sphere interface. We presume you are familiar with the concept of language bundles.


Translating Language Bundles

NOTE: H-Sphere developers are not responsible for adding languages to H-Sphere interface and updating translation of the default English bundles. It is entirely up to H-Sphere owners. All language bundle translations included into H-Sphere interface are kindly provided by our customers. You are also welcome to contact PSoft team and share your new and updated translations, in files or packages, to have them incorporated into the upcoming versions of H-Sphere.

Default H-Sphere interface language is English. The default English files are located in ~cpanel/shiva/psoft/hsphere/lang:

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

- - template and tooltip texts;
- - the navigation menu texts;
- - system e-mail notification texts.

You can also download default (English) language bundles from our site.

Translate these files and save new language bundles to a separate location as:


where <language>, <COUNTRY>, and <ENCODING> are Java locale identifiers. For detailed description and the tables of canonical identifiers, please refer to Understanding Language Bundles.

For example, for Portuguese (Brazil) these files will be:

Please take into account the following considerations on translating the bundles:

  • Using quotes in the text: If a label or message has a variable in curly brackets, e.g. {0}, single quotes and apostrophes (') must be replaced with two single quotes (''). For example, in English we write:

    search.view_invoice = View Client's Invoice


    billing.del_no = No, I don''t want to delete {0}

  • Updating the translation: With upoming versions of H-Sphere, default English texts may be changed and new labels may be added, so you need to update translation of your language bundles accordingly.
  • Encoding: Translation can be performed in any encoding. All language bundles are converted into UTF-8 during their compilation.
  • Right-to-left languages (Arabic, Hebrew, etc.): H-Sphere supports right to left languages, such as Arabic or Hebrew. On this step, you need to specify whether the target language is "left to right" or "right to left":
    In the file hsphere_lang_<LANGUAGE_CODE>.properties, add the following lines:

    # "text_direction" is a special label used to define
    # which text direction is appropriate for the current
    # language bundle.
    # There are 2 possible values:
    # - "ltr" means "Left to right";
    # - "rtl" means "Right to left".
    text_direction = ltr

    setting text_direction to the value which is appropriate for the target language.


Adding New Language Bundles Into H-Sphere

H-Sphere provides the following alternative ways of adding new languages:

With packages

H-Sphere provides an easy way to add languages by installing packages (.hsp files) to the system. You may install ready-to-use and portable packages to any of your H-Sphere control panels or build language packages yourself.

Compiling bundles

Instead of building a package, you create new language bundles in custom bundle directory and run language bundle compiler.

  1. Login as the cpanel user. All affected files must have cpanel:cpanel ownership.
  2. Create custom bundle directory, e.g., ~/shiva/custom/bundles if it is not created yet.
  3. Set custom bundle location in ~cpanel/shiva/psoft_config/ (if it's not set):

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


  4. Create the files,, and in the ~/shiva/custom/bundles directory if they are not there. Even if you don't need to modify them, they are important for correct bundle compilation:

    cd ~cpanel/shiva/custom/bundles

  5. Copy the translated language bundles to ~cpanel/shiva/custom/bundles. For example, for Portuguese (Brazil):

    cd ~cpanel/shiva/custom/bundles
    cp /some/location/ .
    cp /some/location/ .
    cp /some/location/ .

  6. To ensure that the new language is available to choose from the interface, add a label for your language (ID and definition) into the shiva/custom/bundles/ file, following the pattern:

    misc.langs.<LABEL>lang = <LANGUAGE> (<COUNTRY>)

    For example, for Portuguese (Brazil):

    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 presented in Unicode. Use the native2ascii JDK tool to convert these symbols into Unicode characters (\uxxxx notations, like "\u00ea" instead of "ê" 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)

  7. Add new language to the list of languages available in H-Sphere. For this, add the language and encoding of the translated files to the LANG_LIST parameter in ~cpanel/shiva/psoft_config/ For example:

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

    This line contains definitions for the languages that come with H-Sphere, delimited with whitespace, each including the following components:


    Here, misc.langs.<LABEL>lang; is the label with the language name, which is set in the previous step.

  8. In, set system locale and encoding to custom values. The locale should correspond to the Java ISO standards, the encoding must correspond to the browser standards. For example, settings for the Portuguese (Brazil) language will look as follows:

    # Override system locale
    LOCALE = pt_BR
    # Encoding

    The LOCALE value will affect not only the interface language, but also the currency, date, time, days of the week and other locale settings.
  9. Run language bundle compiler to implement new bundles into H-Sphere:

    java psoft.hsphere.LangBundlesCompiler

  10. Restart H-Sphere

Related Docs:   Understanding Templates Understanding Bundles Interface Text Customization Updating Translation of H-Sphere Interface

© Copyright 2018. Parallels Holdings. All rights reserved.