Tutorial for Globalization Support

• Introduction
• SceneComposer Translator Plugin
• Managing Language Packs using AssetTool
• Using Globalization in Applications
• Custom Localizer Support

Introduction

Multi-Language Support

Preparing an application to perform in multiple locales requires the CGI Studio license "Globalization" and in terms of Candera build settings to enable the CMake feature switch "CANDERA_GLOBALIZATION_ENABLED".

Preparing an application to perform in a specific locale requires the following workflow:

Language Pack Source Format

In general, a Language Pack Source file

Master Language Pack Source

The Master Language Pack Source file is a design-time artifact not to be kept at production time. It defines all available translatable texts in an artificial Master Language (locale 00).

Extracting the content of a Master Language Pack Source .lps file shows following content:

Cultures

SceneComposer cultures are defined in the "Cultures" panel accesible either via File->Solution Options menu:

either via toolbar:

The default culture for a solution is defined in the 'General Configuration' panel as explained here.

Multi Language Pack Source

A Multi Language Pack Source provides translations for all translatable texts as defined in the Master Language Pack Source. All supported languages can be combined into a single .lps file, or be separated in single .lps files per language.

The culture definitions in language pack source files should syntactically match the culture definitions in SceneComposer to make the default culture setting of a solution work at application runtime. Example matching to the SceneComposer culture definitions above:

  <lps:Culture Name="German" Locale="de_DE" TextDirection="LeftToRight" />
  <lps:Culture Name="French" Locale="fr_FR" TextDirection="LeftToRight" />  

In case the default language is not set or not present in the asset, the first culture available in the asset will be used as fallback.

Appending Language Packs to Assets

Language Pack Source files are compiled into a binary format and appended to asset libraries

More Details

More details on the globalization workflow are provided here:

SceneComposer Translator Plugin

Overview

CGI Studio SceneComposer Translator Plugin provides the following features:

Globalization License

If the Translator Plugin files are present but no translation features are accessible in Scene Composer, please ensure that the Globalization license is acquired. Refer to the menu Help > Licenses.

Create and Manage Cultures and Translatable Texts

Accessing Translator Plugin in SceneComposer

The translator plugin is fully integrated into SceneComposer. The SceneComposer toolbar provides an icon for opening the Solution Options: Cultures dialog as well as a drop-down menu for selecting an already created culture.

There are five additional menu entries under Language:

Creating Cultures

In order to have texts in different languages, cultures have to be created. This is done by clicking on the button Culture Solution Options in the toolbar.

With the icons on top, cultures can be added (using the green plus sign) and deleted (with the red "x"):

Translate Texts

Texts can be translated in the Language Table Dialog, which is opened via the menu Language > Language Table....

The drop-down on the top right allows the Current Culture selection. The texts of the Master culture or another culture in the solution can be accessed by changing the Current Culture. If the Master culture is selected, the Add and Delete buttons are enabled, otherwise they are disabled.

A search field on top helps to easily find specific texts once the number of texts increases. With the checkbox Unused only it is possible to identify texts that have not yet been assigned to any Text Property of the solution.

Clicking on the globe icon on the top right opens the Solution Options: Cultures dialog.

Translatable Text

A translatable text is a text which supports translation into other languages and which provides information that facilitates its translation to other languages. The translatable text has the following properties:

Editing Text Properties

For editing the texts' properties, Scene Composer provides the Text Properties Dialog, which can be opened via the menu Language > Language Usage....

This dialog lists all Text Properties of the solution. For those Text Properties that have a translatable text assigned, the Text Id and the Text value for the current culture are displayed. The current culture can be changed in the drop-down menu on the right. If necessary, the Solution Options: Cultures dialog can be opened with the globe icon on the left of the drop-down menu.

When pressing Save, the changes made to the Text Properties will be applied to the solution.

Assigning Texts to TextNodes

Assigning texts to Text Properties can either be done in the Language Usage Dialog or in the Text Properties Panel.

Assigning Texts using the Language Usage Dialog

In the Language Usage Dialog a Text property can be selected. When pressing the Assign button on the bottom of the dialog, the Language Table Selection dialog is opened where a text can be chosen from the list.

Assigning Texts using the Text Properties Panel

The Language Table Selection dialog can also be opened when editing a Text property by clicking on the icon Select template for item.

Switching Cultures

If cultures and texts have been created and the texts are assigned to Text properties, the culture can be switched using the drop-down in the toolbar. As soon as another culture is chosen, the solution will be displayed in the other language.

Import and Export of Language Packs

Import of Language Pack Sources

Languages can be imported into a solution either as CGI Language Pack Source or as Excel file, by going to Language > Import Languages and selecting the desired flavor.

The final step of the language import process is to show the differences between the texts in the import file and the texts in solution. There are three possible actions:

Export of Language Pack Sources

The translatable texts of the current solution can be exported by going to Language > Export Languages..., which opens the Select Cultures dialog.

The Select Cultures dialog allows the choice of which cultures to be exported or not. Languages can be exported in Excel or CGI Language Pack Source (.LPS). Click the Browse button to select the Export file path, choose the format in the Save as type drop down and click Save. Click the Export button to finalize the languages export.

Please note that only the texts that have a correspondent in the master language texts, considering their Id, are included in the export, all the others being ignored. In this case warnings will be added to the Output tab in Scene Composer.

Managing Language Packs using AssetTool

Overview

AssetTool application can be used to manage language packs for a given asset. AssetTool application is located in /cgi_studio_bin/AssetTool/ folder and provides the following functionality:

A usage example of AssetTool application for managing language packs can be seen in /cgi_studio_player/content/Tutorials/05_Globalization/AppendMultiLanguagePack.bat script.

Appending a New Language Pack to an Asset

For the example solution, the following command can be called for appending language pack MultiLanguagePack_Source.lps to the existing asset MasterLanguagePack_Asset_Host.bin:

AssetTool.exe -append -a MasterLanguagePack_Asset_Host.bin MultiLanguagePack_Asset_Host.bin MultiLanguagePack_Source.lps

This will result in a new generated asset called MultiLanguagePack_Asset_Host.bin, which will contain the translation for all languages available in the language pack.

Removing an Existing Language Pack from an Asset

For the example solution, the following command can be called for removing master language, with code "00", from the existing asset MasterLanguagePack_Asset_Host.bin:

AssetTool.exe -append -r MasterLanguagePack_Asset_Host.bin temp.bin 00

This will result in a new generated asset called temp.bin, which will no longer contain the translation for the master language pack.

For more details on AssetTool application, see Tool Chain/AssetTool chapter.

Using Globalization in Applications

Requirements for Multi Language Support

Example: Set Culture in the Player

The Player provides, if Globalization is enabled in Candera, a checkbox to select all cultures, which are available as language packs in the loaded asset.

Candera Globalization API

The following table explains the usage of Globalization interfaces and how they are used in application code.

    return CultureManager::GetInstance().GetCultureCount();

    Culture::SharedPointer culture = CultureManager::GetInstance().GetCurrentCulture();

    Culture::SharedPointer culture = CultureManager::GetInstance().GetCulture(index);
    return culture->GetDisplayName();

    Culture::SharedPointer culture = CultureManager::GetInstance().GetCulture(index);
    FEATSTD_LOG_INFO(" -> Select culture '%s'", culture->GetDisplayName());
    rc = CultureManager::GetInstance().SetCurrentCulture(culture->GetLocale());

Custom Localizer Support

Requirements for Custom Localizer

In order to use a custom Localizer, a CMake feature switch CANDERA_CUSTOM_LOCALIZER_ENABLED has to be enabled. This flag will disable the usage of DefaultLocalizer which loads LanguagePacks from an asset.

In addition, please ensure that the following are fulfilled:

Defining a Custom Localizer

A custom Localizer class (eg: CustomLocalizer) should derive from abstract class Candera::Globalization::Localizer and provide implementations for the pure virtual functions:

For consistency, use FEATSTD_TYPEDEF_SHARED_POINTER(CLASS) and FEATSTD_SHARED_POINTER_CREATE_DECLARATION() macros to make the class manageable by SharedPointer.

Please note that FEATSTD_SHARED_POINTER_DECLARATION() macro should not be used in this case, because some base class methods will be overwritten and SharedPointer memory management will not work correctly.

Implement corresponding Create() method like in the following snippet:

/******************************************************************************
  Create
 ******************************************************************************/
CustomLocalizer::SharedPointer CustomLocalizer::Create()
{
    return CustomLocalizer::SharedPointer(FEATSTD_NEW(CustomLocalizer));
}

Example: Using a Custom Localizer in Applications

Define cultures

Create new cultures and add them to the list of available cultures of Candera::Globalization::GlobalizationCultureManager:

    m_cultureManager.RemoveAllCultures();
    for (UInt16 i = 0; i < cultureListSize; ++i) {
        Candera::Globalization::Culture::SharedPointer culture = Culture::Create();
        culture->SetLocale(cultureList[i].locale);
        culture->SetTextDirection(cultureList[i].textDirection);
        culture->SetDisplayName(cultureList[i].locale);
        m_cultureManager.AddCulture(culture);
        m_cultureVct.Add(culture);
    }

Set default culture to be used in case no current culture is set. This step is mandatory since the default culture will be used for initialization.

        m_cultureManager.SetDefaultCulture(m_cultureVct[0]);

Use a custom localizer

Declare a custom localizer:

    CustomLocalizer::SharedPointer m_localizer1;
    CustomLocalizer::SharedPointer m_localizer2;

Create the custom localizer:

    m_localizer1(CustomLocalizer::Create()),
    m_localizer2(CustomLocalizer::Create())

After a custom localizer has been created, the new localizer needs to be registered to the CultureManager:

    GlobalizationCultureManager::GetInstance().SetLocalizer(m_localizer1);

Initialize culture by setting current culture. If current culture is not set, default culture will be used.

        m_cultureManager.SetCurrentCulture(m_cultureVct[0]);

Switching localizer during run-time

Since only one localizer is allowed to be registered, in order to set a new localizer, the previous one has to be unregistered by calling SetLocalizer(0), like in the following snippet.

            GlobalizationCultureManager::GetInstance().SetLocalizer(CustomLocalizer::SharedPointer(0));
            GlobalizationCultureManager::GetInstance().SetLocalizer((toggleLocalizer1) ? m_localizer1 : m_localizer2);

Corresponding localizer cultures have to be added to the CultureManager and default culture has to be defined if no current culture is available.