T.O.C.

Intro

QuickStart

Basics

Databases

Glossaries

Advanced

Scripting


 

TEXT ITEM OPTIONS

PowerGlot provides advanced options for developers and localizers. Each text item in the database can be independantly commented, locked and have its status changed. The current version of PowerGlot does not use the item status while localizing; status is provided as a convenience feature only, to help localizers track the actual state of their translation work.

To access the item options window, double-click on the desired text item in the list. The options window then opens.

 

 

The first three captions in the window give information about the file the item comes from (useful if you have included several files in your database), the resource type, ID and name, the last modification date, a free comments zone (maximum 255 characters) and the item status.

 

LOCKING AND UNLOCKING ITEMS

For specific needs, you can lock a text item in a database. For example, one may have some strings in resources that describe driver or file names that should not be translated. A way to prevent unwanted translation of those terms is to lock them.

You can lock an item by selecting it in the text items list, then go to the Edit menu and select Lock/Unlock item(s). This menu item switches the locked state of the current item, thus setting it or resetting it. Note that you can select multiple items to lock/unlock by shift-clicking or command-clicking in the list to extend the selection (standard Macintosh user interface).

 

 

You can also lock or unlock an item from the item options window, by clicking in the Status pop-up menu and selecting the appropriate status for the item (Locked/Unlocked). To access the item options window, double-click the item.

A locked item has the following behavior: you can view the source text contents, but when you selected the item, the ÔTranslationÕ text field can not be modified. Also, when applying a glossary to the database for automatic pre-translation, locked items are ignored by PowerGlot.

 

COMMENTING ITEMS

You can add comments to items in the comments text field located in the item options window. To access the item options window, double-click the item in the text items list. You can then enter text in the Comments field. If there is any text in the comments field, a comment mark appears for this item in the leftmost column of the text items list.

 

 

Adding comment notes to items is the best way to remind localizers about specific issues regarding the commented items. You can for example inform them of a specific use for a given text string (ÔThis string should not exceed 10 charsÕ) or explain in a few word the context in which this item is used.

Remember that the more hints you give to localizers, the better translation you get. You can this way avoid misinterpretation of the use of specific text items in you software.

 

 

ADVANCED FILE OPERATIONS

Solving complex problems related to software localization can be done fairly easily with PowerGlot, provided that you are aware of all the available mechanisms. It is not always easy to explain a need you have in the area of software localization, but it is very easy to think that your problem can not be solved. DonÕt think it. PowerGlot has been carefully designed to let you handle a range of constraints when localizing your software, saving you lots of time and efforts.

 

SYNCHRONIZING FILES

A critical feature of PowerGlot is its ability to keep synchronization between a database you created and modifications you have done to the original files after database creation. For example, you could have built a database for localization of the final version of your software, but it appeared afterwards that you forgot to add a caption with version numbers, or any other information that was missing in the development builds of your software. This is not a problem. Through the synchronization process, PowerGlot can merge the new items in the database, while keeping the translations already made.

Synchronization is a fairly straightforward process: select the Synchronize files item from the database menu, and thatÕs all. PowerGlot reads the original files, finds all changes that have been made to the text in your files (added/deleted text strings, new resources, deleted resources, and so on). All translations that have been done for unchanged items will be kept. All text present in the previous version of your files but which has disappeared from the new version will be removed from the database.

Note that when you have PowerGlot generate the localized file, it always synchronizes first with the original files to ensure it has correct information about your files structure.

There is only one drawback at this time in PowerGlotÕs synchronization process: to be able to restore the translation for a given text item, the original text must not have changed at all. That is, if you added a comma to a static text in a dialog, and this text had already been translated, the translation will disappear. This drawback may disappear in future releases of PowerGlot.

PowerGlot expects to find the original files on your disk when it synchronizes. As it internally keeps aliases to the files, PowerGlot is able to find them even if they have been moved or renamed. If it can not locate the files, it will present you with a file selector box, asking you to locate each file that could not be found on any mounted volume. If you click the Cancel button for one of these file, the entire operation is aborted (but your database is left untouched).

In case the name of the file has changed, you may want to update to the new file (see below).

 

UPDATING TO NEW WORK FILES

It often happens that the localization process starts when a project reaches alpha stage. This means that you have to start evaluating the amount of work to do, prepare glossaries and maybe do draft translations to be sure everything is alright.

This means that at some point in time, developers will provide you with a new release of their software. Switching to a new release while keeping all the translations you have already done is very easy with PowerGlot. Select the Work Files item from the Database menu, then click on the name of the file to update. PowerGlot will prompt you for the name of the new file in a file selector dialog box: select the new file, then click the Open button. PowerGlot will switch to the new file and perform a synchronize operation to restore your translations in the new version of the file, then youÕre done!

USING PREVIOUSLY LOCALIZED VERSIONS

When switching to PowerGlot, you may encounter a typical problem: recover from the translations already done with AppleGlot or any other tool you use for software localization, or keeping up with the work already done on previous versions of your software. It would be absurd to lose all the work done on the localization of version 1.0 of your software when translating version 2.0. All these cases can be handled with PowerGlot.

The thing to do is to plan the way you are going to recover. All the required tools are built into PowerGlot. Here are a few typical cases:

 

LOCALIZING INTO MODIFIED FILES

It can happen that you have very specific modifications to do on your files for a given localization. For example, as German usually takes up much more space than English, you could have to widen your buttons and static texts in dialogs. But perhaps do you want to do this only for the German version, not all versions. Also, when localizing to a right-to-left script system like Arabic, you could need to change your itemsÕ alignment in windows.

Because of these problems, you donÕt want to generate the localized files from the original files because if you do this, you have to modify the files after the localization process, and if for any reason you need to rebuild the localized files you have to start your changes all over again.

To address this issue, PowerGlot offers a very specific functionality: the ability to localize an already modified version of the original files. This means that you can make any non-structural change to a copy of the original files (even by changing the text in captions to test for width) and have PowerGlot localize this file instead of starting from the original copy.

For example, suppose you have to translate our old friend SimpleText to German, but you notice after localization that a button is not wide enough to enclose all the text it contains. You can just open the freshly built German version, change the width of the button, and thatÕs it. But if afterwards you notice that you mistranslated a term and correct it in the database, you can use the into modified files item of the Generate localized files submenu from the Database menu.

 

 

PowerGlot then displays the window below:

 

 

Select the SimpleText file in the list, double-click it of click the Select file to localize into... button. PowerGlot asks you to select the file to work with. Select the previously built German version of SimpleText, the one that you have modified, then click the Localize button in the window above. PowerGlot then directly retranslates all text in the modified version of SimpleText. You donÕt need to worry if the version is already localized or text has changed, because PowerGlot does not need this information to find the text to localize. Instead, in relies on the position of each text item in resources, which means that you should not add or delete text from the localized version.

 

 

DETAILS ABOUT THE INTERNAL OF FILE LOCALIZATION

At this point, you should be skilled enough with PowerGlot to want to understand how it works when building the localized versions of your files.

 

It is especially important to remember that PowerGlot does not keep the complete contents of resources in the database. It keeps the text if finds (source text), the translation you entered, and information about where the text is located (resource ID, position in the resource).

Positions are not kept as absolute offsets from the beginning of the resource, but as something more general called an Ôobject indexÕ. That is, in a ÔSTR#Õ resource for example, the text at object index number 3 if the third string in the string list. In an alert or dialog box, the object index is the number of the item in the window. For each resource type, the most efficient and secure method was chosen to represent the object index.

This explains why, in the previous chapter, you were advised not to change the structure of the localized file if you wanted to be able to localize again into it. Otherwise, you could get unexpected placement of translated text (in place of other text).

 

PowerGlot keeps aliases to the files you added to a database. You can safely move and even rename the original files, PowerGlot will find them on your disk. But if at one point in time it does not find an original file, it will present you a file selector box and ask you to locate the missing file. Note that, after a database is created, the only time PowerGlot needs to have the original files at hand is when synchronizing or generating localized files from the original files. This allows you to give a database to someone who does not have a copy of the original files: the person can work on the database, but not generate the final result.

 

 

LIST OF TEXT CONTAINERS

Here is a complete list of the text containers that can appear in the Text container pop-up menu in the database window, along with the resource types that are grouped under each container name.

 

Text containers list

Alerts & dialogs

ÔALRTÕ, ÔDLOGÕ, ÔDITLÕ, ÔCNTLÕ

Menus

ÔMENUÕ

PowerPlant windows

ÔPPobÔ

Resources by template

all other resources

Strings & string lists

ÔSTR Õ, ÔSTR#Õ

Text blocks

ÔTEXTÕ

Window titles

ÔWINDÕ

 

Note that the Resources by template container shows all types of resources that are not in the other containers. This is because PowerGlot has built-in parsers for the standard and most common resource types (this also allows it do give a special appearance to a text container, for example the menus), and all other resource types are read through templates (explained below).

You should also be aware of the fact that some resource types may be mapped to another resource type through ÔRMAPÕ resources (see below), thus placing this resource not in the Resources by template container, but in some other container. A good example for this is the ÔFCMTÕ type which maps to ÔSTR Õ, so ÔFCMTÕ resources may appear in the Strings & string lists container.

 

RESOURCE SYNONYMS (RMAP)

Sometimes, different resource types share a common format. For example, ÔaeteÕ (Apple Event TErminology) and ÔaeutÕ (Apple Event User Terminology) have the same structure. To avoid duplicating the ÔaeutÕ template, the Templates & RMAPs file that comes with PowerGlot has a ÔRMAPÕ resource named ÔaeteÕ, which says ÔaeteÕ resources map to ÔaeutÕ resources. This behavior was originally supported by Apple ComputerÕs ResEdit, and works the same way. In fact, if you want to add synonyms you can add ÔRMAPÕ resources to the Templates & RMAPs file or put them in the files you add to the databases.

The content of an ÔRMAPÕ resource is very simple. Here are the rules:

 

TEMPLATES: READING ALL RESOURCES

PowerGlot can read any kind of resource using resource templates. These template are special resources describing the format of other resources. They originated in ResEdit from Apple Computer, then were extended in Resorcerer(tm), a commercial resource editor from Mathemaesthetics. Resorcerer templates are much more powerful than ResEditÕs, and mostly upward compatible. If you want to learn more about templates and the way they work, you should refer to the Resorcerer Technical Manual which gives an exhaustive definition of Resorcerer templates, and the way you can create them.

 

TEMPLATES AND POWERGLOT

PowerGlot recognizes nearly all the Resorcerer templates keywords. There are a few exceptions, listed in Appendix A.

PowerGlot comes with a very small number of predefined templates. These templates describe the following resources: ÔversÕ (version information), ÔFREFÕ (Finder reference), ÔkindÕ (finder document kind).

Due to licensing issues, it was not possible to ship PowerGlot with the whole set of templates you can find in Resorcerer (tm). If you need templates for AppleEvents, Balloon Help or other specific data, you should ask the developers of the application you are translating to provide you with the appropriate templates. You should then copy these templates to the (Templates) subfolder in the PowerGlot folder.

This folder is scanned when PowerGlot starts up. If you have some resource in your files that are in a private format, but that contain text that should be localizable, you must include the appropriate ÔTMPLÕ resources in the file. When adding a file to a database, PowerGlot first scans its ÔTMPLÕ resources to determine which additional resource types can be recognized, and appropriately extracts the text from the resources.

 

ADDING NEW TEMPLATES

While parsing a resource file, PowerGlot looks for ÔTMPLÕ resources in it to obtain additional templates for private resources.

To make some templates permanent, you can also copy one or more resource files containing templates in the (Templates) folder (located in PowerGlot applicationÕs folder). These templates are read when PowerGlot starts and are used to parse all resource files added to databases.

 

ADDITIONAL TEMPLATES FEATURES

There is one extension to templates supported by the software.

In some cases, you may want that a text string in a template be not extracted by PowerGlot. To do this, you can prefix the name of the text string in ResEdit or Resorcer with Ô##Õ. When PowerGlot encounters a template field which is a text string but whose names begins with this special sequence, the text string is not extracted. This feature can be of great help to people having custom templates with strings that are not language dependant (for example, driver names).

THE RIGHT WAY TO KEEP UP WITH ITEM SIZES

A common problem with localization is the change that occur in visual item sizes (alert and dialog boxes, and also PowerPlant windows). This problem is solved in PowerGlot by a special feature which reads item coordinates from the original files and allow you to change the coordinates in the localized version of the files (see the Database Settings paragraph of this manual).

But changing all coordinates by hand can be tedious and error-prone. The best way to go is the following:

  1. Do your translations in the database
  2. Generate a localized version of your files
  3. Open your files with ResEdit (for dialog & alerts) or Metrowerks Constructor (for PowerPlant window) and resize the items as needed.
  4. Choose Merge localized files in the Database menu, then double-click each file in your database and associate it with the localized version youÕve just modified.
  5. Click the Merge button. PowerGlot then reads the localized files, match the translations (fetching all changes youÕve done with other tools) and also fetching the new coordinates for each item.
  6. Now your database includes information about the new item positions and sizes.