We've made ResEdit usable by non-programmers. Ideally, the only skills one should need to localize an application to a foreign language is knowledge of the source and target languages--the translator shouldn't have to work with the source code. You may wish to give just this piece of documentation to your translator instead of burdening them with a full documentation set.
1 Glossary
2 Getting Started
3 What Needs to be Translated?
4 Creating A Translation File
5 Translating Text
5.1 Translating Via an ASCII File
5.2 Translating With ResEdit
6 Creating a Translated Geode
7 Updating an Executable
8 Testing the Translated Geode
9 Resource Editor Menus
9.1 File Menu
9.2 Edit Menu
9.3 Project Menu
9.4 Filter Menu
9.5 Utilities Menu
9.6 Window Menu
Make sure that there are two GEOS installations on your computer: one to hold the original-language version, and one for the translated version. These are often referred to as the source directory and destination directory, respectively.
You will need original-language versions of the geodes you will translate. These should reside in a directory under the source directory. Most applications will be in the WORLD directory. The localization file for each geode you'll translate should be in the same directory as its associated geode.
You'll use ResEdit to generate a foreign-language version of the geode. ResEdit will place the translated geode in the destination directory, at the same relative position as the original language version.
For example, you might have source directory D:\GEOS20.NC and destination directory D:\LATIN. Your original-language application, Connect 4, might reside in D:\GEOS20.NC\WORLD\GAMES. You'd need to copy CONNECT_.VM to D:\GEOS20.NC\WORLD\GAMES. When finished with translating, the resulting translated geode, perhaps named Connect IV, would appear in D:\LATIN\WORLD\GAMES.
To specify the locations of the Source directory or the Destination directory, choose the appropriate item from the Project menu. The Destination directory should not be the same directory as the Source directory.
To create a localized version of your applications, you will need to translate only the applications, libraries, and drivers you have created. All Geoworks software will be translated by Geoworks.
Most applications will use GEOS system libraries whose UI is visible from the application. For example, an application which includes spell checking will have a dialog box containing all the information about the spell checking operation which is included from the Spell library. If the Spell library is not translated, that UI will always appear in its original form. Your application will work with the Spell library, whether or not it has been translated.
At this point you are ready to translate geodes into the target language. The following set of steps can be carried out by a non-programmer running the ResEdit tool. Of course, the translator should have a good idea of the geode's function and use.
To begin creating new Translation Files, double click on the "Res Edit" icon in the Tools folder of the WORLD directory of the original-language version of Ensemble 2.0.
This brings up a dialog box which gives you three choices:
Choose the "Create New" option. Another dialog box appears, allowing you to select the localization (.vm) file for the geode you wish to edit.
The first time you start the Resource Editor, it assumes you will be editing geodes in the GEOS20.NC directory, or whatever installation of GEOS you started in. Once you have a Translation File open, you can change the top-level directory by clicking on the "Set source directory" in the Project Menu. This setting is saved in your .ini file, so the next time you start ResEdit, it will automatically set the top-level source directory to what it was when exited.
To create a new Translation File for a geode that is not in the GEOS20 installation (or whichever installation is currently set as the top-level source directory), change the top-level source directory first--because you cannot access the Project menu with no Translation File open, you may need to create a new Translation File and keep it around until you can access the Project menu to change the Source directory.
There are two main approaches to translating a geode's text. Some people prefer to work with an ASCII text file. Others prefer to use ResEdit's graphical interface.
We will discuss both methods.
Choose Other from the File menu; in the submenu that appears, choose Export Document. In the dialog that appears, choose a file location and name for the ASCII Translation File (ATF).
If you have already gone through the translation process once, and only wish the ASCII Translation File to contain entries for those chunks which have been translated, select the Export only changed chunks box.
Press the OK button.
You may now edit the ASCII file to translate strings.
The important lines of the file are of the form:
[keyword ] data
There should always be one space between the keyword and the data. The following keywords appear in the header:
The ASCII Translation File then lists all resources in the geode, by means of [resource ] lines and [endrsrc ] lines. Do not change the text of these lines. If, examining a resource, you realize it contains no chunk entries you wish to change, you may delete it to make it easier to find the resources you do wish to change. To do so, delete the [resource ] line, the [endrsrc ] line, and all lines in between.
Within each resource, there may be one or more chunks containing localizable strings. For each such chunk, there will be five lines:
[chunk ] chunkname[original ] {original text}[localize ] {instructions} max, min, type[translate ] {translated text}[mnemonic ] mnemonic [shortcut ] mods,shortcutYou will leave most of these fields alone, translating only the translated text, mnemonic, mods, and shortcut fields.
@localize keyword in the source code files.localize keyword.@localize keyword. [translate ] {moustache: :-{{)}[shortcut] PC,s
If, for some reason, the question mark were to be a shortcut, it would be represented by
[shortcut ] ,?
Only monikers may have shortcuts. The lack of shortcut is represented by
[shortcut] ,
Be careful when representing the lack of a shortcut: the carriage return or line feed at the end of the line must occur immediately following the comma. If there is an intervening space, ResEdit will think you want to use the space bar as a shortcut key.
If you will not need to translate a chunk, you may delete its entry to make it easier to find the chunks you do wish to translate. Delete the [chunk ] line and the [shortcut ] line and all lines in between.
To convert your ASCII Translation File into a regular Translation File, use ResEdit to import the file: either press the Import button in the dialog that appears when ResEdit starts up, or choose New/Open from the File menu, and then choose Import in the dialog that appears. In the dialog that appears, show ResEdit the location of both the ASCII Translation File and the Localization (.vm) File.
Press the OK button.
If your original-language geode has changed since the ASCII Translation File was created, ResEdit may present a warning dialog box at this point. Assuming the geode hasn't changed too much, it's probably safe to use the ASCII Translation File anyway. If you're hesitant, you can abort the import. You might then want to export another ASCII Translation File from the newer version of the geode.
After selecting a localization (.vm) file to translate, the Resource Editor will then load the information from this file and the corresponding geode into an untitled Translation File saved into the DOCUMENT directory. The file will be displayed in two views. The left portion of the screen is the Source File, while the right portion is the Translation File. When the file is first opened, the two sides look the same, since no translations have yet been made.
The Resource Editor brings up all the strings or bitmaps which need to be translated, regardless of their context. The only way you will be able to be completely sure that the translation is accurate is to perform the translation and then actually run the translated executable (to be discussed later) and see how the translations appear in the program.
Click on any text string in the right portion of the screen. The blinking text editing cursor should appear, and you will be able to edit the text in the right screen to reflect the changes necessary for the local language. The text in the left portion of the screen acts as a guide and will not change.
At the bottom of the main screen, there are three fields which may have important information about how you should translate the selected chunk.
If there is nothing in these fields, there are no constraints on the size or content of the translation.
This is the character the user will use when navigating the translated geode's UI with keyboard navigation. Only Text Monikers may have mnemonics. The mnemonic should be either a character which occurs in the moniker, the keyword ESCor the keyword NIL(which signals that there is no mnemonic).
You must be careful not to assign the same mnemonic to two monikers whose gadgets are both in the active window at the same time. If there is such a conflict, only one of the two gadgets will be activated by this mnemonic. When you have created the translated executable, you should check that there are no conflicting mnemonics, and change any which are found to overlap with others at the same level.
To choose a different mnemonic, use the Mnemonic gadget in the upper-right area of the ResEdit window. Use the up- or down- buttons to choose a letter from the text moniker, or type in your letter of choice. If you choose a letter which does not occur in the text moniker, it will appear in parentheses.
Keyboard shortcuts, also known as keyboard accelerators, are key combinations which may be used to activate a piece of UI gadgetry. For instance, Ctrl-S is a common keyboard shortcut for activating the Save item under the File menu.
In ResEdit, keyboard shortcuts are displayed when there is a chunk of type Object that has a shortcut. The shortcut will appear as something like "(Physical Ctrl p)".
To translate the shortcut, press the Shortcut... button at the top center of the ResEdit window. This will bring up a dialog box allowing you to specify that there should be no shortcut, or to specify a keyboard combination for a translated shortcut.
The following modifier keys are available: Alt, Shift, Ctrl. The Physical option specifies that Num Lock and Caps Lock states are disregarded when matching the shortcut character.
You may wish to translate a graphic. For example, a calendar application written for an English-speaking audience might have an icon depicting a desk calendar displaying the date "Apr 7"--but in a foreign language, "Apr" might not be anything a customer would see on a calendar.
To translate a graphic:
ResEdit will display the chunks of one resource at a time. To translate all the chunks in a geode, you'll need to work with chunks from several resources.
There are several ways to choose a different resource.
Within a resource, there are several ways to select a chunk to edit.
After all of the chunks and resources in the selected .vm file have been translated and saved in a Translation File, a new local-language executable can be created in the target installation.
The first step to placing the new executable in the correct place is making sure that the localization target kit has been placed in another directory on your hard drive, for example C:\ESPANOL.
Then select the Destination directory option from the Project menu. It will ask you to choose the top level GEOS directory that will hold the modified executables. In this case, you would choose the C: drive from the Drives list, and choose \ESPANOL in the scrolling list of directories.
You need not have a full GEOS installation in the target directory. However, when new executables are created, they are placed into the same subdirectory as the original geode. For example, if you were to translate GeoWrite, which is in the WORLD directory, and you had the destination directory set to ESPANOL, the directory ESPANOL\WORLD must exist when you try to create the new executable. If it doesn't, then you will get an error message saying that the target could not be created.
To create the translated geode, choose Create New Executable... from the File menu.
This new geode will have the identical original-language long name as the original geode (unless you have changed the name in the File Menu's New Name and User Notes dialog). You may wish to rename several of the geodes, especially those in the WORLD directory and the Screen Savers, to reflect local-language names.If you change the name, the new geode will not overwrite the original one, and you will have to go back and delete the old one to avoid duplicates.
Even after all the translations are complete, there may be a need to replace a certain executable with a newer version containing a bug fix or a feature enhancement. You will be able to do this quickly and effectively by using the Update feature in the File menu.
To make this feature work, you must first put the updated geode and .vm file in the proper source directory, overwriting the original files. Then, by clicking Update Translation File (in the Update submenu of the File menu), the existing Translation File will be compared with the new strings in the geode, showing the new or changed chunks, as well as the ones left unchanged. The deleted chunks will be grouped in a separate resource named "Deleted chunks" at the end of the resource list. You will then be able to make the necessary modifications to this file to bring it up to date with the newest version of the geode.
If the name of the original-language geode has changed, you will need to use the Update Geode Name function (in the Update submenu of the File menu) to tell ResEdit about the new name.
After updating the Translation File, you can then create an updated local-language executable as out lined above.
If there have been no changes to the geode that affect editable chunks (as when code changes for a bug fix), it is also possible to simply rebuild the new geode from the existing Translation File by choosing Create A New Executable from the File menu.
After viewing the updated Translation File and making any necessary changes, you can remove the updating information from the Translation File by choosing Commit the Update trigger from the File/Update menu. This will remove information which marks the chunks as "new" or "changed" as well as remove the Deleted Chunks resource.
You may wish to be able to test your translations as soon as you make them. At any point during a translation, you can create an executable, as described in Creating a Translated Geode.
Change directory to your Destination directory (e.g., \ESPANOL) start that installation, and test your new geode.
If your product will run under several video drivers (e.g., if it runs on desktop PCs), we suggest that you take a look at the localized UI under the CGA video driver to make sure that everything fits. You should also observe it under the EGA video mode with a large UI font size.
The quick overview of the menu items below should give you the necessary information to use all of the features.
The items in this menu keep track of how your project is organized.
Each of the "Don't show ..." menu items in the Filter menu is a radio button which allows you to turn on or off a filter. By turning on a filter, you ask that ResEdit not show chunks of a certain type. These options can be helpful when editing updated Translation Files, making it easier to find those items you want to work with.
Each of the "Show ..." menu items is a radio button which allows you to view specific chunks affected by updating the Translation File. At most one of these may be selected at a time. To show all chunks, make sure that none of these menu items are selected--choose the selected item to un-select it.
The first four of these menu items allow for quick movement between chunks and resources:
The last item provides a count of words in the original-language geode. It provides a count both of the total number of words and of the number of unique words (i.e., not counting repeated words):
These menu items make manipulation of multiple Translation Files easy, by opening overlapping windows or tiling active windows.