Languages |
|
|
|
Languages |
|
|
Languages |
|
|
|
Languages |
|
|
|
|
||
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 not only to offer software in a variety of languages, but also to keep this software current.
As you’ll see in this chapter, you can use Visual Patch to create a patch that will automatically display messages and prompts in your user’s native language. With integrated language selection built into all screen dialogs, Visual Patch also makes it very easy to modify your existing translations at any time.
Visual Patch has the ability to automatically detect the user’s system’s language and to display messages and screens in that language. As the developer, you have full control over which languages are supported in your project and over the content that you would like presented to the user.
Language text is mainly used for messages generated throughout the patching process and on screens, both of which can be easily translated for multilingual patches.
Visual Patch allows you to localize your patch 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 patch application 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. The settings are 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 then launch 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 Visual Patch help file.)
Visual Patch maps all known languages and sub-languages according to the language identifiers used by Windows. These mappings exist in a file called language_map.xml located in Visual Patch’s Language folder (usually "C:\Program Files\Visual Patch 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 patch 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 patch. 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 patch application 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 patch will not run on that system; rather, it means that the patch will use the default language.
Every project must have a default language. The default language is the one that will be used when the patch application 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 project with English as the default language. If your user runs the patch 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 patch application. Language files do not contain project-specific messages, such as the text that you enter on screens.
The language files are located in Visual Patch’s Languages folder (usually "C:\Program Files\Visual Patch 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 Visual Patch, 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 you would create a French language file like the one that ships with Visual Patch:
1. Open Windows Explorer to Visual Patch’s Languages folder (usually "C:\Program Files\Visual Patch 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 Visual Patch 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 Visual Patch. The new language will now be available.
To add a new language to your patch, 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:
• Visual Patch 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 Screens 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 Screens dialog (Project > Screens) and double-click on a screen to open the screen’s properties. Next, select the language that you want to edit 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 Visual Patch, 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 Visual Patch or that you need to work with the project in other ways while the translation is taking place. Visual Patch has a solution for this situation. You can:
1. Open the Screens dialog (Project > Screens).
2. Select the screen that you want to have translated in the Screens list.
3. Click the Advanced button (this will open a popup menu).
4. In the popup menu, select Export Language followed by the language that you want to export.
5. Choose a location to save the file to.
6. Send the exported file to your translator.
7. When you receive the file back, select the screen in the Screens list.
8. Click the Advanced button and then choose Import Language from the popup menu.
9. Locate the translated file and click Open.
10. 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 default messages, your modified language file may be overwritten by a future update to Visual Patch. To avoid this, you may want to rename any language files that you modify, for example you might rename english.xml to my_english.xml. (In cases where there is more than one language file for a given language, Visual Patch 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 patch 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.GetLanguage. 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 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 Visual Patch 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 make 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.GetLanguage is used to retrieve the primary and secondary language ID that is actually being used by the patch application. Note that Application.GetLanguage may return a different result than System.GetDefaultLangID if the language being used by the patch 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 patch on their system. Even though their system uses primary ID 10 and secondary ID 13 (which would be returned by System.GetDefaultLangID), Application.GetLanguage would return a primary ID of 9 and a secondary ID of 1, which is the project’s default language (English). The patch application would be using the default language because Spanish was not added to the project.
The value returned by Application.GetLanguage will always correspond to a language that you added to your project using the Language Manager. It will never identify languages that were not explicitly included in the project.
Normally, if the patch application 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.SetLanguage action.
The Application.SetLanguage action allows you to directly set the primary and secondary language IDs that will be used for the patch. Calling this action changes all subsequent error and status messages as well as the text shown on the screens. It effectively "forces" the patch application 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 patch is run on anything other than Simplified Chinese.
However, you might prefer that the patch application use Simplified Chinese if the user runs it on a system configured to use Traditional Chinese.
In other words, you want to override the default language rule and force your patch application to use Simplified Chinese whenever Traditional Chinese is detected. You can do so easily by placing the following short script at the beginning of the On Startup event, before any 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.SetLanguage(4, 2);
end
You may also want to use the Application.SetLanguage action for testing purposes. For example, if you are running an English version of Windows, you might want to see how your patch will look on an Italian system. Because your system is running in English, the patch application will always choose English as the language to display when you run it on your system. However, you could force the patch to use Italian by putting the following script at the beginning of your On Startup event:
Application.SetLanguage(16, 1);
You could even modify your On Startup script to check for a custom command line option, so you could force your patch application 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 patch has been distributed.
Tip: The global variable _CommandLineArgs can be used to determine what arguments were passed to the patch executable.
You may have noticed that there is no language selector when editing scripts in Visual Patch. 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 patch application is using, and then displays one of two possible greetings:
local tblSysLang = Application.GetLanguage();
if (tblSysLang.Primary == 9) then
Dialog.Message("Welcome",
"Welcome to the patch");
end
if (tblSysLang.Primary == 12) then
Dialog.Message("Bienvenue",
"Bienvenue au programme de correction");
end
The Application.GetLanguage action returns a table containing the primary and secondary language ID that is being used by the patch application. 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 patch application 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 patch; 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.GetLanguage action so the scripted language behavior will match the "automatic" language behavior of the screens and error messages in the project.
Visual Patch allows you to get and set translated messages from the language files and screens at run time. This is done using the following 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 language currently being used by the patch application. For example, the default language files provide confirmation messages that can be used if the user wants to abort the patching process. Here is a way to show a dialog that asks the user for confirmation in the current language before exiting:
local strTitle = VisualPatch.GetLocalizedString("MSG_CONFIRM");
local strPrompt = VisualPatch.GetLocalizedString("MSG_CONFIRM_ABORT");
local nResult = Dialog.Message( strTitle
, strPrompt
, MB_YESNO
, MB_ICONQUESTION
, MB_DEFBUTTON2 );
if(nResult == IDYES)then
Application.Exit();
end
This action allows you to change the value of a localized string. This can be useful if you want to override the default value of an error message from script, so 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 patch. By default it is "The patch 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?"
VisualPatch.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 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 VisualPatch.GetLocalizedString and VisualPatch.SetLocalizedString do, except that they will only access strings used on the current screen.
Learn More: Indigo Rose Software - Visual Patch - Buy Now - Contact Us