Inside Macintosh: Apple Guide Complete / Part 2 - Building Guide Files

Chapter 7 - Localizing Your Guide File

Translating Text Strings

When you extract text from source files, Guide Maker stores each text string as a resource of type 'TEXT' and gives it a descriptive resource name (so that you can determine the origin of the text string) and a unique resource ID. For example, a text string that specifies an index term has the resource name <Index> and has a unique resource ID to distinugish it from other resources with the same resource name. Table 7-1 beginning on page 7-10 lists all of the possible resource names and gives a description of the text string contents you can expect to be associated with it.

Figure 7-3 and Figure 7-4 show examples (from the SurfWriter Guide source files) of various text resources that Guide Maker extracts. Figure 7-3 shows the ResEdit window of text resources associated with setup information (such as prompt sets and Help menu information), topic areas, and sequences.

Figure 7-3 Examples of text resources

Figure 7-4 shows the ResEdit window of text resources associated with panels, index terms, and Look For content.

Figure 7-4 Text resources for panels, index terms, and Look For content

To begin translating text, follow these steps.

1. Open one of your .RSRC files using a resource editor (such as ResEdit).

   ResEdit displays the resource ID, size, and resource name of each text string in a window (see Figure 7-4).

2. Select the text string to translate.

   ResEdit opens a window containing the text that needs translation. Translate the text and then close the window. Repeat this process for all text strings.

   Figure 7-5 shows a ResEdit window for a text resource as it appears before and after the text is translated. This example shows the text string of the text resource with resource ID 1015 and resource name "Panel: AddWords2". The string represents panel text, in this case, the tag "Do This", which is translated to "Sådan".

Figure 7-5 Translating a text string

1. Save the .RSRC file containing the translated text strings.

   Repeat steps 1 through 3 for all of your .RSRC files.

Table 7-1 lists the typical 'TEXT' resource names (in alphabetical order) and gives a description of the associated text strings.

The 'TEXT' resource names and the associated text strings

Text resource name	Description of the associated text string
<Balloon Menu Text>	Specifies the text for the help balloon associated with your guide file's menu item name in your application's Help menu.
<Checkbox>	Specifies a label for a checkbox.
<Define Context Check>	Specifies an additional parameter in a context check and indicates a text string of type LPSTRING. The text string specifies a default value. You must translate this text string to match the corresponding default value as it exists in the localized application.
<Define Item Coach>	Specifies the item that is highlighted by a coachmark. You should translate the text string to match the corresponding item as it exists in the localized application.
<Define Menu Coach>	Specifies the menu name or menu item that is highlighted by a coachmark. You should translate the text string to match the corresponding menu name or menu item as it exists in the localized application. The text resource file does not list the menu name and its menu items in consecutive order.
<Define Prompt Set>	Specifies a navigation prompt that appears on the bottom of a panel. A prompt set consists of four navigation prompts; Guide Maker creates a text resource for each of these prompts.
<Define Sequence>	Specifies a sequence display title. This text appears in the title bars of all panels of the sequence.
<Define Window Coach>	Specifies a window in which a coachmark is drawn. You should translate the text string to match the corresponding window name as it exists in the localized application.
<Exception>	Specifies a word that should not be stemmed when Apple Guide parses a search phrase. To get a complete list of all exception words, create a Scopes and Keys report, as described in the chapter "Testing Your Guide File." Apple Guide performs stemming and uses the exception list only for guide files that specify the command <World Script> 0,0. Thus, when translating to other languages, you do not need to translate exception words. So you should delete <Exception> commands from your localized source files.
<Header>	Specifies a header associated with a particular topic area or index term. This text appears in the right column of the access window.
<Help Menu>	Specifies the name of a guide file or the Command key shortcut. Guide Maker creates a text resource for the guide file name and one for the Command key shortcut. The guide file name and its shortcut are displayed in the Help menu.
<Hot Text>	Specifies hot text in a panel. You should translate this text string to match the corresponding text string as it appears in the localized panel.
<If>	Specifies text (with data type LPSTRING) that is part of a condition. If the condition statement contains more than one LPSTRING, Guide Maker creates a text resource for each one. If the condition is part of a compound condition statement, Guide Maker creates one text resource for each LPSTRING in the compound condition. In some cases, the text string specifies a label of a radio button or checkbox. You must translate this text string to match the corresponding text string as it exists in the localized application.
<Ignore>	Specifies a word or phrase that Apple Guide ignores when parsing a search phrase. To get a list of these words and phrases, create a Scopes and Keys report, as described in the chapter "Testing Your Guide File."
<Index>	Specifies an index term. The index term appears in the left column when Index is the active list.
<Look For Instruction>	Specifies an instruction that appears above the search phrase entry box in the Full Access window when Look For is the active list.
<Look For Results Instruction>	Specifies an instruction that appears above the list of topics in the Full Access window when Look For is the active list and the user has performed a successful search.
<Look For Search Btn Instruction>	Specifies an instruction that appears above the Search button in the Full Access window when Look For is the active list.
<Look For String>	Specifies text that appears in the search phrase entry box in the Full Access window when Look For is the active list.
<Make Sure>	Specifies text (with data type LPSTRING) that is part of a condition. The evaluated condition determines whether the next panel should be displayed. If the condition statement contains more than one LPSTRING, Guide Maker creates a text resource for each of these. If the condition is part of a compound condition statement, Guide Maker creates one text resource for each LPSTRING in the compound condition. In some cases, the text string specifies a label of a radio button or checkbox. You must translate this text string to match the corresponding one as it exists in the localized application.
Panel: panel name	Specifies the body text to be displayed in the panel specified by the panel name. If the text in the panel is divided into multiple pieces (for example, the text is split between a picture, a QuickTime movie, or a button, or the text uses more than one format), Guide Maker creates a text resource for each of the text parts. The created text resources have identical text resource names but different resource IDs.
<Radio Button>	Specifies a label for a radio button.
<Skip If>	Specifies text (with data type LPSTRING) that is part of a condition. The evaluated condition determines whether the next panel should be displayed. If the condition statement contains more than one LPSTRING, Guide Maker creates a text resource for each of these. If the condition is part of a compound condition statement, Guide Maker creates one text resource for each LPSTRING in the compound condition. In some cases, the text string specifies a label of a radio button or checkbox. You must translate this text string to match the corresponding text string as it exists in the localized application.
<Standard Button>	Specifies a label for a standard button.
<Synonym> index term, synonymous term	Specifies a synonymous term for the index term specified in the text resource name. If an index term has more than one synonym, Guide Maker creates a text resource for each of these. Note that the text resource file does not group an index term and its synonyms together (unless they're grouped together in the source file). To get a complete list of all index terms and their synonyms, create a Scopes and Keys report, as described in the chapter "Testing Your Guide File."
Text Block: text block name	Specifies a block of text. This block of text typically appears in the body text of a howdy window.
<Topic>	Specifies a topic. This text string appears in the right column of the access window.
<Topic Area>	Specifies a topic area. This text appears in the left column of the Topics screen in the access window. Note that you are limited to 31 one-byte characters.
<Topic Areas Instruction>	Specifies an instruction or a label. This text appears above the list of topic areas in the Full Access window when Topics is the active list.
<Topics Instructions>	Specifies an instruction that appears above the list of topics in the Full Access window when Topics or Index is the active list.
<Version>	Specifies version information for the guide file. Guide Maker creates a text resource for both the long and short version information strings.