view doc/plugin-i18n.dox @ 20333:53afc5cce143

applied changes from d4b316d73ebaf93803ca2642e78b8821c3b5d5c7 through b219fc7a61d692d47953984814f7b4d882f20291 applied changes from b219fc7a61d692d47953984814f7b4d882f20291 through f8476716fbd7f56dd6fe9fd371a8f5429b12d483 applied changes from f8476716fbd7f56dd6fe9fd371a8f5429b12d483 through 2e96e2466f643bc1f895f5983c1c0ecb9730498c applied changes from 2e96e2466f643bc1f895f5983c1c0ecb9730498c through 16d908d77101c3eb83632a6b9febef6d5ee96481 applied changes from 16d908d77101c3eb83632a6b9febef6d5ee96481 through 9207c76719cf14838d6306432140b3f0da9225ae

/** @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 Pidgin
     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 PurplePluginInfo 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.  libpurple is going to try and
     translate our strings using the libpurple gettext package.  So we have to
     convert them before libpurple 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 'PURPLE_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, create 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.
 */