Parallels H-Sphere Documentation Customization Guide

 

Understanding Interface Text (Language) Bundles

 
 

Related Docs:   Understanding Templates Interface Text Customization Adding New Languages To H-Sphere Language Bundle Compiler

Last modified: 28 Dec 2007

 

WARNING: This documentation covers Parallels H-Sphere versions up to 3.1. For the latest up-to-date Parallels H-Sphere documentation, please proceed to the official Parallels site.

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 (see bundle lookup sequence). Default bundle location is set in ~cpanel/shiva/psoft_config/hsphere.properties:

Important: Starting with H-Sphere 3.0 RC 1, menu.properties and messages.properties become deprecated, and all labels are merged into a single hsphere_lang.properties for each language!

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

Important: Starting with H-Sphere 3.0 RC 1, menu.properties and messages.properties become deprecated, and all labels are merged into a single hsphere_lang.properties for each language!

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

 

2. Texts in other languages

Important: Starting with H-Sphere 3.0 RC 1, menu.properties and messages.properties become deprecated, and all labels are merged into a single hsphere_lang.properties for each language!

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:

All source bundles, in whatever encoding they were created, are compiled into Unicode (UTF-8). Therefore, in most cases <ENCODING> and <COUNTRY> identifiers may be omitted in bundle names.

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 or in package properties file 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:

It is also possible to build installable packages with custom bundles.

 

Resulting Internal Bundles

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:

The search is made in the internal bundle directory (~cpanel/shiva/languages by default):

  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.


Related Docs:   Understanding Templates Interface Text Customization Adding New Languages To H-Sphere Language Bundle Compiler



© Copyright 2017. Parallels Holdings. All rights reserved.