Adding New Languages To Parallels H-Sphere

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

Translating Language Bundles

Note: Parallels H-Sphere developers are not responsible for adding languages to Parallels H-Sphere interface and updating translation of the default English bundles. It is entirely up to Parallels H-Sphere owners. All language bundle translations included into Parallels H-Sphere interface or localization packages are kindly provided by our customers.

Default Parallels H-Sphere interface language is English. The default English interface labels are located in the ~cpanel/shiva/psoft/hsphere/lang directory in the hsphere_lang.properties file.

Note: Since H-Sphere 3.0, menu.properties and messages.properties with menu labels and system e-mail notification texts are collected in a single hsphere_lang.properties file.

You can also download default (English) language bundles from our site: http://hsphere.parallels.com/downloads/English.zip

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

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

here, <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) it will be hsphere_lang_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 Freemarker 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 upcoming versions of Parallels 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.): Parallels 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

Adding New Language Bundles Into Parallels H-Sphere

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

With packages

Parallels 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 Parallels 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.

Login as the cpanel user. All affected files must have cpanel:cpanel ownership.
Create custom bundle directory, e.g., ~/shiva/custom/bundles if it is not created yet.
Set custom bundle location in ~cpanel/shiva/psoft_config/hsphere.properties (if it's not set):
CUSTOM_TEMPLATE_BUNDLE=custom.bundles.hsphere_lang
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
Copy the translated language bundles to ~cpanel/shiva/custom/bundles. For example, for Portuguese (Brazil):
cd ~cpanel/shiva/custom/bundles

cp /some/location/hsphere_lang_pt_BR.properties .
To ensure that the new language is available to choose from the interface, add a label for your language (ID and definition) into the ~cpanel/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 "e" 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)
Add new language to the list of languages available in Parallels 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 Parallels 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.
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.
Run language bundle compiler to implement new bundles into Parallels H-Sphere:
java psoft.hsphere.LangBundlesCompiler
Restart Parallels H-Sphere.