[Koha-cvs] CVS: koha-doc/en/sysadmin/templates translation.xml,NONE,1.1

[skemotah]

Update of /cvsroot/koha/koha-doc/en/sysadmin/templates
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv10138/templates

Added Files:
	translation.xml 
Log Message:
Initial xml markup

--- NEW FILE ---
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<article>
  <title>KOHA's Template Translation</title>

  <articleinfo>
    <pubdate>2005-06-22</pubdate>

    <author>
      <firstname>J. Martin</firstname>

      <surname>Longo</surname>

      <email>jmlongo AT uncu.edu.ar</email>
    </author>

    <copyright>
      <year>2005</year>

      <holder>J. Martin Longo</holder>
    </copyright>

    <legalnotice>
      <para>This document is related to Koha and is licensed to you under the
      GNU General Public License version 2 or later (<ulink
      url="http://www.gnu.org/licenses/gpl.html">http://www.gnu.org/licenses/gpl.html</ulink>).</para>

      <para>Koha-related documents may be reproduced and distributed in whole
      or in part, in any medium physical or electronic, as long as this
      copyright notice is retained on all copies.</para>

      <para>You may create a derivative work and distribute it provided that
      you:</para>

      <orderedlist>
        <listitem>
          <para>License the derivative work with this same license, or the
          Linux Documentation Project License (<ulink
          url="http://www.tldp.org/COPYRIGHT.html">http://www.tldp.org/COPYRIGHT.html</ulink>).
          Include a copyright notice and at least a pointer to the license
          used.</para>
        </listitem>

        <listitem>
          <para>Give due credit to previous authors and major
          contributors.</para>
        </listitem>
      </orderedlist>

      <para>Commercial redistribution is allowed and encouraged; however, the
      author would like to be notified of any such distributions.</para>

      <para>No liability for the contents of this document can be accepted.
      Use the concepts, examples and information at your own risk. There may
      be errors and inaccuracies, that could be damaging to your system.
      Proceed with caution, and although this is highly unlikely, the
      author(s) do not take any responsibility.</para>

      <para>All copyrights are held by their by their respective owners,
      unless specifically noted otherwise. Use of a term in this document
      should not be regarded as affecting the validity of any trademark or
      service mark. Naming of particular products or brands should not be seen
      as endorsements.</para>
    </legalnotice>

    <revhistory>
      <revision>
        <revnumber>2.2.2</revnumber>

        <date>2005-06-22</date>

        <revdescription>
          <para>Initial XML markup.</para>
        </revdescription>
      </revision>
    </revhistory>
  </articleinfo>

  <section>
    <title>Introduction</title>

    <note>
      <para>It's assumed, in every example, that you have downloaded the file
      <filename>koha-2.x.tar.gz</filename> and that you have unpacked it in
      the 'home' directory of the 'user' user. Provided this, you should have
      a <filename>koha-2.x</filename> directory under
      <filename>/home/user/</filename></para>

      <para>In each system, directory and user names should be replaced
      accordingly.</para>
    </note>

    <para>KOHA internationalization can be achieved in several ways. Not so
    long ago, it was necesary to copy the entire
    <filename>/home/usuario/koha-2.x/intranet-html/intranet-tmpl/default/en</filename>
    directory into another (i.e.
    <filename>/home/usuario/koha-2.x/intranet-html/intranet-tmpl/default/es</filename>)
    then manually edit each one of the templates contained in the newly
    created directory, translating the text strings they contain, trying, of
    course, not to touch or change anything else. Once the translation was
    finished, it was only necesary to configure KOHA's 'opaclanguages' System
    Preference to use the new language (i.e. es).</para>

    <para>This procedure works and has produced acceptable results but is,
    obviously, very slow and difficult.</para>

    <para>Now, thanks to KOHA's developer team, we have the
    <filename>tmpl_process3.pl</filename> script (provided with the KOHA
    distribution).</para>

    <para>In short, this script takes the file or directory that we want to
    translate (i.e.
    <filename>/home/usuario/koha-2.x/intranet-html/intranet-tmpl/default/en</filename>)
    and generates a single '.po' file (.po comes from Portable Object)
    containing only the text strings contained inside KOHA's template files.
    This type of file is a format standard in the software
    internationalization work in the Free Software world and, because of this,
    there are several tools developed to edit them.</para>

    <para>The present tutorial aims to show how to use the
    <filename>tmpl_process3.pl</filename> script to generate a '.po' file from
    KOHA's templates, introduce the use of one of the tools developed for
    '.po' files treatment (<application>Kbabel</application>) and then the use
    of the <filename>tmpl_process3.pl</filename> script again, to generate a
    set of translated templates for use in our KOHA installation.</para>
  </section>

  <section>
    <title>Using tmpl_process3.pl to generate a '.po' file</title>

    <para>The <filename>tmpl_process3.pl</filename> script lives under the
    <filename>/home/usuario/koha-2.x/scripts/misc/translator/</filename>
    directory and depends on some modules located under the same directory.
    Because of this, in order for it to work, the script must be run from
    inside that directory.</para>

    <example>
      <title>Running tmpl_process3.pl</title>

      <programlisting>user at host: cd /home/usuario/koha-2.x/scripts/misc/translator/ 

user at host: ./tmpl_process3.pl --help</programlisting>
    </example>

    <para>The previous command will produce, as output, a list of options and
    a little help about the script's usage, as shown below:</para>

    <programlisting>Usage: ./tmpl_process3.pl create [OPTION]
  or:  ./tmpl_process3.pl update [OPTION]
  or:  ./tmpl_process3.pl install [OPTION]
  or:  ./tmpl_process3.pl --help
Create or update PO files from templates, or install translated templates.

  -i, --input=SOURCE          Get or update strings from SOURCE file.
                              SOURCE is a directory if -r is also specified.
  -o, --outputdir=DIRECTORY   Install translation(s) to specified DIRECTORY
      --pedantic-warnings     Issue warnings even for detected problems
                              which are likely to be harmless
  -r, --recursive             SOURCE in the -i option is a directory
  -s, --str-file=FILE         Specify FILE as the translation (po) file
                              for input (install) or output (create, update)
  -x, --exclude=REGEXP        Exclude files matching the given REGEXP
      --help                  Display this help and exit

The -o option is ignored for the "create" and "update" actions.
Try `perldoc ./tmpl_process3.pl' for perhaps more information.</programlisting>

    <para>To create a 'circ_es.po' containing the text strings of the English
    templates located in the 'circ' directory of the KOHA's intranet, the
    procedure would be:</para>

    <programlisting>user at host: cd /home/user/koha-2.x/scripts/misc/translator/ 

user at host: ./tmpl_process3.pl create -r -i /home/user/koha-2.x/intranet-html/intranet-tmpl/default/en/circ/ -s /home/user/translation/circ_es.po</programlisting>

    <para>In the above example:</para>

    <itemizedlist>
      <listitem>
        <para>'<emphasis role="bold">create</emphasis>' indicates that we want
        to create a new '.po' file.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">-r</emphasis> indicates that the source is
        a directory.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">-i</emphasis> indicates the path from
        where the text string will be extracted.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">-s</emphasis> indicates the path and name
        of the '.po' file that will be created.</para>
      </listitem>
    </itemizedlist>

    <para>When running the script, there may be some 'warnings' about syntax
    errors in the original templates.</para>

    <para>Output will look like this:</para>

    <programlisting>Warning: Can't determine original templates' charset, defaulting to ISO-8859-1
Removing empty file /home/user/tmp/temp.po
xgettext.pl: Warning (negligible): selectbranchprinter.tmpl: line 15: Suggest ESCAPE=HTML for TMPL_VAR in attribute "value": "&lt;!-- TMPL_VAR NAME="value" --&gt;"
xgettext.pl: Warning (negligible): selectbranchprinter.tmpl: Further similar negligible warnings will not be reported, use --pedantic for details
xgettext.pl: Warning: returns.tmpl: line 17: Strange attribute syntax: /cgi-bin/koha/moremember.pl?bornum=&lt;!-- TMPL_VAR NAME="bornum" --&gt;", "Member"); return false;"
xgettext.pl: Warning: branchtransfers.tmpl: line 20: Probably missing whitespace before or missing quotation mark near: Member", 480, 640); return false;"
xgettext.pl: Warning: branchtransfers.tmpl: line 22: Probably missing whitespace before or missing quotation mark near: Member", 480, 640); return false;"
xgettext.pl: Warning: branchtransfers.tmpl: line 98: Probably missing whitespace before or missing quotation mark near: Member", 480, 640); return false;"
xgettext.pl: Warning: branchtransfers.tmpl: line 128: Probably missing whitespace before or missing quotation mark near: Item", 480, 640); return false;"
The create seems to be successful.</programlisting>

    <para>Despite these warnings, the last line (<emphasis role="bold">The
    create seems to be successful.</emphasis>) indicates that the process has
    ended successfully and that now we have our brand new 'circ_es.po' file in
    <filename>/home/user/translation/</filename> so now we can use
    <application>Kbabel</application> to begin the translation process.</para>
  </section>

  <section>
    <title>Using KBabel to translate a '.po' file</title>

    <para>The <application>KBabel</application> application presents four
    areas, inside the mail window, each one oriented to a particular function.
    You'll work translating the text strings extracted from the templates one
    by one.</para>

    <para>To achieve this efficiently, <application>KBabel</application> gives
    you several tools, as can be seen in the next screenshot:</para>

    <figure>
      <title>Screenshot 1</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="imagesfolder/image1.gif" />
        </imageobject>
      </mediaobject>
    </figure>

    <itemizedlist>
      <listitem>
        <para>The area marked as <emphasis role="bold">Original
        Text</emphasis> is read only and displays the text string to be
        translated.</para>
      </listitem>

      <listitem>
        <para>The area marked as <emphasis role="bold">Translated
        Text</emphasis> is where we will write the translation of the string
        displayed in the <emphasis role="bold">Original Text</emphasis>
        area.</para>
      </listitem>

      <listitem>
        <para>The area marked as <emphasis role="bold">File Names</emphasis>
        displays the path and name of the template files where the text string
        being translated was extracted from.</para>
      </listitem>

      <listitem>
        <para>The area marked as <emphasis role="bold">Context</emphasis>
        displays the previous and next text strings to the one being
        translated, to provide some help about the context of the current text
        string.</para>
      </listitem>
    </itemizedlist>

    <section>
      <title>Examples</title>

      <para>Some tags and markups should not be modified during
      translation:</para>

      <figure>
        <title>Screenshot 2</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="imagesfolder/image2.gif" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>Whenever the translation implies the use of accented words or
      special characters, they should be replaced with the corresponding
      entities, to avoid visualisation problems or errors.</para>

      <figure>
        <title>Screenshot 3</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="imagesfolder/image3.gif" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>To navigate between text strings and launch some useful commands,
      there are shortcuts in the toolbar and many keyboard key
      combinations.</para>

      <informaltable>
        <tgroup cols="2">
          <tbody>
            <row>
              <entry align="center" valign="middle"><emphasis
              role="bold">Command</emphasis></entry>

              <entry align="center" valign="middle"><emphasis
              role="bold">Keyboard</emphasis></entry>
            </row>

            <row>
              <entry>Next text string</entry>

              <entry><emphasis role="bold">PgDown</emphasis></entry>
            </row>

            <row>
              <entry>Previous text string</entry>

              <entry><emphasis role="bold">PgUp</emphasis></entry>
            </row>

            <row>
              <entry>Next not translated text string</entry>

              <entry><emphasis role="bold">Alt+PgDown</emphasis></entry>
            </row>

            <row>
              <entry>Previous not translated text string</entry>

              <entry><emphasis role="bold">Alt+PgUp</emphasis></entry>
            </row>

            <row>
              <entry>Copy the text string displayed on the Original Text area
              to the Translated Text area</entry>

              <entry><emphasis role="bold">Ctrl+Space</emphasis></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>
  </section>

  <section>
    <title>Using tmpl_process3.pl to generate translated templates</title>

    <para>Following the previous examples, we have created a '.po' file named
    <filename>circ_es.po</filename> containing all the text strings present in
    the templates located at
    <filename>/home/user/koha-2.x/intranet-html/intranet-tmpl/default/en/circ</filename></para>

    <para>Afterwards, we used <application>Kbabel</application> to translate
    all those text strings.</para>

    <para>Finally, we only need to generate a new set of translated templates,
    using the original ones as a basis. For this example, we will create our
    new set of translated templates in the
    <filename>/home/user/koha-2.x/intranet-html/intranet-tmpl/default/es/circ</filename>
    directory.</para>

    <para>To achieve this, we'll use the <filename>tmpl_process3.pl</filename>
    script again, but with slightly different parameters:</para>

    <programlisting>user at host: cd /home/user/koha-2.x/scripts/misc/translator/ 

user at host: ./tmpl_process3.pl install -s /home/user/translation/circ_es.po -r -i /home/user/koha-2.x/intranet-html/intranet-tmpl/default/en/circ/ -o /home/user/koha-2.x/intranet-html/intranet-tmpl/default/es/circ/</programlisting>

    <para>In the above example:</para>

    <itemizedlist>
      <listitem>
        <para>'<emphasis role="bold">install</emphasis>' indicates that we
        want to create a set of templates from a '.po' file.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">-r</emphasis> indicates that the target is
        a directory.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">-i</emphasis> indicates the path where the
        original templates are located (the ones we extracted the text strings
        from).</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">-s</emphasis> indicates the path and name
        of the '.po' file that will be used in the process.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">-o</emphasis> indicates the path where the
        new set of translated templates will be created.</para>
      </listitem>
    </itemizedlist>

    <para>As happened when we launched the script to create the '.po' file,
    there may be some 'warnings' about syntax errors in the original
    templates.</para>

    <para>Output will look like this:</para>

    <programlisting>Warning: Can't determine original templates' charset, defaulting to ISO-8859-1
Creating /home/jmlongo/documentos/koha/koha-2.1.1/intranet-html/intranet-tmpl/default/pl/circ//selectbranchprinter.tmpl...
tmpl_process3.pl: Warning (negligible): selectbranchprinter.tmpl: line 15: Suggest ESCAPE=HTML for TMPL_VAR in attribute "value": "&lt;!-- TMPL_VAR NAME="value" --&gt;"
tmpl_process3.pl: Warning (negligible): selectbranchprinter.tmpl: Further similar negligible warnings will not be reported, use --pedantic for details
Creating /home/jmlongo/documentos/koha/koha-2.1.1/intranet-html/intranet-tmpl/default/pl/circ//returns.tmpl...
tmpl_process3.pl: Warning: returns.tmpl: line 17: Strange attribute syntax: /cgi-bin/koha/moremember.pl?bornum=&lt;!-- TMPL_VAR NAME="bornum" --&gt;", "Member"); return false;"
Creating /home/jmlongo/documentos/koha/koha-2.1.1/intranet-html/intranet-tmpl/default/pl/circ//circulation.tmpl...
Creating /home/jmlongo/documentos/koha/koha-2.1.1/intranet-html/intranet-tmpl/default/pl/circ//branchtransfers.tmpl...
tmpl_process3.pl: Warning: branchtransfers.tmpl: line 20: Probably missing whitespace before or missing quotation mark near: Member", 480, 640); return false;"
tmpl_process3.pl: Warning: branchtransfers.tmpl: line 22: Probably missing whitespace before or missing quotation mark near: Member", 480, 640); return false;"
tmpl_process3.pl: Warning: branchtransfers.tmpl: line 98: Probably missing whitespace before or missing quotation mark near: Member", 480, 640); return false;"
tmpl_process3.pl: Warning: branchtransfers.tmpl: line 128: Probably missing whitespace before or missing quotation mark near: Item", 480, 640); return false;"
The install seems to be successful.</programlisting>

    <para>Despite these warnings, the last line (<emphasis role="bold">The
    install seems to be successful.</emphasis>) indicates that the process has
    ended successfully and that now we have our brand new set of translated
    templates at
    <filename>/home/user/koha-2.x/intranet-html/intranet-tmpl/default/es/circ</filename>
    directory.</para>

    <para>To verify this you can use your favorite text editor to open one of
    the various templates located in that directory.</para>
  </section>

  <section>
    <title>Questions, complaints and proposals</title>

    <para>If you have any questions about the process outlined in this
    document or a comment that helps to improve it, you can reach me (Martin
    Longo) at <email>jmlongo AT uncu.edu.ar</email>.</para>
  </section>
</article>