README.i18n 9.29 KB
Newer Older
1
This document exists to document the important things to care
Sven Neumann's avatar
Sven Neumann committed
2 3 4 5 6 7 8
for because of locale support. It is aimed at developers and
translators. If you are a translator, you can skip the first
sections, but you definitely want to read sections 5 - 9.

 Table of Contents

   1. Why localisation?
9
   2. How
Sven Neumann's avatar
Sven Neumann committed
10 11 12 13 14 15 16 17 18
   3. Deep inside ...
   4. Some magic ...
   5. Tools and how to use them
   6. Gimp is different
   7. Adding additional textdomains
   8. Tip of the Day messages
   9. How to contribute
  10. And more ?

19 20 21 22 23

1. Why localisation?

 Many persons from many countries start to get used to Linux.
 Unfortunately not everyone is able to understand English. But
Sven Neumann's avatar
Sven Neumann committed
24
 even those people sometimes like to use good and free software
25
 without using a dictionary to get the unknown words.
26
 So why not simply localise the software to make it available to
Marc Lehmann's avatar
Marc Lehmann committed
27 28
 the mass which isn't wholly English native? Of course this also
 eases the migration from PhotoX to GIMP. :))
29 30 31 32 33 34

2. How?

 GNU provides a very nice package called gettext. This one offers
 the possibility to translate chosen messages from the native language
 of the program into that one of the users if a necessary catalog is
Sven Neumann's avatar
Sven Neumann committed
35 36 37 38 39
 provided. Gettext therefore provides some easy tools to create and
 maintain such catalogs and a few functions which can be called by the
 program to enable automatic translation at runtime. The program gets
 linked to the gettext library or glibc2 which already provides that
 functionality and everything is fine.
40 41 42

3. Deep inside...

Sven Neumann's avatar
Sven Neumann committed
43 44 45 46
 GIMP provides header files called gimpintl.h and stdplugins-intl.h in
 the libgimp directory which check whether gettext is available on the
 system which GIMP is compiled on and will deactivate language support
 if it's not.
47

48
 If the gettext system is there it will declare 3 functions which will be
49
 described below.
50 51 52

3.1 _() [more correctly: char * _( char * )]

Sven Neumann's avatar
Sven Neumann committed
53 54 55 56 57 58
 This one is a macro for the function gettext(). You can wrap any text
 with it that is allowed to be a return value of a function. If you
 use it then libintl will try to translate it into the native language
 of the user according to his/her environmental settings.
 The gettext() function will do a lookup in the hashed catalog which
 contains all the translated texts.
59 60

 - If it is found a pointer to the string will be returned to the caller.
Marc Lehmann's avatar
Marc Lehmann committed
61
 - If not, the caller will receive a pointer to the original string.
62

63
 This way it is ensured that there isn't any harm caused to the program
Sven Neumann's avatar
Sven Neumann committed
64
 if no useful catalog is installed.
65 66 67 68

 Please note that it is important to use _() directly (and not gettext())
 for simple messages because of reasons that will be mentioned below.

69 70
 NOTE: I know some of the developer like short functions like _() but
 for a better source understanding I suggest to use it consistently only
Sven Neumann's avatar
Sven Neumann committed
71 72
 for text (like _("That's text!")) and not for variables (like _(text)).
 Use gettext(text) instead.
73

74

Marc Lehmann's avatar
Marc Lehmann committed
75
3.2 N_() [more correctly: const char * ( const char * ) ]
76

Sven Neumann's avatar
Sven Neumann committed
77 78 79 80
 This one is a macro for the function gettext_noop(). As you can see
 and guess it doesn't really do anything in the programm i.e. it is a
 dummy macro but nevertheless important. As it isn't possible to call
 functions in a structure as seen here:
81 82 83 84 85 86

 struct blurb
 {
  _("This won't work\n");
 }

Sven Neumann's avatar
Sven Neumann committed
87 88 89 90 91
 you have to do it in some other way. In GIMP such structures are
 often used to create menus or similar things very simply. Here you
 have to use the dummy to allow the generation of the template catalog
 which will be described below. This one doesn't do anything but it
 marks the text as important to the xgettext extractor.
92

93 94
 The text has to be translated manually with the next function.

95 96
3.3 gettext()

97
 This function is the same as that macro in 3.1. But there is one big
Sven Neumann's avatar
Sven Neumann committed
98
 difference: The _()'s and N_()'s are the only expressions which get
99
 parsed by the template generator.
Sven Neumann's avatar
Sven Neumann committed
100 101 102 103
 If you have strings that should be translated but are unfortunately
 in a structure you have to do that on your own which means that you
 have to parse the fields with the messages in a loop and translate
 the texts with this gettext() function.
104

Sven Neumann's avatar
Sven Neumann committed
105
 Please note that it may be necessary to free or allocate memory in
106
 this case!
107 108 109

4. Some magic...

Sven Neumann's avatar
Sven Neumann committed
110 111 112
 As you have seen we only did the programming part until now but this
 isn't all by far. To use catalogs we'll have to create them. Now
 there are 3 different files which are importart:
113 114

 gimp.pot:
115

Sven Neumann's avatar
Sven Neumann committed
116 117 118
 This one is the so called template. It contains the messages which
 are extracted from the sources and empty fields which have to get
 filled by the author. It is used to start a new catalog or to update
119
 the an already available one.
120

Sven Neumann's avatar
Sven Neumann committed
121 122 123
 The Makefile will automatically call the program gettext which will
 extract all messages that are wrapped by a _() or a N_() (but NOT
 gettext()) and concat them to this template.
124

125
 [language].po:
126

Sven Neumann's avatar
Sven Neumann committed
127 128 129
 This file has to be an edited gimp.pot and contains the original
 messages plus the translated ones. This file will be delivered
 together with GIMP and is the base for the final catalog.
130 131 132 133

 [language].mo:

 This file is a compiled version of [language.po] which will be
Sven Neumann's avatar
Sven Neumann committed
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155
 automatically compiled by the Makefile system and installed in the
 locale directory of the system. It contains everything that the .po
 file contains except not translated messages, comments and other
 overhead. For maximum speed it is also hashed to allow gettext a
 faster search.

5. Tools and how to use them

 As mentioned the to be translated strings are extracted directly from
 the source and written to the template.

 I guess many of you will now ask if it is necessary to add new
 strings directly to the template or if there's a tool to achieve
 that. I think I can calm down those of you who fear lots of had work
 just to update the language files. There's a program called msgmerge
 which will add all strings that are in the template but not in the
 uncompiled catalog to it. Msgmerge does this job very nicely and also
 tries to use some kind of fuzzy logic method for already translated
 strings for possible reduction of translators work: If an original
 string seems similar to a new one and it already has a translation,
 it will be taken over to the new catalog together with a remark that
this one may not necessarily fit.
156

Sven Neumann's avatar
Sven Neumann committed
157 158
6. Gimp is different

Sven Neumann's avatar
Sven Neumann committed
159 160
 Gimp is a complex application which has a bunch of scripts and
 plug-ins that all want to be internationalized. Therefore there is
161
 not one catalog but many. For a full translation of GIMP's UI,
Sven Neumann's avatar
Sven Neumann committed
162
 you will have to add translations for the following catalogs:
Sven Neumann's avatar
Sven Neumann committed
163

164 165
   po/gimp20.po                       --  the core
   po-libgimp/gimp20-libgimp.pot      --  the libgimp library
Sven Neumann's avatar
Sven Neumann committed
166 167
   po-python/gimp20-python.pot        --  the pygimp plug-ins
   po-plugins/gimp20-std-plugins.pot  --  the C plug-ins
168
   po-script-fu/gimp20-script-fu.pot  --  the script-fu scripts
169
   po-tips/gimp20-tips.pot            --  the startup tips
Sven Neumann's avatar
Sven Neumann committed
170

171
 If you are looking for the translations of gimp-perl, please note that
172 173 174 175 176 177 178 179 180 181 182
 gimp-perl has been moved into it's own Subversion module called
 gimp-perl.

 The version of GIMP you are holding in your hand uses GTK+-2.0. 
 GTK+-2.0 requires that all strings are UTF-8 encoded. Therefore to
 make internationalisation work, po files need to be UTF-8 encoded. If
 your editor doesn't support UTF-8, you need to convert it to an
 encoding your editor can handle and convert it back to UTF-8 before
 commiting your changes back. The gnome-i18n module in Subversion has
 some scripts that help with this task, but it can also easily done
 using iconv.
183

Sven Neumann's avatar
Sven Neumann committed
184 185
7. Adding additional textdomains

Sven Neumann's avatar
Sven Neumann committed
186
 Third-party plug-ins (plug-ins that are not distributed with The
Sven Neumann's avatar
Sven Neumann committed
187 188 189 190 191 192 193 194
 GIMP) can't have their messages in the gimp-std-plugins textdomain.
 We have therefore provided a mechanism that allows plug-ins to
 install their own message catalogs and tell GIMP to bind to that
 textdomain. This is necessary so that GIMP can correctly translate
 the menu paths the plug-in registers. Basically the plug-in has to
 call gimp_plugin_domain_add() or gimp_domain_plugin_add_with_path()
 before it registers any functions. Have a look at the script-fu
 plug-in to see how this is done in detail.
Sven Neumann's avatar
Sven Neumann committed
195

196 197
8. Tip of the Day messages

Sven Neumann's avatar
Sven Neumann committed
198 199 200 201 202 203
 In addition to message catalogs Gimp provides a file with tips that
 are displayed in a Tip of The Day window. This file is in XML format
 and can be found in the tips directory. The english tips messages are
 extracted from gimp-tips.xml.in so translators can use the usual
 tools to create a <lang>.po file that holds the translations. All
 translations are then merged into gimp-tips.xml with language
204
 identifiers taken from the po filename.
205

Sven Neumann's avatar
Sven Neumann committed
206 207 208 209
 GIMP needs to know what language it should select from gimp-tips.xml.
 Therefore, there's the special message "tips-locale:C" in the main
 message catalog that needs to be translated correctly. For a german
 translation of the tips this would look like this:
210

Sven Neumann's avatar
Sven Neumann committed
211 212 213
 #: app/gui/tips-parser.c:158
 msgid "tips-locale:C"
 msgstr "tips-locale:de"
214

215 216
9. How to contribute

Sven Neumann's avatar
Sven Neumann committed
217 218
 Any help with translations is appreciated. If you want to help,
 please get in contact with the people from the GNOME Translation
219 220
 Project who coordinate all translation efforts in the GNOME
 Subversion tree. They have a nice web-page at
221
	http://developer.gnome.org/projects/gtp/.
222 223

10. And more?
224

Sven Neumann's avatar
Sven Neumann committed
225 226 227 228
 We hope we mentioned everything that is worth it and hope that this
 document will clarify some things. If it doesn't please write us a
 mail. This text of course contains errors, so if you find one tell
 us...
Marc Lehmann's avatar
Marc Lehmann committed
229

Sven Neumann's avatar
Sven Neumann committed
230

Sven Neumann's avatar
Sven Neumann committed
231 232
Happy Gimping.
	Daniel Egger
233
	Sven Neumann
Sven Neumann's avatar
Sven Neumann committed
234