+Foreword
+--------
+
+This howto is deliberately incomplete, focusing on working with gettext
+for abook specifically. For more comprehensive informations or to grasp
+the Big Picture of Native Language Support, you should refer to the GNU
+gettext manual at: http://www.gnu.org/software/gettext/manual/
+
+After a quick description of how things work, three parts aimed at three
+different people involved in the translation chain will follow: coders,
+language coordinator, and translators.
+
+
+Overview
+--------
+
+To be able to display texts in the native language of the user, two
+steps are required: internationalization (i18n) and localization (l10n).
+
+i18n is about making abook support multiple languages. It is performed
+by coders, who will mark translatable texts and provide a way to display
+them translated at runtime.
+
+l10n is about making the i18n'ed abook adapt to the specific language of
+the user, ie translating the strings previously marked by the
+developers, and setting the environment correctly for abook to use the
+result of this translation.
+
+So, translatable strings are first marked by the coders within the C
+source files, then gathered in a template file (abook.pot). The content
+of this template file is then merged with the translation files for each
+language (fr.po for french, for instance). A given translation team will
+take this file, translate its strings, and send it back to the
+developers. At compilation time, a binary version of this file (for
+efficiency reasons) will be produced (fr.mo), and then installed. Then
+abook will use this file at runtime, translating the strings according
+to the locale settings of the user.
+
+
+The coders
+----------
+
+* Translating a new file.
+ First, you have to make your C source file aware of the gettext
+ macros by including "gettext.h".
+ Then, you need to make gettext aware that this file contains
+ translatable strings by adding its name to po/POTFILES.in
+
+* Translatable strings
+ This is a two parts process: marking the string to tell gettext to
+ make it available to translators (via the .pot file), and actually
+ translating the string at runtime.
+ There is basically three functions/macros available:
+ * _(): mark the string and translate it.
+ * N_(): only mark the string
+ * gettext(): only translate
+ The last two are used in conjunction, when the string declaration is
+ dissociated in the code from its actual use. You'll then use N_() to
+ mark the string, and later use a gettext() call to translate it.
+
+And that's all, really.
+
+Should the need arise later, it might be handy to know that a few more
+mechanisms exist, for example to deal with ambiguities (same string but
+with different roles should be translated differently), or plurals, etc.
+This is all explained in depth in the gettext manual. But the three
+macros seen above should be enough to handle about all the situations
+met while internationalizing abook.
+
+
+The language coordinator
+------------------------
+
+This is neither a coder, nor a translator. His role is in-between. He
+is the one who will merge the strings changed by the coders into the
+translation files, and merge back the translation files sent to him by
+the translators. He will also take care of initiating language files
+whenever a new translator shows up.
+
+* Updating the template file
+ Translatable strings evolve all the time: coders add some, remove
+ others, change a lot of them. At some point, these strings need to be
+ merged into the po/abook.pot file to reflect the current situation.
+ This is done simply by executing 'make -C po abook.pot-update'.
+
+ The xgettext utility will then parse the files listed into
+ po/POTFILES.in, looking for marked strings, and updating po/abook.pot.
+
+* Merging the new strings into the po-files
+ After updating, you will have to merge the changes into every .po
+ file. This is done by running 'make -C po update-po', which will use
+ the msgmerge program to perform this task.
+
+ Then, some strings will be marked as "fuzzy" (ie needing review,
+ because of slight changes), some strings will be commented out
+ because of removal from sources, some strings will be added, and
+ some strings will not be changed at all. The po-file is now in sync.
+
+* Compiling plain text translation into binary files suited for runtime
+ Please note that this is implicitly done in the previous step.
+ Anyway, you just have to run 'make -C po update-gmo' to update the
+ mo-files (or gmo-files, which is a GNU specific naming) from the
+ po-files.
+
+ For (re)generating just one particular language (french as example),
+ use 'cd po ; msgfmt -c --statistics -o fr.gmo fr.po'.
+
+* Initiating the translation of a new language
+ So a Swedish translator just contacted you to contribute a
+ translation. Nice!
+
+ First, find out what the locale name is. For swedish, it is 'sv_SE',
+ or simply 'sv'. This is the value the user will have to put in his
+ LC_MESSAGES/LANG environment variable for software to be translated.
+
+ Then, go into the po/directory, and create a new po-file from the
+ template file: 'msginit -i abook.pot -o sv.po -l sv --no-translator'.
+ Now, having this sv.po file, the translator is ready to begin.
+
+ Last step is making gettext aware of this new language. Just add the
+ locale name to the po/LINGUAS file.
+
+* Committing a po-file received from a translator
+ The Swedish translator just sent you an updated translation, in
+ sv.po.new. Before replacing sv.po in the po/ directory and committing
+ it to cvs, you should check everything is fine, with this step:
+ 'msgmerge sv.po.new abook.pot -o sv.po'.
+
+
+The translators
+---------------
+
+The gettext part is the easy one: the format of the po-files is really
+straightforward. The hard part will be the quest for the right word, the
+best fitting formulation.
+
+po-files are made of four things:
+ * location lines: tells you where the strings can be seen (name of file
+ and line number), in case you need to see a bit of context.
+ * msgid lines: the strings to translate.
+ * msgstr lines: the translated strings.
+ * lines prefixed with '#': comments (some with a special meaning, as we
+ will see below).
+
+Basically, all you have to do is fill the msgstr lines with the
+translation of the above msgid line. And send the result to the language
+coordinator of abook.
+
+A few notes:
+
+* Fuzzy strings
+ You will meet strings marked with a "#, fuzzy" comment. abook won't
+ use the translations of such strings until you do something about
+ them.
+
+ A string being fuzzy means either that the string has already been
+ translated but has since been changed in the sources of the program,
+ or that this is a new string for which gettext made a 'wild guess' for
+ the translation, based on other strings in the file.
+
+ It means you have to review the translation. Sometimes, the original
+ string has changed just because a typo has been fixed. In this case,
+ you won't have to change anything. But sometimes, the translation will
+ no longer be accurate and needs to be changed.
+
+ Once you are done and happy with the translation, just remove the
+ "#, fuzzy" line, and the translation will be used again in abook.
+
+* c-format strings and special sequences
+ Some strings have the following comment: "#, c-format".
+ This tells that parts of the string to translate have a special
+ meaning for the program, and that you should leave them alone.
+
+ For instance, %-sequences, like "%s". These means that abook will
+ replace them with another string. So it is important it remains.
+
+ There are also \-sequences, like \n or \t. Leave them, too. The former
+ represents an end of line, the latter a tabulation.
+
+* Translations can be wrapped
+ If lines are too long, you can just break them like this:
+ msgid ""
+ "some very long line"
+ "another line"
+
+* po-file header
+ At the very beginning of the po-file, the first string form a header,
+ where various kind of information has to be filled in. Most important
+ one is the charset. It should resemble
+ "Content-Type: text/plain; charset=utf-8\n"
+
+ You should also fill in the Last-Translator field, so that potential
+ contributors can contact you if they want to join you in the
+ translation team, or have remarks/typo fixes to give about the
+ translations. You can either just give your name/nick, or add an email
+ address, f ex "Last-Translator: Cédric Duval <cedricduval+abook@free.fr>\n".
+
+* Comments
+ Adding comments (lines begining with the '#' character) can be a good
+ way to point out problems or translation difficulties to proofreaders
+ or other members of your team.
+
+* Strings size
+ abook is a curses/console program, thus it can be heavily dependant on
+ the terminal size (number of columns). You should think about this
+ when translating. Often, a string must fit into a single line
+ (standard length is 80 characters). Don't translate blindly, try to
+ look where your string will be displayed to adapt your translation.
+
+* A few useful tools
+ The po-file format is very simple, and the file can be edited with a
+ standard text editor.
+
+ But if you prefer, there are few specialized tools you may find
+ convenient for translating:
+ * poEdit (http://www.poedit.org/)
+ * KBabel (http://i18n.kde.org/tools/kbabel/)
+ * GTranslator (http://gtranslator.sourceforge.net/)
+ * Emacs po mode
+ * Vim po mode
+ (http://vim.sourceforge.net/scripts/script.php?script_id=695
+ or http://vim.sourceforge.net/scripts/script.php?script_id=913)
+ * And certainly others I'm not aware of. Just tell me!
+
+
+And finally
+-----------
+
+I hope you'll have fun contributing to a more internationalized world. :)
+
+If you have any more questions, don't hesitate to contact me
+(Cédric Duval <cedricduval+abook@free.fr>) or the abook development
+mailing list (http://lists.sourceforge.net/lists/listinfo/abook-devel).
+
projects / pkg / abook.git / commitdiff