Documentation: Externalizer

Description

Externalizer is a directory based Ant task to externalize strings.

The externalize process searches all occurrences of a pattern defined string and replace them with a label, defined by another pattern. At the same time the string and the label will be send to all registered modules. A module can work with this two values.
The FileExternalizerModule save the externalized strings to a selected file. A specified pattern define how to save the string and label to file. In Future, modules to externalize strings to xml or databases could be imaginable.

At least the Externalizer task needs one module. So you have to define a implicit ExternalizerModule in an Externalizer task. You can also use more than one module in one Externalizer task.

Also the task forms an implicit FileSet and supports all attributes of fileset (dir becomes basedir) as well as the nested include, exclude and patternset elements.

For more informations about the settings and useability, watch the following example.

System Requirements

To use the Externalizer you have to install a actual Java version and Apache Ant. Recommended is the use of eclipse.

Installation

The Externalizer is an Ant task. So you only have to register the task in your Ant build file. Extract the zip file and copy the Externalizer library (externailzer-1.0.jar) into your classpath. To register the task insert the following lines into your build.xml file and adapt the classpath.dir property. If you need more informations, visit: Ant typedef

<taskdef name="externalizer" 
        classname="de.cl.externalizer.Externalizer" 
        classpath="${classpath.dir}/"/>

Afterwards you can insert the Externalizer task into a target.

<target name="run_externalizer">

        <externalizer 
                pattern="_\(&quot;%string&quot;\)"
                substitution="(%label)" >

                <fileset dir="${src.dir}">
                        <include name="**/*.code" />
                </fileset>

                <fileexternalizermodule 
                        file="${src.dir}/messages.txt"  
                        pattern="definethis(&quot;%label&quot;, &quot;%string&quot;);" />
        </externalizer>

</target>

Parameters (Externalizer)

AttributeDescriptionRequired
patternThe pattern to find the strings. This pattern has to include the %string token.Yes
substitutionThe pattern founded strings will be replaced with this substitution-pattern. This pattern should include the %label token.Yes
labelMaxLengthTruncates the label name to this length.No (Default is length of string)
labelPrefixAdds a prefix string to the label.No (Default is "")
encodingThe encoding of the files upon which replace operates.No (Default: JVM encoding)

Modules

A module is a nested element from the Externalizer task. For the moment exists only the FileExternalizerModule. This module provide the functionality to save the externalized strings to files. This file could be a messages-file that contains all strings as variables.

Parameters (FileExternalizerModule)

AttributeDescriptionRequired
fileThe file to write the externalized strings (label + string).Yes
patternThe pattern define how to write the labels and strings to a file. Both tokens: %label and %string can be used here.Yes
headerDefine a header for the new file.No (Default is "")
footerDefine a footer for the new file.No (Default is "")

Examples

<externalizer 
        pattern="_\(&quot;%string&quot;\)"
        substitution="(%label)" 
        labelMaxLength="80"
        labelPrefix="L_">

        <fileset dir="${src.dir}">
                <include name="test.txt" />
        </fileset>

        <externalizermodule 
                file="${messages.dir}/messages.txt"     
                pattern="define(&quot;%label&quot;, &quot;%string&quot;);"
        />
</externalizer>

This example externalize all strings like: _("%string") in the test.txt file and replace them with: (%label). The %string-token represents the string and the %label-token the label. Its very simple and easy to understand.

The externalized strings will be written to messages.txt with following pattern: define("%label", "%string");  

Before starting Externalizer:

test.txt

//Externalize string 
echo_("Header 1. Externalize this string");

//Externalize string with same text/labels
echo_("Same text");
echo_("Same text");


Afterwards the 2 files look like this:

test.txt

//Externalize string 
echo(L_HEADER_1_EXTERNALIZE_THIS_STRING);

//Externalize string with same text/labels
echo(L_SAME_TEXT);
echo(L_SAME_TEXT);

messages.txt

//Externalized Strings from 27.03.2006
define("L_HEADER_1_EXTERNALIZE_THIS_STRING", "Header 1. Externalize this string");
define("L_SAME_TEXT", "Same text");