Multilingual Expressions

A common use for expressions is to create a tag description that inherits some property of a parent tag. For example, given a pump context that contains a status tag, and also a setting in the context named PumpID, which identifies the pump, you might put a parameter expression in the description property like so:

This example is offered only as an introduction, but it illustrates two key points:

• Most non-numeric properties are stored as phrase identifier keys, not simple text.
• Your application might be used in more than one language, in which case you need to create your own phrase keys.

Therefore, best practice for expressions that return text is that they should return either a phrase key, or a parameterized phrase structure built from two or more phrase keys. Given either, VTScada will look after providing the translated version of the phrase when the operator switches to another language, and will do so without needing to reevaluate your expression. Unless you are working in a strictly unilingual application, your expression should not return the actual text of a phrase.

Concat(..\Description, " flow rate")

\ParmPhrase("%0 %1", ..\Description, " flow rate")

You will need to know how to do two things:

1. Create a phrase or parameterized phrase and obtain its phrase key.
2. Create a \ParmPhrase structure.

1. Create a phrase or parameterized phrase and obtain its phrase key.

A parameterized phrase resembles the Concat() function, in that it's a phrase with one or more spots (parameters) that can be replaced on the fly. The advantage is that the parameter placement can be shuffled for one translation compared to another. For example, if the parameter is to be a color, the English phrase might be "The %0 button", but the French phrase would be "Le bouton %0".

The following steps describe the official method of creating a new phrase, which is also the only method of editing that phrase.

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.
   
10. Look it up in the list and note the key.
    (You may need to use the View button to reveal the Key column.
    For this example, "znjmCd+5r" is used because that is key created while your author wrote this.)
11. Use the key in the your expression to create a \ParmPhrase structure.

2. Create a \ParmPhrase structure

If you browse through VTScada's language-related functions, you might discover \GetParmPhrase. Given a phrase key and optional parameters, this will return a phrase in the currently selected language. For example, using the phrase key from the previous example, you might write:

\GetParmPhrase("znjmCd+5r", \GetPhrase(..\Description))

The problem with this example is that it returns a phrase only when the expression runs. An optimized tag expression (such as you would create for a description) is evaluated only when the tag starts and therefore you won't get a translation when the operator switches languages. (Warning: Do not decide from this that you should use a non-optimized tag parameter expression.)

Given a phrase key or \ParmPhrase structure, VTScada will look up the matching phrase for you, and will refresh that when the operator changes languages. Best of all, there is no need to re-evaluate the expression.

\ParmPhrase is a structure, not a function call. You will not find it in the function list.
If you save one of these structures to a tag parameter, VTScada will automatically convert that structure to a phrase in the current language, updating it whenever the current language changes.
Elsewhere, must call \GetPhrase yourself. Do not use \ParmPhrase structures outside of tag configuration.

A \ParmPhrase expression looks like the following. The result is very much like a CONCAT() except this works from one language to another.

\ParmPhrase("PhraseKey1", "PhraseKey2", ...)

It could also look like the following, although this is not as useful(*) since the order of the parameters is being set in the structure rather than the phrase.

\ParmPhrase("%0 %1", ..\Description, "PhraseKeyForSomeLabel")

Returning to the first example in this topic, you could also write:

\ParmPhrase("%0 %1", ..\Description, ..\PumpID)

... which for the tags in that earlier example would return "Primary pump 1".

Or, you could use the phrase key "znjmCd+5r", matching the phrase (in English) "%0 Flow Rate" (from the earlier example). This puts the parameter into the phrase, where it can be moved about from one language to another. For example, perhaps you want to substitute the description of the parent tag for %0. Therefore, the parameter expression should be:

\ParmPhrase("znjmCd+5r", ..\Description)

One more detail: If any of the parameters that you pass to \ParmPhrase are not phrase keys, then they are simply passed through.

(*) Why is it better to set the order in the phrase than the structure? Because the order of words can vary from one language to another. In English, we say "The green door". In French what would be "La porte verte".