Auto Translate

(As of 3.2.001.01)

The DocOrigin Auto Translate feature is a way to create a form whose fixed text labels or fields can be switched from one language to another dynamically. It requires three elements:

• Translate File - A translation table INI file that contains a section for each language to be supported and value pairs for the translate key and value. 
  -translate "$$F/Translate.ini"
• Language option - The language (or section in the INI file) to use in that batch file or specific document (both are supported)
  -Language "FR"
• Translate Key - the name of the value pair that is the "key" for that text label or field 

Translate Key

(Option 1) Fixed Text Label with Tilde 

The Auto Translate mechanism requires that labels (fixed text objects) on the form be defined with text values that begin with a tilde (~), for example, ~address. 

When Merge is run, and the -Translate and -Language options (see below) are specified, the resulting documents generated by Merge will have the ~text values (e.g. ~address) replaced by the appropriate translated text.

• Merge strips off the leading ~ and looks up the remainder of the text in the nominated translation ini file.
• The ~text value can contain blanks, but no leading or trailing spaces, and no equals (=) sign.
• The ~text value must match an entry in the translation ini file; that match is case insensitive. For example, the label's text value could be ~First Name, and the INI entries could look like this:

first name = Prénom

• If no translation is found, Merge leaves the original ~text value in place.

(Option 2) TranslateKey Object Tag  

A TranslateKey Object Tag can be used to define the name or left side of the value pair of the translation table. For example, you can add the tag TranslateKey=address (shown below) instead of using the ~address tilde approach in the sample above.

A Translate Example

An example of this feature, called Sample_Translate, can be found in the DocOrigin/DO/Samples folder. In this form, the ~FirstName, ~LastName, ~Address, and ~Phone text will be automatically replaced with the appropriate language-specific wording.

The Sample_Translate.ini file looks like this:

[EN]
; English text
FirstName =  First Name
LastName = Last Name
Address = Address
Phone = Phone Number
LanguageName = English

[FR]
; French text
FirstName =  Prénom
LastName = Nom de famille
Address = Adresse
Phone = numéro de téléphone
LanguageName = Français
...

And the test form's sample data stream, Sample_Translate.xml, is like this:

<?xml version="1.0" encoding="UTF-8"?>
<XmlData>
	<Document>
		<Pane1>
			<First>Marion</First>
			<Last>Weaver</Last>
			<Address>2364 Pollock Rd, Ottawa</Address>
			<Phone>613 555 1515</Phone>
			<LANG>EN</LANG>
		</Pane1>
	</Document>
	<Document>
		<Pane1>
			<First>Elizabeth</First>
			<Last>Lévesque</Last>
			<Address>82 Boulevard de Clichy, Paris</Address>
			<Phone>+33 1 53 09 82 82</Phone>
			<LANG>FR</LANG>
		</Pane1>
	</Document>
</XmlData>

The Sample_Translate.xatw form looks like this:

The translate function is triggered by two Merge command-line options:

• -Translate - which tells Merge which Translation ini file to use.
• -Language - which tells Merge what Language (section) to use.

In the simplest case, you would just set -Language to (say) "FR" to get the French version of the text. This causes Merge to look in the translation ini file for the [FR] section and match the names in that section to the ~text on the form. For example, the FirstName value under the [FR] section is Prénom, so the text for ~FirstName on the form will be set to "Prénom".

The -Language value can also be set to a named Field on the form by using the standard [name] syntax. So if you loaded the field LANG (which you'll notice is in the data file), then set:

-Language "[LANG]"

This will use the value of the LANG form field as the key to the translation.

Alternatively, and likely more easily, you can reference the LANG data node directly by using the syntax:

-Language "[!Data LANG]"

This finds the data value for the LANG item in the data stream directly rather than requiring a Field on the form.

In the Sample_Translate example above, the data set has data for several documents - each with a different LANG value, so each document is translated to a different language.

Setting Field Values

So far, we've talked about Labels, but you can also configure any form Field to get an automatic translation value by using the following mechanism. In the example form, you'll see a field at the top called Field1. In the Design, that field has a Tag of TranslateKey set to a value of LanguageName.

Any field with a TranslateKey tag will use that tag's value (in this case "LanguageName") as the key to lookup in the translation ini file.

In our ini file above, we have

LanguageName = English ...
LanguageName = Français

So Field1's value will be set to either "English" or "Français" depending on the language active at the time.

This mechanism can be useful where the ~text mechanism gets too crowded. i.e., where the text label is only a few characters wide and you don't have enough room for meaningful ~text. The disadvantage from the form designer's perspective is that unlike the normal ~text label scheme, when using fields there isn't any helpful text visible on the form to make the form more readable to the designer.

Title = The Document in English
Title = Le Document en Français

See Also

-language
-translate