|
This document covers the following issues:
Throughout this document we will often relate to the shiva/ directory,
which is located in /hsphere/local/home/cpanel/. Hereafter, we will refer
to it as shiva/.
Important: Before you do any customization, log in as cpanel superuser under root:
# su - cpanel
All template files and directories should have
cpanel:cpanel ownership.
Adding New Language To H-Sphere Interface
To add a new language to the H-Sphere interface, you have
to create a set of custom resource bundles and configure the
system to use them instead of the defaults. This is achieved by
the following steps:
Step 1: In shiva/, create the directory custom/.
If this directory already exists, skip this step.
Step 2: In the shiva/custom/ directory, create
the directory bundles/. This directory may already
exist.
Step 3: Next, you need to declare the custom files.
In the hsphere.properties file, uncomment the line
that corresponds to the file you have created:
CUSTOM_TEMPLATE_BUNDLE = custom.bundles.hsphere_lang
CUSTOM_MENU_BUNDLE = custom.bundles.menu
CUSTOM_USER_BUNDLE = custom.bundles.messages
Step 4: If you don't intend to
change the standard H-Sphere interface labels, go to the directory shiva/custom/bundles/ and create
empty custom files with the following names:
hsphere_lang.properties
menu.properties
messages.properties
Otherwise, do the following:
1) create these three custom files as described above;
2) in the standard lang.properties files of the shiva/psoft/hsphere/lang/
directory, find the labels you would like to edit;
3) copy-paste these labels into the corresponding new custom files.
4) edit the labels in the custom files. They will replace those that come with H-Sphere.
Step 5: 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.<XYZ>lang = <LANGUAGE> (<ENCODING>)
Consider this example for the Russian language:
misc.langs.ruslang = Russian (Win-1251)
Memorize the ID (e.g. misc.langs.ruslang), as you will need it for further steps.
Step 6: Copy all English language files from shiva/psoft/hsphere/lang/
into the shiva/custom/bundles/ directory changing each filename according to the following pattern:
hsphere_lang.properties -> hsphere_lang_<language>_<COUNTRY>.properties
menu.properties -> menu_<language>_<COUNTRY>.properties
messages.properties -$gt; messages_<language>_<COUNTRY>.properties
Consider the following examples for the Russian language:
hsphere_lang_ru_RU.properties
menu_ru_RU.properties
messages_ru_RU.properties
Sometimes, you might want to add _<ENCODING>
to the end of the filename to support different encodings for your language,
for instance: hsphere_lang_ru_RU_CP1251.properties
The country, language and encoding parameters must correspond
to the ISO standards.
Step 7: Translate interface texts stored in these
files using the target encoding. 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}
Step 8: In the hsphere.properties file, find
the following line:
LANG_LIST = en_US_ISO8859_1|ISO-8859-1:misc.langs.englang ru_RU_CP1
251|windows-1251:misc.langs.ruslang
This line contains definitions for the languages that come with H-Sphere,
each including the following components:
<language>_<COUNTRY>_<ENCODING>|<html_encoding>:misc.langs.<XYZ>lang;
To the end of this line, add a definition for your custom
language following the existing examples - using
space as the delimiter.
Step 9: In the hsphere.properties file, 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 Russian
language will look as follows:
# Override system locale
LOCALE = ru_RU
# Encoding
ENCODING = Windows-1251
DB_ENCODING=windows-1251
The LOCALE value will affect not only the interface language,
but also the currency, date, time, days of the week and other
locale settings.
From the control panel navigation menu, users can choose the
interface language that will override the language set by
the reseller and the hosting provider. Users' language settings
have limited life span that is determined by the age of
cookies in users' browsers. After cookies expire, the user's
CP language will switch back to that of the provider / reseller.
You can set the age of these cookies in the hsphere.properties
file:
#Language cookies maximum age (in seconds)
#Default value = 1 year
COOKIE_AGE = 31536000
Step 10: Log in as root and
restart H-Sphere.
These steps must suffice to incorporate the possibility
of changing the regional settings and the interface language
of H-Sphere. To have your translation incorporated into the
future versions of H-Sphere, send the translated
files to support@psoft.net.
Changing Language of Context Help
Online help texts take a somewhat different approach. Carefully
follow all the procedure described in the Customizing
Templates section - copying the online help files from
the shiva-templates/common/online_help/ folder to
the shiva/custom/templates/ directory. On step 3, translate the
heading and the body of each help file in the corresponding
encoding.
In addition to the steps described in the Customizing Templates
section, change the name of each online help file in the custom-templates
directory by adding the language, country and encoding to
the name base, according to the pattern:
<base>.oh -> <base>_<language>_<COUNTRY>_<ENCODING>.oh
Consider the following example for the Russian language:
01balance.oh -> 01balance_ru_RU_Cp12.oh
Alternatively, you can omit encoding and country (or only
encoding) in the file name:
<base>.oh -> <base>_<language>_<COUNTRY>.oh
or
<base>.oh -> <base>_<language>.oh
In case of the Russian language, the file name will look
as follows:
01balance.oh -> 01balance_ru_RU.oh or
01balance.oh -> 01balance_ru.oh
Mind, however, that omitting country and encoding in the
file name may cause some texts to display incorrectly in some
browsers.
Interface Elements Not To Be Translated
1. Global Resource and Plan Resource Names
Global resource names and plan resource names are not present in the
language files,
they are set in the H-Sphere database. It is possible to
change these names there, but we don't recommend to do this, because these changes would affect
H-Sphere globally, regardless of interface languages.
2. Server Group and Logical Server Names
Server group names and logical server names
are also stored in the database and shouldn't be translated.
3. License Information
License information is required for H-Sphere support and administrators, not for end users.
Therefore, this information MUST NOT be translated in any way!
4. Buttons
The button texts that are unavailable in the language files
are generated by the browsers.
They will be different depending on the language settings of each individual browser.
Resource Bundle Lookup Sequence
Interface texts are stored in the form of
key=value sets called resource bundles, or bundles, where key
is the text mnemonic identifier,
and value is the text itself that may vary depending on language.
Templates include mnemonic identifiers and thus
generate language-independent dynamic content.
The resource bundle lookup searches for language and regional
settings in the following order:
1. USER_BUNDLES directory, file <_name>_<Lang>_<country>_<code_page>.<file_ext>;
2. DEFAULT_BUNDLES directory, file <_name>_<Lang>_<country>_<code_page>.<file_ext>;
3. USER_BUNDLES directory, file <file_name>_<Lang>_<country>.<file_ext>;
4. DEFAULT_BUNDLES directory, file <file_name>_<Lang>_<country>.<file_ext>;
5. USER_BUNDLES directory, file <file_name>_<Lang>.<file_ext>;
6. DEFAULT_BUNDLES directory, file <file_name>_<Lang>.<file_ext>;
7. USER_BUNDLES directory, file <file_name>.<file_ext>;
8. DEFAULT_BUNDLES directory, file <file_name>.<file_ext>;
9. If no appropriate settings were found, the user will get
a corresponding message and a possibility to send a trouble
ticket.
Important:
Changing the language of the interface doesn't make the system
handle non-English characters properly. Therefore, those who
add new interface languages should ensure that the administrators
and customers do not enter non-English symbols in the forms
of the H-Sphere control panel.
Supporting Input Localization for PostgreSQL
(version 2.09 and higher)
To set up a custom language support (e.g. Russian) when entering
data into PostrgreSQL, go through the following steps:
- Recompile PostgreSQL using the following keys:
--enable-locale (enable locale support)
--enable-recode (enable Cyrillic recode support)
--with-mb=WIN (enable multi-byte support, e.g. WIN)
- Create H-Sphere database supporting the new encoding (e.g. WIN).
NOTE: if the browser encoding does not agree with the database
encoding, it is impossible to guarantee a correct record in the database.
In the ~cpanel/shiva/psoft_config/hsphere.properties
configuration file, replace
DB_URL = jdbc:postgresql://127.0.0.1/hsphere
with
DB_URL = jdbc:postgresql://127.0.0.1/hsphere?charSet=<YOUR_LANGUAGE_ENCODING>
For instance, Russian language support takes the following line:
DB_URL = jdbc:postgresql://127.0.0.1/hsphere?charSet=WIN
|
