|
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. We do not recommend to edit the language-specific files of your openCRX installation as you risk messing up your installation if anything goes wrong. We rather recommend to copy the file opencrx-core-CRX.war to a working/temporary directory and then explode/unzip it to get easy access to all the language-specific files. 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:
ui-merge does not overwrite existing files in the target directory. In case of a conflict the existing file is rename by prepending the string .# to the name of the file. To start with a clean slate it is a good idea to delete all the files in the directory C:\temp\opencrx-core-CRX.war\config\ui before executing ui-merge (but do not delete the subdirectories or the files in the subdirectories!). 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:
Modifying language-specific files requires an editor capable of handling files in UTF-8 format. The UTF-8 encoding of an XML file is indicated at the beginning of the file with <?xml version="1.0" encoding="UTF-8"?>. More information about encoding of XML files is available at http://www.w3schools.com/xml/xml_encoding.asp. If you modify the user interface configuration files with an editor that cannot handle UTF-8 encoded files properly you risk running into problems when starting openCRX with such modified files because the XML importer will not be able to correctly import them. 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. It might be helpful to have additional locales available in the merged user interface configuration files to make the translation process easier (e.g. if you want to create a French translation it might be helpful to have the English and the German versions available in the same file). ui-merge supports merging of multiple locales into a single file. When calling ui-merge you can use the parameter -Darg.locale to provide a list of all the locales (put the list in quotes "..." and separate individual locales with slashes, e.g. "aa_BB/cc_DD/ee_FF") that you want to merge (note that there is no need to specify the locale en_US as this default locale is always included). For example, to merge the locales en_US, de_CH, and xx_YY you would use the following command line: ant -f C:\opencrx\core\build.xml ui-merge -Darg.sourceDir=%CD% -Darg.targetDir=%CD% -Darg.locale="de_CH/xx_YY" When calling ui-merge you can use the parameter -Darg.format=schema to produce merged files containing all the formatting information as well (there is no need to specify the default -Darg.format=table). 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. ui-split does not overwrite existing files in the target directories. In case of a conflict the existing file is rename by prepending the string .# to the name of the file. To start with a clean slate it is a good idea to delete all the files in those subdirectories of C:\temp\opencrx-core-CRX.war\config\ui related to the locale(s) you've been modifying before executing ui-merge (but do not delete the files in the directory C:\temp\opencrx-core-CRX.war\config\ui and do not delete the files in the base directory C:\temp\opencrx-core-CRX.war\config\ui\en_US). |
||||