Translate Workflows

If your user base includes speakers of different languages, you may want to translate your workflows. Geocortex Workflow's Translation feature enables you to present a single workflow in different languages.

When an application like the Geocortex Viewer for HTML5 or Web AppBuilder runs, it checks the user's language settings to determine the user's preferred language. Workflows inherit this information from the application and use it to decide which language to use for the workflow. If the workflow is available in the user's language, then the workflow appears in that language.

For example, suppose you have made a workflow available in Spanish and Dutch. A user whose browser is set to Spanish sees the workflow in Spanish. A user whose browser is set to Dutch sees the workflow in Dutch.

When you translate a workflow, you choose one language to be the default language and then configure the translations. If the workflow is not available in the user's preferred language, the workflow appears in the default language.

To translate a workflow, you use text items. A text item corresponds to a particular string in the workflow's user interface. As part of workflow authoring, you provide values for each text item, one value for each language you are supporting. You then use the text items in the configuration of the workflow's activities and form elements.

For example, to provide Portuguese and English versions of an alert, you could add a text item called alert-text, assign it the values Est é o texto for Portuguese and This is the text for English, and then specify the text item in the Alert activity's Text input. To specify a text item, you put "@" before the text item's ID. The @ symbol indicates to Geocortex Workflow that what follows is a text item. In this case, you would enter @alert-text in the Alert activity's Text input.

In Workflow Designer, the activities that display text are listed in the Toolbox's User Interface category. These are the activities with properties that will require translation if you are going to support multiple languages. Among the User Interface activities, the Display Form activity has the most strings that will require translation, especially if your forms contain many elements.

Locales

In software, a locale is a set of user preferences that the software applies to the user interface. These preferences could include the language, currency formats, date/time formats, and other things that vary across regions. In the context of translating workflows, it is the language that is relevant.

Languages are specified using codes like "en" (English), "nl" (Dutch), or "pt" (Portuguese). When you translate a workflow into additional languages beyond the default language, you associate the appropriate code with each set of translated strings. Then, when the workflow runs, it tries to match the user's preferred language to the code you assigned to determine which set of strings to use.

Some languages have variants. For example, in addition to English (en), Geocortex Workflow supports Australian English (en-AU) and British English (en-GB). Translating a workflow into multiple variants allows you to support users of a particular language in different countries.

If the user's language is set to a variant and the workflow is not available in that variant, the workflow looks for the non-variant version of the language. For example, if the user's language is set to Brazilian Portuguese (pt-BR), the workflow first looks to see if you have provided a Brazilian Portuguese translation. If not, then the workflow looks for a Portuguese (pt) translation. If that also fails, then the workflow uses the default language.

Note that this only works in one direction—a workflow will look for the non-variant version of the user's language, but a workflow will never look for a variant of the user's language. For example, if the user's language is set to Portuguese (pt) and the workflow is available in Brazilian Portuguese (pt-BR) and the default language, the workflow will appear int the default language, not Brazilian Portuguese.

Main Steps to Translate a Workflow

The main conceptual steps to translate a workflow are as follows:

  1. Add a text item for each user interface string in the workflow.

    Text items are configured on the Translations panel. With the workflow active in Workflow Designer, click Info and then click Translations.

  2. Configure a value for each text item in each language that you are going to support.

    Select the Default (invariant) locale or some other locale you are going to support and assign a value to each text item. Repeat this for every supported locale.

  3. Use the text items when you configure any that displays text in the running workflow.

    To specify a text item, enter @ followed by the text item’s ID, for example, @text1.

    In an activity input, you can use an expression instead of the "@" notation. The general form of the expression is =strings["text-item-id"]. The general form works for all text item IDs. If the ID doesn't contain any dashes, you can use the shorter form, for example: =strings.text1

When you translate a workflow, you might want to do the steps in a different order than the conceptual steps given above. If you create the workflow first and then translate it, it may be easiest to step through the workflow one activity or form element at a time, translating as you go.

Configure Text Items

Add Text Items and Assign Values

To add a text item and assign values to it:

  1. In Workflow Designer, click Info in the sidebar, and then click Translations.

  2. Click Add.

    The text item is added to the Translations table.

    You only have to add a text item once. It will appear in every locale that you configure. It doesn't matter which locale is selected when you add the text item.

  3. In the ID column, click the edit icon , change the ID to a meaningful name, and then click the check mark .

    The text item's ID changes for every locale.

    Text item IDs can include the characters a-z, A-Z, 0-9, dashes (-), and underscores (_). They cannot include spaces, special characters, or accented characters.

  4. Assign values to the text item:

    1. In the Choose a locale drop-down list, select the Default (invariant) locale or some other locale that you support for this workflow.

    2. In the Text column, type the item's text in the language for the selected locale.

      If you need to use a character that is not available on your keyboard, see Insert Characters from Other Languages.

      Text items can span multiple lines. Press Enter to go to a new line.

    3. Continue assigning values until you have assigned a value for every supported locale.

  5. Press Ctrl+S to save the workflow.

    Translations are saved in the workflow.

Use Text Items in a Workflow's Configuration

After you have added and configured a text item, you must use it in an activity input or form property. Otherwise, the workflow will never use it.

Text items can be used in display properties of activities, form elements, and form element items.

To configure a property to use a text item:

  1. In Workflow Designer, select the activity or form element where you want to use the text item.

  2. Locate the desired property in the Properties panel.

  3. Type @ to open a drop-down list of text items and select the text item.

    Alternatively, type in @ followed immediately by the ID of the text item.

    In activity inputs, you can use an expression of the form =strings.text1 instead of @text1, provided the text item's ID doesn't contain any dashes. For example, to use a text item with ID alert, you could enter either =strings.alert or @alert.

    Alert activity's Text property configured with a text item called "alert"

Insert Characters from Other Languages

In general when you translate a workflow, you will be able to use your keyboard to enter the characters that you need for the text items' values. Typically, you translate workflows into languages that are used in your region, so your computer will already be set up to work in those languages.

Occasionally, however, you may need to use characters that are not available on your keyboard. For example, you may need to enter accented characters that are not available in the languages that you use daily, or you may need to enter characters from a different alphabet. In this case, you can get the characters you need in two ways:

Change an Existing Text Item

You can change a text item's ID or one or more of its values at any time.

To change a text item's ID:

  1. In Workflow Designer, click Info to open the Info panel, and then click Translations.

    It doesn't matter which locale is selected when you change a text item's ID.

  2. In the ID column, click the edit icon beside the text item you want to change, change the ID, and then click the check mark .

    Workflow Designer updates the text item's ID throughout the entire workflow.

  3. Press Ctrl+S to save your workflow.

To change a value for a text item:

  1. In Workflow Designer, click Info to open the Info panel, and then click Translations.

  2. In the Choose a locale drop-down list, select the locale for the value you want to change.

    For example, if the workflow is available in Portuguese (default), Spanish, and French, and you want to change the text item's Spanish value, you would select the "es" (Spanish) locale.

  3. Edit the value in the Text column.

  4. Press Ctrl+S to save your workflow.

Remove Text Items

Deleting a text item deletes it from all locales, not only the currently selected locale. If the deleted text item is used in the workflow's configuration, you must update the properties that use it.

To remove one or more text items:

  1. In Workflow Designer, click Info to open the Info panel, and then click Translations.

  2. Select the checkbox beside each text item you want to delete, or, to select all the text items, select the checkbox in the column header.

  3. Click Delete Selected.

  4. Click OK to confirm.

  5. If you have used any of the deleted text items in the workflow's configuration, update every property that uses one or more of the deleted items.

  6. Press Ctrl+S to save your workflow.

Remove a Locale

Every time you select a locale in the Translations panel, the locale is added to the list of configured locales in the Choose a Locale drop-down list. You may want to remove a locale from the list, either because you added it without intending to use it, or because you no longer want to support it.

To remove a locale from the list of configured locales:

  1. In Workflow Designer, click Info to open the Info panel, and then click Translations.

  2. Select the locale in the Choose a locale drop-down list.

  3. Delete the value of each text item by inserting the cursor in the Text column and pressing Delete or Backspace. Do not leave any space characters.

    Do not delete the text items themselves, as this would delete them from every locale. Only delete the values of the text items.

    The Text column should not have any values in it.

  4. Press Ctrl+S to save your workflow.

    The locale is removed from the workflow's internal list of configured locales. However, the locale will continue to appear in Workflow Designer until you refresh the page or re-open the workflow.

Test a Workflow's Translations

After you translate a workflow, you will want to test the different languages that you support. Although you can review your translations in the Translations panel, it is also useful to see them in the context of the running workflow. You can change your browser's language settings to force the running workflow to use one of the supported languages, but this is not convenient. A quicker method is to launch the host application with the locale URL parameter:

locale=[configured locale]

The Sandbox does not support translations. In the Sandbox, workflows always use the default language.

For example, if a workflow is available in French (default), UK English (en-GB), and German (de), you can run the workflow in English by launching the application with &locale=en-gb (or &locale=en-GB) added to the end of the URL. To run the workflow in German, you would launch the application using &locale=de. To run the workflow in the default language, omit the locale parameter.

Example of a Geocortex Viewer for HTML5 URL with a locale parameter set to German (de)

See also...

Translate a Geocortex Viewer for HTML5 viewer

Example - Translate a Form and an Alert

This example shows how to translate the user interface text for a workflow that contains a Display Form activity and an Alert activity. The Display Form activity prompts the user to select a region in the Canadian province of Québec. The Alert activity echoes the selected region back to the user.

The workflow's default language is French. In addition, the workflow is translated into Canadian English (en-CA). If the user's language is set to en-CA, the workflow appears in Canadian English. If the user's language is set to some other variant of English, for example, en-AU or en-US, the workflow will not find the variant, so it will look for the non-variant, en. The non-variant en is not configured, so the workflow will use the default language, French. Similarly, if the user's language is set to some other language, for example, nl or pt, the workflow will not find the language, so it will use the default language.

Workflow Logic

The workflow has the following activities, in the order shown:

To translate a workflow with a simple form and an alert:

This example has the following steps:

Step 1: Create the workflow

  1. Open Workflow Designer.

  2. In a new, blank workflow, add and connect the following activity:

  3. Double-click the Display Form activity to edit it.

  4. Create the following form:

    Preview of the form in its default language

    To configure the form:

    1. Select the Form Title element in the preview and set its Title property to: Régions administratives du Québec

    2. Add a Radio Group form element and set its Title property to: Choisir une région :

    3. Configure three radio buttons manually and set their Label properties to:

      • Laval
      • Montréal
      • Québec

    4. Add a change event to the radio group.

    5. Add and connect an Alert activity and set its Text property to: ="Vous avez choisi " + $form1.state.radioGroup1.items[$form1.state.radioGroup1.current].label.markdown

    You now have a functional workflow that is available in French only.

  5. Test the workflow:

    1. Press Ctrl+S to save the workflow.

    2. Run the workflow in the Sandbox.

      To run a workflow in the Sandbox, click Info in the sidebar, click Run in Sandbox, select the environment, and then click Run Workflow. You can press F12 at any time to see the verbose log.

Step 2: Create the text items

This workflow has two activities (Display Form, Alert) and three form elements (header, radio group, footer) that require translation. Usually, workflows also have activities that do not require translation.

  1. Click Info in the sidebar to open the Info panel.

  2. Click Translations to open the Translations panel.

  3. French (Default): Add the text items and configure the French values:

    1. Make sure Default (invariant) is selected in the Choose a locale box.

    2. Add and configure a text item for each user interface string in the workflow, listed in the following table.

      Text items for the Default (invariant) locale

      ID

      Text

      To be used in...

      form-title

      Régions administratives du Québec

      Title property of the header form element

      radio-group-title

      Choisir une région :

      Title property of the radio group

      submit

      Envoyer

      Label property of the footer form element, first button

      cancel

      Annuler

      Label property of the footer form element, second button

      alert *

      Vous avez choisi

      Text property of the Alert activity in the radio group's change subworkflow

      * In the running workflow, the alert text item will be followed by the name of the region that the user selected. Leave a space at the end of its text ("Vous avez choisi ") to separate it from the region name.

       

      The Translations panel for the Default (invariant) locale should look like this:

  4. English: Configure the English values:

    1. In the Choose a locale drop-down list, select en-CA.

      The text items already appear in the table for Canadian English.

    2. Configure the value for each text item.

      Text items for the Canadian English locale

      ID

      Text

      To be used in...

      form-title

      Administrative Regions of Quebec

      Title property of the header form element

      radio-group-title

      Choose a region:

      Title property of the radio group

      submit

      Submit

      Label property of the footer form element, first button

      cancel

      Cancel

      Label property of the footer form element, second button

      alert *

      You chose

      Text property of the Alert activity in the radio group's change subworkflow

      * In the running workflow, the alert text item will be followed by the name of the region that the user selected. Leave a space at the end of its text ("You chose ") to separate it from the region name.

       

      The Translations panel for the Canadian English locale should look like this:

  5. Press Ctrl+S to save the workflow.

Step 3: Use the text items in the workflow's configuration

  1. Display Form Header:

    1. In the form preview, select the form's header element.

    2. Type @ in the Title box and select @form-title from the drop-down list. Alternatively, type @form-title in the Title box.

  2. Radio Group: Select the radio group. Set the Title property to @radio-group-title.

  3. Display Form Footer: Select the footer form element. Set the first button's Label property to @submit. Set the second button's Label property to @cancel.

  4. Alert: Open the radio group's change subworkflow and select the Alert activity. Set the Text property to @alert.

  5. Press Ctrl+S to save the workflow.

Step 4: Test your translations

You can preview a form in each language that you have configured. Make sure the workflow is saved and then select the locale that you want to preview in the Translations panel's Choose a Locale drop-down list.

Form preview shown in French and English

In addition, you can use the locale URL parameter to test your translations in the host application:

  1. Launch the application that runs the workflow, without using a locale parameter.

  2. Run the workflow.

    The workflow appears in the default language, French.

  3. In the browser's address bar, add &locale=en-ca to the end of the URL and refresh the page.

  4. Run the workflow.

    The workflow appears in English.

    Workflow running without a locale parameter () and with the locale set to Canadian English ()

© 2018 Latitude Geographics Group Ltd. All Rights Reserved.

Documentation Version 5.9