Setting Up a Multi-Language Environment for VI Guidance

From SIMboxWiki
Jump to navigation Jump to search

Overview

Usually VI guidance actions inside agents use text in a specific language. However, in some cases there is a need to have the same lesson display the same messages in different languages based on the trainee preference. This article will describe the necessary preparations and configurations to setup multi-language capability in the VI (Virtual Instructor).

Setting Up the LMS Side

These steps guide you to define the list of languages (locales) in the KnowBook Learning Management System (LMS), so that the languages are available for simulation VI localization. Here you’ll find how to configure the multi-language on the KnowBook Server (Server Settings) and on the KnowBook Client (Client Settings).

Server Settings

Multi-language settings defined at the KnowBook server level will be available at the KnowBook client level after the client connects to the server and synchronizes with the server. Use the Client-to-Server synchronization to distribute the multi-language settings to all KnowBook clients that connect to the server.

  1. The site administrator must configure the (logical) list of available languages on the server. Navigate to the WebAccess and log-in as user who has Web Access Admin permissions.
  2. Select Admin -> Server Synchronization from the menu, and scroll down to LMS Simulation Settings section.
    Multi-1.png

To add new locale:

  1. Click the Add locale TextBox button (You can only press one time for each locale).
  2. The page will reload.
  3. Go to the LMS Simulation Settings section.
  4. A Text Box appears:
    Multi-2.png
  5. Enter a valid locale, for example: “en-US”.
  6. Click on Update (at the bottom of the page) to save the changes.
    1. If you entered a valid locale, the page will be reloaded and the changed locale will show the locale display name next to it, in this example, “English (United States)”:
      Multi-3.png
    2. If you entered an invalid locale you’ll get this message on top of the screen:
      Multi-4.png
    3. Once you click OK, go to section LMS Simulation Settings and you will see the error message with explanation why it is invalid.
      Multi-5.png

To delete locale:

  1. Next to each locale, there is a Delete link.
    Multi-6.png
  2. On the row of the locale that you’d like to delete, press the Delete link.
  3. The page will reload with the locale list without the deleted locale.
  4. Press on Update in the bottom of the page to save the changes.

To update or change an existing locale:

  1. Change the text in the relevant TextBox.
  2. Click on Update at the bottom of the page to save the changes. All changes are validated.
    1. If you entered a valid locale, the page will be reloaded and the changed locale will show the locale display name next to it, in this example, “English (United States)”:
      Multi-7.png
    2. If you entered an invalid locale you’ll get this message on top of the screen:
      Multi-8.png
    3. Once you click OK, go to section LMS Simulation Settings and you will see the error message with explanation why it is invalid.
      Multi-9.png

Client Settings

Multi-language settings defined at the KnowBook client level will only be available on the KnowBook client where you defined the settings. Refer to KnowBook Server (Server Settings above) if you want to distribute the multi-language settings to multiple KnowBook clients that connect to the server through Client-to-Server synchronization.

To add new locale on the client:

  1. Open KnowBook on the client computer and select Tools -> Options from the main menu.
  2. In the Options window, click on Simulation.
  3. Look for Localization pane.
    Multi-10.png
  4. Click on New button. The Add New Language dialog appears.
    Multi-11.png
  5. You can open the list to see all the available languages of the operating system.
    Multi-12.png
  6. Select a locale and click OK to close the Add New Language dialog. You will see the locale that you selected in the localization list.
    Multi-13.png
  7. Click OK or Apply to save the changes.

To delete a locale from the client:

  1. Chose a locale from the localization list.
    Multi-14.png
  2. Select the locale you’d like to delete and click Delete.
  3. Click OK or Apply to save the changes.

Viewing the Locales in the Simulation Launcher Page

Once multi-languages are configured, the lesson-launch bar will display a Preferred Language field where the trainee can select their preferred language for the lesson. The selection will persist to the next session the trainee runs and so on. The selection is based on student KnowBook credentials – ensuring each trainee will have their own selected language when they open the same lesson.

To view the locales (languages) you added to the LMS

  1. Open the KnowBook client and select a lesson in KnowBook Today.
  2. The Simulation Launcher page will display a Preferred Language field where the trainee can select their preferred language for the lesson.
    Multi-15.png
  3. Select the preferred language and click the GO button to start the lesson.

Technical Information

Once you press the GO button:

  1. If locales/languages are defined, KnowBook gets the default language for the logged-in user. In case there is no default language for the user, KnowBook takes the language of the operating system as the default.
  2. The preferred language locale will be stored to the specific user in the DB.
  3. The locale will be stored in SCORM data model – “cmi.learner_preference.language” - The trainee’s preferred language for SCOs with multilingual capability.
  4. The locale will be sent to the simulation, to tell the simulation which language will be used in the lesson.

Setting up the Simulation Side

Defining the CLR localization mechanism for showing locale specific strings

  1. The simulation uses the CLR localization mechanism for showing locale specific strings. These strings are stored in resource string tables as key-value pairs, and compiled into assemblies by using Visual Studio. Every agent will automatically load a localization assembly with the same name.
  2. In Visual Studio, create a C# class library project with the same name as the agent – in this example we are using Agent1. Click OK to create the project.
    Multi-16.png
  3. Remove the Class1.cs file that was created automatically. This file will not be needed.
  4. Add a resource file by right-clicking the Project > Add > New Item… and in the dialog that opens, choose ‘Resources File’ under the ‘General’ category. You should name the file with the same name of the agent and project – in this example Agent1:
    Multi-17.png
  5. Click Add. A resx file was created in the project – this will be the default locale if none is specified.
  6. Open the file which opens the Name-Value table. Put string identifiers in the Name column and localized strings in the Value column:
    Multi-18.png
  7. Now add another resource file (in the same way as before) which will be locale specific. Use the same name as the main resource file with the locale name as a suffix, for example, Agent1.it-IT.resx. Note that the locale name can contain only the language (it).
  8. Define the same identifiers that exist in the main file and put the localized text in the Value column – you can copy-paste the rows from one editor to another. Note: If an identifier is not found in a locale specific file, the code will default to the main resource file. It is therefore recommended that the main file will not contain actual values but rather the IDs themselves so that it will be clear whenever a localized string wasn’t found.
    Multi-19.png
  9. Define post build events to copy the binaries to the place they will be loaded from – the default is under sitec/resource/localization. The main assembly will be copied to that location and any locale specific dll will be copied to a subdirectory with the name of the locale (i.e. it-IT, fr-FR, zh-CN…). To open the dialog, right click project > properties
    Multi-20.png
  10. Compile the project and verify that the main dll exists where you copied it to and that the locale specific assemblies were placed in sub directories with the locale names. Deployment of the resource assemblies to other computers is discussed in the deployment section.
    Multi-21.png

Editing the VI guidance

  1. In the agent that you want to localize, edit the VI guidance and replace the text with a block in the format [Localize:<IDENTIFIER>]
  2. Where <IDENTIFIER> is a string that appears in the resx file in the ‘Name’ column. For example, ID_WELCOME. You can use as many blocks as you need and also use words and characters outside of these blocks.
  3. For each of these blocks, the code will replace it (including the brackets) with the string at the ‘Value’ column in the resx file.
    Multi-22.png

Configuring the locales to voices map file

If you have text to speech engines for different languages, configure the locales to voices map file (optional).

  1. A sample file in csv format named LocaleToVoiceEngine.csv is provided in Sitec\Resource\Config. It contains 2 columns, the 1st contains the locale and the 2nd contains the name of the text to speech voice as it appears in GLOBAL_ATT_AVAILABLE_TEXT_TO_SPEECH_VOICES. All lines that start with ‘//’ are treated as comments and ignored.
  2. You can place the file anywhere else under the Sitec\Resource directory. Set GLOBAL_PROP_TEXT_TO_SPEECH_MAP_FILE in BrainUtilities to the relative path. The default is Config\LocalesToVoices.csv. Rename it in order to avoid an override upon product upgrade.
  3. If the locale used by the agent is in the map file, the VI guidance will use the mapped voice. Otherwise it will use the default voice.

Deployment

The deployment of the localization resource assemblies can be done using the SIMbox Software Updates Mechanism.

  1. The SIMbox Toolkit is used to create a SIMbox package containing the localization resources you want to deploy. In the SIMbox Toolkit, right-click on Packages and select Add New from the local menu.
    Multi-23.png
  2. Name the new package and then browse the left side to where the resource assemblies are located. Use the right arrow button to add the main assembly and locale directories to the package. If you have prepared a voice map file, you can add it as well.
    Multi-24.png
  3. Click the Compile button. Browse for the destination you want the package to be created in and click the Save and Compile button.
    Multi-25.png
  4. When the compilation completes, a window will open on the package location. Note that each additional compilation will increment the build number and create a new directory at the same location.
  5. The directory structure will be: <Destination>\<Package name>\<Package GUID>\<Version>
  6. Open the Software Updates metadata file in a text editor, and change the AutoUpdate element to ‘true’ – Note – this value is case sensitive!
    Multi-26.png
    Here is the Software Updates metadata file in a text editor showing the AutoUpdate element with a value set to ‘true’.
    Multi-27.png
  7. Next you need to host this update on the Software Updates server – by default it is located on the KnowBook Server under C:\Program Files\KnowBook\Software Updates – place the <GUID> folder under the applications folder:
    Multi-28.png
  8. Any client machine connected to the server can now install this update, and future updates automatically.
    1. You can manually install it by running SIMbox Check for updates from the start menu.
    2. You can also use the installed service to automatically and silently check for updates and install these whenever you place new versions on the server. Change the settings (interval) and make sure the service is running on the client machine.
      Multi-29.png
      Open the Software Updates Preferences dialog
      Multi-30.png
      Make sure the ‘SIMbox Auto Software Updates’ service is running on the client machine
      Multi-31.png