You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
792 lines
31 KiB
792 lines
31 KiB
<!-- <?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>tdelibs.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
|
|
tdelibs 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 tdelibs.
|
|
</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
|
|
-->
|