Creating translation of content

This document provides the workflow for creating a translation of content in order to support the multi-language Vortex Console application.

Support for creating and updating translations for clients purchasing Vortex Studio releases is new in the 2020b release. Until now, content and its applicable translations were customized and integrated as part of a delivered simulator.

Why is translation required?

The Vortex Console is a multi-language application that uses Qt, which supports translation. In order for new languages to be supported, a set of translation files must be provided, that defines the text that will be shown to the user of the Console.

Some of the translation files for the Console are provided as part of the Vortex Studio Toolkit, while others depend on the content and must match the text strings found in the content.

What is 'Content'?

Content is defined as the asset files that are created and populated using the Vortex Editor. Those asset files define the graphics, the dynamics, and the simulation logic: everything that will be in the simulation.

The Setup, Equipment, Scenes, Mechanisms, Assemblies, and their extensions contain text that can be displayed on the Console:

as part of the UI itself, such as button and page names
as identification of elements of the exercises: exercise, equipment and sub-equipment names, metric names
others, such as readouts of simulation status, metric values, messages, and other information

All such text needs to be translated to support the Console user's language preferences.

Identify Content Fields as Translatable

Text strings that can appear in the Console must be included in translation files so that they can be shown in the user's language of choice when the Console is displayed.

Exercise Reports are produced in the language selected for the Console, so translation files are also used to generate the reports.

Only Input or Parameter extension fields of type string can be tagged as Translatable via the Vortex Editor.

There are a few exceptions. String type fields cannot be set Translatable if:

there is an incoming connection to the field or
the field is read-only.

The Translatable flag can be set only on a definition. This means that in order to tag a field as Translatable, you must be editing the Setup, Scene, Mechanism or Assembly definition where the field is defined, or where the extension owning the field was added.

Some extensions' string-type fields are specifically intended to be shown in the Console'S interface and are automatically tagged as Translatable for convenience.

To tag an Input or Parameter field as Translatable, click on the Translatable icon shown on the right side of the field in the Properties panel. The icon is highlighted when the field is Translatable, as shown below:

Once you are confident that your content has the string-type fields properly tagged, you can create the translation files. It is always possible to modify the tagging if needed.

Create Translation Files

The tools in the Your Documents section on the Vortex Editor home page are used for the following operations. Refer to the Asset Browser document.

First, create a Project with assets. See Adding Documents to Your Simulation.

Then, create the translation files for your Project. See Localizing a Project.

It is important that translation files must always be in a folder under the 'assets' folder of the project, so they can be found at runtime.

Add Translation Text

Each *.ts source translation file created in the TS files location (except the English one named ***_en_US.ts) must have the correct words and phrases added to complete the translations. If the translation is not done, the source text will be used.

Use the Qt linguist application, included in the Vortex Studio toolkit, to add the translations to the file. Refer to https://doc.qt.io/qt-5/linguist-translators.html.

This task is typically outsourced to a translation service. The English language file does not normally need a translation.

Once the *.ts source translation files have been translated, they must be replaced in the translation files location in your Project. Run "Update translation files" again to update the associated *.qm binary translation files which are used at runtime.

Validate the Translations

Launch the simulation, including the Vortex Console.

On the Console's Login Page, select the language you want to work with from the list in the upper right corner.

Quit the Console application, then launch it again. The language you selected will now be in effect for the Console.

Confirm that the Login Page appears correctly for the selected language.

Log in and run the simulation normally, taking care to check the translations on each page as you do so. Generate several Exercise Reports and check that the translations are correct for the Reports.

Some text strings appear only on the Console display, some only in Reports, and some in both. Any missing or incorrect translations need to be fixed. See Troubleshooting Tips for how to diagnose some possible translation problems.

Any time the content is modified, you must update the translation files, to ensure they are always up-to-date with the Translatable string fields in the content.

Troubleshooting Tips

Problem 1 The new language does not appear in the Language selection list on the Login Page, or the Language selection list does not appear on the Login Page.

What to do

The Language selection list will be shown with a list of languages that have translation files defined for both Vortex Studio and for the Content. If the Language selection list does not appear, it means that only the English language is available.

Check the Setup (*.vxc) file for your Project (usually in assets/resources) to be sure the Console Module's Assets Base Path is correct, and points to the assets folder for your Project.
Check that the *.qm file for your desired language is present in the localization sub-folder (usually in assets/localization).
Check that the resources/languages folder in the Vortex Studio installation folder contains a console_ll_cc.qm file (ll=language, cc=country) matching your desired language file. If you are creating a translation for a new language, you will need to create a set of Vortex Studio translation files for the new language. Refer to Translating a Simulator into a New Language.

Problem 2 A string that should be shown in the new language is shown in English instead.

What to do

The actual translation is missing. Use Qt linguist to open the *.tm source translation file for the new language. Find the English text, and verify if a translation string is assigned. See Add Translation Text above.
The string was not included in the *.ts translation file.
Only the string-type fields which are marked as Translatable in the content will be extracted and included in the *.ts source translation file.
Use the Vortex Editor to examine the content and locate the extension where the untranslated string is defined.
Make sure the field is tagged as Translatable. Perform the 'Update translation files...' operation again after making any changes in the content. See Create Translation Files above.

Problem 3 A Python Script is using a hard-coded string to set the value of an output field, and the string appears untranslated on the Console or in the Exercise Report. How can I translate that string?

What to do

For strings that require translation, do not use hard-coded strings in Python script code. Instead, you must create a parameter of type string in the Script's extension. Set the parameter's value to the English text to be shown, and tag it as Translatable.
In the script code, use the parameter to set the value of the output field, instead of using the hard-coded string, as shown in the snippet below:

Using a translatable parameter to set an output in a Python Script

import VortexLocalization
...
...
extension.Outputs.OutputField.value = VortexLocalization.translate(extension, extension.Parameters.ParameterField.value)

You will need to create a new parameter for each hard-coded string that needs to be translated. See the example below.