Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 3 Tasks : Localizing a Form

Localizing a Form
TIBCO Forms allows you to create forms that support multiple languages. Form logic, including layout and control types and validation rules, is stored in the form file. Language-specific information, including labels and validation messages, is stored in locale-specific properties files.
To simplify the localization of forms, all text that appears on a form is stored in a properties file. The properties file includes the strings that make up the labels for controls and panes, as well as the strings for hints, validation messages, and error messages.
Each form has a base properties file that is generated automatically when the form is created, and is regenerated each time the form is saved. This file appears in Presentation Resources special folder in the Project Explorer. The base properties file contains the strings that appear as labels and messages in the form’s property sheets.
Figure 123 Base Properties File
To create a localized version of a form, you will make a copy of the base properties file, rename it, and edit the strings it contains.
Do not edit the strings in the base properties file itself. Any changes you make to this file will be lost as soon as the project is built (which is to say, as soon as you save the form, with the default setting, where auto-build is enabled). To change the labels and messages for the base version of the form, use the form’s property sheets instead. The changes you make in the property sheets will appear in the base properties file when the form is saved.
The renamed locale-specific versions of the properties file will not be automatically regenerated, and thus your locale-specific strings will not be lost when the form is saved.
To create a locale-specific Properties file:
1.
Select the <form>.properties file from the Presentation Resources special folder in the Project Explorer. Make a copy of this file for each locale.
2.
3.
For every new properties file created in the Presentation Resources folder, the builder automatically creates a matching <file>.properties.json file at the same location.
4.
5.
Click Project > Clean to clean and rebuild the project. This updates the <form>.locales.json file with the details of the language in which the form has been localized. For example, if you create DemoForm_fr.properties file, then the Demoform.locales.json will contain ["fr"]. This file is updated when the you rebuild the project after creating a new locale-specific version of the properties file.
6.
Run the JDK command-line tool native2ascii, using the locale-specific properties file as input, to ensure that the file contains only ISO_8859-1-encoded characters:
The native2ascii command-line tool is available in the directory %JDK_HOME%\bin.
7.
8.
To create language-specific and country-specific properties files:
The language specific properties file is a copy of the base properties file. This file is renamed using the naming conventions for languages and regions.
Each localized language is represented by a two-letter code, in the format ll, where ll is a lowercase, two-letter ISO 639 language code. For a list of language codes, visit the following web site:
http://www.loc.gov/standards/iso639-2/langhome.html
Each country is represented by a two-letter code, in the format CC, where CC is an uppercase, two-letter ISO 3166 country code. For a list of country codes, visit the following web site:
 
http://www.iso.org/iso/english_country_names_and_code_elements
The form name, language code, and optional country code are separated by underscores. Table 18 shows examples of locale-specific properties files for a form named DemoForm.)
As shown in Table 18, if your form is called DemoForm, the automatically generated base properties file will be called DemoForm.properties. This is the file that will contain the strings typed on the form’s property sheets.
To create a French version of this form, copy the DemoForm.properties file and rename the copy DemoForm_fr.properties. This is a language specific variant of the properties file which contains the translation for the French language.
You can also create country specific versions of DemoForm_fr.properties file for France and French-speaking Canada. The country specific variant of the properties file contains only those keys for which the translation varies locally in each country.
While creating country specific properties file such as DemoForm_fr_FR.properties and DemoForm_fr_CA.properties, it is better to create the DemoForm_fr_FR.properties and do all the translations. Then copy the latter to DemoForm_fr_CA.properties and make the additional changes.
Finally, in both DemoForm_fr_FR.properties and DemoForm_fr_CA.properties delete all the entries whose keys and values are identical to those in DemoForm_fr.properties.
If you want to make changes to the labels or messages in the base properties file of your form, and you want corresponding changes to appear in the language specific versions of the properties file, you must make the latter changes manually by editing the strings in the language-specific version of the properties files. An alternative way of doing these changes is as follows:
a.
You can select both the base properties and your language specific properties file in Project Explorer and use Context Menu > Compare With > Each Other to open them side-by-side in the Property Compare editor.
b.
Use the Copy All Non-Conflicting Changes or Copy Current Change (From ... To ...) actions to add new keys and delete old keys from your localized version. For new keys and those with updated values you can provide a new translation.
To choose a locale-specific version of a form at run time:
When localized versions of a form exist along with the base version in the runtime environment, the runtime will choose the locale-specific version that corresponds to the locale that is set on the user’s system. If no version is present on the runtime server for that locale, the base version will be used.
You can use the Form.setLocale(String) and Form.getLocale() methods to change the locale settings of the form.
Defining Localization Properties Outside the Form
In addition to creating localized versions of a form’s base properties file, TIBCO Forms supports the creation and localization of additional properties files whose scope is not limited to a given form. These can be referenced by a form and, in fact, shared by any number of different forms within the same or other projects.
To create a localization properties file outside the form, follow these steps:
1.
Create a new resource file, with the extension .properties, within the folder /<project>/Presentation Resources in the Project Explorer. (Note that this is unlike the base properties file, which is also contained in the Presentation Resources folder, but is within a sub-folder for resources specific to the form, a sub-folder named with the name of the form.)
2.
Edit the properties file by adding key-value pairs in the format <key> = <value>, each on a separate line. For example:
       mykey1 = My Key One
       mykey2 = My Key Two
The format is that of a standard Java resources file, identical to the generated base properties file found in the form folder.
3.
4.
5.
Example: Using a Localization Properties File Defined Outside the Form
This example shows how a localized properties file might be used within a form. In the example, a button is created that changes the label for a text field. The value for the label is localized using properties files external to the form’s own properties files.
1.
2.
In the Properties view for the form, go to the Resources tab. Click the plus sign to add a resource, locate the new properties file you created in the Presentation Resources folder, and add it as a resource for the form.
The properties file now appears as a resource in the Resources tab, identified by a name and path (URI). The Localized button is automatically selected for the properties file, indicating that the run time should search for localized copies to match the user’s locale.
3.
In the Properties view for the text control, give the control a name in the Name field on the General tab, for instance localizedText.
4.
Go to the Rules tab in the Properties view for the button. Click the button to Define a new rule for the button that will be triggered when the button is clicked.
5.
Leave the values unchanged in the Rule Details dialog, and click Next.
6.
Leave the values unchanged in the Rule: Pick Events dialog and click Next. This simply means the rule we create will be triggered when the button is clicked, which is the default event for buttons.
7.
In the Define Actions dialog, click the plus sign to define a new action.
8.
In the Add Action dialog, select the radio button Create a new action, and leave the radio button Script Action selected. Click Next to specify a script that defines the action.
9.
      control.localizedText.setLabel(resource.
         MyLocalizedResourceFile.mykey1);
10.
Preview the form in the GWT Preview tab. Click the button on the form, and the text field’s label should say My Key One.
11.
12.
 

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved