TD Localizing and Customizing SQLWindows Applications
TD Localizing and Customizing SQLWindows Applications
Team Developer
Localizing and Customizing SQLWindows Applications
Legal Notice
Gupta, Gupta Technologies, the Gupta logo, Gupta Powered, the Gupta Powered logo, ACCELL, Centura, Centura
Ranger, the Centura logo, Centura Web Developer, Component Development Kit, Connectivity Administrator,
DataServer, DBIntegrator, Development Kit, eWave, Fast Facts, NXJ, Object Nationalizer, Quest, Quest/Web,
QuickObjects, RDM, Report Builder, RPT Report Writer, RPT/Web, SQL/API, SQLBase, SQLBase Exchange, SQLBase
Resource Manager, SQLConsole, SQLGateway, SQLHost, SQLNetwork, SQLRouter, SQLTalk, Team Developer, Team
Object Manager, TD Mobile, Velocis, VISION, Web Developer and WebNow! are trademarks of Gupta Technologies and
may be registered in the United States of America and/or other countries.
SQLWindows is a registered trademark, and TeamWindows, ReportWindows and EditWindows are trademarks
exclusively used and licensed by Gupta Technologies.
The product described in this document is distributed under licenses restricting its use, copying, distribution, and
decompilation/reverse engineering. No part of this document may be reproduced in any form by any means without prior
written authorization of Gupta Technologies Corporation and its licensors, if any.
THE DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS,
REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE
EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. GUPTA TECHNOLOGIES, INC.
SHALL NOT BE LIABLE FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH THE
FURNISHING, PERFORMANCE, OR USE OF THIS DOCUMENTATION. THE INFORMATION CONTAINED IN
THIS DOCUMENTATION IS SUBJECT TO CHANGE WITHOUT NOTICE.
This document may describe features and/or functionality not present in your software or your service agreement. Contact
your account representative to learn more about what is available with this Gupta Technologies® product.
www.guptatechnologies.com
2
Table of Contents
3
Multiple Views for One Application at a Time ................................................................................................... 17
Using the Toolbars................................................................................................................................................................. 17
Spacing and Sizing Components ...................................................................................................................................... 18
Arranging Components with Precision......................................................................................................................... 19
Configuring the Grid ..................................................................................................................................................... 19
Setting the width and height of the grid ....................................................................................................... 19
Showing and hiding the grid ............................................................................................................................. 19
Making the grid active or inactive ................................................................................................................... 19
Verifying your settings ......................................................................................................................................... 19
Viewing Obscured Components....................................................................................................................................... 20
Scrolling in a Dialog Box or Window ............................................................................................................................. 20
Showing Sample Text ........................................................................................................................................................... 20
Localizing Menus ................................................................................................................................................................... 20
Localizing QuickTabs ............................................................................................................................................................ 21
Previewing a Window or Dialog Box ............................................................................................................................. 22
Changing the Tab Order ...................................................................................................................................................... 22
Showing Hidden Components .......................................................................................................................................... 23
Localizing Day and Month Names ................................................................................................................................... 23
Chapter 3 – Examples ................................................................................................................................................ 25
Creating the Sample Executables .................................................................................................................................... 25
Translating a Dialog Box ..................................................................................................................................................... 26
Translating Tabs ..................................................................................................................................................................... 27
Translating Menus ................................................................................................................................................................. 30
Translating Application Text ............................................................................................................................................. 31
Appendix – Menu Reference ................................................................................................................................... 34
File Menu ................................................................................................................................................................................... 34
Edit Menu .................................................................................................................................................................................. 34
Layout Menu ............................................................................................................................................................................ 35
Tools Menu ............................................................................................................................................................................... 36
Windows Menu ....................................................................................................................................................................... 36
Help Menu................................................................................................................................................................................. 36
4
Chapter 1 – Introduction
This document describes what Object Nationalizer™ can do and how you can use it.
Object Nationalizer is used to localize (translate) Team Developer applications from one language to another
without changing the application source code. All you need is the executable file (and dynalib files, if any)
that the programmer builds using Team Developer.
You can also use Object Nationalizer to modify the appearance of an application’s user interface. For example,
you can resize the various components of the user interface (such as push buttons, background text, list
boxes, and so on) to accommodate translations that are too large to fit on the existing components.
Audience
This document is written for anyone who is localizing (translating) a SQLWindows application into another
language, or modifying the appearance (but not the logic) of a SQLWindows application.
You do not have to be a programmer to use Object Nationalizer.
Resources
Resources are attributes associated with the visual elements of an application that affect only the appearance
of those elements.
For example, the background color or font used in a data field affects only the appearance of the data field—
these attributes are resources. This is different from the type of a data field (numeric, string, and so on),
which is tied to the logic of the program—the type of a data field is not a resource.
Other typical application resources are window titles, menu items, status bar text, messages (when defined
as string constants), table column titles, and labels for such things as push buttons, radio buttons, and check
boxes. (Read the book Developing with SQLWindows for more information about resources.)
Important: Object Nationalizer allows you to change only the resources in an application; you cannot change
anything that can affect the logic of the application.
5
Using Object Nationalizer, you can:
• View resources.
• Translate text resources.
• Change the resources that affect the size or position of components in the user interface.
• Save resources to a file in binary format.
• Save resources to a file in human-readable format.
• Apply resources to an executable file or dynalib.
Localizing Applications
In the typical scenario for translating a Team Developer application, a translator is set up to use Object
Nationalizer, then given a copy of the executable file and dynalibs to translate.
The translator opens the application files and extracts the resources into the Object Nationalizer
editor/designer. Using the editor/designer, the translator translates the application text and resizes
components as needed. Finally, the translator applies the changed resources back into the application.
When you now run the application, it displays text in the target language.
Note: The Object Nationalizer editor/designer can display translated text for Western European languages.
To view translations into other languages (such as Japanese, Hebrew, Russian, and so on), you must
obtain a version of Object Nationalizer that has been adapted to display the characters for that
language.
Files to Localize
You can use Object Nationalizer to localize executable (.exe) files or dynalib (.apd) files built using
SQLWindows.
Important: Read the release notes to find out which version of Team Developer you must use to create the
.exe or .apd file that Object Nationalizer can process.
6
When you open one of these files, Object Nationalizer extracts the resources into the editor/designer where
you can localize and modify them.
Once you make your changes to the application’s resources, you can update the executable file or dynalib
with the modified resources, save as a new executable or dynalib with the modified resources, or save the
modified resources into a resource file. The resource file can be in either binary (.apr file) or human-readable
(.txt file) format.
Important: Before programmers build the .exe or .apd files that are to be modified with Object Nationalizer,
they must check the Enable Resource Editing box in the Build Settings dialog box when they build the
application with SQLWindows.
7
6. The programmer opens the .apr file in Object Nationalizer and applies the resources in the .apr file to the
executable or dynalib.
Note: The steps a programmer performs and the steps a translator performs in the localization process is, of
course, determined by how your organization decides to divide up these tasks. The descriptions
above are assumed to be typical of many organizations.
8
This function takes two parameters: a string parameter with the pathname of the resource file to load, and a
number parameter that must be set to zero (this parameter is reserved for future use).
SalResourceSet returns TRUE if it succeeds and FALSE if it fails.
When called, SalResourceSet loads the resources from the specified resource file and modifies the
application’s resources stored in memory (RAM). The application files on disk (.exe and .apd) are not
modified.
Here is an example of the code the programmer might write in the SQLWindows outline:
Application Description: Dynamic Localization Example Libraries
Global Declarations Window Defaults Formats
External Functions
Library name: Kernel32.dll Function:
GetUserDefaultLangID
Description: Export Ordinal: 0
Returns
Number: WORD Parameters
Constants System
!LANG_ constants defined in winres.h Number: LANG_English = 0x09
Number: LANG_French = 0x0C
User Resources Variables
Number: nPrimaryLangID Internal Functions
Named Menus
Class Definitions Application Actions
On SAM_AppStartup
Set nPrimaryLangID = GetUserDefaultLangID() & 0xFF Select Case
nPrimaryLangID
Case LANG_French
Call SalResourceSet('french.apr', 0) Break
Case LANG_English
Call SalResourceSet('english.apr', 0) Break
The constants used to designate various languages come from the Windows header file winres.h.
This example assumes that the application is being deployed with two resource files: french.apr and
english.apr. (The resource file names are arbitrary—you can name them whatever you like).
Note: A string can span multiple lines. Everything after the opening curly brace is part of the string up to the
closing curly brace. To denote a literal closing curly brace in a string, you must escape it with a
backslash by entering “\}”.
Another serious problem with translating .txt files is that the translator cannot check to see if the
components on which translated text will appear are large enough to show all of the translated text.
For these reasons it is highly desirable to always use Object Nationalizer to translate the text in a Team
Developer application.
10
Chapter 2 – Using Object Nationalizer
This chapter explains how to install, start, and use Object Nationalizer.
Getting Ready
This section briefly describes what you should know or do before you can actually begin localizing a Team
Developer application using Object Nationalizer.
System requirements. The hardware and software system requirements for installing Object Nationalizer are
the same as for Team Developer.
Installing Object Nationalizer. Please read the release notes to learn how to install Object Nationalizer.
Preparing to use Object Nationalizer. Object Nationalizer has a user interface which is very similar to that
used in Team Developer. You will find it much easier to use Object Nationalizer if you first familiarize yourself
with the Team Developer interface by doing the tutorials presented in the Team Developer book Introducing
Team Developer.
Starting Object Nationalizer. To start Object Nationalizer, click the Start button, and select Programs > Gupta >
Team Developer 6.3 > Object Nationalizer 6.3.
Opening a file. Once you have started Object Nationalizer, open the file to localize (.exe or .apd file) or the
resource file in which you saved an application’s resources (.apr or .txt file) by selecting File > Open, and then
select the file.
Important: If resource editing was not enabled when a .exe or .apd file was built, Object Nationalizer refuses
to open the file and displays an error message. To learn how to build a .exe or .apd file with resource editing
enabled, read Creating the Sample Executables on page 25.
11
Localizing Text Resources
You can localize (translate) the text portions of an application’s interface in either of two ways: by translating
the application text directly or by modifying resources graphically. This section describes both methods.
12
To do the same translation multiple times, select Edit > Replace. Put the original text in the Find What field
and its translation in the Change To field. Click Find Next to locate the next occurrence of the original text,
then click Change to translate it. To translate all occurrences of the original text in one operation, click
Change All instead of Change.
Warning: If you click Change All and then discover you have changed too much, you cannot undo this
operation. If you are not sure it is safe to click Change All, alternate between clicking Change and Find Next so
you can control the operation one change at a time. If you find text that you do not want to change, click Find
Next again instead of clicking Change to continue searching for the text in the Find What field.
13
4. Type the translation in the text box, and click the close icon on the Attribute Inspector window. The
background text resource changes from Password: to the translation you entered.
Another way to change the same text graphically is the following:
1. Expand the explorer tree to show the dlgQOLogin dialog box component, and then select it.
2. Select the Password: background text in the right pane, pause without moving the mouse, and then click
again to make the text editable.
3. Translate the text and press Enter.
A third way to change the same text graphically is the following:
1. Expand the explorer tree to show the dlgQOLogin dialog box component.
2. Expand the dlgQOLogin component, then expand the Child Windows component underneath it.
3. Select the Password: background text component in the explorer tree, pause without moving the mouse,
and click again to make the text editable.
4. Translate the text and press Enter.
Resizing a component
Once you translate the text, you may discover that the component on which the text appears is too small to
show all of the translation. To enlarge the component, position the mouse cursor over one of the dark grab
handles so that the cursor changes to a double-headed arrow. Hold down the left mouse button, drag the
double-headed arrow in the direction you want to expand the component, then release the mouse button
when you finish.
Note: Each copy of an executable, dynalib, or resource file should contain the translations for just one
language.
15
the class of which the component is an instance (if any), and the file with which the component is
associated (if any).
When you expand the Child Windows component in the explorer tree, the Components tab in the right
pane lists all of the components (child windows) in that component.
• Description—This tab displays the textual information about either the entire application (if you select
the top of the explorer tree) or one of its components (if you select a dialog box, MDI window, table
window, or form window in the explorer tree).
To view the description of the entire application, select the Application node in the explorer tree, then
select the Description tab. To view the description of a component in the application, select that
component in the explorer tree, then select the Description tab.
You can also edit this text if you want to. You can use the description to provide information about what a
component is, how it is used, how it has been changed over time, which components should not be
translated, and anything else you feel is important to record.
Users who run the application will never see this description text. You do not have to translate
descriptions to localize the application.
• Layout—This tab lets you graphically alter a dialog box, MDI window, table window, or form window. This
tab is available only if you select a dialog box, MDI window, table window, or form window in the left
pane.
16
Note: Only the window that appears when you first open a file (the application window) shows the explorer
tree for the entire application. Each additional window that you open displays just that portion of the
tree starting with the selected component. When the window first opens up, you cannot see this
reduced tree. To view it, drag the left inner edge of the window to the right.
Note: A checkmark always appears next to the window that is currently topmost.
17
Arrange toolbar—Use this toolbar to arrange the components of a dialog box or window in a systematic way.
To use the Arrange toolbar, select the components to be arranged, and click the appropriate toolbar button.
Use the Arrange toolbar buttons to:
• Turn on the grid.
• Align the left edges of the selected components.
• Align the right edges of the selected components.
• Align the top edges of the selected components.
• Align the bottom edges of the selected components.
• Space the components evenly on the horizontal axis.
• Space the components evenly on the vertical axis.
• Align the centers of the selected components horizontally.
• Align the centers of the selected components vertically.
• Make the selected components the same width.
• Make the selected components the same height.
• Make the selected components both the same width and the same height.
When Object Nationalizer first starts, the Standard toolbar is displayed and the Arrange toolbar is hidden.
To change whether a toolbar is visible or hidden, select Tools > Toolbars to display the Toolbars dialog box.
Check the box next to the name of the toolbar to make it visible; clear the box to hide it.
18
Arranging Components with Precision
You can arrange components on a window or dialog box in exactly the locations you want by using the grid.
The grid consists of regularly spaced raised dimples on the background of a window or dialog box.
To use the grid, make sure it is enabled by seeing if the Grid menu item (on the Layout menu) is checked. If it
is not checked, click the Grid menu item.
Once you have enabled the grid, you can align components to the nearest grid point. Select the component,
then select Layout, Align to Grid.
19
Viewing Obscured Components
When you rearrange the components on a form or dialog box, you can partially or totally obscure another
component. To see the obscured component, select the component that is in the way, then select Layout,
Send to Back; this places the component behind any other component that is being obscured.
Use this method if the component you can see completely hides another component you want to view.
If you can see only part of a component and you want to see all of it, you can select the component that is in
the way and send it to the back, or you can select the partially visible component and select Layout, Bring to
Front; this puts the selected component in front of the component that was obscuring it.
Localizing Menus
You can localize the menus and status bar text in an application using either one of two editors:
• The Application Text editor. Menu items and status text appear in the Original Text column of the editor.
To learn how to use this editor, read Translating the Application Text on page 12.
• The Menu Editor. The rest of this section tells you how to use this editor.
20
To display the Menu Editor, use the right mouse button to select a component in the explorer tree that has
menus, then select Menu Editor. The three kinds of components that can have menus are form windows, top-
level table windows, and MDI windows.
The Menu Editor looks like this:
Left
Select the menu item to be translated in the left pane of the dialog box. (In the screen shot above, the File
menu item is highlighted.) Next, click in the Title field and translate the existing text. Then click in the Status
Text field and translate the text there. Repeat these steps for each menu item in the left pane, then click OK.
You can also rearrange the menu items in the left pane. To move a menu item, click on it, then drag it to its
new location in the list of menu items and release.
The ampersand (&) in the Title text indicates that the following letter is the keyboard shortcut key for that
menu item. When translating a menu item, you need to determine which letter in the translated text (if any)
should be the shortcut key and precede that letter with an ampersand.
To actually see the menus that a window has, you can preview the window. Read Previewing a Window or
Dialog Box on page 22 for more information.
Localizing QuickTabs
To localize or modify the tab labels created using QuickTabs on a form or dialog box, select the form or dialog
box in the explorer tree, then click the Layout tab in the right pane to view the form or dialog box. Right-click
on the tab frame (the outline of the tab—see the picture below) to display the context menu, click
Properties, and then click Tab Frame Properties to display the Tab Frame Properties dialog box.
21
Tab frame
Tab
In the Tab Frame Properties dialog box, select the Tabs tab, click any of the entries in the Tab Label column,
then replace the existing text with the appropriate translation. Repeat for all the entries in the Tab Label
column, then click OK.
23
To extract and modify these resources, first make a copy of GTLSI62.DLL and store it in another directory. (You
can find this DLL in the Deploy subdirectory of your Team Developer installation.)
Important: Do not modify the resources in the original GTLSI62.DLL. Also, do not change the name of the
copied file. It must also be named GTLSI62.DLL.
Open the copy of GTLSI62.DLL using a suitable resource editor (such as the one that comes with Microsoft
Visual C++) and translate the day and month names. You cannot use Object Nationalizer to edit this DLL;
Object Nationalizer can only edit the resources in a .exe or .apd file generated by Team Developer.
24
Chapter 3 – Examples
This chapter provides several example snippets of localizing Team Developer applications using Object
Nationalizer. The examples use some of the sample applications that are available as part of the Team
Developer installation.
This chapter describes how to localize parts of several sample SQLWindows applications into standard French.
The sample applications used in this chapter are: qckfinal.app, company.app, and stddlg.app. All of these files
are located in the Samples subdirectory of the Team Developer installation directory.
To do the examples, you must have the executable (.exe) versions of the sample applications. Moreover, these
.exe files must have been built with resource editing enabled.
25
Click OK in the message box saying that the build was successful. Select File > Exit and click No in the Save
Changes dialog box.
26
Note: You don’t have to close Attribute Inspector each time. If you have several changes to do, it is faster to
simply open Attribute Inspector for the first change and, after doing that change, left-click on the
next item to be changed. When you do, your first change is shown in the layout window, and the
properties for the second item are displayed in Attribute Inspector. You can continue this process of
changes and left-clicks as long as you like.
Translate the two other background text items (User and Password) and the two push buttons (OK and
Cancel) just as you translated the background text Database: use right click and the Attribute Inspector, and
replace the existing Object Title with the translated text.
The dialog box now looks like this:
Translating Tabs
This section explains how to translate the tab labels that appear on the tabbed form window in the sample
application company. The SQLWindows source file is company.app; the executable file is company.exe. You
may need to build company.exe if it does not already exist.
1. Open the sample file company.exe.
2. Expand the explorer tree on the left until you can select the form frmStat (one of the child windows of
the mdiMain window), then display the Layout tab on the right.
3. Right-click the Company Purchases by Style tab to display the Edit menu, then select the Tab Frame
Properties menu item (as shown below).
27
You now see the Tab Frame Properties dialog box.
4. Select the Tabs tab if it is not already on top. Drag the divider between the Tab Label column and the Tab
Name column to the right to show the entire tab name “Company Purchases by Style.”
5. Click in the first cell (with the text “Company Purchases by Style”), then change the text to “Achats de la
compagnie par style.” Click in the cell with the text “EMail Company Report” and change the text to
“Sommaire de la messagerie électronique.”
28
6. Now that you have localized the tab labels, you can go further and customize the appearance of the
labels as well. Click the Fonts tab, click Use Custom Font, then select Times New Roman from the Name
drop-down list.
7. Click OK.
You have both translated the tab text and customized the appearance of the text (as shown below).
29
Translating Menus
This section explains how to translate one of the menus in the sample application stddlg. The SQLWindows
source file is stddlg.app; the executable file is stddlg.exe.
1. Open the sample file stddlg.exe.
2. Expand the explorer tree on the left until you can select the component frmMain.
3. Right-click frmMain, and select Menu Editor from the context menu (as shown below):
30
To localize all the menus, you would continue scrolling down the left window pane, selecting and translating
each one until you had done them all. At the end, you click OK to finish.
31
The translation appears both in the Translated Text column where you typed it in and the Translated Text
window pane (above the Translated Text column).
6. You can see how well the translation fits by viewing the form on which it appears. The first part of the
identifier (mdiIsland.Invoices) tells you that the push button you just translated appears on the Invoices
form in the mdiIsland window. Expand the Windows component in the explorer tree until you see the
Invoices form, select it, then display the Layout tab in the right-hand window pane.
32
You can see in the next screen shot the translation on the push button. You can verify also that, in this
particular case, the button does not need to be enlarged to display all of the translated text.
Translated button
33
Appendix – Menu Reference
The following menus and menu items are available in Object Nationalizer.
File Menu
Menu Item Description
Open Opens an executable (.exe), a dynalib (.apd), a binary resource file (.apr), or a
text resource file (.txt)
Save Updates the contents of the file you opened with all the changes you have
made so far.
Save As… Saves the current values of the resources into a resource file, or creates a new
executable or dynalib with the current values of the resources.
You are prompted to choose the type of file to create and to name the file.
Apply… Updates the resources in an executable (.exe) or dynalib (.apd) file. See the note
below.
Exit Closes down Object Nationalizer.
This menu also displays a list of the most recently opened applications between the Print and Exit menu
items.
Note: When you select Apply, you are prompted for different information depending on the kind of file you
currently have open. If you have a .exe or .apd file open, you are prompted to specify which resource
file to use to update the executable (.exe) or dynalib (.apd) file; if you have a resource file open, you
are prompted to specify which .exe or .apd file to update (using the information in the resource file
you currently have open).
Edit Menu
Menu Item Description
Undo Undoes the last change you made to a resource.
Note: Once you undo a step, you cannot redo it. Also, you can undo only one
step, not multiple steps.
Cut Moves the selected component or text to the Clipboard.
Copy Copies the selected component or text to the Clipboard.
Paste Copies the contents of the Clipboard to the active window at the cursor
location.
Delete Discards the selected component or text.
Find… Finds the specified application text.
34
Menu Item Description
Find Again Repeats the most recent search.
Replace… Replaces the specified application text with the replacement text.
Properties… Displays the Properties context menu for the currently selected component.
Layout Menu
Menu Item Description
Preview Window Displays the window or dialog box currently visible on the Layout tab as it would
appear in the running application.
Bring to Front Places the selected component in front of all other components that share at
least some of the same area on a dialog box or window.
Send to Back Places the selected component behind all other components that share at least
some of the same area on a dialog box or window.
Align to Grid Aligns the selected components with the points of the grid.
Align Edges Aligns the edges or centers of two or more selected components. (The edge of
the first component selected is used to align the edges of the other
components.)
Space Evenly Makes the spacing between selected components uniform.
Make Same Size Makes the width, height, or both width and height of all the selected
components identical. The width or height of the first component selected is
used to set the width or height of the remaining components.)
Grid Enables or disables aligning (snapping) components to the grid.
Tab Order… Displays the Tab Order dialog box, which is used to view and modify the tab
order of components in a window or dialog box.
Show Sample Text Fills data fields, multiline fields, and table window columns with sample data
according to the component’s assigned format or input mask (depending on the
data type of the component).
Show Design Scroll Bars Shows or hides scroll bars that let you view parts of a window or dialog box that
may not be visible when the application runs.
Show Hidden Windows Respects or overrides the Visible property associated with components. If Show
Hidden Windows is enabled, all components in the application are visible in the
editor/ designer, even components whose Visible property has been set to “no”.
35
Tools Menu
Menu Item Description
Toolbars… Displays a dialog box on which you select which toolbars (standard and
alignment) are to be visible.
Attribute Inspector Accelerator: Alt-3. Displays the Attribute Inspector dialog, which allows you to
modify the attributes of the object that is currently selected.
Preferences… Displays the Preferences dialog box. Use this dialog to customize the grid.
Windows Menu
Menu Item Description
Cascade Displays all open child MDI windows in a stepladder fashion, with only the
topmost window completely visible.
Tile Horizontally Displays all open child MDI windows from left to right.
Tile Vertically Displays all open child MDI windows from top to bottom.
Close All Closes all child MDI windows.
At the bottom of the Windows menu is a list of the windows that are currently open. A checkmark appears in
front of the window that currently has the focus.
You can use this list to change the focus to another window. If the windows are being displayed in cascade
mode, the window you select is brought to the top of the stack of windows.
Help Menu
Menu Item Description
About Object Nationalizer Displays the version of Object Nationalizer.
…
36