Multilingual Expressions

In VTScada, all text for the user-interface is stored as phrases, each with a matching phrase key. This is also true for nearly(*) all text that you add to your application including tag descriptions, engineering units, labels and more.

(* Exceptions include tag names, tag areas and user-defined application properties, all of which are stored exactly as written.)

For example, anywhere that displays the English label "1 Day", actually uses the key "1DayLabel". This allows VTScada to translate the user interface to another language such as French.

The advantage is clear for those who need a user-interface that can be displayed in a language other than English. But when creating expressions that involve text and any part of the user interface, you must be prepared to work with phrase keys rather than directly with text.

VTScada comes with French, Simplified Chinese and Traditional Chinese phrases for most user-interface text. You must create your own translations for your text.

Get a phrase, given a phrase key

A phrase is one or more words. Because one language may use words in different order compared to another language, it is best to store complete labels as phrases rather than attempt to assemble labels from individual words. For example, for a phrase key such as "GreenButtonLabel", the English phrase might be "The green button", while the French phrase would be "Le bouton vert".
Given a key, you can find the matching phrase in the currently selected language by using the \GetPhrase function like so:
\GetPhrase("GreenButtonLabel")

A parameterized phrase has one or more spots (parameters) in the form %0, %1, etc., that can be replaced on the fly. The advantage is that the parameter placement can be shuffled within each translation. For example, if the expected parameter to ParmButtonLabel is a color name, the English phrase might be "The %0 button", but the French phrase would be "Le bouton %0". In this case, your expression should use the \GetParmPhrase function like so:
\GetParmPhrase("ParmButtonLabel", "GreenLabel")

In both of the examples just shown, the parameters are enclosed in quotation marks because it is the name of the key that is being passed to the function. You could also use variables that hold those names, which would be more typical for the parameter being passed to the phrase.

Phrases in tag parameters

Tag parameters (such as the Description parameter) present a special case: These are typically snapshot expressions that evaluate only when the tag starts or re-starts. Changing from one language to another does not cause your tags to restart.

The solution to this problem is not to deselect the Optimize option in the parameter expression editor. Rather, it is to use a \ParmPhrase structure instead of a \GetPhrase or \GetParmPhrase function. (In situations where a non-optimized tag parameter must be created, use MakeParmPhrase)

\ParmPhrase is not a function and you will not find it in the function reference (other than a page that will tell you "This is not a function"). When a \ParmPhrase structure is used in certain tag parameters, the translation will update automatically whenever you change the current language. This is true for the following:
Description, Units, Position text on the selector switch, Equipment Type, IngredientName, Recipe Tag Mode, Pump OnText and OffText, the PLC alarm tag's PLCType and AlarmType, and the I/O tag mode.

A parameter phrase structure (\ParmPhrase) has a form much like the \GetParmPhrase function. For example, if your tag's description should describe the color of a button, you would create a parameter expression like so:
\ParmPhrase("ParmButtonLabel", "GreenLabel")

If any of the parameters that you pass to \ParmPhrase are not phrase keys, then they are simply passed through and not translated.

Do not use \ParmPhrase structures alone outside of tag parameter configuration.
Elsewhere, a \ParmPhrase structure may be passed to a \GetPhrase or \GetParmPhrase function call in place of a phrase key, but there is seldom an advantage to doing so.

Create phrases and obtain their keys

New phrases and phrase keys are created automatically whenever you save a new phrase, such as a new tag description or a new label on a page. Having created a new phrase, you can then use the Languages page in the Application Configuration dialog to search for the matching key. A more efficient way to create new phrases and keys is to work directly in the Languages page. An example follows:

1. Open the Languages panel of the Application Configuration dialog.
2. Ensure that the Key column is displayed.
   Click the View button and select Key from the pop-up dialog if it is not.
3. Click the Insert button.
   The Phrase Definitions dialog opens.
4. Click where indicated to add the new phrase.
5. Place a %0 to mark the position for the first replaceable parameter. (%1 for the second, etc.)

6. Click where indicated to add a description that will help translators know the meaning of the phrase.
7. [Optional] If you have added another language to your application, create the phrase in that language now.
8. Save the phrase.
   Your new phrase should be selected in the list. It will not be saved until you click Apply, but do not click that button yet.
9. Click the copy tool, to the right of the phrase key.
   
   The key shown here is an example. Yours will differ.
10. Use the key in the your expression.
    If creating several phrases, it may be helpful to keep a text editor handy, copying phrases and keys to it as you create them.
11. Click Apply to save the new phrase and its key.
    Because the list is sorted alphabetically by phrase or key, the new entry is unlikely to be visible on the screen after you click Apply.

 

Example: A tag description that reflects the parent tag:

This is a relatively common task. You have a tag structure and would like the description of each child tag in each instance to identify which instance it belongs to. Perhaps (for example) you would like the description to read "Primary pump in the XX region" where XX should be the Area name for the tag.

Begin by opening the Language page in the Application Configuration dialog and creating the phrase, "Primary pump in the %0 region", as described earlier. For the sake of this example assume that the assigned key is named "EU43y4gag".

Create translations if required.

Open the tag's properties dialog and create an expression as shown: