DYNAMIC RULE FILE TRANSLATIONS

At runtime, a translation file can be associated with a rule file in order to perform dynamic substitution of text and barcode values, and also anchor text to which many enhancements can be related.  The purpose of this feature, added in version 8.0.25, is to ease the effort of translating rule sets for different languages.  By editing a messages file that is associated with hard code text fragments in a rule file, UnForm can perform word and phrase substitutions dynamically.

The structure of the translation file is an "ini" file, with sections that match the names of rule sets in the current rule file.  At runtime, UnForm will load assignment lines from the section that matches the current rule set name, plus any assignment lines found in the file before the first section header.  For example, if a rule file contains the rule set "Invoice", then lines in the [Invoice] section of the translation file are used.  Any assignment lines at the top of the file are appended to these lines, allowing for global settings to be used as well as ruleset-specfic settings.  An example of a translation file is the samples/advanced.spanish.ini file, which contains translation samples associated with some rule sets in the advanced.rul file.

A translation file can be specified in the uf101c command line with a –trans "filename" option.  In addition, the active file can be changed at runtime in any code block, using the settrans("filename") code block command.

The format of an assignment line is simply a name=value pair.  The name value can include a context prefix, where the context can be one of the words text, barcode, or anchor, followed by a tilde (~).  For example, the line text~Invoice=Factura would replace "Invoice" in a text command with "Factura".  A line without the context prefix (just Invoice=Factura) may apply to both text and barcode commands.

Values are case sensitive, and only whole values are replaced.  For example, if a text command specifies "Invoice No:", then the assignment line might be: Invoice No:=Factura no:.

When assignment lines are evaluated, they are first evaluated in a context of text, barcode, or anchor.  If a match is found, that assignment is used. If not, text and barcode values are next evaluated without a context, and if a match is found, that assigned value is used.  Without a match, the original text is used.

Anchor context substitutions apply to content that is searched on the page and only work in context mode (the "anchor~" prefix is required).  While text and barcode substitutions apply to content added to the job, anchor substitutions apply to content in the print stream of the job.  Anchor substitutions do not change text values, but instead change the text values searched for.  Many commands support anchors in their syntax, when the first command is a quoted string.  For example, a font command might look like this:

 Font "Continued@50,60,80,66",0,0,9,1,cgtimes,12,bold

This command will search each page, in columns 50-80 and rows 60-66, for the word "Continued".  When it finds the word, it applies a font at 0 columns and 0 rows offset from the position, for 9 columns and 1 row.  When a translation file is active, UnForm will look for a line "anchor~Continued=value, and search instead for value.  Additional numerical adjustments are performed on anchor contexts:

•The difference in lengths of the original text and new text is calculated

•The difference is added to the ending column if @col,row,endcol,endrow syntax is used

•If the offset column is 0, the difference is added to the number of columns, to accommodate enhancements designed to apply to the text that is located.

•If the offset column is not 0, the difference is added to the offset column itself, to accommodate a new relative position based on the new text.

Anchors can include the following prefixes: ~, !=, and !~.  These prefixes modify how the anchor text and the search are performed, and are not considered part of the assignment name.  A ~ prefix indicates the text is a regular expression, and the != and !~ options indicate "not", so match all positions where the search does not find the sought string or regular expression.  Since regular expressions can result in variable lengths, the above described numerical adjustments are not performed with regular expression anchors.  Another limitation of anchor-based translations is that they are not supported in Application Formatted Output (AFO) jobs, though text and barcode translations are supported.

Since both "~" and "=" characters have special meaning, if they should be part of the actual name they must be escaped with a backslash.  For example, if the name value should contain an equal sign, which normally separates it from the value, that equal sign must be escaped:  "Cost=", for example, should appear as Cost\= =value.

It should be noted that the dynamic translation feature is a simple substitution function, and it does not account for cases where a substitution dramatically alters the space used by a particular text fragment, or when a different font or character set should be used.  In some cases, it might be necessary to use fit or wrap options, expressions for positioning, or code block exec() functions to accommodate some aspects of translation.

Code blocks can also utilize the features of text translation through three functions:

•settrans("filename") sets the translation file dynamically as the job runs.  This overrides what might be set via a -trans command line option.

•gettrans() returns the active translation file.

•translate(name$ [,context$], forcecontext) returns the value associated with the specified name, based on the translation file and current rule set.  The context value can be "text", "barcode", or "anchor", and if forcecontext is true (non-zero), only context-based names are searched.

There is a rule file, samples/trans.rul, with the rule set "trans", available in the samples directory.  This rule set is designed to scan any rule file sent through it as input, and build as output a skeleton translation file based on hardcoded text found in the rule sets.  In order to run this rule set, use this command line:

uf101c -i "rulefile" -f trans.rul -r trans -o "inifile"