annotate doc/plugin-i18n.dox @ 18897:d0be4366e876

Change msim_msg_new() and msim_msg_new_v() to accept the first key name as the first argument, instead of a boolean value indicating that variadic arguments follow. So now, you don't need to pass TRUE as the first argument all the time. NULL can still be passed in the first argument (well, instead of FALSE) to create a new empty message.
author Jeffrey Connelly <jaconnel@calpoly.edu>
date Sat, 11 Aug 2007 17:57:19 +0000
parents 1414e0e01dc5
children 901cbc91db27
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
13400
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
1 /** @page plugin-i18n Third Party Plugin Translation Support
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
2
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
3 @section Introduction
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
4 For a plugin to have translation support there are a few steps that need to
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
5 followed:
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
6
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
7 - The plugin must be setup to use autotools. It may be possible to add
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
8 translation support without autotools, but I have no idea how.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
9 - In your autogen.sh, bootstrap.sh, or whatever you called it, add the
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
10 following after your other utility checks:
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
11 @code
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
12 (intltoolize --version) < /dev/null > /dev/null 2>&1 || {
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
13 echo;
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
14 echo "You must have intltool installed to compile <YOUR PLUGIN NAME>";
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
15 echo;
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
16 exit;
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
17 }
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
18 @endcode
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
19 Then before your call aclocal add:
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
20 @code
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
21 intltoolize --force --copy
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
22 @endcode
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
23 - Now edit configure.ac, configure.in, or whatever you may have called it
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
24 and add the following:
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
25 @code
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
26 AC_PROG_INTLTOOL
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
27
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
28 GETTEXT_PACKAGE=<YOUR PLUGIN NAME>
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
29 AC_SUBST(GETTEXT_PACKAGE)
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
30 AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, ["$GETTEXT_PACKAGE"], [Define the gettext package to be used])
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
31
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
32 ALL_LINGUAS=""
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
33 AM_GLIB_GNU_GETTEXT
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
34 @endcode
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
35 The position of these macros in the file don't really matter, but if you
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 13402
diff changeset
36 have issues either play around with it or feel free to ask one of the Pidgin
13400
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
37 developers. Finally add 'po/Makefile.in' to you 'AC_OUTPUT' command.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
38 - Now create a directory named 'po'.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
39 - 'cd' into the 'po' directory.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
40 - Create/edit the file 'POTFILE.in' in your favorite editor. Each line
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
41 should be the name of a file that could or does have strings marked for
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
42 translating (we're getting to that step). These file names should be
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
43 relative to the top directory of your plugin.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
44 - 'cd' back to the top directory of your plugin.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
45 - Open 'Makefile.am' and add 'po' to your 'SUBDIRS' variable.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
46 - While still in the top directory of your plugin execute
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
47 'intltool-prepare'. This will setup anything extra that intltool needs.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
48 - Fire off an 'autogen.sh' and when it's completed, verify that you have a
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
49 'po/POTFILES', notice the lack of a .in. If you do, everything should be
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
50 set on the autotools side.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
51 - Take a break, stretch your legs, smoke a cigarette, whatever, because
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
52 we're done with the autotools part.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
53 - When you're ready, 'cd' into the directory with the source files for your
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
54 plugin.
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 13402
diff changeset
55 - Open the file containing the PurplePluginInfo structure.
13400
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
56 - If you're not already, please make sure that you are including the
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
57 'config.h' file for you plugin. Note that 'config.h' could be whatever
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
58 you told autohead to use with AM_CONFIG_HEADER. Also add the following:
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
59 @code
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
60 #include <glib/gi18n-lib.h>
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
61 @endcode
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
62 Make sure that this include is after you include of your 'config.h',
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
63 otherwise you will break your build.
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 13402
diff changeset
64 - This is where things get a bit goofy. libpurple is going to try and
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 13402
diff changeset
65 translate our strings using the libpurple gettext package. So we have to
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 13402
diff changeset
66 convert them before libpurple attempts to.
13400
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
67 - To do this, we're going to change the entries for name, summary, and
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
68 description to NULL.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
69 - Next, locate your 'init_plugin' function. Your name for this function
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 13402
diff changeset
70 may vary, but it's the second parameter to 'PURPLE_INIT_PLUGIN'.
13400
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
71 - Now add the following within your 'init_plugin' function:
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
72 @code
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
73 #ifdef ENABLE_NLS
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
74 bindtextdomain(GETTEXT_PACKAGE, LOCALEDIR);
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
75 bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8");
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
76 #endif /* ENABLE_NLS */
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
77
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
78 info.name = _("<YOUR PLUGIN NAME>");
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
79 info.summary = _("<YOUR PLUGIN SUMMARY>");
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
80 info.description = _("<YOUR PLUGIN DESCRIPTION>");
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
81 @endcode
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
82 Note that the _() is intentional, and that it is telling intltool that
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
83 this string should be translated. There is also N_() which says that a
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
84 string should only be marked for translation but should not be translated
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
85 yet.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
86 - Go through the rest of your code and mark all the other strings for
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
87 translation with _().
13402
1d8fc7347a91 [gaim-migrate @ 15777]
Richard Laager <rlaager@wiktel.com>
parents: 13400
diff changeset
88 - When thats done, feel free to commit your work, create your po template
13400
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
89 (pot file) or whatever.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
90 - To create you po template, 'cd' to 'po' and execute:
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
91 @code
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
92 intltool-update --pot
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
93 @endcode
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
94 - To add new translations to your plugin, all you have to do is add the
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
95 language code to the 'ALL_LINGUAS' variable in your configure.ac. Take
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
96 note that this list of languages should be separated by a space. After
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
97 you have added the language code to 'ALL_LINGUAS', drop the xx.po file
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
98 into 'po', and re-'autogen.sh'. After a full build you should now be
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
99 able to use the translation.
6a8a595e17b1 [gaim-migrate @ 15775]
Gary Kramlich <grim@reaperworld.com>
parents:
diff changeset
100 */