doc/plugin-i18n.dox

   1 /** @page plugin-i18n Third Party Plugin Translation Support
   2
   3  @section Introduction
   4   For the purpose of this document we're going to assume that your plugin:
   5
   6    - Is set up to use autotools.  It may be possible to add translation support
   7      without autotools, but we have no idea how.  We may not want to know, either ;)
   8    - Has an autogen.sh.  You may have also called this bootstrap.sh or similar.
   9    - Resides in a source tree that has @c configure.ac and @c Makefile.am in the
  10      top-level directory as well as a @c src directory in which the plugin's source
  11      is located.  A @c Makefile.am should also exist in the @c src directory.
  12
  13   For a plugin to have translation support there are a few steps that need to
  14   followed:
  15
  16    - In your autogen.sh, add the following after your other utility checks:
  17      @code
  18 (intltoolize --version) < /dev/null > /dev/null 2>&1 || {
  19     echo;
  20     echo "You must have intltool installed to compile <YOUR PLUGIN NAME>";
  21     echo;
  22     exit;
  23 }
  24      @endcode
  25      Then before your call to aclocal add:
  26      @code
  27 intltoolize --force --copy
  28      @endcode
  29    - Now edit configure.ac and add the following:
  30      @code
  31 AC_PROG_INTLTOOL
  32
  33 GETTEXT_PACKAGE=<YOUR PLUGIN NAME>
  34 AC_SUBST(GETTEXT_PACKAGE)
  35 AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, ["$GETTEXT_PACKAGE"], [Define the gettext package to be used])
  36
  37 ALL_LINGUAS=""
  38 AM_GLIB_GNU_GETTEXT
  39      @endcode
  40      The position of these macros in the file don't really matter, but if you
  41      have issues either play around with it or feel free to ask one of the Pidgin
  42      developers.  Finally add 'po/Makefile.in' to you 'AC_OUTPUT' command.
  43    - Now create a directory named 'po'.
  44    - 'cd' into the 'po' directory.
  45    - Create/edit the file 'POTFILE.in' in your favorite editor.  Each line
  46      should be the name of a file that could or does have strings marked for
  47          translating (we're getting to that step).  These file names should be
  48          relative to the top directory of your plugin's source tree.
  49    - 'cd' back to the top directory of your plugin's source tree.
  50    - Open 'Makefile.am' and add 'po' to your 'SUBDIRS' variable.
  51    - While still in the top directory of your plugin's source tree,  execute
  52      'intltool-prepare'.  This will setup anything extra that intltool needs.
  53    - Fire off 'autogen.sh' and when it's completed, verify that you have a
  54      'po/POTFILES' (notice the lack of a .in).  If you do, everything should be
  55          set on the autotools side.
  56    - Take a break, stretch your legs, smoke a cigarette, whatever, because
  57      we're done with the autotools part.
  58    - When you're ready, 'cd' into the directory with the source files for your
  59      plugin.
  60    - Open the file containing the PurplePluginInfo structure.
  61    - If you're not already, please make sure that you are including the
  62      'config.h' file for you plugin.  Note that 'config.h' could be whatever
  63          you told autohead to use with AM_CONFIG_HEADER.  Also add the following:
  64          @code
  65 #include <glib/gi18n-lib.h>
  66      @endcode
  67          Make sure that this include is after you include of your 'config.h',
  68          otherwise you will break your build.  Also note that if you wish to
  69      maintain compatibility with older versions of GLib, you will need to
  70      include additional preprocessor directives, which we won't cover here.
  71    - This is where things get a bit goofy.  libpurple is going to try to
  72      translate our strings using the libpurple gettext package.  So we have to
  73      convert them before libpurple attempts to.
  74    - To do this, we're going to change the entries for name, summary, and
  75      description to NULL.
  76    - Next, locate your 'init_plugin' function.  Your name for this function
  77      may vary, but it's the second parameter to 'PURPLE_INIT_PLUGIN'.
  78    - Now add the following within your 'init_plugin' function:
  79      @code
  80 #ifdef ENABLE_NLS
  81         bindtextdomain(GETTEXT_PACKAGE, LOCALEDIR);
  82         bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8");
  83 #endif /* ENABLE_NLS */
  84
  85         info.name        = _("<YOUR PLUGIN NAME>");
  86         info.summary     = _("<YOUR PLUGIN SUMMARY>");
  87         info.description = _("<YOUR PLUGIN DESCRIPTION>");
  88      @endcode
  89      Note that the _() is intentional, and that it is telling intltool that
  90          this string should be translated.  There is also N_() which says that a
  91          string should only be marked for translation but should not be translated
  92          yet.
  93    - Go through the rest of your code and mark all the other strings for
  94      translation with _().
  95    - When thats done, feel free to commit your work, create your po template
  96      (pot file) or whatever.
  97    - To create you po template, 'cd' to 'po' and execute:
  98      @code
  99 intltool-update --pot
 100      @endcode
 101    - To add new translations to your plugin, all you have to do is add the
 102      language code to the 'ALL_LINGUAS' variable in your configure.ac.  Take
 103          note that this list of languages should be separated by a space.  After
 104          you have added the language code to 'ALL_LINGUAS', drop the xx.po file
 105          into 'po', and re-'autogen.sh'.  After a full build you should now be
 106          able to use the translation.
 107  */