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

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:

- hsphere_lang.properties - template and tooltip texts;
- menu.properties - the navigation menu texts;
- messages.properties - 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:

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.

  • Encoding: Translation can be performed in any encoding. However, in H-Sphere 2.4 and up, all language bundles are converted into UTF-8 during their compilation.

  • 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 or build language packages yourself.

  • 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. 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 .
      cp /some/location/menu_pt_BR.properties .
      cp /some/location/messages_pt_BR.properties .

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

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

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

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

      java psoft.hsphere.LangBundlesCompiler

  • Overriding default bundles with custom bundles

    (outdated in HS 2.4)

    This method is outdated in HS 2.4. Find documentation here.


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





User comments
No comments for this page.
Add comment


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