Appendix C.  Internationalizing KEYpak Messages

This appendix describes how to internationalize KEYpak messages to a language of your choice.  These messages include warning/error messages, system names, character names, configuration labels, and configuration values. 

                        Note        You cannot internationalize the KEYpak command line or User Interface to a language of your choice.

To generate KEYpak messages in a language of your choice, you will require the following two files:

 

KEYpak Message File (<lang>.txt)

This is the text file representing all KEYpak messages in a language of your choice.  (<lang> can be any name such as French, German, Spanish, English, etc.). 

Your installation includes the English message file stddoc.txt in the main KEYpak directory.  You can use any text editor to modify the existing message file or create a new one. 

Binary Message File (<lang>.msg)

This is the binary representation of the language file <lang>.txt.  KEYpak uses the binary file to generate messages during its conversion process.  This binary file is created by compiling the text file <lang>.txt with the program msgcnv.  (See Compiling New Messages at the end of this appendix). 

For your use, the file default.msg is included with your installation.  By default, KEYpak will use this file to generate messages in English. 

The following documentation describes in detail how to modify the existing message file or create a new one so that messages appear in a language of your choice.

Creating/Modifying KEYpak Message File

A KEYpak message file (<lang>.txt) is made up of 5 basic sections.  Each section must begin with a Section Header and must end with a Section Trailer.  The following types of Section Headers are currently supported.

 

$MESSAGE                  Warning/Error Messages

$CHRNAME                 Extended Character Names

$SYSNAME                  System Names

$CONFLAB                 Configuration Labels

$TOGGLE                     Toggle Values

Each of the sections must end with the Section Trailer   $END.

 

The existing message file stddoc.txt contains warning/error messages, character names, and system names in English text form.  This file does not currently contain configuration labels or toggle values; however, you can edit this file to include the configuration information.

$MESSAGE

All warning/error messages may be internationalized.  These messages are provided to you, in text format, in the stddoc.txt file.  Every message is assigned a unique identifying number which is used by the KEYpak conversion program.  Do not change these message numbers. 

 

These messages can be subdivided by message number into the following types of messages:

 

Type                                               Message number range

 

Source Messages                        10,000 to 19,999

Target Messages                         20,000 to 29,999

KEYpak Host Messages             30,000 to 32,767

 

 

The basic format for KEYpak messages is:

 

<id number> = “<message>” ;<comment>

<id number>                 is a number ranging from 10,000 to 32767.  DO NOT change this value at any time.

 

<message>                    is the body of the message.  The actual message must be written within double quotes.  This message may be internationalized to a language of your choice.  The order and sequence of the variable names within the message may be changed, but you must not remove or add variable names to a message.

 

<comment>                   is any comment you want to add about the entry for documentation purposes.  This value may be internationalized to a language of your choice.

 

 ;                                      is a comment delimiter.  It must precede the comment.  Anything that appears after the semicolon will be ignored.  It is assumed that any line beginning with a semicolon is a comment line.

 

 

A standard KEYpak ASCII message may contain special variables within itself.  These character combinations are replacement variables used by KEYpak at run time.  These variables are listed below:

 

%n           System name                        For example, WordPerfect.  KEYpak generally looks up this name in a table.

 

%i            Integer value                        Any number 0 through 32767.

 

%s           ASCII string                        A string can be any list of characters such as “Control Xv”.

 

%t            Toggle value                         Toggle value defines a number of possible options such as, ‘HEADER,FOOTER,FOOTNOTE’.  The KEYpak program will select one of these possible toggle options and insert it into the message. 

Toggle options must follow their respective “%t”, and must be delimited by single quotes (‘).  Toggle values may be internationalized to a language of your choice, but the listed order of the toggle values must not change.

 

%c           Alternate character            An alternate character name which is used to label or identify a specific character.

 

 

The variables %i, %c, %s, and %t must be prefixed by a number.  For example, %2i.  This number allows for greater flexibility since more than one of each variable type may exist within one message.

 

 

                        Note        You can change only a variable’s (%n, %i, %s, %t, %c ) location within a message.  Do not remove or add variables to a message.

The following page provides an extract of the messages listed in the file stddoc.txt.  Note the following important points in the format of these messages:

 

       All Message ID numbers are left justified.

       All comments are preceded by a semicolon.

       A backslash (\) continues all messages which are greater than one line length to the next line. (See message number 11020).

       The listed order of the toggle values must not be changed.  (See message number 20040).

       Empty braces (‘{}’) represent a null value.  If this is one of the toggle options, no text will be printed for that toggle value.

 

 

Extract of KEYpak Messages

$MESSAGE
;
;*+         STANDARD SOURCE WARNINGS ;
;
10000 = “%n: Document contains library definitions; Document not translated”
10010 = “%n: Document contains merge list commands; Document not translated”
10080 = “%n:  Improperly aligned tab; Space inserted Pg.%1i  Ln.%2i”

10110 = “%n: Page insert; Ignored Pg.%1i Ln.%2i”
10120 = “%n: Ribbon color change; Ignored Pg.%1i Ln.%2i”
;
;/*+        NON STANDARD SOURCE WARNINGS
;
11000 = “%n: Alternate paper tray command; Ignored Pg.%1i Ln.%2i”
11010 = “%n: Blank merge fields used; May be incorrect”
11020 = “%n: Character %3i unsupported; %4t‘Encoded,Ignored,Marked’            \

 
Pg.%1i Ln.%2i”
11180 = “%n: Get next merge record; Ignored Pg.%1i  Ln.%2i”

;
;/*+        STANDARD TARGET WARNINGS
;
20010 = “%n: Backspaces not supported; %3i discarded,Marked Pg.%1i  Ln.%2i”
20040 = “%n: Character ‘%3c’ unsupported; %4t‘Marked,Deleted,Replaced’       \
  Pg.%1i Ln.%2i”
20150 = “%n: Document exceeds %3t‘page,size’ limit; Document split Pg.%1i      \
  Ln.%2i”
;
;/*+        NON STANDARD TARGET WARNINGS
;
21005 = “%n: Backspace not followed by printable character;                                 \
  Marked Pg.%1i Ln.%2i”
21120 = “%n:  Footnote document (%1s) created”

21480 = “%n: Text exceeds form %3t‘width,length’; Printed on separate         \
  sheets Pg.%1i Ln.%2i”
21490 = “%n: Unable to %3t‘subscript,superscript’ when %4t                           \
  ‘subscripting, superscripting,underlining’; Ignored Pg.%1i Ln.%2i”

$END

 

 

The following examples provide description for some of the messages.

              Example 1        10080 = “%n:  Improperly aligned tab; Space inserted Pg.%1i Ln.%2i”

 

10080            is the id number of the message.

%n                 is the variable for the system name.

%1i               is the page number.

%2i               is the line number.

 

 

If the system is Microsoft Word (PC) and there is an improperly aligned tab on line 23 of page 5 in the source document, the above message will print as:

MS Word: Improperly aligned tab; Space inserted Pg.5 Ln.23

This message can be changed so that the order of page and line numbers is reversed.  For example:

 

10080 = “%n:  Improperly aligned tab; Space inserted  Ln. %2i Pg. %1i”

 

will print as:

 

MS Word: Improperly aligned tab; Space inserted Ln.23 Pg.5

              Example 2        11180 = “%n: Get next merge record; Ignored Pg.%1i Ln.%2i”

 

11180            is the id number of the message.

%n                 is the system name.

%1i               is the page number.

%2i               is the line number.

 

 

If the system is Word Perfect and the merge record function is on line 23 of page 5, the message will print as:

 

WordPerfect: Get next merge record; Ignored Pg.5 Ln.23

              Example 3        21120 = “%n:  Footnote document (%1s) created”

 

21120            is the id number of the message.

%n                 is the system name.

%1s               is the name of the footnote file created.

 

 

If the system is MultiMate and the footnote file is footnote.txt, the following message will be printed:

 

MultiMate:  Footnote document (footnote.txt) created

              Example 4        20040 = “%n:  character ‘%3c’; %4t‘Marked, Deleted, Replaced’ Pg.%1i Ln.%2i”

 

20040            is the id number of the message.

%n                 is the system name.

%1i               is the page number.

%2i               is the line number.

%3c               is the extended or alternate character name.

%4t               is a toggle selection of Marked, Deleted or Replaced.

 

 

If the system is WordStar and the alternate character pi is not supported but is marked in the text, the following message will be printed:

 

WordStar:  character ‘pi’; Marked Pg.5 Ln.23

$CHRNAME

KEYpak supports an extended character set of several hundred characters.  Every character has a name and a unique identification number by which KEYpak references it.  For detailed information on the KEYpak character set, refer to chapter 8 of the KEYpak ODX Conversion Reference Guide.

 

The KEYpak character set contains the name, number, and description of each character supported by KEYpak.  Every character is identified by means of a unique identification number.  Do not change this number.  Both the character name and character description are completely modifiable.

 

The basic format for the definition of a character is:

 

<id number> = “<character name>” ; <comment>

<id number>                         is a number ranging from 1 to 423.  DO NOT change this value at any time.

 

<character name>               is the name of the character.  The character name must be entered within double quotes following the equal (=) sign.  This value may be internationalized to a language of your choice.

 

<comment>                           is any comment you want to add about the entry for documentation purposes.  This description may be internationalized to a language of your choice.

 

;                                               is a comment delimiter.  It must precede the comment.  Anything that appears after the semicolon will be ignored.  It is assumed that any line beginning with a semicolon is a comment line.

 

 

The following page provides an extract of some of the character codes listed in the file stddoc.txt.  Note the following important points in the format of these characters:

 

       All character ID numbers are left justified, and followed by a space, an equal sign (=), and another space.

       All comments are preceded by a semicolon.  These comments may be internationalized.

       All character names are enclosed within double quotes.  These names may be internationalized.

Extract of KEYpak Character Set

$CHRNAME
;
          1 = “space”                ; PREFIX 0, MEMBER 032 ;
          2 = “exclamation !”  ; PREFIX 0, MEMBER 033 ;
          3 = “quote, double” ; PREFIX 0, MEMBER 034 ;
          4 = “number sign #” ; PREFIX 0, MEMBER 035 ;
          5 = “dollar sign $”   ; PREFIX 0, MEMBER 036 ;
     112 = “acute”                ; PREFIX 1, MEMBER 016 ;
     113 = “A acute”             ; PREFIX 1, MEMBER 017 ;
     114 = “a acute”             ; PREFIX 1, MEMBER 018 ;
     115 = “E acute”             ; PREFIX 1, MEMBER 019 ;
     174 = “u umlaut”          ; PREFIX 1, MEMBER 078 ;
     389 = “face”                   ; PREFIX 2, MEMBER 037 ;
     390 = “face, solid”        ; PREFIX 2, MEMBER 038 ;
     391 = “female”               ; PREFIX 2, MEMBER 039 ;
     392 = “male”                  ; PREFIX 2, MEMBER 040 ;
     393 = “music note”       ; PREFIX 2, MEMBER 041 ;
;
$END

 

The comments in the character set extract refer to the internal organization of the KEYpak character set.  Internally the characters are organized into three subgroups and assigned numbers within those subgroups.

 

PREFIX 0       Contains all ASCII characters

PREFIX 1       Contains all alternate or special characters

PREFIX 2       Contains characters that are used for line drawings

 

 

These comments are provided only for information and do not affect the process of internationalization.  When the character set is being internationalized to a language of your choice, only the character name needs to be changed.

 

 

                 Example        174 = “u umlaut”

174                 is the identification number of the character.

u umlaut        is the character name.  This name can be internationalized.

 

 

$SYSNAME

Each format supported by KEYpak is assigned a unique system identification number.  KEYpak references each format through these system numbers.  (Do not change system identification numbers).  $SYSNAME allows you to change and internationalize the names and descriptions of conversion formats.

 

The basic format for $SYSNAME is:

 

<id number> = “<name>” ; <comment>

<id number>                 is a unique system ID number.

 

<name>                          is the name of the system.  The system name must be entered within double quotes.  It can be internationalized to a language of your choice.

 

<comment>                   is any comment you want to add about the entry for documentation purposes.  It can be internationalized to a language of your choice.

 

;                                       is a comment delimiter.  It must precede the comment.  Anything that appears after the semicolon will be ignored.  It is assumed that any line beginning with a semicolon is a comment line.

 

 

The following page provides a list of the system codes listed in the file stddoc.txt.  Note the following important points in the format of these system numbers:

 

       All system identification numbers are left justified, and followed by a space, an equal sign (=), and another space.

       All character names must be enclosed within double quotes.  These names may be internationalized.

       For your convenience, this table includes the mnemonic of each system as a comment.  The actual list in the file stddoc.txt does not specify these mnemonics.  You may find it useful to include the mnemonics as comments during the process of internationalization.

 

 

                 Example        221 = “WordMARC”

221                         is the system identification number.

WordMARC         is the current name of the system.

 

To refer to WordMARC as PRIMEWORD, this entry should be changed to:

 

221 = “PRIMEWORD”

Extract of KEYpak System Names

$SYSNAME
;
204 = “MultiMate”                                ; MM
209 = “MS Word”                                   ; MW
210 = “WP 4.2”                                       ; WP
211 = “WordStar”                                  ; WS
212 = “DisplayWrite”                            ; IP
213 = “OfficeWriter”                              ; OW
215= “Lotus AMI Professional”          ; AMI
218 = “Mass11”                                     ; M1
219 = “Q-One”                                        ; Q1
221 = “WordMARC”                              ; WM
223 = “IBM DCA-RFT”                         ; DC
224 = “DECdx”                                      ; DX
227 = “Wang PC”                                  ; WC
228 = “WangWPS”                                 ; WF
230 = “Xerox 860”                                 ; XF
231 = “NBI Async”                                 ; NA
232 = “WITA”                                          ; WT
235 = “WordERA”                                  ; WE
236 = “MS Word(Mac)”                       ; MA
238 = “IBM DCA-FFT”                         ; IF
240 = “CT DEF”                                     ; CD
241 = “CPT-CF”                                    ; PF
242 = “DSA101”                                    ; D1
301 = “ASCII”                                         ; AF
302 = “COM.FILE”                                ; CF
304 = “Line Printer”                             ; LP
315 = “Picture Conversion                  ; PIC
$END                                                        

 

 

$CONFLAB

This section header identifies the configuration labels that are used by KEYpak.  The file stddoc.txt, does not currently contain information on $CONFLAB.  During internationalization this information may be added as required.

 

Each $CONFLAB entry links an internationalized configuration label with its original English label.  Once this has been done, the configuration can be referenced through its internationalized label.

 

The basic format for $CONFLAB is:

 

“<Internationalized label>”= “<English label>”

              Example 1        “Genre de document”  =  “Document type”

Genre de document      is the French configuration label.

Document type             is the standard KEYpak English label.

 

 

              Example 2        “Empreinte de marge”  =  “Print margin”

Empreinte de marge     is the French configuration label.

Print margin                   is the standard KEYpak English label.

 

 

              Example 3        “Centrage”  =  “Centering”

Centrage                        is the French configuration label.

Centering                       is the standard KEYpak English label.

 

 

$TOGGLE

$TOGGLE identifies the toggle values associated with each configuration.  See source/target reference files (xxsrc.doc/xxtrg.doc) for toggle values available for configurations with each conversion format.  Each $TOGGLE entry links an internationalized toggle label with its original English label.  Once this has been done, the required toggle values can be referenced through their internationalized labels.

 

Internationalization of configurations and their associated toggle values requires the two sections of the configuration to be defined separately from each other.  Thus all configurations are defined under the section $CONFLAB, and all associated toggle values are defined under the section $TOGGLE.  Each section must be concluded with a $END.

 

The basic format for $TOGGLE is:

 

“<Internationalized toggle>”= “<English toggle>”

              Example 1        “OUI”  =  “YES”

OUI                                         is the French toggle label for “YES”.

YES                                         is the standard KEYpak English toggle value.

 

 

              Example 2        Extraire  =  “EXTRACT”

Extraire                            is the French toggle label.for “EXTRACT”.

EXTRACT                             is the standard KEYpak English value.

 

 

              Example 3        Avec des espaces  =  “WITH SPACES”

Avec des espaces          is the French toggle label.for “WITH SPACES”.

WITH SPACES                    is the standard KEYpak English value.

 

 

The following example describes the use of $CONFLAB and $TOGGLE.  Note the following important points in their format:

 

       All configuration names and toggle values must be enclosed within double quotes.  These values may be internationalized.

       Note the separation of the configuration parameter from its associated toggle values by the section headers $CONFLAB and $TOGGLE.

       All configuration parameters must be defined together under a single $CONFLAB section.

       All toggle values must be defined together under a single $TOGGLE section.

                 Example        Internationalized Configurations

$CONFLAB
;
“Genre de document” = “Document type”
“Empreinte de marge” = “Print margin”
“Centrage” = “Centering”
$END
;
;
$TOGGLE
;
“OUI” = “YES”
“EXTRAIRE” = “EXTRACT”
“AVEC DES ESPACES” = “WITH SPACES”
$END

 

 

Compiling KEYpak Message File

After you have internationalized your text file for messages, it is necessary to compile these messages into the binary format.  Use msgcnv, the KEYpak compiler, to produce a binary message file.   

 

The basic format for compiling a message file is:

 

msgcnv <text file> <binary file>

                      Notes               The KEYpak compiler msgcnv is installed at the time of installation in the “library directory”.

                                               All binary message file names must have the “.msg” extension, but do not specify this extension on the command line (see Example 2).

              Example 1        Use the following command to create the default binary message file from the standard message file:

msgcnv stddoc.txt  default.msg

This default.msg file will be used in all cases where a language message file is not specified.

 

 

              Example 2        Use the following command to create the binary message file french.msg from the French message file french.txt:

msgcnv french.txt  french.msg

If you want to make French message file as the default, rename or copy french.msg to default.msg.

 

To use the new French file french.msg with KEYpak, enter the following command:

 

kw -smw -taf -Lfrench srcfile trgfile