tdesdk/doc/kbabel/using.docbook

<!-- <?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> -->
<!-- Uncomment the previous two lines to validate this document -->
<!-- standalone.  Be sure to recomment them before attempting to -->
<!-- process index.docbook -->

<chapter id="using-kbabel">
<chapterinfo>
<!-- Fill in this section if this document has a different author -->
<authorgroup>
<author>
<personname><firstname></firstname><surname></surname></personname>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->
</chapterinfo>


<title>Using &kbabel;</title>

<sect1 id="using-introduction">
<title>Introduction</title>

<para>Usually program messages and documentation are written in
English.  Using a framework made of a set of tools and libraries, it
is possible to have your favorite applications speak your native
non-English language.  This process of adapting an application to a
specific language is known as localization.  The localization process
includes translating the program's interfaces and documentation to the
various languages users need and, in some countries or regions, making
the inputs and outputs conform to particular conventions.  &kbabel; is
a tool which will assist you in the localization process to
make an application's interface speak many languages.</para>

<para> Every internationalization-aware program makes available for
translation one or more message-catalog files. The extension of these
files is <literal role="extension">.pot</literal>.
<acronym>POT</acronym> is an acronym for <quote>Portable Object
Template</quote>.</para>

<para>
Each translator takes a copy of one of these <acronym>POT</acronym> templates and
begins to fill in the blanks: each message is translated into the
language desired.  The file containing the translated text is referred
to as a <acronym>PO</acronym> (Portable Object) file.
</para>

<para>
Once all the messages have been translated, the
<acronym>PO</acronym> file is compiled into a machine-readable binary
format, known as a <acronym>MO</acronym> (Machine Object) file.  These
files, which will be stored with a <literal
role="extension">.mo</literal> extension
(or a <literal role="extension">.gmo</literal> extension to show
that they were processed by &GNU; gettext), act as a database to
minimize the time taken by the applications to look up each translated
message.
</para>

<para> This suggests a question: do I need to know what is
inside a <acronym>PO</acronym> file even though I have &kbabel;?  The
answer is, undoubtedly, yes.  There are situations when a message
catalog can become corrupted and needs to be manually fixed.  Most of
these problems are the so-hated <acronym>CVS</acronym> or <acronym>SVN</acronym> conflicts which
occur when a translating process is coordinated by a version management
system, like <acronym>CVS</acronym> or Subversion (<acronym>SVN</acronym>).
&kbabel; cannot help you much if a problem like this arises so a
text editor and some knowledge of <acronym>PO</acronym>-files are
needed. Let's see how a <acronym>PO</acronym> file is made.</para>

<para><acronym>PO</acronym> files consist of pairs of messages&mdash;a
<emphasis>msgid</emphasis> and a <emphasis>msgstr</emphasis>.  The
msgid is the text in English and the msgstr is the text translated
into the appropriate language.  The text that accompanies each msgid
and msgstr is enclosed within C-like double quotes. An example, taken
from a <acronym>PO</acronym> file for &noatun;, is <literal>msgid
&quot;Open a Playlist&quot;</literal> </para>

<!-- ### TODO: we would need an example of an entry -->

<para>Empty lines and those starting with <literal>#</literal> are
ignored.  Lines starting with a # represent comments and are a useful
way of providing a note detailing which file this message is going
to be used in and, in the case of the application writers, to provide
additional comments to help translation.  &kbabel; displays these
comment lines for every message.</para>

<para>In many cases the first msgid-msgstr pair in
<acronym>PO</acronym> file is a fake entry (acting as
<acronym>PO</acronym> file header) that contains various information
about the translated <acronym>PO</acronym> file, such as the
application name, translating date, translator name and so on.</para>

<para>
An useful feature is called <emphasis>plural forms</emphasis>.
English uses only singular and one plural form of nouns, &eg; <quote>1 file
</quote> and <quote>10 files</quote>. This leads many developers
to an idea that the world is that simple and they can use messages like
<quote>Do you want to delete %1 file(s)?</quote>, where
<literal>%1</literal> denotes a number of files to be deleted.
But this is fundamentally wrong and for many languages such a kind of translation
will not work. For Slovak translation you need 3 different
forms of the message. This number is  different for different languages
and even when it is the same, &eg; Czech uses 3 forms as well, the rule to decide which
form to use can be very different. Plural forms in <acronym>PO</acronym> files are here to help.
</para>

<note><para>
&kde; developers have chosen a different implementation for the plural forms than
<application>&GNU; gettext</application> and they have introduced their own
format and handling for them.
It is planned to use &GNU; gettext's plural forms in &kde; version 4.
</para></note>

</sect1>

<sect1 id="using-editor">
<title>Editor</title>

<para>Here is a screenshot of &kbabel;.</para>

<screenshot>
<screeninfo>Screenshot of &kbabel;</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="snap1.png" format="PNG"/>
</imageobject>
<textobject><phrase>Screenshot of &kbabel;</phrase></textobject>
</mediaobject>
</screenshot>

<para>
For convenience &kbabel; has
toolbars to speed up many operations and, for busy users, there are
many keyboard shortcuts.  The main window is divided into four
parts.
</para>

<para>The <emphasis>upper-left</emphasis> edit box is read-only and
contains the current msgid field from the opened PO-file and its
English text.</para>

<para>The <emphasis>bottom-left</emphasis> edit box contains the
msgstr field related to the msgid shown and here you can edit the
translated text.</para>

<para>The <emphasis>top-right</emphasis> part of the window is a comments
panel where you can view the comments added for entry currently being
edited.</para>

<para>It can be used:</para>

<itemizedlist>
<listitem><para>
to find out how the current message is treated by the
application (c-formatted or simple)
</para></listitem>
<listitem><para>
in some cases, to read helpful comments added by the application's
developer to assist the translators in their work&mdash;for example,
there may be technical hints (used to great effect in the
<application>LyX</application> project)
</para></listitem>
<listitem><para>
when you need to know which file a message is from because you
want to report a spelling mistake in the original English string.
</para></listitem>
</itemizedlist>

<para>
The editor window (in the bottom right) is the most sophisticated part
of &kbabel;'s main window.  Its size can be
adjusted using the splitter line between it and the comment panel
(the panel in the top right).
The editor window has two tabbed panels&mdash;one storing search
information, the other context information. The context information
tab contain a scrolled view which shows the previous and next 4 entries
associated with the current entry&mdash;essentially it's a small
'snapshot' of the PO file.  While translating, it is very common for
message strings to be related to subsequent and previous messages,
so the context panel is useful for looking at the nearby messages to
get a hint as to how the current message can best be
translated.  Dialog interface translation is a good example, or widgets
with their associated text and "what's this" message.
</para>

<sect2 id="more-kbabel-features">
<title>More &kbabel; Features</title>

<para>
Each msgid entry can be in three states:
</para>

<variablelist>
   <varlistentry>
     <term>untranslated</term>
     <listitem>
       <para>
        there is no translated text currently associated with the msgstr
       </para>
     </listitem>
   </varlistentry>
   <varlistentry>
      <term>fuzzy</term>
      <listitem>
         <para>
    <command>msgmerge</command> has tried to match a translated
    string by looking in rest of PO-file entries. This does not work
    perfectly and you must edit the translated text to fit the current
    English text.
         </para>
      </listitem>
   </varlistentry>
   <varlistentry>
      <term>translated</term>
      <listitem>
         <para>
         the msgid is the completed translated form of the msgstr
         </para>
      </listitem>
   </varlistentry>
</variablelist>

<para>The state of the current entry is indicated by two
<acronym>LED</acronym>s.  Depending on your configuration these can
either be in the status bar or above the <guilabel>translated
string</guilabel> edit box.  Both have a customizable color (to
reflect your visual requirements or taste).  Please read the <link
linkend="preferences">Preferences</link> section to see how you can
adjust these settings.</para>

</sect2>

</sect1>

<sect1 id="kbabel-features">
<title>Advanced Translation</title>

<para>
Now you have an idea how to translate a PO-file. In this section we will follow the standard way
of translating a new PO-file using the advanced features of &kbabel;. We assume you have already
opened a template POT-file and saved it as a PO file.
</para>

<sect2 id="kbabel-navigation">
<title>Navigation in PO-file</title>
<para>&kbabel; allows you to easily navigate through the file according to the state of their
translation. The untranslated/fuzzy status was introduced already. A message can be marked as erroneous
as a result of <link linkend="kbabel-validation">validation checking</link> or validation done by <command>msgfmt</command>.
And, of course, &kbabel; supports browsing the history of visited messages with 
<guilabel>Forward</guilabel>/<guilabel>Back</guilabel>, like in &konqueror;.</para>
<para>
All commands for navigation are in <menuchoice><guimenu>Go</guimenu></menuchoice> menu.
</para>
<informaltable>
<tgroup cols="2">
<tbody>

<row>
<entry><para><keycombo action="simul"><keycap>Page Up</keycap></keycombo></para></entry>
<entry><para>Move to the previous message </para></entry>
</row>
<row>
<entry><para><keycombo action="simul"><keycap>Page Down</keycap></keycombo></para></entry>
<entry><para> Move to the next message</para></entry>
</row>
<row>
<entry><para><keycombo action="simul">&Ctrl;<keycap>Page Up</keycap></keycombo></para></entry>
<entry><para>Move to the previous fuzzy message</para></entry>
</row>
<row>
<entry><para><keycombo action="simul">&Ctrl;<keycap>Page Down</keycap></keycombo></para></entry>
<entry><para>Move to the next fuzzy message</para></entry>
</row>
<row>
<entry><para><keycombo action="simul">&Alt;<keycap>Page Up</keycap></keycombo></para></entry>
<entry><para>Move to the previous untranslated message</para></entry>
</row>
<row>
<entry><para><keycombo action="simul">&Alt;<keycap>Page Down</keycap></keycombo></para></entry>
<entry><para>Move to the next  untranslated message</para></entry>
</row>
<row>
<entry><para><keycombo action="simul">&Shift;<keycap>Page Up</keycap></keycombo></para></entry>
<entry><para>Move to the previous error message</para></entry>
</row>
<row>
<entry><para><keycombo action="simul">&Shift;<keycap>Page Down</keycap></keycombo></para></entry>
<entry><para>Move to the next  error message</para></entry>
</row>
<row>
<entry><para><keycombo action="simul">&Ctrl;&Shift;<keycap>Page Up</keycap></keycombo></para></entry>
<entry><para>Move to the previous fuzzy or untranslated message</para></entry>
</row>
<row>
<entry><para><keycombo action="simul">&Ctrl;&Shift;<keycap>Page Down</keycap></keycombo></para></entry>
<entry><para>Move to the next fuzzy or untranslated message</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>

<sect2 id="kbabel-cleveredit">
<title>Clever editing</title>
<para><emphasis>Clever editing</emphasis> means that the editor will help you
easily edit the translation while taking into account specials of the PO format.
It will correctly <quote>escape</quote> as necessary.</para>
<para>
It also supports more than
one mode for inserting end of the line. This is very useful because of the way
gettext handles end of the lines. It simply ignores them. (You can imagine that
all the text in <acronym>msgstr</acronym> is a single line.) If you want insert a <quote>real</quote> end of the
line, you need to insert <userinput>\n</userinput>. But most of translators
do not realize, that a new line in <acronym>msgstr</acronym> does not
add any space between the lines. This can be easily solved by adding a space
at the end of every line. But you can easily forget, so clever editing does this automatically
for you.
</para>
<para>The table below summarizes clever editing features.
</para>

<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry><para><keycombo action="simul"><keycap>Tab</keycap></keycombo></para></entry>
<entry><para>Insert <emphasis>\t</emphasis></para></entry>
</row>
<row>
<entry><para><keycombo action="simul"><keycap>"</keycap></keycombo></para></entry>
<entry><para>Insert <emphasis>\"</emphasis></para></entry>
</row>
<row>
<entry><para><keycombo action="simul"><keycap>Enter</keycap></keycombo></para></entry>
<entry><para>If the last character before cursor is not a space, insert one space.
Then start a new line.</para></entry>
</row><row>
<entry><para><keycombo action="simul">&Ctrl;<keycap>Enter</keycap></keycombo></para></entry>
<entry><para>Start a new line without any additional logic</para></entry>
</row>
<row>
<entry><para><keycombo action="simul">&Shift;<keycap>Enter</keycap></keycombo></para></entry>
<entry><para>Insert <emphasis>\n</emphasis> and start a new line</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<note>
<para>
If you want to see where spaces are, you can turn on <guibutton>Highlight background</guibutton>
and/or <guibutton>Mark whitespaces with points</guibutton> in preferences dialog
on tab <guilabel>Edit</guilabel> <guilabel>Appearance</guilabel>.
</para>
</note>
</sect2>

<sect2 id="kbabel-roughtranslation">
<title>Automatic translation</title>
<para>As the first step when starting a new translation, &kbabel; provides a function
for automatic filling of the messages translations by the older translations. Choose
<menuchoice><guimenu>Tools</guimenu><guimenuitem>Rough Translation</guimenuitem>
</menuchoice>
and &kbabel; will present the following dialog:
</para>
<para>
<screenshot>
<screeninfo>Rough translation dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="roughtranslation.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
In the dialog, you should specify what to translate and choose the sources for
the old translations.
</para>
<para>
At the top of the <guilabel>What to translate</guilabel> frame are three
checkboxes (<guilabel>Untranslated entries</guilabel>, <guilabel>Fuzzy entries
</guilabel>, <guilabel>Translated entries</guilabel>) for specifying the kind of
messages you want to translate. Untranslated and fuzzy entries are natural
choices for automatic translation, but you can change already translated
messages as well.
</para>
<para>
The exact matching for <acronym>msgid</acronym>s will always be used for 
rough translation. However, you can add more strategies, &ie;
<guilabel>Allow fuzzy translation (slow)</guilabel> and 
<guilabel>Allow single word translation</guilabel>. Both of these
additional strategies must be supported by the sources used (see below).
There is no specification, what does <quote>fuzzy translation</quote> mean,
but the purpose is quite obvious. <quote>Single word translation</quote>
is suitable for only some of the languages. &kbabel; will try to translate
each word in <acronym>msgid</acronym> separately and then 
put the translated words (or phrases) in the same order in <acronym>msgstr
</acronym>.
</para>
<para>
As a source for rough translation, any dictionary module available can be 
used. There is a list of <guilabel>Don't use</guilabel> modules and
<guilabel>Use</guilabel> modules. Modules are used in the order
in the <guilabel>Use</guilabel> list. First module is asked for
translation. If it is not found, next module in the list is asked and so on.
You can use the buttons with arrows for moving modules between the
lists. Don't forget to change the order to suit your needs by <guibutton>Move Up
</guibutton> and <guibutton>Move Down</guibutton> buttons.
</para>
<para>
Normally &kbabel; will mark every roughly translated message as
fuzzy, because it assumes that any automatic translation needs to
be reviewed by a translator. If you are 100% sure that the automatic
translation will be correct, or you will review all the translation anyway.
<guilabel>Mark changed entries as fuzzy</guilabel> allows you to
turn off this automatic fuzzy marking, but you will need to confirm this.
</para>
<para>
If you have set all the options to suit your needs, push <guibutton>Start
</guibutton> to automatically translate messages. You can follow the
progress bar and in case, there is always the <guibutton>Stop</guibutton>
button.
</para>
</sect2>

<sect2 id="kbabel-validation">
<title>Validate your translation</title>
<para>Everyone makes mistakes. So &kbabel; supports a number
of checks for typical problems in translations. These checks (not
syntax check) can be basically performed in two ways.</para>
<para>
Checks can be done at each change of the translated text. These
are called <emphasis>automatic</emphasis> checks and they can
be turned on in <link linkend="preferences-editor">the &kbabel; configuration dialog</link>.
Automatic checking of syntax is possible at each saving of the file.
</para>
<para>
The automatic checks can slow down &kbabel;. If you have a slower
computer, you can turn off the automatic checks and use only the
second possibility. You can invoke every kind of check from the
<menuchoice><guimenu>Tools</guimenu><guisubmenu>
Validation</guisubmenu></menuchoice>. Then the check is
performed for all messages in the file and faulty ones are marked as errors.
</para>
<variablelist>
   <varlistentry>
     <term><guimenuitem>Check Syntax</guimenuitem></term>
     <listitem>
       <para>
       This invokes <command>msgfmt</command> to check validity of the PO file
       as seen by &GNU; gettext package. It will show the result of the command
       and mark error <acronym>msgstr</acronym>s.
       </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term><guimenuitem>Check Arguments</guimenuitem></term>
     <listitem>
       <para>
       Incorrect translations can crash the application. The most dangerous
       parts of translation are arguments, &eg; for printf-like functions. This check
       compares the number and types of the arguments in <acronym>msgid</acronym>
       and <acronym>msgstr</acronym>. They must match.
       </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term><guimenuitem>Check Accelerators</guimenuitem></term>
     <listitem>
     <para>
       &GUI; text commonly contain accelerators, &ie; letters which can be used
       for fast access to &GUI; elements by keyboard. They are denoted by
       special character, &eg; &amp; in &kde;. Typical requirement of the
       translation is that translated text should contain accelerator as well.
       This check will notice this problem for you. The accelerator character
       can be specified in <guilabel>Preferences</guilabel> on <guilabel>Misc</guilabel> tab.
       </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term><guimenuitem>Look for Translated Context Info</guimenuitem></term>
     <listitem>
     <para>
       You will probably need this only for &kde; translation. Some of the text are too common
       and they need to be translated differently in different contexts. In &kde; the context
       is described at the beginning of <acronym>msgid</acronym> after the special sequence
       <userinput>:_</userinput>. But if some translators are not aware of this convention
       and they try to translate context information as well. This check will try to find these.
       If the check founds translated context information, you should remove it.
       </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term><guimenuitem>Check Plural Forms</guimenuitem></term>
     <listitem>
       <para>
       If the <acronym>msgid</acronym> is specified as a <quote>plural form</quote>,
       the translation has to contain the correct number of translations separated by
       <userinput>\n</userinput>. The correct number depends on the language of
       translation and is specified on <guilabel>Identity</guilabel> tab in <guilabel>
       Preferences</guilabel> dialog. This is implemented only for &kde; at the moment.
       </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term><guimenuitem>Check Equations</guimenuitem></term>
     <listitem>
       <para>
       Equations are special format of <acronym>msgid</acronym> typically
       used in <filename>.desktop</filename> files.
       And because your translations will be merged back to these files, <acronym>msgstr</acronym>
       must use this special format as well. This means that the translation must start (up to the
       first occurrence of <literal>=</literal> with the same text as the original message, &eg;
       <userinput>Name=</userinput>.
       <!-- ### TODO: is this feature is specific to KDE too? How does e.g. GNOME translate them? -->
       </para>
     </listitem>
   </varlistentry>
</variablelist>
</sect2>

<sect2 id="kbabel-spellcheck">
<title>Spellchecking the translation</title>
<para>As always, it is very important to spell-check your translation before
using your result. This way you can find typos and other problems in your translation.
&kbabel; uses the standard &kde; library for spellchecking and its standard
settings can be found in <link linkend="preferences-project-spellcheck">the project setting dialog</link>. Spell checking itself can be found in
<menuchoice><guimenu>Tools</guimenu><guisubmenu>Spelling</guisubmenu>
</menuchoice> submenu.
You can use a number of modes for spell checking:
</para>
<variablelist>
   <varlistentry>
     <term><guimenuitem>Spell check...</guimenuitem></term>
     <listitem>
       <para>
       This is a generic invocation of a dialog where you can choose
       the spellchecking mode and set the default mode. This is
       invoked by pressing <keycombo action="simul">&Ctrl;<keycap>I</keycap>
       </keycombo>.
       </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term><guimenuitem>Check All...</guimenuitem></term>
     <listitem>
       <para>
       Spellcheck all messages in the file.
       </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term><guimenuitem>Check from Cursor Position...</guimenuitem></term>
     <listitem>
       <para>
       Start spellchecking at the position in the current message and
       progress towards the end of the file.
       </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term><guimenuitem>Check Current...</guimenuitem></term>
     <listitem>
       <para>
       Spellcheck the current message only.
       </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term><guimenuitem>Check Selected Text...</guimenuitem></term>
     <listitem>
       <para>
       If there is a selected text in <acronym>msgstr</acronym> editor,
       this option is available and will spellcheck this text only.
       </para>
     </listitem>
   </varlistentry>
</variablelist>
</sect2>

<sect2 id="kbabel-tags">
<title>Translating &XML;, <acronym>HTML</acronym>, ...</title>
<para>
Markup languages are used more and more in &GUI;.
&kde; project also uses <acronym>PO</acronym>-files for translating
DocBook documentation files (which is also a markup language). &kbabel;
contains quite a lot of functionality to support this trend.
</para>
<note>
<para>
Here, we will describe only functions related to tags used for markup itself. The
other problem introduced by using markup languages is translation of
longer texts. This issue is addressed by the <emphasis>diff</emphasis>
feature described in <link linkend="kbabel-diff">the following section</link>.
</para>
</note>
<para>
The current version of &kbabel; is capable to find out which tags are
used in <acronym>msgid</acronym> and provide an easy access to
them using following actions from the <guimenu>Edit</guimenu>:
</para>

<variablelist>
<varlistentry>
    <term>
        <guimenuitem>Insert Next Tag</guimenuitem>
    </term>
    <listitem>
      <para>
        <action>
          This inserts next tag found in msgid to the translation. &kbabel; finds
          the tag to be inserted by counting the number of tags from the
          beginning of the translation.
        </action>
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <menuchoice>
        <guimenu>Edit</guimenu>
        <guisubmenu>Insert Tag</guisubmenu>
      </menuchoice>
    </term>
    <listitem>
      <para>
        <action>
          This submenu contains all different markup tags found in original english string.
          By selecting a tag you can insert it at the current position of cursor in translated text.
          translation.
        </action>
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="kbabel-diff">
<title>Showing the difference</title>
<para>
As explained already, current applications, trying to be user friendly, contain a lot of
longer descriptive texts, including markup. If a developer changes
a part of the text, the &GNU; gettext system will, in the best case, retain the old
translation and mark it as fuzzy. (In the worst case you will lose the translation
completely, depending on the size of the text changes). This works OK, if
a <acronym>msgid</acronym> is short, because then you can find
the changes quickly. But if the text is long enough, you will struggle to find out
what has been changed (For example, it can be only an article change by proof-reading team.)
</para>
<para>
To help, &kbabel; can be asked to lookup the original <acronym>msgid</acronym>
and to show the difference. The changes are graphically displayed in 
the <guilabel>Original String</guilabel> window. The exact method can 
be set in the <link linkend="preferences-editor-appearance">&kbabel; 
configuration dialog</link>. <menuchoice><guimenu>Tools</guimenu>
<guisubmenu>Diff</guisubmenu> <guimenuitem>Show Diff</guimenuitem>
</menuchoice> will show the differences found. To see the current text
without the mixture of original text and differences, use <menuchoice><guimenu>Tools</guimenu>
<guisubmenu>Diff</guisubmenu> <guimenuitem>Show Original Text</guimenuitem>
</menuchoice>.
</para>
<para>
You can turn automatic lookup of difference on and off by choosing
<menuchoice><guimenu>Tools</guimenu>
<guisubmenu>Diff</guisubmenu> <guimenuitem>Diff Mode</guimenuitem>
</menuchoice>. When the diff mode is on, difference searching starts when you
go to another message.
</para>
<para>
As always, you can use different sources for finding the old version of the
text, all being set in in <link linkend="preferences-diffmode">&kbabel; configuration dialog</link>:
</para>
<variablelist>
   <varlistentry>
     <term>Translation Database</term>
     <listitem>
       <para>
       You can use Translation Database for difference lookup.
       We strongly recommend to turn on the automatic storing of the newly translated messages
       into Translation Database in <link linkend="database-fill">
       Translation Database configuration dialog</link>.
       This mode can be turned on by <guilabel>Use messages from Translation
       Database</guilabel>.
       </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term>Tree of the old files</term>
     <listitem>
       <para>
       This will be used only if searching in Translation Database is turned off.
       By setting <guilabel>Base folder for diff files</guilabel> you can
       navigate &kbabel;, which file to use for difference.
       It takes the relative path of the opened file and uses this relative
       path in the folder specified here. If there is a corresponding file, it will
       be used. To use this mode, you should make a copy of
       old files before each update.
       </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term>Manually chosen file</term>
     <listitem>
       <para>
       If the previous possibility does not work, correctly, you can always
       set the difference file manually by choosing <menuchoice>
       <guimenu>Tools</guimenu><guisubmenu>Diff</guisubmenu>
       <guimenuitem>Open File for Diff</guimenuitem></menuchoice>.
       </para>
     </listitem>
   </varlistentry>
</variablelist>
<note>
<para>
The difference lookup is not always accurate, because the
<acronym>PO</acronym>-file does not contain any reference to the original
message.
</para>
</note>
</sect2>

</sect1>

<sect1 id="kbabel-pluralforms">
<title>Plural Forms</title>
<para>
Because plural forms are quite a complicated issue, we devote a special section
for their support in &kbabel;.
</para>

<note><para>
This section handles about &kde; plural forms (to be precise of &kde; version 3).
From &kbabel; version 1.11 (KDE 3.5) on, &kbabel; should be able to
read, edit and save the &GNU; gettext plural forms too.
</para></note>

<para>
Every language to which &kde; is translated must have set a correct
number of plural forms. This is done by translating a specific entry in <filename>kdelibs.po</filename>.
The number is set by selecting the name of a language, which uses
the same number and <emphasis>rules</emphasis> for finding the
right plural form. The up-to-date list of possible values can be found in the
kdelibs source code, in the file <filename>tdecore/klocale.cpp</filename>.
</para>

<note><para>
&GNU; gettext allows to define the number and type of plural forms by a formula and to set this
formula independently for each PO file. &kde; can only define the number and type of plural forms
one time in kdelibs.
</para></note>

<para>
&kde; plural forms are denoted by comment <userinput>_n:</userinput> (including a trailing space) containing
the <literal>%n</literal> argument. This argument is then used in the message
itself and it controls which plural form of your language should be used
depending on the rules for your language.
</para>
<para>
The translation of a plural form message has to have a special format. 
It must contain the correct number of translations (one for each plural form)
separated by an end of the line <literal>\n</literal>,
<emphasis>without</emphasis> any <userinput>_n:</userinput> sequence (without the space either). For example,
<quote>_n: Selected 1 file\nSelected %n files</quote> translated to Slovak would be:
</para>
<programlisting>
Vybraný %n súbor\n
Vybrané %n súbory\n
Vybraných %n súborov
</programlisting>
<para>
To check if your translation contains the correct number of 
plural forms, use the <menuchoice><guimenu>Tools</guimenu> <guisubmenu>Validation
</guisubmenu> <guimenuitem>Check Plural Forms (KDE only)</guimenuitem>
</menuchoice> menu.
</para>
</sect1>
</chapter>

<!--
Local Variables:
mode: xml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab 
-->