Added kmymoney

git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/applications/kmymoney@1239792 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 248 insertions, 0 deletions

diff --git a/developer-doc/phb/translation.docbook b/developer-doc/phb/translation.docbook
new file mode 100644
index 0000000..2a171f6
--- /dev/null
+++ b/developer-doc/phb/translation.docbook
@@ -0,0 +1,248 @@
+
+<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/kde3/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>