wwtools/aot/dev-guide/07-internationalizing.md

Internationalizing Objects

If your object will be used in localized environments, you can internationalize it by defining a multilingual dictionary that contains translated strings for the target locales. At run time, the object can retrieve the appropriate strings for the locale it is used in, and show those translated strings to the end user.

About Internationalizing Objects

By internationalizing an object, you enable it to run in various language environments and use different translated text messages, prompts, etc. in each case. For example, assume that you develop a complex object with its own custom editor pages. Customers in North America would expect to see English editor pages. On the other hand, customers in South America might use the object on a Spanish operating system and expect to see the editor pages in Spanish.

One way to do this is to create and maintain separate language versions of the object. However, this makes it very hard to maintain and update your code. A better way is to maintain one object version that will use the correct translated strings depending on the locale it is used in.

To do this, you separate the object’s code (which works identically in all locales) from the translatable text phrases (which are different for each locale). The translatable content in the code is replaced with abstract phrase IDs. The object then retrieves the appropriate translated content for whatever phrase ID it needs, when it needs it.

If an ApplicationObject contains local primitives, all local primitives use the object’s main dictionary. Reusable primitives, on the other hand, have their own dictionary.

To internationalize your objects, the ArchestrA Object Toolkit provides:

• An object dictionary that stores translated strings for each resource ID
• A function to retrieve translated strings for a resource ID

For more information, see Configuring the Object Dictionary and Retrieving Localized Dictionary Strings.

Configuring the Object Dictionary

For each translatable resource (“phrase”), the object dictionary defines an ID and translated strings for all locales that the object will be used in. You could visualize it as a table like the following:

Phrase ID	English	Spanish	German
idsWelcome	Welcome	Bienvenidos	Willkommen
idsValve1	Valve 1	Válvula 1	Ventil 1
...	...	...	...

When you request the phrase “idsWelcome” on an English operating system, you get the string “Welcome.” On a Spanish operating system, you get “Bienvenidos” instead, and so on.

The object dictionary is saved as an XML file with the .aaDCT extension. By default, it contains only a sample entry, and you have to add phrases and translations before you can use it.

You can edit the dictionary using any text editor or a special XML editor. For more information, see Dictionary File Format and Structure and Editing the Dictionary in Visual Studio.

Dictionary File Format and Structure

The XML dictionary file has the following structure:

<Dictionary>
    <Phrase_Index PhraseID="SampleEntry">
        <Language LangID="1033">
            <VALUE>English string</VALUE>
        </Language>
        <Language LangID="1031">
            <VALUE>String translated into German</VALUE>
        </Language>
        ... more <Language> elements for other languages ...
    </Phrase_Index>
    <Phrase_Index PhraseID="Entry2">
        ... <Language> elements ...
    </Phrase_Index>
</Dictionary>

There is a single Phrase_Index element for every translatable string. Its PhraseID attribute defines the ID by which you can access the string.

Each Phrase_Index element contains one Language element for each language-specific translation of the string. The LangID attribute of the Language element specifies the locale that the translation applies to.

Each Language element contains a single VALUE element with the translated string for the specified locale.

Editing the Dictionary in Visual Studio

You can directly edit the object dictionary using the built-in Visual Studio editor.

To edit the dictionary in Visual Studio

1. In the Object Design View, double-click Dictionary. Visual Studio opens a tab with the dictionary file.

You can now add or edit strings according to the dictionary XML structure (see Dictionary File Format and Structure).

Retrieving Localized Dictionary Strings

To retrieve a localized dictionary string at config time or run time, simply use the GetText method. For example:

GetText("idsError");

This statement gets the translation for the dictionary entry with the ID “idsError” for the default locale of the process it is called from. For config time code, this is the default locale of the Galaxy,that is, the OS locale at the time the Galaxy was created.

For more information, see the documentation on the GetText method in the ArchestrA Object Toolkit Reference Guide.