code table files

For advanced openCRX administrators there is a fast procedure to create code table files for a new locale xx_YY:

• add a new entry to the file C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\en_US\locale.xml reflecting the new locale xx_YY

• copy an existing locale directory (e.g. de_CH) with all its files and rename the copied directory to xx_YY

• translate all texts in the code table files

You must ensure that the index number in locale.xml matches the index number in web.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 to the index number m in web.xml). See also Configuring locales for openCRX with web.xml

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:

• locales can be managed individually in their respective subdirectories (e.g. the files for locale de_CH are located in a directory named de_CH)

• it is easy to add/remove locales and you can manage a very large number of locales in a convenient way

• configuring locales for openCRX is a matter of manually editing 1 file only: web.xml

• migrating to new versions of openCRX does not destroy/damage existing locales

• the use of code-merge and code-split ensures that all locale files conform to a standard structure (i.e. are schema-validated)

Furthermore, code-merge and code-split support locale-migration as follows:

• if a new version of openCRX contains new codes it is easy to spot the "gaps" in a merged code table file

• removed codes (which may still be present in some of your personalized locale files) are protocolled by code-merge

• all operations by code-merge and code-split create schema-validated files and ensure consistency

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:

• add a new entry to the file C:\temp\opencrx-core-CRX.war\WEB-INF\config\code\en_US\locale.xml reflecting the new locale xx_YY

• Open a new command shell and set the current directory to C:\temp\opencrx-core-CRX.war\config\code

• Enter the command ant -f C:\opencrx\core\build.xml code-merge -Darg.sourceDir=%CD% -Darg.targetDir=%CD% -Darg.locale=xx_YY and execute it to create merged code table files containing place holders for your new locale xx_YY (don't forget to adapt the path to the file utilities.xml in the command line above to reflect your local installation directory! In a Linux/Unix environment you have to replace %CD% with $PWD to indicate the current directory)

code-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\code before executing code-merge (but do not delete the subdirectories or the files in the subdirectories!).

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:

...
<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.

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 code table 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 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.

It might be helpful to have additional locales available in the merged code table 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). code-merge supports merging of multiple locales into a single file. When calling code-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 code-merge -Darg.sourceDir=%CD% -Darg.targetDir=%CD% -Darg.locale="de_CH/xx_YY"

When calling code-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 code table files. This is done with code-split.

• Open a new command shell and set the current directory to C:\temp\opencrx-core-CRX.war\config\code

• Enter the command ant -f C:\opencrx\core\build.xml code-split -Darg.sourceDir=%CD% -Darg.targetDir=%CD% -Darg.locale=xx_YY and execute it to create individual code table files for each specified locale (don't forget to adapt the path to the file utilities.xml in the command line above to reflect your local installation directory! In a Linux/Unix environment you have to replace %CD% with $PWD to indicate the current directory)

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.

code-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\code related to the locale(s) you've been modifying before executing code-merge (but do not delete the files in the directory C:\temp\opencrx-core-CRX.war\config\code and do not delete the files in the base directory C:\temp\opencrx-core-CRX.war\config\code\en_US).