1*********************************
2*
3* trans.py - language extraction toolkit
4*
5* - Brandon Long, David Jeske
6*
7
8** Getting Started
9
101) First you need to create a MySQL trans database for your application.
11
12  > mysql -uroot
13  mysql> create database trans_data
14  mysql> quit
15  > mysql -uroot trans_data < trans.sql
16
172) Then just run trans on the test data to verify that it is working..
18
19  > ./trans.py
20
21   Check out the 'testroot/gen' directory.
22
233) Then, in your application, make sure your CSPage setup equivilant is
24   doing the following:
25
26   1) Make sure "gen/tmpl/<lang>" and "gen/tmpl" are in hdf.loadpaths
27      before your template directories. This assures that the load will
28      prefer files in the language specific template directory first,
29      the language directory second, and your template directories last.
30
31   2) after loading your page-specific HDF file, be sure to
32      load "lang_<lang>.hdf" over the top. This will automatically
33      override HDF lang strings with the proper values from the translated
34      language files.
35
364) Configure trans.py in the __init__ function (sorry for the hardcoded
37   stuff)
38
395) When you want to translate into a new language, take the
40   'strings_en.hdf' file and copy it to trans_XX.hdf. Translate
41   the strings in it, and then run:
42
43   > ./trans.py --lang XX --load trans_XX.hdf
44   > ./trans.py
45
46   Each time trans is run, it will dump the list of missing strings for
47   every language which has any strings at all. Simply follow the same
48   procedure above with the missing strings file to update the
49   translation in that language.
50
51
52** About trans.py
53
54This tools allows you to (mostly) automatically extract language
55strings from HTML Clearsilver templates, and from Clearsilver HDF
56files. trans inserts all unique strings into a database, and
57provides you facilities for exporting and importing the strings in the
58database. trans then creates a 'gen' tree where your source files
59reference language strings, and dumps lang_XX.hdf files which
60define those strings.
61
62
63Two mechanisms are used to find language strings:
64
651) Any language string present in an HDF file should be marked
66   with the [Lang] attribute. For example:
67
68     Menu.Name [Lang] = Start Here
69
70   Trans will automatically replace this with a copy reference to
71   the lang hash-keyed string in the currently imported language.
72
73     Menu.Name : Lang.L112414
74
752) Parsing of html attempts to find language strings automatically.
76   This allows you to leave most of your language strings in-tact
77   in your primary language, making working on your application
78   much easier.
79
80   Some parts of HTML structure, including some tag attributes and
81   javascript, are too complicated for trans to automatically do
82   the right thing. In these cases, you must manually extract
83   the string into an HDF file and then reference it in your HTML.
84
85   For example, in the following HTML/Clearsilver fragment,
86   the heading will be automatically identified, but the submit
87   button title cannot be extracted by trans safetly.
88
89    <html>
90    <body>
91    <h1> Send us your Feedback </h1>
92    <form>
93    <input type=text name=feedback>
94    <input type=submit name="Action.Submit"
95           value="Send Feedback">
96    </form>
97    </body>
98    </html>
99
100   You must convert the above fragment into something like this:
101
102    <html>
103    <body>
104    <h1> Send us your Feedback </h1>
105    <form>
106    <input type=text name=feedback>
107    <input type=submit name="Action.Submit"
108           value="<?cs var:Lang.SendFeedback ?>">
109    </form>
110    </body>
111    </html>
112
113   The "Lang.SendFeedback" item must be declared in your static page
114   HDF, and must be marked with the '[Lang]' attribute.
115
116    Lang.SendFeedback [Lang] = Send Feedback
117
118
119