home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / coders / c2local / c2local.doc < prev    next >
Text File  |  1977-12-31  |  17KB  |  457 lines
  1.  
  2.  
  3.                              C2Local V1.0
  4.                              ============
  5.  
  6.                       © 1994-95 by Matthias Meixner
  7.  
  8.  
  9.  
  10.                               Copyright
  11.                               ---------
  12.  
  13. C2Local, CComp, CTMerge, StrMerge (C) Copyright 1994-95 by Matthias Meixner.
  14. All rights reserved.
  15.  
  16. For legal issues read the readme file.
  17.  
  18.  
  19.  
  20.                            Background
  21.                            ----------
  22. From version 2.1 of the Amiga operatingsystem on, it is possible to generate
  23. programs that support more than one language. One language is compiled into
  24. the program and the other languages are stored in the so called catalogs.
  25. The operatingsystem determines the language on runtime and loads the corres-
  26. ponding catalog. If you want to write a program that supports catalogs, you
  27. must replace all strings by a localizeable version, since the strings are not
  28. the same in all languages. The goal of C2Local was to allow the programmer to
  29. continue programming in the old way, using normal strings, since such source-
  30. code is more readable, and then automatically generate a localized version of
  31. this program. C2Local allows this for nearly all C and C++ sourcecodes. Pro-
  32. grams like CatComp generate sourcecode to access localized strings, but the
  33. programmer must adapt his program by hand. "Localize" is able to patch source-
  34. codes to support locale.library, but it leaves many cases, which cannot be
  35. automatically localized, e.g. the static initialization of structures. Now
  36. C2Local can even localize most of these cases. There is only one exception:
  37. the static initialization of char-arrays.
  38.  
  39. e.g.
  40.  
  41.    char a[]="test";
  42.  
  43. cannot be localized automatically, but the more important case
  44.  
  45.    char *a="test"
  46.  
  47. can be localized using C2Local. This latter case is far more often used, e.g.
  48. it is required for static initialization of menus. Therefore one can localize
  49. menus or gadgets without any problems using C2Local.
  50.  
  51.  
  52.  
  53.  
  54.                         System requirements
  55.                         -------------------
  56. The programs require at least OS2.0 (V37) as operatingsystem. The programs
  57. that were localized by c2local do not need another version of the operating-
  58. system than the original, but localization only takes effect from OS2.1 on.
  59.  
  60.  
  61.  
  62.  
  63.                               Programs
  64.                               --------
  65. This package contains the following programs:
  66.  
  67.    C2Local:    program for generating localized sourcecodes
  68.    CComp:      program for generating catalogs
  69.    CTMerge:    programm for mixing of catalog-translation files
  70.    StrMerge:   programm for mixing of stringfiles
  71.  
  72. They can be found in the "Bin" directory.
  73.  
  74.  
  75.  
  76.                              Installation
  77.                              ------------
  78. Just copy the C2Local-directory to the preferred location and add the
  79. Bin-directory to the searchpath. If you want to copy the programs to a
  80. different location, make sure that you do not forget to copy also the
  81. catalogs-directory to the same path, or the programs will not find their
  82. translated strings of the localization and will use the builtin english
  83. strings. This is also the case, if you are working with a version of the
  84. operating system, that does not support localization yet.
  85.  
  86.  
  87.  
  88.  
  89.                                 Usage
  90.                                 -----
  91.  
  92. C2Local Scan/S,Patch/S,Compile/S,Pattern/M,Ign=Ignore/K,Lab=Labels/K,
  93.         Cat=Catalog/K,Lang=Language/K,Ver=Version/N,Name/A/K
  94.  
  95. Name serves as a basename, all needed filenames are derived from this name.
  96.  
  97.  
  98. C2Local has three differend modes: Scan, Patch and Compile.
  99.  
  100. 'Scan' checks all files, whose name match the given pattern for strings and
  101. writes a stringfile <Name>_locale.str, which contains all strings of the
  102. program except those given in the file selected via the IGNORE option.
  103. The lines of this file have the following format:
  104.  
  105. <Label> <String> [<Size>]
  106.  
  107.                   ^^^^^^  This field is not generated in this stage, but it
  108.                           can be added using an editor. It is used in the
  109.                           compile pass to select a new maximum stringlength.
  110.  
  111. '+' at the end of a string indicates that the string is continuated in the
  112. next line, e.g.:
  113.  
  114. label "a string "+
  115.       "that needs two lines"
  116.  
  117. You can use IGNORE to supply a file, which contains strings that should not
  118. be localized. The file given by LABEL is used to assign specific labels to
  119. the strings. If no labels are given C2Local generates its own labels. These
  120. two files have the same structure mentioned above, although you can ommit
  121. the field <Label> in the file for IGNORE.
  122. Typically you would use 'Scan' to get a file containig all strings and edit
  123. this one to generate the ignore-file or the label-file. In the rare case
  124. that the selection of strings, that shall not be localized, is not exact
  125. enough, you may exclude them by writing '/*-' directly after the string
  126. without whitespace. E.g.:
  127.  
  128.        char *a="will not be localized"/*-*/;
  129.  
  130. Comments in stringfiles begin with '//' and mark the rest of the line as
  131. comment.
  132.  
  133.  
  134. 'Patch' does the same as 'Scan' in the first step, but additionally
  135. generates the localized sourcecode in the directory 'Localized'.
  136. IMPORTANT: You cannot edit <Name>_locale.str to get new labels or ignore
  137. certain strings, since it is overwritten by 'Patch', you have to use the
  138. IGNORE and LABEL options instead. If you already have a file that contains
  139. the strings, that shall not be localized, then you can ommit the 'Scan'
  140. pass.
  141.  
  142. 'Compile' generates from <Name>_locale.str, the following files:
  143.  
  144.    Localized/<Name>_locale.cd   catalog-description file
  145.    Localized/<Name>_locale.ct   empty catalog-translation file
  146.    Localized/<Name>_locale.h    headerfile, which is #included in every
  147.                                 patched sourcecodefile.
  148.    Localized/<Name>_locale.c    C-sourcecode which contains all builtin
  149.                                 strings and the function InitStrings();
  150.  
  151. 'Compile' requires the following options:
  152.    Catalog: this is the name of the catalog that shall be used.
  153.    Version: versionnumber of the catalog (IMPORTANT the versionnumber must
  154.             match exactly the one in the catalog, if it is not 0)
  155.             (default: 0)
  156.    Language: builtin language (default: english)
  157.  
  158. These values get hardcoded into InitStrings()!
  159. The function InitStrings() must be called within your program as early as
  160. possible (i.e. in main() ) to activate the localized strings. You can do
  161. this in the original sourcecode using the following method:
  162.  
  163.  
  164. #ifdef __LOCALIZED
  165.    InitStrings();
  166. #endif
  167.  
  168.  
  169. __LOCALIZED is defined in Localized/<Name>_locale.h. Since this file is
  170. included in the patched files, InitStrings() is automatically activated in
  171. the localized version of your program.
  172.  
  173.  
  174.  
  175.                            Localizing
  176.                            ----------
  177. Requirement for a successful localization of your program is, that you do
  178. not write to strings, because equal strings are only stored once in the
  179. program. If you would write to one string, then you would modify all
  180. instances of this string. If your program compiles using StringMerge of the
  181. SAS C-Compiler, then you should not get problems with this.
  182. BTW, that is exactly how the strings are localized by InitStrings(), they get
  183. overwritten by their translated versions.
  184.  
  185. Typically you would proceed in the following way to localize your program:
  186.  
  187. First you would want to get a list of all strings in your program:
  188.  
  189. C2Local SCAN #?.c #?.h NAME test
  190.  
  191. Then you delete all strings from test_locale.str, that should be localized
  192. and rename this file, that now contains all strings to be ignored by the
  193. localization, to ignore.str. Since you normally would not want to read the
  194. generated sourcecode, you need not worry about the labels.
  195.  
  196. Now you can generate the localized sourcecode:
  197.  
  198. C2Local PATCH #?.c #?.h NAME test IGNORE ignore.str
  199.  
  200. If you get the message, that the catalog-translation file was not newly
  201. generated, then delete or rename this file and repeat this step. This was
  202. implemented this way, that you do not accidently overwrite a translation of
  203. your program.
  204.  
  205. C2Local COMPILE NAME test VERSION 1 CATALOG test.catalog
  206.  
  207. generates the last missing files, and after this you can recompile your
  208. program:
  209.  
  210. cd Localized
  211. sc #?.c link  // e.g. for SAS-C
  212.  
  213. If you get errors, then there is one of the above mentioned exceptions in
  214. your program.
  215.  
  216. Now comes the part, that requires the most work: translate the strings :)
  217. First you should copy the catalog-translation file <Name>_locale.ct, to keep
  218. it for other translations, and fill in the translated strings in the copied
  219. file. The comments that begin with ';' contain the strings of the builtin
  220. language. One entry in this file looks like that:
  221.  
  222. Label
  223. deutscher String
  224. ; english string
  225. ;
  226.  
  227. IMPORTANT: You must not modify the comments, if you want to use CTMerge.
  228.  
  229. You can use the standard C escape-sequences plus some additional ones in
  230. the translation file (see table).
  231.  
  232. '\' at the end of a line indicates, that the string is continued in the next
  233. line.
  234.  
  235. Hint: Some editors remove trailing whitespaces from the end of the line. Then
  236.       you can add '\' to the end of the line after the whitespace and add an
  237.       empty line in the next line.
  238.  
  239. Comments begin whith ';' in the first column.
  240.  
  241. When you fill in your translations, you should not forget to add the language
  242. of this translation after '## language' and the versionnumber after
  243. '## version'. The versionnumber must be given as a standard versionstring.
  244.  
  245.  
  246. From this file you can generate the catalog-file:
  247.  
  248. CComp <name>_locale.cd translation.ct Catalogs/deutsch/test.catalog
  249.  
  250. If you get the errormessage, that a translated string is too long, then you
  251. can change the maximum length that is reserved for a string by editing the
  252. stringfile. Just add the required maximum length after the string
  253.  
  254. msg_0 "Teststring" 20
  255.  
  256. Default is twice the length of the builtin string. You can also use this to
  257. reduce the amount of reserved memory used for long strings, but remember,
  258. that translated strings can be significant longer.
  259.  
  260. If you have modified the stringfile in this case, then you need to repeat all
  261. steps from 'C2Local COMPILE' on (including 'Compile'). Don't forget that you
  262. have to recompile your program after this to activate the modifications.
  263.  
  264. IMPORTANT: The name of the catalog must be the same as that, that you have
  265. used in the 'Compile' pass of C2Local.
  266.  
  267. Instead of CComp you can also use CatComp, FlexCat, KitCat, MakeCat or one
  268. of the other catalog-tools.
  269.  
  270. That's it!
  271.  
  272.  
  273. If your Program does not use other languages even, if you selected it with
  274. preferences:
  275.  
  276. - is the catalog in the right directory ?
  277. - is the name of the catalog correct ?
  278. - is the version of the catalog correct ?
  279. - did you fill in the correct language in the .ct-file?
  280. - is there an old version of the catalog in memory (-> "avail flush") ?
  281. - did you call InitStrings() ?
  282.  
  283.  
  284.  
  285.                           How things work
  286.                           ---------------
  287. C2Local searches for all strings within the sourcecode and replaces them by
  288. a label which is a reference to this string. Every string is stored in
  289. a char-array. Therefore strings cannot be longer than a specific length and
  290. the other translations are limited by this length. The advantage of this is
  291. that they can be overwritten on startup and they do not change their
  292. address. InitStrings searches for the catalog and replaces the strings by
  293. simply overwriting them with their localized versions.
  294.  
  295. Since strings are stored in arrays, you cannot initialize other arrays with
  296. them. These are the above mentioned restrictions. However there are some
  297. workarounds for these cases. If the array is read-only, then it can be
  298. replaced by a pointer:
  299.  
  300.    char a[]="test";                -> char *a="test";
  301.  
  302. For local arrays:
  303.  
  304.    test() {                        ->  test() {
  305.       char a[10]="String";         ->     char a[10];
  306.    }                               ->     strcpy(a,"String");
  307.                                    ->  }
  308.  
  309. Global arrays must be initialized by hand.
  310.  
  311.    char a[10]="String";            ->  char a[10];
  312.                                    ->
  313.    main() {                        ->  main() {
  314.    }                               ->     strcpy(a,"String");
  315.                                    ->  }
  316.  
  317.  
  318. For static local arrays there are two ways:
  319. 1) Make it a global variable
  320.  
  321. 2)
  322.    test() {                        ->  test() {
  323.       static char a[10]="String";  ->     char a[10];
  324.    }                               ->     static int init=0;
  325.                                    ->     if(!init) {
  326.                                    ->        strcpy(a,"String");
  327.                                    ->        init=1;
  328.                                    ->     }
  329.                                    ->  }
  330.  
  331.  
  332.  
  333.                   The other programs in the package
  334.                   ---------------------------------
  335.  
  336. CComp Catalogdescription/A,Translation/A,Catalog/A
  337.  
  338. CComp generates catalog-files. It needs three parameters: A catalogdescrip-
  339. tion-file (.cd), the catalogtranslation (.ct) and the name of the catalog
  340. that should be generated.
  341.  
  342.  
  343. CTMerge From/A,Merge/A/M,To/K/A
  344.  
  345. CTMerge takes the catalogtranslation-file 'From', replaces the translations
  346. with the ones found in the 'Merge' files and writes the result to 'To'.
  347. 'From' and 'To' must be different files! CTMerge uses the comment-lines to
  348. find already known translations. Labelnames are not changed. This is very
  349. useful, if you modify existing programs, since you need not translate the
  350. texts, that have not changed. You cannot directly use the old translation-
  351. file if you have used labels, that were automatically generated, since they
  352. may have changed. That's why you must use CTMerge for this purpose, if you
  353. do not want to retranslate all texts.
  354.  
  355.  
  356. StrMerge From/A,Merge/A/M,To/K/A
  357.  
  358. StrMerge merges size-fields in stringfiles. One can assign new max-lengths
  359. for strings by editing the file <name>_locale.str before calling c2local
  360. with the 'Compile' option. But this file is destroyed by every call to
  361. c2local with 'Scan' or 'Patch'. With StrMerge you can copy the edited file
  362. and merge it to the file <name>_locale.str after every 'Scan'- or 'Patch'-
  363. run. 'From' and 'To' may be the same filename.
  364.  
  365.  
  366.  
  367.                  Additional information for the file-formats
  368.                  -------------------------------------------
  369. Suffix:  Description:
  370.  
  371. .cd      'Catalog Description'-file
  372.  
  373.          It contains the number, ID and the original text and the length-
  374.          restrictions for the translations.
  375.  
  376.          E.g.         Text1_STR (22/7/80)
  377.                       Hallo Leute, ein deutscher String !
  378.  
  379.          string no. 22, minimal length: 7, maximal length: 80
  380.          These values are optional, (//) would be valid.
  381.          Comment-lines begin with ';'.
  382.          '\' means that the line is continued in the next line.
  383.          Escape-codes: see table
  384.  
  385. .ct:     'Catalog Translation'-file
  386.  
  387.          It contains the translation in a specific language
  388.  
  389.          E.g.:     Text1_STR
  390.                    C'est français !
  391.                    ; Hallo Leute, ein deutscher String !
  392.  
  393.          The header contains some additional informations:
  394.  
  395.          ## version $VER: name.catalog ver.rev (10.09.92)
  396.          ## language français
  397.  
  398.          Comment-lines begin with ';'.
  399.          You should not delete comment-lines, since CTMerge requires them to
  400.          identify translations.
  401.          '\' means that the line is continued in the next line.
  402.          Escape-codes: see table
  403.  
  404.  
  405. .str     Stringfile
  406.  
  407.          It contains the strings:
  408.  
  409.          <Label> <String> [<Size>]
  410.  
  411.          E.g.:     msg_0 "String" 10
  412.  
  413.          Strings may span over several lines:
  414.  
  415.          E.G.:     msg_0 "Str"+
  416.                          "ing"
  417.  
  418.          <Label> is optional for ignore-files or for files that are merged
  419.          to another file using StrMerge. <Size> is always optional,
  420.          (default: 2*length of the string).
  421.  
  422.  
  423.  
  424.                         Table of escape-codes
  425.                         ---------------------
  426.  
  427.   \a    Beep            (ASCII 7)
  428.   \b    Backspace       (ASCII 8)
  429.   \c    Control Sequence Introducer CSI (ASCII 155)
  430.   \e    ESC             (ASCII 27)
  431.   \f    Formfeed        (ASCII 12)
  432.   \n    Newline         (ASCII 10)
  433.   \r    Carriage Return (ASCII 13)
  434.   \t    Tab             (ASCII 9)
  435.   \v    Vertical Tab    (ASCII 11)
  436.   \xNN  ASCII-Code NN (Hexadezimal)
  437.   \NNN  ASCII-Code NNN (Oktal)
  438.   \\    Backslash (\)
  439.  
  440. '\' at the end of the line indicates that the line should be continued in
  441. the next line.
  442.  
  443.  
  444.  
  445.                               The Author
  446.                               ----------
  447. Send questions or bug-reports to:
  448.  
  449.    Matthias Meixner
  450.    Sandberg 13
  451.    36145 Schwarzbach
  452.    Germay
  453.  
  454. or EMail:
  455.    meixner@rbg.informatik.th-darmstadt.de
  456.  
  457.