Understanding Interface Text (Language) Bundles

Interface texts are defined in key=value sets collected in separate files for each language and encoding, where key is a mnemonic identifier for the text, and value is the text itself that is different for each language and encoding. Such files are called resource bundles, or language bundles, or simply bundles. H-Sphere templates include mnemonic identifiers and thus generate language-independent dynamic content.

Default Bundles (Installed With H-Sphere)

Default bundles are bundles containing text values H-Sphere takes by default. Default bundle location is set in ~cpanel/shiva/psoft_config/hsphere.properties:

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

It means that default bundles are set in the following files of the /hsphere/local/home/cpanel/shiva/psoft/hsphere/lang/ directory:

1. Texts in English

• hsphere_lang.properties - template and tooltip texts;
• menu.properties - the navigation menu texts;
  
• messages.properties - system e-mail notification texts. Since HS 2.4, it is recommended changing them in CP interface.

2. Texts in other languages

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

Here, <language>, <COUNTRY>, and <ENCODING> are Java-compliant language, country and encoding identifiers.

Please refer to the tables of canonical identifiers:

• Countries
• Encodings (aka charsets or variants).
  Note: For CP server under FreeBSD, use canonical encodings for Java 1.3.

1) Some languages have different character sets, e.g., standard Chinese and simplified Chinese. In such case you cannot omit the encoding in bundle names.

For example, standard Chinese (Big5 encoding) bundles will look like:

hsphere_lang_zh_CN_Big5.properties
menu_CN_Big5.properties
messages_CN_Big5.properties

And for simplified Chinese (EUC_CN encoding) bundles will be:

hsphere_lang_zh_CN_EUC_CN.properties
menu_CN_EUC_CN.properties
messages_CN_EUC_CN.properties

2) Some languages have variations in different countries, e.g., Portuguese (Portugal) and Portuguese (Brazil). Then, you specify language and country for each case:

For example, Portuguese (Portugal) bundles will be:

hsphere_lang_pt_PT.properties
menu_pt_PT.properties
messages_pt_PT.properties

Portuguese (Brazil) bundles will be:

hsphere_lang_pt_BR.properties
menu_pt_BR.properties
messages_pt_BR.properties

3) If you know for sure the language won't be used for other countries, you may omit the country identifier, e.g., for Russian:

hsphere_lang_ru.properties
menu_ru.properties
messages_ru.properties

Important: In any case, you must fully specify the correct language, country and encoding identifiers in the LANG_LIST parameter in hsphere.properties for H-Sphere packages. In particular, H-Sphere should know in what encoding the bundles were created to be able to convert them to Unicode.

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:

• <HTML_ENCODING> is HTML-compliant encoding (parameter deprecated since 2.4 and is not really used but must still be specified for the sake of compatibility);
• misc.langs.<LABEL>lang is the label for the language name in H-Sphere interface. These labels are set in hsphere_lang bundles. For example:

  misc.langs.rulang = Russian

Custom Bundles

Default bundle directory is being rewritten with each H-Sphere update. So, if you make changes in the default bundles or add new bundles to the default bundle directory, you will lose all such modifications.

Instead, you use custom bundles to modify and expand default bundles.

Custom bundle location is set in hsphere.properties in the CUSTOM_TEMPLATE_BUNDLE, CUSTOM_MENU_BUNDLE, and CUSTOM_USER_BUNDLE parameters. For example:

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

It means that custom bundles will be searched by H-Sphere in the ~cpanel/shiva/custom/bundles/ custom bundle directory.

Custom bundle files are of the same filename format as in the default bundle directory. To customize texts in the default bundles, files with the same names are created in the custom bundle directory; they contain only labels to be added or to override the default texts. New language bundles are also created in the custom bundle directory, and you don't worry they'll be lost with the next updates.

See the following documents for customization instructions:

• Interface Text Customization
• Adding New Language To H-Sphere

Resulting Internal Bundles

(HS 2.4 and up)

In H-Sphere 2.4, default and custom bundles, along with bundles coming with H-Sphere packages, are compiled and merged into the so-called internal bundles located in the ~cpanel/shiva/languages directory. It is there that H-Sphere takes bundles from.

Internal bundles location can be changed. You either set INT_LANGBUNDLE_DIRECTORY to override the whole internal bundles directory (~cpanel/languages), or set INT_TEMPLATE_BUNDLE, INT_MENU_BUNDLE, INT_USER_BUNDLE to override the respective internal bundles.

Please refer to Compiling Language Bundles for details.

Bundle Lookup Sequence

H-Sphere searches for text labels in language bundles in the following order:

• In HS versions earlier than 2.4:

  1. CUSTOM_BUNDLES directory, file <bundle_name>_<language>_<COUNTRY>_<ENCODING>.properties;
  2. DEFAULT_BUNDLES directory, file <bundle_name>_<language>_<COUNTRY>_<ENCODING>.properties;
  3. CUSTOM_BUNDLES directory, file <bundle_name>_<language>_<COUNTRY>.properties;
     
  4. DEFAULT_BUNDLES directory, file <bundle_name>_<language>_<COUNTRY>.properties;
     
  5. CUSTOM_BUNDLES directory, file <bundle_name>_<language>.properties;
     
  6. DEFAULT_BUNDLES directory, file <bundle_name>_<language>.properties;
     
  7. CUSTOM_BUNDLES directory, file <bundle_name>.properties;
     
  8. DEFAULT_BUNDLES directory, file <bundle_name>.properties;
     
  9. If no appropriate labels are found, the user will get a corresponding notification and a possibility to send a trouble ticket.
• 1. <bundle_name>_<language>_<COUNTRY>_<ENCODING>.properties
  2. <bundle_name>_<language>_<COUNTRY>.properties
  3. <bundle_name>_<language>.properties
  4. <bundle_name>.properties (default English text)
  5. If no appropriate labels are found, the user will get a corresponding notification and a possibility to send a trouble ticket.

  Note that no different encodings for languages are present in internal bundles. Language bundle compiler converts all regional data in default and custom language bundles into UTF-8 format.