![]() |
||
openCRX Language Localization GuideVersion 1.5.0www.opencrx.orgThe contents of this file are subject to a BSD license (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License here
Chapter 1. About this BookThis book describes which openCRX files are language-specific and how you can localize openCRX for a (new) language or a set of (new) languages. What do you need to understand this bookThis book describes how to get openCRX to work with different language files and how to create (new) language files for openCRX. You should be comfortable with editing XML files. Chapter 2. PrerequisitesThis book assumes that you have downloaded an openCRX core distribution and set up openCRX for Ant as described in the openCRX README (including the installation of openMDX). Creating/changing language-specific files does not require a full installation of openCRX, although it is helpful to have access to a working installation in order to test your changes. You can create/edit language-specific files without installing an application server or a database. Chapter 3. Language-specific filesAll the language-specific files of openCRX are contained in the file opencrx-core-CRX.war, which is included in the file opencrx-core-CRX-web.ear included in the openCRX distribution (please note that this file may already be exploded/unzipped in which case you will have a directory called opencrx-core-CRX.war instead of a file). Language-specific files can be grouped as follows:
Note: openCRX locale IDs are based on a widely accepted standard where the locale ID xx_YY is composed of an alpha-2 language code xx (see http://en.wikipedia.org/wiki/ISO_639) and an alpha-2 country code YY (see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). The following directory listing gives an overview of the structure discussed above. Example 3-1. language-specific files in opencrx-core-CRX.war opencrx-core-CRX.war | ... | helpJsCookie_de_CH.html | helpJsCookie_en_US.html | helpSearch_de_CH.html | helpSearch_en_US.html | ... \--WEB-INF | ... | web.xml | ... +--config | +--code | | +--de_CH | | | accountcategory.xml | | | ... | | | utcoffset.xml | | | | | \--en_US | | accountcategory.xml | | | ... | | utcoffset.xml | | | +--texts | | +--de_CH | | | opencrx.texts.properties | | | texts.properties | | | | | \--en_US | | | opencrx.texts.properties | | texts.properties | | | \--ui | +--de_CH | | abstractcontract.xml | | | ... | | wf.xml | | | \--en_US | abstractcontract.xml | | | ... | wf.xml ...
Chapter 4. Create files to support a new localeThe following steps are required to create new language-specific files to support a new locale xx_YY:
Subsequently, we will look at each of the steps required to create language-specific files in more detail.
For this guide it is assumed that
Example 4-1. directory structure of the exploded/unzipped file opencrx-core-CRX.war C:\temp\opencrx-core-CRX.war | ... \--WEB-INF +--config | +--code | | +--de_CH | | \--en_US | | \--... | +--texts | | +--de_CH | | \--en_US | | \--... | \--ui | | +--de_CH | | \--en_US | | \--... | ... user interface configuration filesFor advanced openCRX administrators there is a fast procedure to create user interface configuration files for a new locale xx_YY:
This "manual" management of localized files, however, makes it rather difficult to maintain consistency across multiple locales if the user interface customization changes. The tools ui-merge and ui-split exist to help you manage and maintain a large number of locales. With ui-merge you can pull together information from several locales and create XML files that are easy to edit, with ui-split you can push the relevant information back into the respective locale files. The automated approach with ui-merge and ui-split offers the following advantages:
Furthermore, ui-merge and ui-split support locale-migration as follows:
Hence, we strongly encourage you to use the provided tools ui-merge and ui-split and do not recommend to edit individual files manually unless you know exactly what you are doing. So, let's get started. In a first step, you run ui-merge to create merged user interface configuration files containing place holders for your new locale xx_YY (and optionally other locales in addition to the default locale en_US to have more "examples" available for the translation process). Then you edit the merged user interface configuration files to add the translated strings for the new locale xx_YY. Once you are done with the translations you run ui-split to extract the relevant files for each locale from the merged user interface configuration files. The following steps will guide you through the process of creating the user interface configuration files for the new locale xx_YY:
Example 4-2. example output of ui-merge C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui>ant -f C:\opencrx\core\build.xml ui-merge -Darg.sourceDir=%CD% -Darg.targetDir=%CD% -Darg.locale=xx_YY Buildfile: C:\opencrx\core\build.xml ui-merge: [java] sourceDir= C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\en_US\abstractcontract.xml [java] writing file C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\abstractcontract.xml [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\en_US\account.xml [java] writing file C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\account.xml ... [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\en_US\wf.xml [java] writing file C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\wf.xml [java] shutdown BUILD SUCCESSFUL Total time: 6 seconds ui-merge creates merged user interface configuration files in the directory C:\temp\opencrx-core-CRX.war\config\ui. These merged files contain all the ElementDefinitions with labels and/or toolTips: Example 4-3. example ElementDefinition containing information for the locale en_US (default, always included) and gaps for the newly created locale xx_YY ... <ElementDefinition name="org:opencrx:kernel:contract1:Segment"> <Text type="Label"> <en_US>Pipeline</en_US> <xx_YY></xx_YY> </Text> <Text type="ToolTip"> <en_US>all Pipeline Objects</en_US> <xx_YY></xx_YY> </Text> </ElementDefinition> ... You can now use any editor suitable to edit UTF-8 encoded files to add the translations for the locale xx_YY. You simply insert the translated string between the opening tag <xx_YY> and the closing tag </xx_YY>. If you have access to an xml editor that features a grid view (e.g. XMLfox or xmlspy) it is almost like filling in a spreadsheet. Even though xmlspy is also available in a free edition (xmlspy Home Edition) which allows you to activate the grid view feature for 1 day, you may want to have a look at some of the following alternatives if you do not want to use a simple text editor supporting UTF-8 encoding:
As you will realize, there are quite a lot of strings to translate. However, you might get away with translating a subset of the existing labels/toolTips by making use of the Fallback Mechanism built into openCRX in the case where no label/toolTip exists for a particular locale. The fallback mechanism is explained in detail in Fallback Mechanism.
Once you are done with the translations you need to extract the relevant files for each locale from the merged user interface configuration files. This is done with ui-split.
Example 4-4. example output of ui-split C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui>ant -f C:\opencrx\core\build.xml ui-split -Darg.sourceDir=%CD% -Darg.targetDir=%CD% -Darg.locale=xx_YY Buildfile: C:\opencrx\core\build.xml ui-split: [java] sourceDir= C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\en_US\abstractcontract.xml [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\abstractcontract.xml [java] writing file C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\xx_YY\abstractcontract.xml [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\en_US\account.xml [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\account.xml [java] writing file C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\xx_YY\account.xml .... [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\en_US\wf.xml [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\wf.xml [java] writing file C:\temp\opencrx-core-CRX.war\WEB-INF\config\ui\xx_YY\wf.xml [java] shutdown BUILD SUCCESSFUL Total time: 7 seconds ui-split creates all the required directories and files for the new locale xx_YY. In particular, the directory C:\temp\opencrx-core-CRX.war\config\ui should now contain a subdirectory xx_YY with all the user interface configuration files specific to locale xx_YY.
code table filesFor advanced openCRX administrators there is a fast procedure to create code table files for a new locale xx_YY:
This "manual" management of localized files, however, makes it rather difficult to maintain consistency across multiple locales if code tables are modified/extended. The tools code-merge and code-split exist to help you manage and maintain a large number of locales. With code-merge you can pull together information from several locales and create XML files that are easy to edit, with code-split you can push the relevant information back into the respective locale files. The automated approach with code-merge and code-split offers the following advantages:
Furthermore, code-merge and code-split support locale-migration as follows:
Hence, we strongly encourage you to use the provided tools code-merge and code-split and do not recommend to edit individual files manually unless you know exactly what you are doing. In a first step, you run code-merge to create merged code table files containing place holders for your new locale xx_YY (and optionally other locales in addition to the default locale en_US to have more "examples" available for the translation process). Then you edit the merged code table files to add the translated strings for the new locale xx_YY. Once you are done with the translations you run code-split to extract the relevant files for each locale from the merged code table files. The following steps will guide you through the process of creating the code table files for the new locale xx_YY:
Example 4-5. example output of code-merge C:\temp\opencrx-core-CRX.war\WEB-INF\config\code>ant -f C:\opencrx\core\build.xml code-merge -Darg.sourceDir=%CD% -Darg.targetDir=%CD% -Darg.locale=xx_YY Buildfile: C:\opencrx\core\build.xml code-merge: [java] sourceDir=C:\temp\opencrx-core-CRX.war\WEB-INF\config\code [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\en_US\accountcategory.xml [java] writing file C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\accountcategory.xml [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\en_US\accountstate.xml [java] writing file C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\accountstate.xml ... [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\en_US\utcoffset.xml [java] writing file C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\utcoffset.xml [java] shutdown BUILD SUCCESSFUL Total time: 7 seconds code-merge creates merged code table files in the directory C:\temp\opencrx-core-CRX.war\config\code. These merged files contain all the CodeValueContainers with CodeValueEntries: Example 4-6. example CodeValueEntry containing information for the locale en_US (default, always included) and gaps for the newly created locale xx_YY ... <CodeValueContainer name="accountCategory"> <CodeValueEntry code="0"> <en_US_short> NA</en_US_short> <en_US_long> N/A</en_US_long> <xx_YY_short></xx_YY_short> <xx_YY_long></xx_YY_long> </CodeValueEntry> . ... You can now use any editor suitable to edit UTF-8 encoded files to add the translations for the locale xx_YY. You simply insert the translated string between the opening tag <xx_YY> and the closing tag </xx_YY>. If you have access to an xml editor that features a grid view (e.g. XMLfox or xmlspy) it is almost like filling in a spreadsheet.
As you will realize, there are quite a lot of strings to translate. However, you might get away with translating a subset of the existing code values by making use of the Fallback Mechanism built into openCRX in the case where no code value string exists for a particular locale. The fallback mechanism is explained in detail in Fallback Mechanism.
Once you are done with the translations you need to extract the relevant files for each locale from the merged code table files. This is done with code-split.
Example 4-7. example output of code-split C:\temp\opencrx-core-CRX.war\WEB-INF\config\code>ant -f C:\opencrx\core\build.xml code-split -Darg.sourceDir=%CD% -Darg.targetDir=%CD% -Darg.locale=xx_YY Buildfile: C:\opencrx\core\build.xml code-split: [java] sourceDir=C:\temp\opencrx-core-CRX.war\WEB-INF\config\code [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\en_US\accountcategory.xml [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\accountcategory.xml [java] writing file C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\xx_YY\accountcategory.xml [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\en_US\accountstate.xml [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\accountstate.xml [java] writing file C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\xx_YY\accountstate.xml ... [java] loading C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\utcoffset.xml [java] writing file C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\xx_YY\utcoffset.xml [java] shutdown BUILD SUCCESSFUL Total time: 7 seconds code-split creates all the required directories and files for the new locale xx_YY. In particular, the directory C:\temp\opencrx-core-CRX.war\config\code should now contain a subdirectory xx_YY with all the code table files specific to locale xx_YY.
texts.properties filesThe files opencrx.text.properties and text.properties contain several strings used by JSP. These files must exist for each locale configured in openCRX. The following steps will guide you through the process of creating the files opencrx.text.properties and text.properties for the new locale xx_YY:
Example 4-8. extract from the file ...\en_US\text.properties - each line containing a name-value-pair Locale=en_US dir=ltr LocaleTitle=English (United States) CancelTitle=Cancel OkTitle=OK SaveTitle=Save SortAscendingText=Click to sort ascending SortDescendingText=Click to sort descending DisableSortText=Click to disable sorting DeleteTitle=Delete EditTitle=Edit ... If you don't feel like translating all the values, you can just leave the template values unchanged. However, it is important that the files opencrx.text.properties and text.properties exist for all configured locales and the files must contain all name-value-pairs. html help pagesopenCRX html help pages are located in the directory C:\temp\opencrx-core-CRX.war. The following steps will guide you through the process of creating the html pages for the new locale xx_YY:
Repeat the above steps for the rest of the openCRX html help pages located in the directory C:\temp\opencrx-core-CRX.war.
modify Login.jspThe openCRX login page Login.jsp is located in the directory C:\temp\opencrx-core-CRX.war. The login page is a special case because prior to authentication the user does not have access to the openCRX application (and hence the openCRX localization features are not available). However, you only need to modify the login page if you want to offer your users a login page in a locale not already configured. You can add a new locale xx_YY by extending the code at the appropriate positions (e.g. by searching for "en_US" or "de_CH" which are both locales built into Login.jsp). The language specific part of Login.jsp starts with the following lines: Example 4-9. extract from the file ...\opencrx-core-CRX.war\Login.jsp // test whether requested locale is supported if((locale == null) || (!locale.equals("en_US") && !locale.equals("de_CH") && !locale.equals("es_MX") && . Extend all the hash maps following the above code sequence so that the updated login page can fully support the new locale xx_YY.
Chapter 5. Configuring locales for openCRX with web.xmlConfiguring 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>
.
Fallback MechanismThe 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:
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. Bibliography |
||
![]() | ![]() |