path: root/developer-doc/phb/translation.docbook

<chapter id="translation">
<chapterinfo>
<authorgroup>
<author>
        <firstname>J.</firstname>
        <surname>Rundholz</surname>
</author>
</authorgroup>
</chapterinfo>

<title>Translation</title>
<para>
This chapter should give any one (in particular people who are not developers) a first overview on how they can translate &app; into another language. The information given here is not only valid for &app; but as serves for the translation of any KDE project.
</para>


<sect1 id="files">
<title>Basics</title>

<para>
First of all you need to get the required files. There are two types of files which might be of interest to you.
Files ending in <literal role="extension">.pot</literal> and files ending
in <literal role="extension">.po</literal>.
</para>
<para>
Files ending in <literal role="extension">.pot</literal> are the source
for the translation.
They only contain the English texts you need to translate and are generated
for each release of the project.  The one for &app; is named <filename>kmymoney2.pot</filename>.
The po file contains the English and the translated text, e.g. German.
There might be two cases: The first case you can't find a po file for your
language or the second there is already a po file for your language available.
In the latter case you can already start &app; in your language, but may be the
translation is not complete or you simply want to improve the translation.

Now you need to get these files from the project's &cvs; repository.
You don't need to worry what exactly &cvs; does, for a translater it
is more or less only a file system from where
you can download the files you need. For &app; you can either go to the &cvs;
page and call the &cvs; web front end or follow
<ulink url="http://kmymoney2.cvs.sourceforge.net/kmymoney2/kmymoney2/po/?pathrev=rel-0-8-branch">this link</ulink>.
I would recommend to download the pot and po file of the latest stable version
(at the moment 0.8), not any older files and not the one which is under
development at the moment. In order to test your translation later you should
run the same version on your box.

For the actual translation I recommend the program <application>kbabel</application>.
Other people use <application>emacs</application>, as usual it is just a personal
choice. All examples given here are based on <application>kbabel</application>.

</para>

<sect2 id="po-file">
<title>How to get your po file</title>
<para>
As explained earlier the actual translation is done by modifying the po file.
The next step is to create a po file to start the translation.
</para>

<sect3 id="no-po">
<title>No po file for my language available</title>
<para>
That's the most simple case: Rename <filename>kmymoney2.pot</filename> to
<filename><emphasis>lang</emphasis>.po</filename> where <emphasis>lang</emphasis>
is your language code e.g. <emphasis>de</emphasis> for German.
</para>

</sect3>

<sect3 id="po">
<title>po file for my language available</title>
<para>
In case you already have a language file it is advisable that you check how
the English text entries in that file differ from the English texts in the
pot file. Maybe for some reason the pot file is further developed than the
po file. In this case even though you would translate the whole po file you
would still see some English texts in &app;. If you know that this is not
the case, i.e. your po file has all the latest English text inside, you can
use this one for translation. The minimum check you should perform is to
compare the number of messages. Just load the po and the pot file into kbabel
and you see how many messages you have in each file.
</para>
<para>
In case that both files differ you should merge them (since
you don't want to lose someone else's work). Merging can be
done using <application>kbabel</application> very easily .

<itemizedlist>
<listitem>
<para>
Copy <filename>kmymoney2.pot</filename> to <filename>lang-new.po</filename>
and open this file with <application>kbabel</application>.
</para>
</listitem>
<listitem>
<para>
In <application>kbabel</application> choose
<guimenu>
Tools
<guimenuitem>Rough translation</guimenuitem>
</guimenu>
from the menu. A dialog pops up. Choose the following options:
<itemizedlist>
<listitem><para>What to translate::Untranslated Entries</para></listitem>
<listitem><para>Options::Mark changed entries as fuzzy</para></listitem>
<listitem><para>Dictionaries::Use::PO Compendium</para></listitem>
</itemizedlist>
Don't select anything else.
</para>
</listitem>
<listitem>
<para>
Now press the "configure" button. In the next dialog enter the path to your
already existing po file. Furthermore set the options:
<itemizedlist>
<listitem><para>Options::Case sensitive</para></listitem>
<listitem><para>A text matches if::Equal to searched text</para></listitem>
</itemizedlist>
Don't select anything else.
</para>
</listitem>
</itemizedlist>
<caution>
The original po file could have entries marked as "fuzzy", that means that
the translation might be not very good or even horribly wrong. After you
did this merger process you lose this information. It might be a good
idea to translate all fuzzy strings in the old, unmerged po file before
you do this explained merging process.
</caution>
</para>
</sect3>
</sect2>
</sect1>
<sect1 id="translating">
<title>Translating</title>
<para>
Now you can take the new po file and start the translation with kbabel
or any other tool. It might be a good idea to create a glossary of terms
whenever you use a technical term. Such a glossary is available for the
German translation, check it out to see how it should look like. You might
want to check the gnucash project if they have already a glossary for your
language. This would be a starting point for you, but please extend it.
</para>
</sect1>
<sect1 id="testing">
<title>Test your work</title>
<para>
Last but not least you need to check your translation, especially if the
translated text fits into the context. Also you shouldn't be surprised
how many typos and mistakes you make while translating the text. Check
it carefully! Now a few steps you should perform to test your translation
(after you used a spellchecker etc.).
</para>
<para>
First you can run the command

<screen>

  <prompt>thb:~&gt; </prompt><userinput><command>msgcat</command> <option>--width=77</option> <option>-o</option> <replaceable>lang-output.po</replaceable> <replaceable>lang-input.po</replaceable></userinput>

</screen>

as root. This command just restricts the length of each line to 77
characters. This is only necessary if you want to read the raw po file in
some text editor. Some people who do proof reading prefer this instead of
endless lines. The number of characters depends of some personal taste. I
prefer about 50 characters per line, then a diff file can be displayed
without vertical scrolling.
</para>
<para>
Now run as root the command

<screen>

  <prompt>thb:~&gt; </prompt><userinput><command>msgfmt</command> <option>-vvv</option> <replaceable>lang.po</replaceable> kmymoney2.mo</userinput>

</screen>

The mo file is the language file you need for your program. You just need
to replace the original mo file of &app; with this one (perform a backup of
the original file before). The location of your mo file depends on your
distro, for SuSE it is <filename>/opt/trinity/share/local/lang/LC_MESSAGES</filename> and for Debian
<filename>/usr/share/local/lang/LC_MESSAGES</filename>. For lang you can use
any string, like de or even de_test if you want to run it with a test
language. Be aware that &app; uses some text strings from KDE and since they
are probably not available with de_test you still might see some English
text. If you can't find the file on your harddrive try either

<screen>

  <prompt>thb:~&gt; </prompt><userinput><command>find</command> / <option>-name</option> kmymoney2.mo</userinput>

</screen>

as root or if you used an <command>rpm</command> file for the
installation you can run

<screen>

  <prompt>thb:~&gt; </prompt><userinput><command>rpm</command> <option>-q kmymoney2</option> <option>--filesbypkg</option></userinput>

</screen>

</para>
<para>
In order to run &app; either start it as usual (if your default KDE language
is the language you want to test) or call it via

<screen>

  <prompt>thb:~&gt; </prompt><userinput>KDE_LANG=de <command>kmymoney2</command></userinput>

</screen>

from a <application>konsole</application> or
<application>xterm</application>.
</para>
</sect1>
<sect1 id="merging">
<title>Merging an old po file with an updated pot file</title>
<para>
There are cases when the pot file is regenerated before you can send your 
updated po file. If you just commit your file after that, it will show up 
as old in the translation stats, because it references an outdated pot file.
</para>
<para>
To fix this, you have to merge the po file with the updated pot file.

First, get the latest pot file. And in the po folder, run this command.

<screen>

  <prompt>thb:~/kmymoney2/po&gt; </prompt><userinput><command>make</command> <option>-f</option> <option>../admin/Makefile.common</option> <option>package-merge</option> <option>POFILES=<replaceable>"de.po"</replaceable></option> <option>PACKAGE=kmymoney2</option></userinput>

</screen>

You can merge multiple po files at the same time. Just list them in the POFILES option.

<screen>

  <prompt>thb:~/kmymoney2/po&gt; </prompt><userinput><command>make</command> <option>-f</option> <option>../admin/Makefile.common</option> <option>package-merge</option> <option>POFILES=<replaceable>"de.po es.po"</replaceable></option> <option>PACKAGE=kmymoney2</option></userinput>

</screen>

</para>
</sect1>
</chapter>