|
|
Chapter 5. Configuring locales for openCRX with web.xml
Configuring locales for openCRX is done by modifying the file web.xml in the directory C:\temp\opencrx-core-CRX.war\WEB-INF. If you open the file web.xml you will find the following section:
Example 5-1. web.xml containing locale configuration information
.
<!-- locales -->
<init-param>
<param-name>locale[0]</param-name>
<param-value>en_US</param-value>
</init-param>
<init-param>
<param-name>locale[1]</param-name>
<param-value>de_CH</param-value>
</init-param>
.To configure an additional locale for openCRX you need to add a new locale-block. For example, to add the locale xx_YY you modify web.xml as follows:
Example 5-2. web.xml containing locale configuration information for en_US, de_CH, and the new locale xx_YY
.
<!-- locales -->
<init-param>
<param-name>locale[0]</param-name>
<param-value>en_US</param-value>
</init-param>
<init-param>
<param-name>locale[1]</param-name>
<param-value>de_CH</param-value>
</init-param>
<init-param>
<param-name>locale[2]</param-name>
<param-value>xx_YY</param-value>
</init-param>
.
Please note that the index number must be unique (i.e. you can only assign locale xx_YY to index number "2" with locale[2] if no other locale is assigned to index number "2"). Furthermore, index number "0" is reserved for the default locale (by default, locale en_US is assigned to index number "0").
You must ensure that the index number in web.xml matches the index number in locale.xml for this newly added locale (e.g. if xx_YY is assinged to index number m in locale.xml then xx_YY must be assigned the index number m in web.xml). See also code table files.
When configuring locales for openCRX it is important that you are aware of the Fallback Mechanism. Taking into account what happens when there is no localized directory/file/string/entry/etc. available for a configured locale helps you to control what the user of openCRX is going to see in place of a nicely translated text.
Fallback Mechanism
The following rules apply for missing localization information (it is assumed that the locale is xx_YY):
user interface configuration
if no entry is found for the respective label/toolTip, then the existing entry of the locale xx_ZZ (i.e. same language as xx_YY) with the highest index number (see Configuring locales for openCRX with web.xml) is taken. if no entry is found with the same language xx, then the entry of the default locale (i.e. the locale with index number "0", usually en_US) is taken.
code tables
if no entry is found for the respective code, then the existing entry of the locale xx_ZZ (i.e. same language as xx_YY) with the highest index number (see Configuring locales for openCRX with web.xml) is taken. if no entry is found with the same language xx, then the entry of the default locale (i.e. the locale with index number "0", usually en_US) is taken.
opencrx.texts.properties and texts.properties
if no entry is found for the respective name, then the existing entry of the locale xx_ZZ (i.e. same language as xx_YY) with the highest index number (see Configuring locales for openCRX with web.xml) is taken. if no entry is found with the same language xx, then the entry of the default locale (i.e. the locale with index number "0", usually en_US) is taken.
html help pages
there is no fallback mechanism - if a page is missing for a requested locale the user will get an error 404 (page not found)
login.jsp
there is no fallback mechanism - login.jsp is a special case anyway (see modify Login.jsp)
The following description explains the implemented locale fallback mechanism of openCRX in a somewhat more formal way (only applies to user interface configuration, code tables, and text.properties). Please note that the locale fallback is based on language xx and not on a fully qualified locale string xx_YY:
Iterate all locales configured in web.xml starting with index number 0, i.e. locale[0], locale[1], .
Try to load resources from locale i, i.e. config/code/<locale i>, config/ui/<locale i>, config/texts/<locale i>
If no resources are found at locale i fallback to resources of locale j, where j = max(J), J = {0} + {j, locale[i].lang == locale[j].lang}
Example: If e.g. the locales en_US (locale[0]), de_CH (locale[1]) and de_DE (locale[2]) are configured and no resources are available for de_DE then de_DE falls back to de_CH.
