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.
To use the Externalizer you have to install a actual Java version and Apache Ant. Recommended is the use of eclipse.
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="_\("%string"\)" substitution="(%label)" > <fileset dir="${src.dir}"> <include name="**/*.code" /> </fileset> <fileexternalizermodule file="${src.dir}/messages.txt" pattern="definethis("%label", "%string");" /> </externalizer> </target>
Attribute | Description | Required |
pattern | The pattern to find the strings. This pattern has to include the %string token. | Yes |
substitution | The pattern founded strings will be replaced with this substitution-pattern. This pattern should include the %label token. | Yes |
labelMaxLength | Truncates the label name to this length. | No (Default is length of string) |
labelPrefix | Adds a prefix string to the label. | No (Default is "") |
encoding | The encoding of the files upon which replace operates. | No (Default: JVM encoding) |
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.
Attribute | Description | Required |
file | The file to write the externalized strings (label + string). | Yes |
pattern | The pattern define how to write the labels and strings to a file. Both tokens: %label and %string can be used here. | Yes |
header | Define a header for the new file. | No (Default is "") |
footer | Define a footer for the new file. | No (Default is "") |
<externalizer pattern="_\("%string"\)" substitution="(%label)" labelMaxLength="80" labelPrefix="L_"> <fileset dir="${src.dir}"> <include name="test.txt" /> </fileset> <externalizermodule file="${messages.dir}/messages.txt" pattern="define("%label", "%string");" /> </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");