Adding New Languages To H-Sphere

This document introduces methods of adding languages to H-Sphere interface. We presume you are familiar with the concept of language bundles.

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

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

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

hsphere_lang_<language>_<COUNTRY>_<ENCODING>.properties
menu_<language>_<COUNTRY>_<ENCODING>.properties
messages_<language>_<COUNTRY>_<ENCODING>.properties

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:

hsphere_lang_pt_BR.properties
menu_pt_BR.properties
messages_pt_BR.properties

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

  but:

  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.

• Right-to-left languages (Arabic, Hebrew, etc.): Starting with version 2.4.1, 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

  (HS 2.4 and up)

  Since version 2.4, 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.

• Compiling bundles

  (HS 2.4 and up)

  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/hsphere.properties (if it's not set):

     CUSTOM_TEMPLATE_BUNDLE=custom.bundles.hsphere_lang
     CUSTOM_MENU_BUNDLE=custom.bundles.menu
     CUSTOM_USER_BUNDLE=custom.bundles.messages

  4. Create the files hsphere_lang.properties, menu.properties, and messages.properties 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
     touch hsphere_lang.properties menu.properties messages.properties

  5. 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/hsphere_lang.properties file, following the pattern:

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

     For example, for Portuguese (Brazil):

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

  6. 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/hsphere.properties. 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:

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

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

  7. In hsphere.properties, 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
     ENCODING = UTF-8
     

     The LOCALE value will affect not only the interface language, but also the currency, date, time, days of the week and other locale settings.

  8. Run language bundle compiler to implement new bundles into H-Sphere:

     java psoft.hsphere.LangBundlesCompiler