diff options
Diffstat (limited to 'doc/kbabel/using.docbook')
| -rw-r--r-- | doc/kbabel/using.docbook | 791 |
1 files changed, 791 insertions, 0 deletions
diff --git a/doc/kbabel/using.docbook b/doc/kbabel/using.docbook new file mode 100644 index 00000000..091361e6 --- /dev/null +++ b/doc/kbabel/using.docbook @@ -0,0 +1,791 @@ +<!-- <?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—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 +"Open a Playlist"</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, ⪚ <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, ⪚ 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—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—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—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, ⪚ 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, ⪚ & 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, ⪚ + <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>kdecore/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 +--> |