@database CatEdit @$VER: CatEdit.guide 38.16 (17.9.93) @(C) Rafael D'Halleweyn @author Rafael D'Halleweyn @index index @node main "CatEdit 1.0" @prev main @next main @{b}CatEdit 1.0@{ub} ============= CatEdit is Copyright © 1993 @{"Rafael D'Halleweyn" link author}. All rights reserved. @{" Introduction " link introduction} @{" Requirements " link requirements} @{" Starting " link starting} @{" Menus " link menus} @{" Gadgets " link gadgets} @{" Localization " link localization} @{" Translating a catalog " link translating} @{" Copyright notice " link copyright} @{" History " link history} CatEdit was written by @{"Rafael D'Halleweyn" link author}. Thanks go to Nico François who had the original idea and also made some suggestions. You offer infrared instead of sun You offer paperspoons and bubblegum Prefab Sprout @endnode @node introduction "Introduction" @prev introduction @{b}@{u}Introduction@{ub}@{uu} One of the major updates of Workbench 2.1 was it's ability to run the Workbench or any other program (that is @{"localized" link localized}) in different languages. This way, even if a program isn't translated in your native language, there is always a language that you understand. Now there is CatEdit, a program that allows you to translate @{"localized" link localized} programs in any language that the Amiga supports. Currently the Amiga supports 9 languages: -Dansk -Deutsch -Español -Français -Italiano -Nederlands -Norsk -Português -Svenska [Other languages are also possible but you'll have to make your own '.language' file.] With CatEdit it is also possible to remove those little (or big) errors in the translation of a program or translate @{"strings" link string} into other @{"strings" link string} that you prefer. You can even change Workbench @{"strings" link string}. Unlike the Commodore CatComp program, you don't need the original @{"catalog description" link cd} to translate a @{"catalog" link catalog}, all you need is a @{"catalog" link catalog} (it doesn't matter which language, as long as you can understand it). But CatEdit can also read @{"catalog descriptions" link cd}, it can even write @{"catalog descriptions" link cd}. @endnode @node requirements "Requirements to run CatEdit" @{b}@{u}Requirements@{ub}@{uu} CatEdit requires Workbench 2.1 or higher (locale.library and iffparse.library version 38 or higher) and ReqTools version 38 or higher (© Nico François). Don't forget: you also need an Amiga!! @endnode @node starting "Starting CatEdit" @{b}@{u}Starting CatEdit@{ub}@{uu} CatEdit can be started from the Shell or the Workbench. To start CatEdit from the Workbench you have to double-click its icon (the worldmap). Via Tool Types (use the 'Information...' menu item from the 'Icons' menu of the Workbench) you can set four arguments: CATALOG - filename of @{"catalog" link catalog} to be loaded; DESCRIPTION - filename of the @{"catalog description" link cd} (.cd) to be loaded; TRANSLATION - filename of the @{"catalog translation" link ct} (.ct) to be loaded (works only if a description is also loaded, otherwise it is ignored); PUBLICSCREEN - name of the public screen to open on (case sensitive). You can also start CatEdit from the Workbench with a Project icon. When you set the Default Tool (use the 'Information...' menu item from the 'Icons' menu of the Workbench) of the icon to CatEdit, CatEdit will also be started. To start CatEdit from the Shell you have to enter 'CatEdit' in a Shell window. The template is: CatEdit CATALOG/K,CD=DESCRIPTION/K,CT=TRANSLATION/K,PS=PUBLICSCREEN/K The arguments have, of course, the same meaning as the tooltypes with the same name. The CatEdit catalogs should be placed in the 'CatEdit/' subdirectory of the directory where CatEdit resides in or in the 'LOCALE:Catalogs/' directory. @endnode @node menus "CatEdit Menus" @next gadgets @{b}@{u}Menus@{ub}@{uu} Since you are able to use CatEdit in different languages, I've made a graphical representation of the menus so that you are still able to find information about a menu item that has another name in the language that you are using. Project Edit Extras @{"Open... " link open} @{"Paste Original " link pasteoriginal} Read @{"Catalog Description..." link readcd} @{"Merge... " link merge} ------------------- @{"Catalog Translation..." link readct} @{"Save As..." link saveas} @{"Change Language..." link changelanguage} Write @{"Catalog Description..." link writecd} ----------- @{"Catalog Translation..." link writect} @{"Info... " link info} @{"About... " link about} ----------- @{"Quit " link quit} @endnode @node open "CatEdit Menus: Project/Open..." @prev open @toc menus @{b}Open...@{ub} Read a @{"catalog" link catalog} from disk into memory. The filerequester will open in the 'LOCALE:Catalogs' directory if no @{"catalog" link catalog} was specified as a shell argument or Workbench tooltype. CatEdit can also read @{"catalogs" link catalog} that contain no language or version information. Version and revision will then be initialized to 1.1. If the loaded @{"catalog" link catalog} has been changed you will be asked if you want to save that @{"catalog" link catalog} before opening another one. @endnode @node merge "CatEdit Menus: Projects/Merge..." @toc menus @{b}Merge...@{ub} Merge @{"catalog" link catalog} from disk with catalog in memory. This is very handy if a @{"catalog" link catalog} doesn't contain a certain @{"string" link string}: you first open the @{"catalog" link catalog} you want to translate, you then merge a @{"catalog" link catalog} in another language, but for the same program, that does contain the @{"string" link string}. Before merging begins you will be asked if you want @{"strings" link string} that are in both catalogs to replace the original, the new, both or no @{"string(s)" link string}. If loaded @{"catalog" link catalog} and the @{"catalog" link catalog} to merge with don't have the same name or if the versions aren't the same CatEdit will display a requester saying that the @{"catalogs" link catalog} or not compatible, you can then choose to ignore the warning or cancel the merging. @endnode @node saveas "CatEdit Menus: Projects/Save As..." @toc menus @{b}Save As...@{ub} Write a @{"catalog" link catalog} to disk. If the @{"catalog" link catalog} already exists you will be asked if you want to overwrite that @{"catalog" link catalog} (overwriting that @{"catalog" link catalog} will mean that you loose all the translations in that @{"catalog" link catalog}, be careful). Before the @{"catalog" link catalog} is written the revision and the date of the catalog are updated. If the @{"catalog" link catalog} is still in memory because a program was using it and if you are using locale.library version 38 (Workbench 2.1, 3.0), CatEdit will try to flush the @{"catalog" link catalog} from memory. If CatEdit doesn't flush the @{"catalog" link catalog} then programs using that @{"catalog" link catalog} will still be using the old @{"strings" link string}, because they are still in memory. Technical note: the catalog is flushed by trying to flush the locale.library from memory, but since it can't flush (CatEdit is still using it) it will only remove all the catalogs from memory. Since I'm not sure if this will also work with newer versions of the locale.library the flush will only happen with locale.library version 38. @endnode @node info "CatEdit Menus: Projects/Info..." @toc menus @{b}Info...@{ub} Gives information about currently loaded @{"catalog" link catalog}: name of the catalog, version and revision, date, language of the catalog, number of @{"strings" link string} in the catalog and 'more'. 'More' is the text that is placed after the date in the version string of the catalog, this can for example contain the name of the author of the catalog (i.e. by Rafael D'Halleweyn); @endnode @node about "CatEdit Menus: Projects/About..." @toc menus @{b}About...@{ub} Gives version information about CatEdit. It also gives information about the translation of CatEdit. @endnode @node quit "CatEdit Menus: Projects/Quit" @toc menus @{b}Quit@{ub} Quit CatEdit. Note that the default Quit shortcut (i.e. 'Q') is not usable when a @{"catalog" link catalog} is loaded, because the @{"string gadget" link stringgadget} is always active and RightAmiga-Q means undo to a string gadget. If the loaded @{"catalog" link catalog} has been changed you are asked if you want to save the @{"catalog" link catalog} before quitting. @endnode @node pasteoriginal "CatEdit Menus: Edit/Paste Original" @toc menus @{b}Paste Original@{ub} Replace the translated @{"string" link string} with the original @{"string" link string}. While working with a @{"catalog" link catalog} CatEdit always keeps two representations of a @{"string" link string} in memory: the original @{"string" link string} (as it was loaded) and the new (i.e. translated) @{"string" link string}. @endnode @node changelanguage "CatEdit Menus: Edit/Change Language..." @toc menus @{b}Change Language...@{ub} Change the language of a @{"catalog" link catalog}. A requester will be displayed where you can replace the language with the new language. If the language is changed, the path of the file requester will also be changed, for example if you change from 'english' to 'nederlands' and the path was 'LOCALE:Catalogs/english/Sys' then the path will be changed to 'LOCALE:Catalogs/nederlands/Sys'. @endnode @node readcd "CatEdit Menus: Extras/Read/Catalog Description..." @toc menus @{b}Read Catalog Description...@{ub} Read a @{"catalog description" link cd} into memory. If there is already a @{"catalog" link catalog} loaded the @{"catalogs" link catalog} will be merged, the @{"catalog description" link cd} will overwrite the original @{"string" link string} and the string name. If there is no @{"catalog" link catalog} loaded, the @{"catalog description" link cd} will fill both the original and the new @{"string" link string}, the string names will also be read. While reading the @{"catalog description" link cd}, the validity of the string names will be checked and the @{"string" link string} length will be compared against the minimum and maximum string length described in the catalog description. If something is wrong a requester will be displayed giving the type of error and its position in the @{"catalog description" link cd} file. @endnode @node readct "CatEdit Menus: Extras/Read/Catalog Translation..." @toc menus @{b}Read Catalog Translation...@{ub} Read a @{"catalog translation" link ct} into memory. You'll only be able to read a @{"catalog translation" link ct} if you have already read a @{"catalog description" link cd}. When a certain string name can not be found a requester will be displayed, you can then choose to ignore that @{"string" link string} or stop reading. While reading the @{"catalog translation" link ct}, the validity of the string names will be checked and the @{"string" link string} length will be compared against the minimum and maximum string length described in the @{"catalog description" link cd}. The @{"% commands" link procentcommand} will also be compared against the @{"% commands" link procentcommand} of the original strings. If something is wrong a requester will be displayed giving the type of error and its position in the @{"catalog translation" link ct} file, after which the rest of the @{"catalog translation" link ct} will be read @endnode @node writecd "CatEdit Menus: Extras/Write/Catalog Description..." @toc menus @{b}Write Catalog Description...@{ub} Write a @{"catalog description" link cd} to disk. To be able to write a @{"catalog description" link cd}, CatEdit has to now the names of the @{"strings" link string}, if CatEdit doesn't now the names a requester will appear asking you if you want CatEdit to generate these names. These names will probably differ from the names in the original @{"catalog description" link cd} that was used to generate the @{"catalog" link catalog}. If the file you selected already exists, a requester will appear saying that the file already exists, you can then choose to overwrite the old file. @{i}WARNING: @{ui}a @{"catalog translation" link ct} can't be used to recreate a @{"catalog" link catalog}, so make sure that you also have a @{"catalog description" link cd} otherwise the @{"catalog translation" link ct} will be worthless. @endnode @node writect "CatEdit Menus: Extras/Write/Catalog Translation..." @toc menus @next writect @{b}Write Catalog Translation...@{ub} Write a @{"catalog translation" link ct} to disk. To be able to write a @{"catalog translation" link cd}, CatEdit has to now the names of the @{"strings" link string}, if CatEdit doesn't now the names a requester will appear asking you if you want CatEdit to generate these names. These names will probably differ from the names in the original @{"catalog translation" link cd} that was used to generate the @{"catalog" link catalog}. If the file you selected already exists, a requester will appear saying that the file already exists, you can then choose to overwrite the old file. The @{"catalog translation" link cd} will contain language and version information. The strings placed in the @{"catalog translation" link cd} are the new (e.g. translated) strings. @{i}WARNING: @{ui}a @{"catalog translation" link ct} can't be used to recreate a @{"catalog" link catalog}, so make sure that you also have a @{"catalog description" link cd} otherwise the @{"catalog translation" link ct} will be worthless. @endnode @node gadgets "CatEdit Gadgets" @prev menus @next localization @{b}@{u}Gadgets@{ub}@{uu} The main CatEdit window contains four gadgets: two listviews, one string gadget and one cycle gadget: ·@{"string listview" link stringlistview} (the upper listview) contains all the @{"strings" link string} in @{"catalog" link catalog} and is used to select a @{"string" link string} to edit; ·@{"string gadget" link stringgadget} is used to edit the selected @{"string" link string}; ·@{"show cyclegadget" link showcycle} selects the @{"string" link string} that you can see in the @{"show listview" link showlistview}; ·@{"show listview" link showlistview} (the lower listview) gives a representation of the selected @{"string" link string}. @endnode @node stringlistview "CatEdit Gadgets: String listview" @toc gadgets @prev stringlistview @{b}String listview@{ub} The string listview is a list of all the @{"strings" link string} that are in a @{"catalog" link catalog}. The new @{"string" link string} will always be displayed in that list. You can scroll through the list with the scroll bar or the up and down arrow-gadgets. You can also scroll with the arrow keys on the keyboard: up and down will select the previous resp. next @{"string" link string}. If you press the arrow keys together with the shift key the listview will scroll one view at a time, together with the ctrl key the listview will scroll to the first or the last @{"string" link string}. (Scrolling might not work optimal under Kickstart 2.04.) Whenever you select a @{"string" link string} from the list with the mouse, the @{"string" link string} will automatically be placed in the @{"string gadget" link stringgadget}. When no @{"catalog" link catalog} is loaded the string listview will be ghosted (listview doesn't ghost under Kickstart 2.04). @endnode @node stringgadget "CatEdit Gadgets: String gadget" @toc gadgets @{b}String gadget@{ub} The string gadget always contains the currently selected @{"string" link string} and is always active. With the string gadget you can edit the new @{"string" link string}. When you set the @{"show cyclegadget" link showcycle} to original you can always see the original (untranslated) @{"string" link string}. You can then use RightAmiga X to make the string gadget empty, so that you can enter the new @{"string" link string}. When you press return the @{"string listview" link stringlistview} and possibly the @{"show listview" link showlistview} will be updated. If you forget to press return before you select a new @{"string" link string} your changes will be lost! While entering a @{"string" link string}, CatEdit will check that you don't enter an invalid hexadecimal number with '\x'. The screen will flash if you do and the key press won't be accepted. When you press return the @{"strings" link string} length will be compared against the minimum and maximum string length (CatEdit will only now the minimum and maximum length if you loaded the catalog from a @{"catalog description" link cd}), if the length is to short or to long, a requester will warn you about it. When you press return the new and original @{"string" link string} will be compared to see if they contain the same @{"% commands" link procentcommand}, if not, a requester will warn you. When no @{"catalog" link catalog} is loaded the string gadget will be ghosted. @endnode @node showcycle "CatEdit Gadgets: Show cyclegadget" @toc gadgets @{b}Show cyclegadget@{ub} With the show cyclegadget you can choose the @{"string" link string} that is displayed in the @{"show listview" link showlistview}. CatEdit always keeps two representations of a @{"string" link string} in memory: the original @{"string" link string} (as it was loaded) and the new (i.e. translated) @{"string" link string}. To cycle the show cyclegadget you can use the its shortcut: use RightAmiga plus the underlined character (when using the built-in strings, the shortcut is RightAmiga S). When no @{"catalog" link catalog} is loaded the show cyclegadget will be ghosted. @endnode @node showlistview "CatEdit Gadgets: Show listview" @toc gadgets @next showlistview @{b}Show listview@{ub} The show listview gives a WYSIWYG (What You See Is What You Get) view of the currently selected @{"string" link string}. Newlines, formfeeds, vertical tabs and '\0' force a newline. This is more or less the way that the string will look like when used by its program. With the @{"show cyclegadget" link showcycle} you can select the @{"string" link string} to view: the original or the new @{"string" link string}. If the show listview contains more lines then it can display, you can scroll with the scroll bar or the up and down gadgets. You can also scroll the show listview with the keyboard: alt down scrolls the listview down, alt up scrolls the listview up (keyboard scrolling of the show listview doesn't work under Kickstart 2.04). @endnode @node localization "Localizing CatEdit" @prev gadgets @{b}@{u}Localization@{ub}@{uu} CatEdit is localized, this means that you can translate CatEdit in any language that the Amiga supports. The built-in CatEdit language is english and currently there is only a dutch (nederlands) translation. If you want you can translate CatEdit in your own language. To do that you should -of course- use CatEdit. When you double-click the 'TranslateCatEdit' icon the CatEdit @{"strings" link string} will automatically be loaded, ready to be translated. When translating CatEdit make sure that every shortcut (menus and gadget) is unique. @endnode @node translating "CatEdit: Translating a catalog" @{b}@{u}Translating a catalog@{ub}@{uu} When translating a catalog there are a few rules that you should stick to: When you are picking the shortcuts for gadgets and menus, make sure that they are unique, don't use the same key twice. A good program will automatically use this new shortcut when the @{"string" link string} is changed. Gadget shortcuts are usually preceded by an underscore '_' (e.g. '_Cancel') and menu shortcuts precede the menu text followed by a nil character (e.g. 'Q\0Quit'). The standard way to indicate that you don't want a shortcut is to not place an underscore in the gadget text or place a space ' ' in the menu text (e.g. ' \0Quit'). Always make sure that the original string and the new string contain the same number and type of @{"% commands" link procentcommand}. CatEdit will automatically checks this. Sometimes the @{"string" link string} contains some sort of control sequence (hexadecimal numbers (\xXX) or escape sequences (starting with \e or \c)), it's best to leave them unchanged. Since @{"catalogs" link catalog} don't contain information about minimum and maximum width, you should be careful not to use to short or to long @{"strings" link string}. Don't take advantage of @{"catalogs" link catalog} containing the programs copyright notice to change the copyright notice. @endnode @node copyright "CatEdit Copyright" @{b}@{u}Copyright@{ub}@{uu} CatEdit is Copyright © 1993 @{"Rafael D'Halleweyn" link author}. CatEdit may be freely distributed if: ·no more then a reasonable fee is charged for copying or down-loading; ·no file in this distribution is changed; ·the distribution is complete (at the end of this chapter there is a list of all files in this archive); ·the distribution is not part of a commercial product. I repeat: no commercial usage allowed. The idea is, that if some person is making money with this program that that person should be me. Although CatEdit has been thoroughly tested, no guarantee is given nor implied that this program is fit for any use. The program and the information within this text is provided on an "as is" basis. In no event will I be liable for any direct, indirect, incidental, or consequential damages resulting from the use of this program or the information presented within this text. Inclusion of CatEdit in other freely distributable software is allowed, under the above stated restrictions, but the documentation has to state that CatEdit is copyright Rafael D'Halleweyn. Commercial distribution of CatEdit or of a package containing CatEdit requires @{"my" link author} approval. List of all files in the distribution: Catalogs (dir) nederlands (dir) catedit.catalog catedit.cd nederlands.ct libs (dir) reqtools.library CatEdit CatEdit.guide CatEdit.guide.info CatEdit.info Install Install.info TranslateCatEdit.info @endnode @node history "CatEdit history" @next history @{b}@{u}History@{ub}@{uu} ·release 1.0 [38.890 (17.9.93)] -first release. @endnode @node author "About the Author" @prev author @next author CatEdit was written by @{b}Rafael D'Halleweyn@{ub}. If you have any questions, remarks, suggestions or bug reports please let me know. You can contact me via normal mail (sorry still no e-mail): Rafael D'Halleweyn Perckhoevelaan 17 B-2610 Antwerpen BELGIUM CatEdit is Copyright © Rafael D'Halleweyn. @endnode @node catalog "CatEdit: Catalogs" @prev catalog @{i}Catalogs @{ui} Catalogs are files that contain all the translated strings. They are normally placed in the 'LOCALE:Catalogs/' drawer or in the 'PROGDIR:Catalogs/' drawer ('PROGDIR:' is the directory where the program using the catalog resides). These catalogs are very hard to change by hand, that's where CatEdit comes in. The normal way to make a catalog is with the 'CatComp' program from Commodore, but then you'll need a @{"catalog description" link cd} and a @{"catalog translation" link ct}. @endnode @node cd "CatEdit: Catalog Descriptions" @{i}Catalog Descriptions (.cd) @{ui} A catalog description is a normal text file that describes a @{"catalog" link catalog}. It contains every string that a program uses (in the original language) and the minimum and maximum width for that string. The catalog description also contains a name for every string, this name should only contain uppercase alphanumeric characters and underscores (0...9A...B_). @endnode @node ct "CatEdit: Catalog Translations" @next ct @{i}Catalog Translations (.ct) @{ui} A catalog translation is a normal text file that describes the translation of a @{"catalog" link catalog} in a certain language. Within a catalog translation the @{"strings" link string} are identified by there names, these names should only contain uppercase alphanumeric characters and underscores (0...9A...B_). @{i}WARNING: @{ui}a catalog translation can't be used to recreate a @{"catalog" link catalog}, so make sure that you also have a @{"catalog description" link cd} otherwise the catalog translation will be worthless. @endnode @node localized "CatEdit: Localized" @prev localized @next localized @{i}Localized @{ui} For a program to be able to work in different languages it has to be localized. That means that it has to look for it strings in the right @{"catalog" link catalog}, e.g. the @{"catalog" link catalog} that describe the strings in the language that you selected with the Locale preference editor. @endnode @node string "CatEdit: String" @prev string @next string @{i}String @{ui} A @{"catalog" link catalog} contains all the strings that a program uses. CatEdit always keeps two representations of a string in memory: the original (untranslated) string and the new (translated) string. In CatEdit, strings can contain several control codes: @{b}\a@{ub} ASCII 7 (audiable bell) @{b}\b@{ub} ASCII 8 (backspace) @{b}\c@{ub} ASCII 155 (CSI) @{b}\e@{ub} ASCII 27 (ESC) @{b}\f@{ub} ASCII 12 (formfeed) @{b}\n@{ub} ASCII 10 (newline) @{b}\r@{ub} ASCII 13 (carriage return) @{b}\t@{ub} ASCII 9 (tab) @{b}\v@{ub} ASCII 11 (vertical tab) @{b}\0@{ub} ASCII 0 @{b}\x@{ub}XX XX is a hexadecimal number The @{b}\o@{ub}OOO control code, to enter octal numbers, is not supported. @endnode @node procentcommand "CatEdit: % Commands" @prev procentcommand @next procentcommand @{i}% Commands@{ui} Often % commands are used in strings to replace numbers or names that change during the execution of the program. The format of the % commands that CatEdit recognizes is: %[arg_pos$][flags][width][.limit][length]type arg_pos ordinal position of the argument for this command; $ must follow the arg_pos value, if specified; flags only one allowed: '-' specifies left justification; width field width, if the first character is a '0', the field is padded with leading 0s; . must precede the field limit value, if specified; limit maximum number of characters to output from a string (only valid for %s or %b); length size of input data, can be a 'l'; type recognized types are: b BSTR, d signed decimal, D signed decimal using the locale's formatting conventions, u unsigned decimal, U unsigned decimal using the locale's formatting conventions, x hexadecimal with hex digits in uppercase, X hexadecimal with hex digits in lowercase, s string and c character (the right brackets mean that that part is optional) You can use the arg_pos to change the position of the arguments, for example if the original @{"string" link string} was '%ld chickens and %ld eggs' you could change it to '%2$ld eggs and %1$ld chickens' and the information would still be correct. CatEdit always checks to see if the original and new @{"string" link string} contain the same number and type of % commands. @endnode @node index "CatEdit Index" @prev index @next index @{i}Index @{ui} @{b}A@{ub} @{"About..." link about} @{"author" link author} @{b}C@{ub} @{"catalog" link catalog} @{"catalog description" link cd} @{"catalog translation" link ct} @{"Change Language..." link changelanguage} @{"copyright" link copyright} @{b}G@{ub} @{"gadgets" link gadgets} @{b}H@{ub} @{"history" link history} @{b}I@{ub} @{"Info..." link info} @{"introduction" link introduction} @{"localization" link localization} @{"localized" link localized} @{b}M@{ub} @{"menus" link menus} @{"Merge..." link merge} @{b}O@{ub} @{"Open..." link open} @{b}P@{ub} @{"Paste Original" link pasteoriginal} @{"procent commands" link procentcommand} @{b}Q@{ub} @{"Quit" link quit} @{b}R@{ub} @{"Read Catalog Description..." link readcd} @{"Read Catalog Translation..." link readct} @{"Requirements" link requirements} @{b}S@{ub} @{"Save As..." link saveas} @{"Show cyclegadget" link showcycle} @{"Show listview" link showlistview} @{"starting" link starting} @{"string" link string} @{"String gadget" link stringgadget} @{"String listview" link stringlistview} @{b}T@{ub} @{"Translating" link translating} @{b}W@{ub} @{"Write Catalog Description..." link writecd} @{"Write Catalog Translation..." link writect} @endnode