]> git.deb.at Git - pkg/abook.git/blob - doc/HOWTO.translating_abook
Updated config.guess and config.sub.
[pkg/abook.git] / doc / HOWTO.translating_abook
1 Foreword
2 --------
3
4 This howto is deliberately incomplete, focusing on working with gettext
5 for abook specifically. For more comprehensive informations or to grasp
6 the Big Picture of Native Language Support, you should refer to the GNU
7 gettext manual at: http://www.gnu.org/software/gettext/manual/
8
9 After a quick description of how things work, three parts aimed at three
10 different people involved in the translation chain will follow: coders,
11 language coordinator, and translators.
12
13
14 Overview
15 --------
16
17 To be able to display texts in the native language of the user, two
18 steps are required: internationalization (i18n) and localization (l10n).
19
20 i18n is about making abook support multiple languages. It is performed
21 by coders, who will mark translatable texts and provide a way to display
22 them translated at runtime.
23
24 l10n is about making the i18n'ed abook adapt to the specific language of
25 the user, ie translating the strings previously marked by the
26 developers, and setting the environment correctly for abook to use the
27 result of this translation.
28
29 So, translatable strings are first marked by the coders within the C
30 source files, then gathered in a template file (abook.pot). The content
31 of this template file is then merged with the translation files for each
32 language (fr.po for french, for instance). A given translation team will
33 take this file, translate its strings, and send it back to the
34 developers. At compilation time, a binary version of this file (for
35 efficiency reasons) will be produced (fr.mo), and then installed.  Then
36 abook will use this file at runtime, translating the strings according
37 to the locale settings of the user.
38
39
40 The coders
41 ----------
42
43 * Translating a new file.
44   First, you have to make your C source file aware of the gettext
45   macros by including "gettext.h".
46   Then, you need to make gettext aware that this file contains
47   translatable strings by adding its name to po/POTFILES.in
48
49 * Translatable strings
50   This is a two parts process: marking the string to tell gettext to
51   make it available to translators (via the .pot file), and actually
52   translating the string at runtime.
53   There is basically three functions/macros available:
54    * _(): mark the string and translate it.
55    * N_(): only mark the string
56    * gettext(): only translate
57   The last two are used in conjunction, when the string declaration is
58   dissociated in the code from its actual use. You'll then use N_() to
59   mark the string, and later use a gettext() call to translate it.
60
61 And that's all, really.
62
63 Should the need arise later, it might be handy to know that a few more
64 mechanisms exist, for example to deal with ambiguities (same string but
65 with different roles should be translated differently), or plurals, etc.
66 This is all explained in depth in the gettext manual. But the three
67 macros seen above should be enough to handle about all the situations
68 met while internationalizing abook.
69
70
71 The language coordinator
72 ------------------------
73
74 This is neither a coder, nor a translator. His role is in-between. He
75 is the one who will merge the strings changed by the coders into the
76 translation files, and merge back the translation files sent to him by
77 the translators. He will also take care of initiating language files
78 whenever a new translator shows up.
79
80 * Updating the template file
81   Translatable strings evolve all the time: coders add some, remove
82   others, change a lot of them. At some point, these strings need to be
83   merged into the po/abook.pot file to reflect the current situation.
84   This is done simply by executing 'make -C po abook.pot-update'.
85
86   The xgettext utility will then parse the files listed into
87   po/POTFILES.in, looking for marked strings, and updating po/abook.pot.
88   
89 * Merging the new strings into the po-files
90   After updating, you will have to merge the changes into every .po
91   file. This is done by running 'make -C po update-po', which will use
92   the msgmerge program to perform this task.
93
94   Then, some strings will be marked as "fuzzy" (ie needing review,
95   because of slight changes), some strings will be commented out
96   because of removal from sources, some strings will be added, and
97   some strings will not be changed at all. The po-file is now in sync.
98
99 * Compiling plain text translation into binary files suited for runtime
100   Please note that this is implicitly done in the previous step.
101   Anyway, you just have to run 'make -C po update-gmo' to update the
102   mo-files (or gmo-files, which is a GNU specific naming) from the
103   po-files.
104
105   For (re)generating just one particular language (french as example),
106   use 'cd po ; msgfmt -c --statistics -o fr.gmo fr.po'.
107
108 * Initiating the translation of a new language
109   So a Swedish translator just contacted you to contribute a
110   translation. Nice!
111   
112   First, find out what the locale name is. For swedish, it is 'sv_SE',
113   or simply 'sv'. This is the value the user will have to put in his
114   LC_MESSAGES/LANG environment variable for software to be translated.
115
116   Then, go into the po/directory, and create a new po-file from the
117   template file: 'msginit -i abook.pot -o sv.po -l sv --no-translator'.
118   Now, having this sv.po file, the translator is ready to begin.
119
120   Last step is making gettext aware of this new language. Just add the
121   locale name to the po/LINGUAS file.
122
123 * Committing a po-file received from a translator
124   The Swedish translator just sent you an updated translation, in
125   sv.po.new. Before replacing sv.po in the po/ directory and committing
126   it to cvs, you should check everything is fine, with this step:
127   'msgmerge sv.po.new abook.pot -o sv.po'.
128
129
130 The translators
131 ---------------
132
133 The gettext part is the easy one: the format of the po-files is really
134 straightforward. The hard part will be the quest for the right word, the
135 best fitting formulation.
136
137 po-files are made of four things:
138  * location lines: tells you where the strings can be seen (name of file
139    and line number), in case you need to see a bit of context.
140  * msgid lines: the strings to translate.
141  * msgstr lines: the translated strings.
142  * lines prefixed with '#': comments (some with a special meaning, as we
143    will see below).
144
145 Basically, all you have to do is fill the msgstr lines with the
146 translation of the above msgid line. And send the result to the language
147 coordinator of abook.
148
149 A few notes:
150
151 * Fuzzy strings
152   You will meet strings marked with a "#, fuzzy" comment. abook won't
153   use the translations of such strings until you do something about
154   them.
155   
156   A string being fuzzy means either that the string has already been
157   translated but has since been changed in the sources of the program,
158   or that this is a new string for which gettext made a 'wild guess' for
159   the translation, based on other strings in the file.
160
161   It means you have to review the translation. Sometimes, the original
162   string has changed just because a typo has been fixed. In this case,
163   you won't have to change anything. But sometimes, the translation will
164   no longer be accurate and needs to be changed.
165
166   Once you are done and happy with the translation, just remove the
167   "#, fuzzy" line, and the translation will be used again in abook.
168
169 * c-format strings and special sequences
170   Some strings have the following comment: "#, c-format".
171   This tells that parts of the string to translate have a special
172   meaning for the program, and that you should leave them alone.
173
174   For instance, %-sequences, like "%s". These means that abook will
175   replace them with another string. So it is important it remains.
176
177   There are also \-sequences, like \n or \t. Leave them, too. The former
178   represents an end of line, the latter a tabulation.
179
180 * Translations can be wrapped
181   If lines are too long, you can just break them like this:
182     msgid ""
183     "some very long line"
184     "another line"
185
186 * po-file header
187   At the very beginning of the po-file, the first string form a header,
188   where various kind of information has to be filled in. Most important
189   one is the charset. It should resemble
190   "Content-Type: text/plain; charset=utf-8\n"
191
192   You should also fill in the Last-Translator field, so that potential
193   contributors can contact you if they want to join you in the
194   translation team, or have remarks/typo fixes to give about the
195   translations. You can either just give your name/nick, or add an email
196   address, f ex "Last-Translator: Cédric Duval <cedricduval+abook@free.fr>\n".
197
198 * Comments
199   Adding comments (lines begining with the '#' character) can be a good
200   way to point out problems or translation difficulties to proofreaders
201   or other members of your team.
202
203 * Strings size
204   abook is a curses/console program, thus it can be heavily dependant on
205   the terminal size (number of columns). You should think about this
206   when translating. Often, a string must fit into a single line
207   (standard length is 80 characters). Don't translate blindly, try to
208   look where your string will be displayed to adapt your translation.
209
210 * A few useful tools
211   The po-file format is very simple, and the file can be edited with a
212   standard text editor.
213   
214   But if you prefer, there are few specialized tools you may find
215   convenient for translating:
216    * poEdit (http://www.poedit.org/)
217    * KBabel (http://i18n.kde.org/tools/kbabel/)
218    * GTranslator (http://gtranslator.sourceforge.net/)
219    * Emacs po mode
220    * Vim po mode
221      (http://vim.sourceforge.net/scripts/script.php?script_id=695
222      or http://vim.sourceforge.net/scripts/script.php?script_id=913)
223    * And certainly others I'm not aware of. Just tell me!
224
225
226 And finally
227 -----------
228
229 I hope you'll have fun contributing to a more internationalized world. :)
230
231 If you have any more questions, don't hesitate to contact me
232 (Cédric Duval <cedricduval+abook@free.fr>) or the abook development
233 mailing list (http://lists.sourceforge.net/lists/listinfo/abook-devel).
234