doc/reference/libpurple/plugin_i18n.xml

   1 <?xml version='1.0' encoding="ISO-8859-1"?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   4 ]>
   5 <chapter id="chapter-plugin-i18n">
   6   <title>Third Party Plugin Translation</title>
   7
   8   <sect2 id="plugin-i18n-introduction">
   9   <title>Introduction</title>
  10
  11   <para>
  12   For the purpose of this document we're going to assume that your plugin:
  13
  14   <itemizedlist>
  15     <listitem><para>
  16 Is set up to use autotools.  It may be possible to add translation support
  17 without autotools, but we have no idea how.  We may not want to know, either ;)
  18     </para></listitem>
  19     <listitem><para>
  20 Has an autogen.sh.  You may have also called this bootstrap.sh or similar.
  21     </para></listitem>
  22     <listitem><para>
  23 Resides in a source tree that has <literal>configure.ac</literal> and
  24 <literal>Makefile.am</literal> in the top-level directory as well as a
  25 <literal>src</literal> directory in which the plugin's source is located.  A
  26 <literal>Makefile.am</literal> should also exist in the <literal>src</literal>
  27 directory.
  28     </para></listitem>
  29   </itemizedlist>
  30   </para>
  31   </sect2>
  32
  33   <sect2 id="plugin-i18n-steps">
  34   <title>Steps to follow</title>
  35
  36   <para>
  37   For a plugin to have translation support there are a few steps that need to
  38   followed:
  39
  40   <itemizedlist>
  41     <listitem><para>
  42 In your autogen.sh, add the following after your other utility checks:
  43 <programlisting>
  44 (intltoolize --version) &lt; /dev/null &gt; /dev/null 2&gt;&amp;1 || {
  45     echo;
  46     echo "You must have intltool installed to compile &lt;YOUR PLUGIN NAME&gt;";
  47     echo;
  48     exit;
  49 }
  50 </programlisting>
  51 Then before your call to aclocal add:
  52 <programlisting>
  53 intltoolize --force --copy
  54 </programlisting>
  55     </para></listitem>
  56     <listitem><para>
  57 Now edit configure.ac and add the following:
  58 <programlisting>
  59 AC_PROG_INTLTOOL
  60
  61 GETTEXT_PACKAGE=&lt;YOUR PLUGIN NAME&gt;
  62 AC_SUBST(GETTEXT_PACKAGE)
  63 AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, ["$GETTEXT_PACKAGE"], [Define the gettext package to be used])
  64
  65 ALL_LINGUAS=""
  66 AM_GLIB_GNU_GETTEXT
  67 </programlisting>
  68 The position of these macros in the file don't really matter, but if you
  69 have issues either play around with it or feel free to ask one of the Pidgin
  70 developers.  Finally add 'po/Makefile.in' to you 'AC_OUTPUT' command.
  71     </para></listitem>
  72     <listitem><para>
  73 Now create a directory named 'po'.
  74     </para></listitem>
  75     <listitem><para>
  76 'cd' into the 'po' directory.
  77     </para></listitem>
  78     <listitem><para>
  79 Create/edit the file 'POTFILE.in' in your favorite editor.  Each line
  80 should be the name of a file that could or does have strings marked for
  81 translating (we're getting to that step).  These file names should be
  82 relative to the top directory of your plugin's source tree.
  83     </para></listitem>
  84     <listitem><para>
  85 'cd' back to the top directory of your plugin's source tree.
  86     </para></listitem>
  87     <listitem><para>
  88 Open 'Makefile.am' and add 'po' to your 'SUBDIRS' variable.
  89     </para></listitem>
  90     <listitem><para>
  91 While still in the top directory of your plugin's source tree,  execute
  92 'intltool-prepare'.  This will setup anything extra that intltool needs.
  93     </para></listitem>
  94     <listitem><para>
  95 Fire off 'autogen.sh' and when it's completed, verify that you have a
  96 'po/POTFILES' (notice the lack of a .in).  If you do, everything should be
  97 set on the autotools side.
  98     </para></listitem>
  99     <listitem><para>
 100 Take a break, stretch your legs, smoke a cigarette, whatever, because
 101 we're done with the autotools part.
 102     </para></listitem>
 103     <listitem><para>
 104 When you're ready, 'cd' into the directory with the source files for your
 105 plugin.
 106     </para></listitem>
 107     <listitem><para>
 108 Open the file containing the 'plugin_query' function.
 109     </para></listitem>
 110     <listitem><para>
 111 If you're not already, please make sure that you are including the
 112 'config.h' file for you plugin.  Note that 'config.h' could be whatever
 113 you told autohead to use with AM_CONFIG_HEADER.  Also add the following:
 114 <programlisting>
 115 #include &lt;glib/gi18n-lib.h&gt;
 116 </programlisting>
 117 Make sure that this include is after you include of your 'config.h',
 118 otherwise you will break your build.  Also note that if you wish to
 119 maintain compatibility with older versions of GLib, you will need to
 120 include additional preprocessor directives, which we won't cover here.
 121     </para></listitem>
 122     <listitem><para>
 123 This is where things get a bit goofy.  libpurple is going to try to
 124 translate our strings using the libpurple gettext package.  So we have to
 125 convert them before libpurple attempts to.
 126     </para></listitem>
 127     <listitem><para>
 128 To do this, we're going to change the entries for name, summary, and
 129 description to NULL.
 130     </para></listitem>
 131     <listitem><para>
 132 Next, locate your 'plugin_load' function.  Your name for this function
 133 may vary, but it's the third parameter to 'PURPLE_PLUGIN_INIT'.
 134     </para></listitem>
 135     <listitem><para>
 136 Now add the following within your 'plugin_load' function:
 137 <programlisting>
 138         bindtextdomain(GETTEXT_PACKAGE, PURPLE_LOCALEDIR);
 139         bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8");
 140
 141         info.name        = _("&lt;YOUR PLUGIN NAME&gt;");
 142         info.summary     = _("&lt;YOUR PLUGIN SUMMARY&gt;");
 143         info.description = _("&lt;YOUR PLUGIN DESCRIPTION&gt;");
 144 </programlisting>
 145 Note that the _() is intentional, and that it is telling intltool that
 146 this string should be translated.  There is also N_() which says that a
 147 string should only be marked for translation but should not be translated
 148 yet.
 149     </para></listitem>
 150     <listitem><para>
 151 Go through the rest of your code and mark all the other strings for
 152 translation with _().
 153     </para></listitem>
 154     <listitem><para>
 155 When thats done, feel free to commit your work, create your po template
 156 (pot file) or whatever.
 157     </para></listitem>
 158     <listitem><para>
 159 To create you po template, 'cd' to 'po' and execute:
 160 <programlisting>
 161 intltool-update --pot
 162 </programlisting>
 163     </para></listitem>
 164     <listitem><para>
 165 To add new translations to your plugin, all you have to do is add the
 166 language code to the 'ALL_LINGUAS' variable in your configure.ac.  Take
 167 note that this list of languages should be separated by a space.  After
 168 you have added the language code to 'ALL_LINGUAS', drop the xx.po file
 169 into 'po', and re-'autogen.sh'.  After a full build you should now be
 170 able to use the translation.
 171     </para></listitem>
 172   </itemizedlist>
 173   </para>
 174  </sect2>
 175 </chapter>