ResEdit Originaldoku
Startseite  > Programme  > ResEdit  > ResEdit Originaldoku
 
The Resource Editor is a tool created by Geoworks to translate UI elements of an existing GEOS program into another language. Download this document - 11 Kb

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


top - 1 Glossary In explaining how to use the Resource Editor, we use some vocabulary to describe certain operations and program constructs.

Geode, Executable - A "geode" or "executable" is a GEOS program: a GEOS application, library, or driver.

Source Executable - The original-language program.

Destination Executable - The local-language executable, which is created by translating the source executable.

Resource - Geodes are divided into memory blocks called resources. Resources may contain code that will be executed, data that will be referred to, or text and bitmaps which will be displayed to users. The Resource Editor will only allow you to edit those resources which contain strings or bitmaps. Each resource has a unique number or extended name.

Chunk - Resources are, in turn, divided into chunks. Inside a resource, there are many different kind of chunks, each containing a unique piece of information, such as a text string, a bitmap, or an object structure. Each chunk has a unique number or name. Your translation will consist of new contents for these chunks.

Driver - A driver is a special sort of executable that performs a very specific function that may not be needed by every user. Many drivers are responsible for interactions with particular kinds of hardware peripherals. In GEOS, there are DOS, video, mouse, communications, and printer drivers, along with a few other types. Most drivers are designed to work with more than one device. For example, the EPSON9.GEO printer driver actually supports more than 50 printers--if you were to localize the driver, you might need to translate the names of those printers.

Localization File - When a geode is created, an extra file to be used by the Resource Editor is created at the same time. This file (which is named like the .geo file but with a .vm extension) contains localization information about the resources and chunks which you will be editing. You cannot localize a geode without this file. A programmer may create a localization file much as they would compile a geode. Using the GEOS SDK, issue the command "pmake full" to compile a Localization file in addition to a geode.

Translation File - The file that the Resource Editor creates is called a Translation File. The information stored in this file will be merged with the source executable to create the destination executable. Internally, the file holds a copy of the original-language text or bitmap, along with your translation and may contain some translation instructions.

Moniker - Text or graphics which serves as the visual name for objects such as menu items, button labels, and dialog box options. E.g., the File menu's moniker is "File"; an OK button would have moniker "OK".

Text String - Text in the geode which is not a moniker.

Mnemonic - A key that, when pressed with the Alt key, will activate a specific UI gadget which has this letter or symbol underlined in its moniker.

GString - Graphics string. This data structure is used for describing many types of graphics. Most application icons and document icons are GString Monikers.

Bitmap - Bitmap image.

Keyboard Shortcut - A combination of keystrokes than when pressed will cause an object to perform a specific action. Keyboard shortcuts are stored in the chunk containing the object to which they are connected.

Updating - Unfortunately, software often changes. As you make changes to the original-language software, it might become necessary for you to take a Translation File you created with an older version of a particular geode and update it with the newer version. The newest software may contain new strings, may have modified existing strings, or may have eliminated some strings. The Resource Editor is however able to match these two executables and show the newest changes. The process of updating a file will be discussed in more detail later in these instructions.


top - 2 Getting Started

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.


top - 3 What Needs to be Translated?

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.


top - 4 Creating A Translation File

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:

  • Create New Translation File
  • Open a Translation File
  • Import an ASCII Translation File

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.


top - 5 Translating Text

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.

Translating Via an ASCII File Translating With ResEdit


top - 5.1 Translating Text: Translating Via an ASCII File

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:

[source] - This is the long name of the geode.

[path] - This is the geode's path, relative to the Source directory. Applications will typically be in the WORLD path.

[version] - The geode's version number.

[DOS name] - The geode's DOS filename.

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,shortcut

You will leave most of these fields alone, translating only the translated text, mnemonic, mods, and shortcut fields.

chunkname - The chunkname is a unique identifier for the chunk. Do not change this.

original text - The original text in the chunk. Do not change this. The text is delimited by curly braces ("{" and "}"). If any curly braces occur in the string, they will be represented by two curly braces.

instructions - Instructions to the person translating. Do not change this. These instructions are taken from the original-language geode. The geode's programmers specified the instructions by means of the @localize keyword in the source code files.

max - Maximum number of characters you may use in the translated text. Do not change this. The geode's programmers specified this number by means of the @localize keyword.

min - Minimum number of characters you may use in the translated text. Do not change this. The geode's programmers specified this number by means of the @localize keyword.

type - The text's purpose in the program. Do not change this. A Text Moniker is the visible name of a gadget. A piece of Text appears in the program, but not as the name of a gadget.

translated text - This is how the text will appear in the translated geode. You'll probably want to change this text. The text is delimited by curly braces. If you want the translated string to contain curly braces, you should double them--use "{{" and "}}". E.g., to have translated text "moustache: :-{)", the line would read

[translate] {moustache: :-{{)}

If the original text looks like a shortcut key (e.g., "{(Physical Ctrl u)}", then to translate the keyboard shortcut, work with mods and shortcut (described below) and leave this field alone.

mnemonic - 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 overlap with others at the same level.

mods, shortcut - Together, mods and shortcut form a keyboard shortcut which the user may use to activate a UI gadget in the translated geode. For instance, Ctrl-S typically activates the Save item of the File menu. This shortcut would be represented by

[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.

The following mods are available: A (Alt), S (Shift), C (Ctrl), and P ("Physical"--Num Lock and Caps Lock state is disregarded). These modifiers may be combined as in the Ctrl-S example.

The shortcut should be a single character. If this character is a letter, pay attention to its case--it should probably be a lower-case letter.

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.


top - 5.2 Translating Text: Translating With ResEdit

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.

Translating a Text String - 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.

  • The Minimum and Maximum Length fields show the size limits on the number of characters that the selected chunk may have.
  • The Instructions field shows special characteristics of the selected chunk, or may give a context where the specific chunk appears.

If there is nothing in these fields, there are no constraints on the size or content of the translation.

Changing a Mnemonic - 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.

Changing a Keyboard Shortcut - 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.

Translating a Graphic - 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:

  1. Copy the graphic to be translated--select the displayed graphic in ResEdit, and choose Copy from the Edit menu.
  2. Start up the GeoDraw graphics editor program, creating a new GeoDraw document if necessary.
  3. Paste the graphic into the GeoDraw document--choose Paste from GeoDraw's Edit menu.
  4. Edit the bitmap, being careful not to change the dimensions of the bitmap.
  5. When you are done editing the bitmap, select the bitmap with the arrow tool, and choose Copy from GeoDraw's Edit menu.
  6. Return to the ResEdit application, select the graphic to translate, and choose Paste from ResEdit's Paste menu.

Choosing a Chunk - 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.

  • Type Ctrl-> (Ctrl-reater) to move to the next resource or Ctrl-< (Ctrl-less) to move to the previous resource.
  • Click on Next Resource/Previous Resource in the Utilities menu.
  • Click on the Resource pop-up list in the upper left corner of the screen and choose any resource.

Within a resource, there are several ways to select a chunk to edit.

  • Use the mouse to click on any chunk.
  • Type Ctrl-.(Ctrl-period) to move to the next chunk or Ctrl-, (Ctrl-comma) to move to the previous chunk.
  • Click on Next Chunk or Previous Chunk in the Utilities menu.
  • Click on the Chunk pop-up list in the upper left corner of the screen and choose any chunk.

top - 6 Creating a Translated Geode

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.


top - 7 Updating an Executable

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.


top - 8 Testing the Translated Geode

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.


top - 9 Resource Editor Menus

The quick overview of the menu items below should give you the necessary information to use all of the features.

File Menu Edit Menu Project Menu Filter Menu Utilities Menu Window Menu


top - 9.1 Resource Editor Menus: File Menu

New/Open - Brings up the New/Open dialog box, allowing you to create a new Translation File, open an existing one, or import an ASCII Translation File.

Close - Closes the active Translation File.

Save - Saves the active Translation File.

Save As - Saves the active Translation File under a different name.

Backup - Makes a backup of the active Translation File or restores from a backup file.

Other

Copy To - Creates a copy of the Translation File and places it in the directory of your choice.

Move To - Moves the Translation File to the directory of your choice.

Export Document - Creates an ASCII Translation File. See Translating Via an ASCII File for details.

Discard Changes - Discards all changes since last saved version of the Translation File.

Rename - Gives the Translation File a new name.

Edit Document Notes - Edits the notes for the Translation File.

Set Document Password - Creates a document password.

Set Document Type - Allows the user to choose between a normal, read-only, or public document.

New Name and User Notes - Allows user to change geode name and make annotations to the file for later reference.

Create a New Executable - Takes the Translation File, merges it with the source geode, creates a new translated geode, and puts the translated geode in the Destination directory.

Update

Update Geode Name - Use this to warn ResEdit that the name of the original-language geode has changed. (Otherwise, ResEdit will not be able to find the original-language geode.)

Update Translation File - Using a new or updated geode, matches chunks in the old file with those in the new file, creating an updated Translation File which shows new or changed chunks and groups deleted chunks at the end.

Commit the Update - Deletes intermediate matching information, deleting those chunks which have been marked for deletion, showing only the newest version of the Translation File.

Print - Allows you to print out a report of the Translation File to paper. You must have configured your printer if this is to work.

Exit - Exits the Resource Editor.


top - 9.2 Resource Editor Menus: Edit Menu

Cut - Takes highlighted information and moves it to the clipboard.

Copy - Takes highlighted information and copies it to the clipboard, leaving a copy in place.

Paste - Pastes information from the clipboard to the location of the cursor.

Undo - Reverts to previous saved version of individual chunk.

Find and Replace - Allows user to search for designated words throughout the Translation File and replace text in the Translation File (as displayed in the right view) with local language translation. You can limit a forward or backward search by selecting filters for certain types of chunks from the Filters menu.


top - 9.3 Resource Editor Menus: Project Menu

The items in this menu keep track of how your project is organized.

Source directory - Set the top level directory holding source geodes.

Destination directory - Set the top level directory holding modified geodes.

Reset Source Geode Path - Reset the path of the source geode if it moves to a different subdirectory.


top - 9.4 Resource Editor Menus: Filter Menu

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.

Don't show Text:p - If this filter is on, ResEdit won't display any text monikers or other text chunks.

Don't show Monikers - If this filter is on, ResEdit won't display any monikers, whether graphic or text.

Don't show GStrings - If this filter is on, ResEdit won't display any graphic strings. This will filter out graphic monikers.

Don't show Bitmaps - If this filter is on, ResEdit won't display any bitmap graphics. This will filter out most graphic monikers, since most of these are simple graphics strings displaying it maps.

Don't show Objects - ResEdit will normally display the keyboard shortcuts associated with an object so that you may change the shortcut. If this filter is on, then ResEdit won't try to display the objects, and thus no keyboard shortcuts will appear.

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-- hoose the selected item to un-select it.

Show changed chunks

Show new chunks

Show deleted chunks


top - 9.5 Resource Editor Menus: Utilities Menu

The first four of these menu items allow for quick movement between chunks and resources:

Next Chunk

Previous Chunk

Next Resource

Previous Resource

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):

Word Count


top - 9.6 Resource Editor Menus: Window Menu

These menu items make manipulation of multiple Translation Files easy, by opening overlapping windows or tiling active windows.

Overlapping - Choose this item to allow Translation File windows to overlap. This is probably only useful if you are working with more than one such file at a time.

Full-Sized - Force each Translation File to take up all of Resource Editor's document display area.

Tile - If you're working with multiple Translation Files, this will lay them out side by side.
 

Zum Anfang der Seite     Mit Edith zuletzt bearbeitet am 02.02.24 / ... & Mütze