# HG changeset patch
# User Gary Kramlich <grim@reaperworld.com>
# Date 1141669006 0
# Node ID 6a8a595e17b1251e172d4f8d223e66887bfb2c10
# Parent  18d5d40186044a86499049241d1091c6dced5a90
[gaim-migrate @ 15775]
and the developer part of third party translatable plugins..

committer: Tailor Script <tailor@pidgin.im>

diff -r 18d5d4018604 -r 6a8a595e17b1 doc/Makefile.am
--- a/doc/Makefile.am	Mon Mar 06 17:01:32 2006 +0000
+++ b/doc/Makefile.am	Mon Mar 06 18:16:46 2006 +0000
@@ -23,6 +23,7 @@
 	gtkrc-2.0 \
 	log-signals.dox \
 	notify-signals.dox \
+	plugin-i18n.dox \
 	plugin-ids.dox \
 	plugin-signals.dox \
 	savedstatus-signals.dox \
diff -r 18d5d4018604 -r 6a8a595e17b1 doc/plugin-i18n.dox
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/plugin-i18n.dox	Mon Mar 06 18:16:46 2006 +0000
@@ -0,0 +1,100 @@
+/** @page plugin-i18n Third Party Plugin Translation Support
+
+ @section Introduction
+  For a plugin to have translation support there are a few steps that need to
+  followed:
+
+   - The plugin must be setup to use autotools.  It may be possible to add
+     translation support without autotools, but I have no idea how.
+   - In your autogen.sh, bootstrap.sh, or whatever you called it, add the
+     following after your other utility checks:
+     @code
+(intltoolize --version) < /dev/null > /dev/null 2>&1 || {
+    echo;
+    echo "You must have intltool installed to compile <YOUR PLUGIN NAME>";
+    echo;
+    exit;
+}
+     @endcode
+     Then before your call aclocal add:
+     @code
+intltoolize --force --copy
+     @endcode
+   - Now edit configure.ac, configure.in, or whatever you may have called it
+     and add the following:
+     @code
+AC_PROG_INTLTOOL
+
+GETTEXT_PACKAGE=<YOUR PLUGIN NAME>
+AC_SUBST(GETTEXT_PACKAGE)
+AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, ["$GETTEXT_PACKAGE"], [Define the gettext package to be used])
+
+ALL_LINGUAS=""
+AM_GLIB_GNU_GETTEXT
+     @endcode
+     The position of these macros in the file don't really matter, but if you
+     have issues either play around with it or feel free to ask one of the Gaim
+     developers.  Finally add 'po/Makefile.in' to you 'AC_OUTPUT' command.
+   - Now create a directory named 'po'.
+   - 'cd' into the 'po' directory.
+   - Create/edit the file 'POTFILE.in' in your favorite editor.  Each line
+     should be the name of a file that could or does have strings marked for
+	 translating (we're getting to that step).  These file names should be
+	 relative to the top directory of your plugin.
+   - 'cd' back to the top directory of your plugin.
+   - Open 'Makefile.am' and add 'po' to your 'SUBDIRS' variable.
+   - While still in the top directory of your plugin execute
+     'intltool-prepare'.  This will setup anything extra that intltool needs.
+   - Fire off an 'autogen.sh' and when it's completed, verify that you have a
+     'po/POTFILES', notice the lack of a .in.  If you do, everything should be
+	 set on the autotools side.
+   - Take a break, stretch your legs, smoke a cigarette, whatever, because
+     we're done with the autotools part.
+   - When you're ready, 'cd' into the directory with the source files for your
+     plugin.
+   - Open the file containing the GaimPluginInfo structure.
+   - If you're not already, please make sure that you are including the
+     'config.h' file for you plugin.  Note that 'config.h' could be whatever
+	 you told autohead to use with AM_CONFIG_HEADER.  Also add the following:
+	 @code
+#include <glib/gi18n-lib.h>
+     @endcode
+	 Make sure that this include is after you include of your 'config.h',
+	 otherwise you will break your build.
+   - This is where things get a bit goofy.  Gaim is going to try and translate
+     our strings using the Gaim gettext package.  So we have to convert them
+	 before Gaim attempts to.
+   - To do this, we're going to change the entries for name, summary, and
+     description to NULL.
+   - Next, locate your 'init_plugin' function.  Your name for this function
+     may vary, but it's the second parameter to 'GAIM_INIT_PLUGIN'.
+   - Now add the following within your 'init_plugin' function:
+     @code
+#ifdef ENABLE_NLS
+	bindtextdomain(GETTEXT_PACKAGE, LOCALEDIR);
+	bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8");
+#endif /* ENABLE_NLS */
+
+	info.name        = _("<YOUR PLUGIN NAME>");
+	info.summary     = _("<YOUR PLUGIN SUMMARY>");
+	info.description = _("<YOUR PLUGIN DESCRIPTION>");
+     @endcode
+     Note that the _() is intentional, and that it is telling intltool that
+	 this string should be translated.  There is also N_() which says that a
+	 string should only be marked for translation but should not be translated
+	 yet.
+   - Go through the rest of your code and mark all the other strings for
+     translation with _().
+   - When thats done, feel free to commit your work, creat your po template
+     (pot file) or whatever.
+   - To create you po template, 'cd' to 'po' and execute:
+     @code
+intltool-update --pot
+     @endcode
+   - To add new translations to your plugin, all you have to do is add the
+     language code to the 'ALL_LINGUAS' variable in your configure.ac.  Take
+	 note that this list of languages should be separated by a space.  After
+	 you have added the language code to 'ALL_LINGUAS', drop the xx.po file
+	 into 'po', and re-'autogen.sh'.  After a full build you should now be
+	 able to use the translation.
+ */