The Set Language control enables a limited multilingual capability for K2 SmartForms. The control was developed by a developer at K2, though the control is not officially supported as part of the K2 SmartForms product. The control may be downloaded from the K2 Community. An account is required to perform the download. Be sure to consult the document included in the download.
This post walks through a simple demonstration of how to use the Set Language multilingual control. In my brief exploration, I found that the control will not work on objects like message popups. In this demonstration, I manufacture a message popup using a simple subform, and show how a language value can be passed from one form to another to preserve the appearance of text in a chosen language.
The demonstration is comprised of two forms, each containing a single view.
The first form has a dropdownlist control, a couple of labels and data labels, plus the Set Language control. It also has a button control, which is used to spawn the subform.
The second form (the subform) contains only a data label, the Set Language control, and a button control which is used to close the form. This form has two parameters: one for the text to be displayed and one for the language value passed in from the main form.
The Set Language control requires a resource file to be planted in the
Program Files (x86)\K2 blackpearl\K2 smartforms Runtime\bin directory. The resource file is an XML document with nodes for the label (the text to be converted) and the language equivalents of the label value in nodes named for the languages. In the example that follows, the resource file contains the equivalents of “Yes” and “No” in Arabic (“ar”), Swedish (“sv”), and English (“EN”).
. . .
The name of this XML file is the value that belongs in the Resource file/s field of the Set Language control’s properties (in this case,
Additionally, all of the text to be translated must be entered into the resource file(s). Text on the form that does not have translations will remain in its original language.
The main form initializes with a dropdownlist control and a submit button at left, and a series of language buttons at right.
The labels for the language buttons are simple text to reflect the digraphs in the Language resource file. In an actual solution, one might consider using images of country flags instead.
Click any of the language buttons to change the displayed language on the form.
The language changes also affect the options not selected in the dropdownlist.
The rules behind the language buttons are the secret sauce that makes possible the transmission of the language preference to the subform.
Specifically, each button performs a Data Transfer to the Set Language control and to a data label.
When the subform is opened, the value of the Language Data Label is transferred to the subform’s Language parameter.
Then the Set Language control on the subform gets set to the parameter value.
Originally, I had a rule on the submit button to produce a small message prompt. Unfortunately, I found that the text in the messages was not getting translated. So I opted to build a subform as a workaround.
When the submit button on the main form is clicked, a rule in the main form directs the subform to be opened.
The subform has a pair of parameters – one for the selected language and another for the text being sent for display.
The language parameter is fed by the Language Data Label from the Main Form, as described above.
For this test, a translatable word was set as the text parameter. Obviously in a real application the text would be passed in from some sort of label on the form or perhaps a configurable string value. The text must have translations in your resource file.
The subform is opened when the Submit button on the main form is clicked.
The selection of other languages causes the modal text and “OK” button to appear in the target language. (I didn’t have “OK” available as translatable text, so I used the value of “Yes” instead.)
Clicking the “OK” button closes the subform.
Values are Not Altered
In the Overview, I used the phrase “the appearance of text in a chosen language” for a very specific reason: The Set Language control does not alter the value of text in a control. It only changes the value’s appearance on the screen – my guess is through jQuery.
If you were to capture the word “Yes” in a label, then change the language to German or Swedish, the value will appear as “Ja,” but if you were to transfer the data into another control, the value will remain “Yes.” This has implications when attempting to pass text to another form.
Set Language Dropdownlist Control
The Set Language control includes the option to use a dropdownlist control to select a specific language. The option appears in the properties:
The languages are in a resource file you create (in XML) and store in
Program Files (x86)\K2 blackpearl\K2 smartforms Runtime\bin. The list recounts the nodes under
root\Languages that represent each language.
Notice the dropdownlist values appear in the same order as they appear in the resource files (see “Dependencies,” above).
The answer: Don’t use the dropdownlist control, and use the buttons-oriented approach I described in the walkthrough. This approach allows you to manually set the value using Transfer Data rules. I used this technique to transfer data into a Data Label control, which allowed me to pass the value into the subform.
Some Text Not Affected
The translation-related properties of the Set Language control include a litany of controls, but some of the mechanisms K2 offers in their SmartForms product are as yet unaffected by translation. These include message prompts and window titles. It was the inability to translate the message text that prompted me to use the subform approach described in the walkthrough.