Language Bundle Compiler

H-Sphere 2.4 and up provides a new scheme of interface text customization and multilingual support. Language bundles - default, custom, and those installed with H-Sphere packages - are now compiled and merged into the resulting internal bundles located in the internal bundle directory, ~cpanel/shiva/languages by default. Instead of parsing default and custom bundles, H-Sphere now takes interface texts directly from this directory.

Merging language bundles is performed by a Java tool called language bundle compiler:

java psoft.hsphere.LangBundlesCompiler

Implications

You need to run bundle compiler if you customize language bundles, namely:

• add new languages to H-Sphere;
• edit interface texts.

Also, bundle compiler is launched when you install a package with language bundles.

How Does Language Bundle Compiler Work

1. Bundle compiler parses the LANG_LIST parameters set in:

   LANG_LIST contains definitions for the languages, delimited with whitespace, each including the following components:

   <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"). <ENCODING> is an encoding in which bundles were created and saved,
   • <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 a label for language name in H-Sphere.

   According to Java locale identifiers set in the LANG_LIST parameters, bundle compiler looks for the bundles:

   hsphere_lang.properties
   menu.properties
   messages.properties
   
   hsphere_lang_<language>.properties
   menu_<language>.properties
   messages_<language>.properties
   
   hsphere_lang_<language>_<COUNTRY>.properties
   menu_<language>_<COUNTRY>.properties
   messages_<language>_<COUNTRY>.properties
   
   hsphere_lang_<language>_<COUNTRY>_<ENCODING>.properties
   menu_<language>_<COUNTRY>_<ENCODING>.properties
   messages_<language>_<COUNTRY>_<ENCODING>.properties
   

   in the following directories, in order of priority:

   • installed package bundles: ~cpanel/shiva/packages/PackageName.
     

     Package bundle location is set in the package properties file ~cpanel/shiva/packages/PackageName/default.properties:

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

   • custom bundles: ~cpanel/shiva/custom/bundles.
     

     Custom bundle location is set in hsphere.properties:

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

   • default bundles: ~cpanel/shiva/psoft/hsphere/lang.

     Default bundle location is set in hsphere.properties:

     TEMPLATE_BUNDLE=psoft.hsphere.lang.hsphere_lang
     MENU_BUNDLE=psoft.hsphere.lang.menu
     USER_BUNDLE=psoft.hsphere.lang.messages

   See Introduction To Bundles for details.

2. Bundle compiler merges default, custom and package bundles with the same filenames and save the resulting bundles in UTF format into the internal bundle directory ~cpanel/shiva/languages.

   See Bundle Lookup Sequence for HS 2.4 and up.

   Notes:

   • If the ~cpanel/shiva/languages directory is not found, language bundle compiler will be launched automatically and will create this directory with the resulting bundles.

   • To override the default internal bundle directory, set the INT_LANGBUNDLE_DIRECTORY parameter in hsphere.properties. Or, set INT_TEMPLATE_BUNDLE, INT_MENU_BUNDLE, INT_USER_BUNDLE to override the location of the respective internal bundles.

   • When a text label is set several times, e.g., in a package bundle and in a custom/default bundle, package bundle takes precedence and override labels set in custom or default bundles. The order of priority is: package bundles, custom bundles, default bundles.

   • Depending on bundle encodings specified in the LANG_LIST parameters, bundle compiler converts all regional language bundles into UTF-8. This is done due to the Java restrictions in relation to regional encodings: Java can work only with ISO-8859-1 and UTF symbols.

     Hints:

     a) To convert regional symbols into Unicode, you can use the native2ascii JDK tool.

     b) To convert a lang file into Unicode, you can also run make in the ~cpanel/shiva/psoft/hsphere/lang directory.