User's Guide - Chapter 8: Languages
The Internet has opened many new markets to software developers whose past products would usually have supported only their own local language. In the international marketplace, it is important to not only offer software in a variety of languages, but also to keep this software current.
As you’ll see in this chapter, you can use TrueUpdate to create an update that will automatically display messages and prompts in your user’s native language. With integrated language selection built into all screen dialogs, TrueUpdate also makes it very easy to modify your existing translations at any time.
TrueUpdate has the ability to automatically detect the user’s system’s language and to display messages and screens in that language. The developer has full control over which languages are supported in their project and over the content presented to the user.
Language text is mainly used for messages generated throughout the update and on screens, both of which can be easily translated for multilingual updates.
TrueUpdate allows you to localize your application in two areas:
· Common error messages, status messages and prompts
· Application-specific screens
The following sections of this chapter will look more closely at how to achieve this localization.
The language that the TrueUpdate Client detects is based on the user’s regional and language settings. These settings allow Windows users to configure which language is displayed, which input locale is used and which keyboard layout is supported in the Windows operating system environment. These settings are usually configured when Windows is installed and can usually be changed from the Windows Control Panel. For example, in Windows XP, a user can select Start > Settings > Control Panel and start the Regional and Language Settings control panel application.
Each language in Windows has a constant language identifier. A language identifier is a standard international numeric abbreviation for the language that is used in a country or geographical region. Each language identifier is made up of a primary and secondary language ID. (There is a complete list of primary and secondary language IDs in the TrueUpdate help file.) TrueUpdate maps all known languages and sub-languages according to the language identifiers used by Windows.
Tip: TrueUpdate maps language identifiers to language names in a file called language_map.xml located in TrueUpdate’s Language folder (usually "C:\Program Files\TrueUpdate 3.0\Languages"). You can look at this file to see which primary and secondary language IDs are mapped to which languages. It is NOT recommended that you modify this file unless you have a very specific reason to do so.
The languages that are supported by your client are all configured from the Language Manager. You can access the language manager by selecting Project > Languages from the menu.
Although you can localize messages in several areas of the design environment, the Language Manager is the only place where you can control the project’s default language as well as which languages are supported by your update. For example, if you are editing one of your screens and decide that you would like to add a German translation, you will have to use the Language Manager to do so. Once you add German support here, it will be available in all other areas of your project.
When you add a language to your project, you are indicating that you want the client to recognize that particular language identifier on a system and to use specific messages for that language when identified. Conversely, if a system’s language is not represented in the languages list, it does not mean that the update will not run on that system; rather, it means that the update will use the default language.
Every project must have a default language. The default language is the one that will be used when the client encounters a system language that is not represented in the languages list.
For example, let’s suppose that you have English, French and German support in your update with English as the default language. If your user runs the update on a Greek system, the user will see the English messages since you did not specifically include support for the Greek language.
Note that the default language must be one that has a corresponding language file (see the next section).
A language file is an XML file that contains all of the "internal" error messages, status messages and prompts that are used by the TrueUpdate Client. Language files do not contain project-specific messages, such as the text that you enter on screens.
The language files are located in TrueUpdate’s Languages folder (usually "C:\Program Files\TrueUpdate 3.0\Languages"). They are named according to the English name for the language they represent. Each file contains a language map that identifies which language the file is responsible for and all of the built-in messages that will be used for that language.
Not all languages have a pre-configured language file. If you add a language to your project that does not have a language file, that language will use the same messages as the default language.
If you need a language file that is not shipped with TrueUpdate, please visit the Indigo Rose website (www.indigorose.com) and user forums (www.indigorose.com/forums/) where new language files are made available from time to time.
If after consulting the Indigo Rose web site you still can’t find the language file you need, you can always make one yourself. To make a new language file, simply make a copy of the existing language file that you want to translate from, rename it to the new language name, change the language map in the file accordingly, and then translate the messages.
To clarify this process, here is an example of how to create a French language file:
1. Open Windows Explorer to TrueUpdate’s Languages folder (usually "C:\Program Files\TrueUpdate 3.0\Languages").
2. Make a copy of English.xml and name it French.xml.
3. Open French.xml in a text editor such as Notepad.
4. Open language_map.xml from the Languages folder in a text editor as well.
5. Locate the section that maps French in the language_map.xml file. It should look like this:
<Language>
<Name>French</Name>
<Primary>12</Primary>
<Secondary>
<ID>1</ID>
<ID>2</ID>
<ID>3</ID>
<ID>4</ID>
<ID>5</ID>
<ID>6</ID>
</Secondary>
</Language>
6. Copy the above section from language_map.xml and paste it in place of the <Language></Language> section of the French.xml file. This will allow TrueUpdate to recognize this file as a language file for the French language.
7. Translate all messages in the <Messages></Messages> section to French. Do not change any actual XML tags. For example:
<MSG_SUCCESS>Success</MSG_SUCCESS>
becomes:
<MSG_SUCCESS>Succès</MSG_SUCCESS>
8. Save the file and re-open TrueUpdate. The new language will now be available.
9. Feel free to visit the Indigo Rose user forums (www.indigorose.com/forums/) and share the file with others so they can use your translations in their projects.
To add a new language to your project, click the Add button in the Language Manager. This will open the Add New Language dialog.
Simply select the language that you want to add and click OK. You will then see the language appear in the languages list.
When you add a new language to your project, the following happens automatically:
• TrueUpdate searches the Languages folder for an appropriate language file for the language. If one is not found, the new language is set to use the default language’s language file.
• The newly added language is added to all screens. That is, all screens have messages added to them for the new language. If a translated language file for that particular screen already exists, it will be used. Otherwise, the messages from the default language will be replicated for the new language.
• The language is added to the list of languages that you can select from in the language selectors throughout the design environment.
Of course, you will still need to go into the screen dialogs to verify and/or translate the text for the new language.
To remove a language from the project, select it in the Language Manager’s list and click the Remove button.
Note that the default language cannot be removed. In order to remove a language that is currently being used as the default language for a project, you will need to make another language the default language first.
When you remove a language, all of the translations for that language are removed from the screens in the project. Therefore, use caution when removing languages.
Once a language is added to your project, it is available for translation. When you’re editing the text on a screen, you can select the language that you want to edit by using the language selector. The language selector is simply a drop-down list that lets you choose the current language (for editing purposes) of the screen.
For example, if your project supports English, French and German, the language selector on every screen’s properties dialog will let you choose whether to edit the English, French, or German text.
Selecting a language in the language selector replaces the editable text on the dialog with the text for that language. Any changes that you make to the screen text will be restricted to that language.
Note: If you select a newly added language for which there is no language file, the editable text will initially be the same as the text for the default language.
Only the languages that have been added to the project will appear in the language selector. If you want to work on a language that is not in the drop-down list, you will first have to add it to the project using the Language Manager.
To localize a screen, open the specific screen’s properties. Next, select the language that you want to enter text for in the language selector. Then, simply type the text that you want for the various fields in that language.
Note: The Screen ID field on the Attributes tab cannot be translated. The Screen ID is a unique identifier for the screen and is never displayed to the user.
Tip: If the language that you want to translate to doesn’t appear in the language selector, you need to add support for that language to your project. This is done by adding the language in the language manager.
There may be times when you want to have your screens translated by a third party translator. If the translator owns a copy of TrueUpdate, you can simply send them your project file, have them translate the screens using the method explained above, and then have them send the project file back to you.
However, it may be that the translator does not own TrueUpdate or that you need to work with the project in other ways while the translation is taking place. TrueUpdate has a solution for this situation. You can:
1. Select the screen that you want to have translated in either the client or server screens list.
2. Click the Advanced button (this will open a popup menu).
3. Select Export Language and then the language that you want to export to.
4. Choose a location to save the file to.
5. Send the exported file to your translator.
6. When you receive the file back, select the screen in the Screens list.
7. Click the Advanced button and then choose Import Language from the popup menu.
8. Locate the translated file and select Open.
9. You will now have the new translated strings in your screen.
If you want to change the default error messages, prompts or status messages, you can edit the appropriate XML file in the Languages folder using a text editor such as Notepad. However, this is not generally recommended; the messages that you change will be propagated to all projects that are built after the changes are made.
Note also that if you choose to change the default messages, your modified language file may be overwritten by a future update to TrueUpdate. To avoid this, you may want to rename any language files that you modify, for example renaming english.xml to my_english.xml. (In cases where there is more than one language file for a given language, TrueUpdate will use the last one that it finds in the Languages folder.)
There are a number of advanced techniques that you can use to manipulate the language and the translated language strings in your update at run time. Most of these methods are accomplished using actions. This section covers a few of these advanced techniques.
There are two actions that can be used to retrieve information about the user’s language ID: System.GetDefaultLangID and Application.GetUpdateLanguage. Although both actions return a table of information containing language IDs, it is important to know the difference between the two.
System.GetDefaultLangID is used to get the primary and secondary language ID for the language that the user employs in Windows. This is absolute and cannot be changed with any other actions. For example, if this action returns 10 as the primary ID and 13 as the secondary ID, you will know that the user’s Windows system is configured for Spanish (Chile). (There is a complete list of primary and secondary language IDs in the TrueUpdate help file.)
The information returned by this action can be used in cases where you want to make specific choices about what to do based on the user’s absolute system language. For example, if you have a Web site that is translated into several different languages, you might want to use a series of if…then statements to open the appropriate site:
-- Determine the absolute system language
local tblSysLang = System.GetDefaultLangID();
-- Set a default
local strURL = "http://www.yourcompany.com/english");
-- See if we should go to a different site
if (tblSysLang.Primary == 7) then
strURL = "http://www.yourcompany.com/german");
elseif (tblSysLang.Primary == 10) then
strURL = "http://www.yourcompany.com/spanish");
elseif(tblSysLang.Primary == 16) then
strURL = "http://www.yourcompany.com/italian");
end
-- Go to the Web site
File.OpenURL(strURL);
Application.GetUpdateLanguage is used to retrieve the primary and secondary language ID that is actually being used by the TrueUpdate Client. Note that Application.GetUpdateLanguage may return a different result than System.GetDefaultLangID if the language being used by the client differs from the language your user employs in Windows.
For example, let’s say that you have three languages in your project: English (which is the default language), French, and German. Suppose a user from Chile runs the update on their system. Even though their system uses primary ID 10 and secondary ID 13 (which would be returned by System.GetDefaultLangID and corresponds to a dialect of Spanish), Application.GetUpdateLanguage would return a primary ID of 9 and a secondary ID of 1, which is the update’s default language (English). The TrueUpdate Client would be using the default language because Spanish was not added to the project at design time.
The value returned by Application.GetUpdateLanguage will always be a value for a language that you added to your project using the Language Manager. It will never contain values for languages that were not explicitly included in the project.
Normally, if TrueUpdate detects a language on the user’s system that is not supported in the Language Manager, the default language will be used. However, you may prefer to have your update use a different language in such situations. You can accomplish this by using the Application.SetUpdateLanguage action.
The Application.SetUpdateLanguage action allows you to directly set the primary and secondary language IDs that will be used for the update. Calling this action changes all subsequent error and status messages as well as the text shown on the screens. It effectively "forces" the TrueUpdate Client to act like it detected that language in the first place.
For example, let’s say that your project supports two languages: English (which is the default language) and Simplified Chinese. Since English is the default language, it will be used whenever the client is run on anything other than Simplified Chinese.
However, you might prefer that the client use Simplified Chinese if the user runs the client on a system configured to use Traditional Chinese.
In other words, you want to override the default language
rule and force your client
to use Simplified Chinese whenever Traditional Chinese is detected. You
can do so easily by placing the following short script at the beginning
of your client script, before any screens or dialogs are shown:
-- Determine the absolute system language
local tblSysLang = System.GetDefaultLangID();
if (tblSysLang.Primary == 4) and (tblSysLang.Secondary == 1) then
-- Traditional Chinese on user's system,
-- so use Simplified instead
Application.SetUpdateLanguage(4, 2);
end
You may also want to use the Application.SetUpdateLanguage action for testing purposes. For example, if you are running an English version of Windows, you might want to see how your update will look on an Italian system. Because your system is running in English, the client will always choose English as the language to display when you run it on your system. However, you could force the client to use Italian by putting the following script at the beginning of your client script:
Application.SetUpdateLanguage(16, 1);
You could even modify your client script to check for a custom command line option, so you could force your TrueUpdate Client to use a different language at any time. This could be useful for testing purposes, or to handle any language detection issues that are discovered after the client has been distributed.
Tip: The global variable _CommandLineArgs can be used to determine what arguments were passed to the TrueUpdate Client executable.
You may have noticed that there is no language selector when editing scripts in TrueUpdate. Any text you enter directly into a script will remain the same, regardless of what language is detected on the user’s system.
However, it is possible to use actions to detect the current language, and to use multiple "if" statements to specify different text for different languages.
For example, let’s say that your project supports English and French and you want to show a dialog box using actions that will be localized according to those languages. The following script first determines the language that the client is using, and then displays one of two possible greetings:
local tblSysLang = Application.GetUpdateLanguage();
if (tblSysLang.Primary == 9) then
Dialog.Message("Welcome",
"Welcome to the update");
end
if (tblSysLang.Primary == 12) then
Dialog.Message("Bienvenue",
"Bienvenue à la mise à jour");
end
The Application.GetUpdateLanguage action returns a table containing the primary and secondary language ID that is being used by the TrueUpdate Client. Note that this may or may not be the exact language that was detected on the user’s system; rather, it is the appropriate language that the TrueUpdate Client has chosen from the list of supported languages in the project. In other words, it is the user’s system language if that language is supported by the update; otherwise, it is the default language.
Tip: You can get the user’s actual system language by using the System.GetDefaultLangID action. However, it is usually preferable to use the Application.GetUpdateLanguage action so the scripted language behavior will match the "automatic" language behavior of the screens and error messages in the project.
TrueUpdate allows you to get and set translated messages from the language files and screens at run time. This is done through several actions.
This action allows you to retrieve the localized text for a general message from the language files at run time. The message will be returned in the current update language. For example, the default language files provide messages to confirm if the user wants to abort the update. Here is a way to show a dialog that confirms if the user wants to abort the update in the current language:
local strTitle = TrueUpdate.GetLocalizedString("MSG_CONFIRM");
local strPrompt = TrueUpdate.GetLocalizedString("MSG_CONFIRM_ABORT");
local nResult = Dialog.Message( strTitle
, strPrompt
, MB_YESNO
, MB_ICONQUESTION
, MB_DEFBUTTON2 );
if(nResult == IDYES)then
Application.Exit();
end
Note: The message IDs (like MSG_CONFIRM) for the localized message strings can be found in the XML language files, e.g. English.xml in the TrueUpdate Languages folder.
This action allows you to change the value of a localized string. This could be useful if you want to override the default value of an error message so that you don’t have to permanently change your language file. For example, let’s say that you want to change the message that is displayed if the user tries to cancel the update. By default it is "The update is not finished! Do you really want to abort?", but you want to change it to: "Stopping now is not a good idea. Are you sure?"
TrueUpdate.SetLocalizedString("MSG_CONFIRM_ABORT",
"Stopping now is not a good idea. Are you sure?");
These actions are used to get and set the value of a localized string from the current screen’s message file. Every editable text item on a screen has a corresponding string ID that is used internally to retrieve the appropriate text for the current update language when the screen is displayed.
The actions can also be used to create new, temporary localized strings that are only valid on the current screen, by using custom string IDs. For example, you could create a number of custom localized error messages to be used in the screen’s event scripts, without having to implement "if…then" branching wherever an error message was displayed.
Note: The Screen.GetLocalizedString and Screen.SetLocalizedString actions work the same way that TrueUpdate.GetLocalizedString and TrueUpdate.SetLocalizedString do, except that they will only access strings used on the current screen.