diff options
Diffstat (limited to 'doc/kbabel')
63 files changed, 5880 insertions, 0 deletions
diff --git a/doc/kbabel/Makefile.am b/doc/kbabel/Makefile.am new file mode 100644 index 00000000..17a314c3 --- /dev/null +++ b/doc/kbabel/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = AUTO +KDE_MANS = AUTO diff --git a/doc/kbabel/TODO b/doc/kbabel/TODO new file mode 100644 index 00000000..916027bf --- /dev/null +++ b/doc/kbabel/TODO @@ -0,0 +1,4 @@ +KBabel documentation TODO: + +missing: +catman - find/replace dialogs diff --git a/doc/kbabel/back.png b/doc/kbabel/back.png Binary files differnew file mode 100644 index 00000000..2ffa9395 --- /dev/null +++ b/doc/kbabel/back.png diff --git a/doc/kbabel/bottom.png b/doc/kbabel/bottom.png Binary files differnew file mode 100644 index 00000000..caf4ea5a --- /dev/null +++ b/doc/kbabel/bottom.png diff --git a/doc/kbabel/catalogmanager.png b/doc/kbabel/catalogmanager.png Binary files differnew file mode 100644 index 00000000..48bbade3 --- /dev/null +++ b/doc/kbabel/catalogmanager.png diff --git a/doc/kbabel/catalogmanager_broken.png b/doc/kbabel/catalogmanager_broken.png Binary files differnew file mode 100644 index 00000000..d0948e92 --- /dev/null +++ b/doc/kbabel/catalogmanager_broken.png diff --git a/doc/kbabel/catalogmanager_missing.png b/doc/kbabel/catalogmanager_missing.png Binary files differnew file mode 100644 index 00000000..e0311068 --- /dev/null +++ b/doc/kbabel/catalogmanager_missing.png diff --git a/doc/kbabel/catalogmanager_needwork.png b/doc/kbabel/catalogmanager_needwork.png Binary files differnew file mode 100644 index 00000000..e31413d8 --- /dev/null +++ b/doc/kbabel/catalogmanager_needwork.png diff --git a/doc/kbabel/catalogmanager_nopot.png b/doc/kbabel/catalogmanager_nopot.png Binary files differnew file mode 100644 index 00000000..1e220bee --- /dev/null +++ b/doc/kbabel/catalogmanager_nopot.png diff --git a/doc/kbabel/catalogmanager_nopot_ok.png b/doc/kbabel/catalogmanager_nopot_ok.png Binary files differnew file mode 100644 index 00000000..50028c65 --- /dev/null +++ b/doc/kbabel/catalogmanager_nopot_ok.png diff --git a/doc/kbabel/catalogmanager_ok.png b/doc/kbabel/catalogmanager_ok.png Binary files differnew file mode 100644 index 00000000..f2b731a0 --- /dev/null +++ b/doc/kbabel/catalogmanager_ok.png diff --git a/doc/kbabel/catalogmanager_reload.png b/doc/kbabel/catalogmanager_reload.png Binary files differnew file mode 100644 index 00000000..e7aeaac5 --- /dev/null +++ b/doc/kbabel/catalogmanager_reload.png diff --git a/doc/kbabel/catman.docbook b/doc/kbabel/catman.docbook new file mode 100644 index 00000000..a55d46ec --- /dev/null +++ b/doc/kbabel/catman.docbook @@ -0,0 +1,214 @@ +<!-- <?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-catalogmanager"> + +<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 &catalogmanager;</title> +<anchor id="catalogmanager"/> + +<screenshot> +<screeninfo>Screenshot of &catalogmanager;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="snap_catalogmanager.png" format="PNG"/> +</imageobject> +<textobject><phrase>Screenshot of &catalogmanager;</phrase></textobject> +</mediaobject> +</screenshot> +<para> +The Catalog Manager merges two folders into one tree and displays +all the <acronym>PO</acronym> and <acronym>POT</acronym> files in +these folders. The display allows you to easily see if a new +template has been added or an old one has been removed. Some +information is shown along with each file name: total number of +entries, number of fuzzy entries, number of untranslated entries, the +date of the last revision and the last translator of the file. +</para> + +<important><para> +KBabel's Catalog Manager is meant for projects structured like KDE, +where the <acronym>POT</acronym> and <acronym>PO</acronym> files +share a same name, save the extensions. However this is not the +case of &GNU; projects and of many projects structured like &GNU; ones. +Typically in such projects, the <acronym>PO</acronym> file is named +following the language code and so is very different than the name +of the <acronym>POT</acronym> files. Also such projects have +one <acronym>POT</acronym> file sharing a directory with all its +translated <acronym>PO</acronym> files. Unfortunately, all these reasons +mean that the Catalog Manager is <emphasis>not</emphasis> suitable for +such projects. (See <ulink url="http://bugs.kde.org/show_bug.cgi?id=76495">KDE bug #76495</ulink>.) +</para></important> + +<para> +To make it easier for you to find files that need work or are +missing the status of each file is also displayed using an icon: +</para> + +<itemizedlist> + <listitem> + <para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_ok.png" format="PNG"/> +</imageobject> +</inlinemediaobject> All the messages in this file are translated.</para> + </listitem> + <listitem> + <para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_needwork.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +Some of the messages in this file are fuzzy or untranslated + </para> + </listitem> + <listitem> + <para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_missing.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +This file does not exist in the folder of the <acronym>PO</acronym> files. + </para> + </listitem> + <listitem> + <para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_broken.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +This file contains syntax errors. + </para> + </listitem> + <listitem> + <para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_reload.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +Information about this file is being currently updated. When the update is +finished, it will get one of the icons listed above to reflect its state. + </para> + </listitem> +</itemizedlist> + +<para> +If an icon is marked with this icon +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_nopot.png" format="PNG"/> +</imageobject> +</inlinemediaobject>, like +<inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager_nopot_ok.png" format="PNG"/> +</imageobject> +</inlinemediaobject>, +it indicates that this file or folder does not exist in the +folder of the <acronym>POT</acronym> files.</para> + +<para> You can mark or unmark a file by selecting <guimenuitem>Toggle +Marking</guimenuitem> in the context menu of a file.</para> + +<para>If you want to toggle or remove all markings in a folder, +press the right mouse button over the folder and select +<guimenuitem>Toggle Markings</guimenuitem> or <guimenuitem>Remove +Markings</guimenuitem>. The markings are automatically saved when +leaving &kbabel;.</para> + +<para>To open a file either double-click on the file, select +<menuchoice><guimenuitem>Open</guimenuitem></menuchoice> from the +context menu or press either <keycap>Return</keycap> or <keycombo +action="simul">&Ctrl;<keycap>O</keycap> </keycombo>.</para> + +<para>You can configure the &catalogmanager; by +<menuchoice><guimenu>Project</guimenu><guimenuitem> +Configure...</guimenuitem></menuchoice>. +See section <link linkend="preferences-project-settings">Project Settings</link> for more +details.</para> + +<sect1 id="catman-features"> +<title>&catalogmanager; Features</title> +<para> +Besides the main feature for opening the files in &kbabel; &catalogmanager; +supports number of other features for maintaining a tree of +<acronym>PO</acronym>-files. +</para> + +<sect2 id="catman-find"> +<title>Find and replace in multiple files</title> +<para> +One of the most requested features for &kbabel; was a possibility to search and replace in +multiple files at once. &catalogmanager; supports this feature with +a tight integration with &kbabel; +</para> +</sect2> + +<sect2 id="catman-statistics"> +<title>Statistics</title> +<para> +&catalogmanager; can show you a number of statistics about a single file +or about the whole folders. The statistics contain number of files, +how many of the files have their templates, how many templates are missing. +It also counts number of messages in the files and shows statistics about +how large parts of the messages are translated, fuzzy-translated or +untranslated. +</para> +</sect2> + +<sect2 id="catman-syntax"> +<title>Checking the syntax</title> +<para> +This allows you to check the syntax of multiple <acronym>PO</acronym>-files +using <command>msgfmt</command>. If a file fails this check, it cannot +be used for generating a <acronym>MO</acronym>-file for binary distribution. +Such an incorrect file will typically result in failing compilation of the package +the <acronym>PO</acronym>-file belongs to. +</para> +</sect2> + +<sect2 id="catman-commands"> +<title>User-defined commands</title> +<para> +Because &catalogmanager; cannot provide any functionality you would like +to use, you can extend it by defining your own commands. +</para> +<!-- ### TODO: we should lik to preferences-project-file-commands too --> +<para> +There are two sets of commands. One for folders and one for single files. +You can set them in <link +linkend="preferences-project-folder-commands">configuration dialog </link> and +access by pressing &RMB; on an entry in the file list.</para> +</sect2> + +</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 +--> diff --git a/doc/kbabel/dbcan.png b/doc/kbabel/dbcan.png Binary files differnew file mode 100644 index 00000000..a8cf3080 --- /dev/null +++ b/doc/kbabel/dbcan.png diff --git a/doc/kbabel/dictionaries.docbook b/doc/kbabel/dictionaries.docbook new file mode 100644 index 00000000..a9e5ed70 --- /dev/null +++ b/doc/kbabel/dictionaries.docbook @@ -0,0 +1,517 @@ +<!-- <?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="dictionaries"> + +<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>Dictionaries</title> + +<para>&kbabel; has 3 modes which can be used to search translated +<acronym>PO</acronym> message strings:</para> + +<itemizedlist> + <listitem> + <para>Searching translation, using a translation database + </para> + </listitem> + <listitem> + <para>Rough translation + </para> + </listitem> + <listitem> + <para>&kbabeldict; + </para> + </listitem> +</itemizedlist> + +<sect1 id="database"> +<!-- FIXME: settings --> +<title>Translation database</title> + +<!-- ### TODO: only *one* file? Seems more to be four... --> +<para>Translation database allows you to store translations in a +database based on Berkeley Database IV, &ie; it is stored in a binary +file on your disk. The database guarantees fast searching in a large +number of translations.</para> + +<para>This mode is the one best integrated with &kbabel;. Besides +searching and rough translation it also supports the following +features:</para> + +<itemizedlist> +<listitem> +<para>Every new translation typed in the &kbabel; editor can be +automatically stored in the database.</para> +</listitem> +<listitem> +<para>This database can be used for <quote>diff</quote>-ing +<acronym>msgid</acronym>.</para> +</listitem> +</itemizedlist> + +<para>Of course, the more translations are stored in the database, the +more productive you can be. To fill the database, you can use the +<guilabel>Database</guilabel> tab in the preferences dialog or you can +turn on automatic addition of every translated messages on the same +tab.</para> + +<sect2 id="database-settings"> +<title>Settings</title> +<para> +You can configure this searching mode and how it should be used by selecting +<menuchoice> + <guisubmenu>Settings</guisubmenu> + <guisubmenu>Configure Dictionary</guisubmenu> + <guimenuitem>Translation Database</guimenuitem> +</menuchoice> +in &kbabel; menu. +</para> +<para> +The <guilabel>Generic</guilabel> tab contains general settings for searching in the +database. +</para> +<variablelist> + <varlistentry> + <term><guilabel>Search in whole database (slow)</guilabel></term> + <listitem> + <para> + Do not use <quote>good keys</quote>, search in the whole database. + This is slow, but will return the most precise results. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Search in list of "good keys" (best)</guilabel></term> + <listitem> + <para> + Use <quote>good keys</quote> strategy. This option will give you the + best tradeoff between speed and exact matching. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Return the list of "good keys" (fast)</guilabel></term> + <listitem> + <para> + Just return <quote>good keys</quote>, do not try to eliminate any more + texts. This is the fastest provided method, but can lead to a quite large + number of imprecise matches. + </para> + </listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Case sensitive</guibutton></term> + <listitem> + <para> + Distinguish case of letters when searching the text. + </para> + </listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Normalize white space</guibutton></term> + <listitem> + <para> + Skip unnecessary white space in the texts, so the searching will ignore small + differences of white space, ⪚ number of spaces in the text. + </para> + </listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Remove context comment</guibutton></term> + <listitem> + <para> + Do not include context comments in search. You will want this to be turned on. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Character to be ignored</guilabel></term> + <listitem> + <para>Here you can enter characters, which should be ignored while searching. + Typical example would be accelerator mark, &ie; & for &kde; texts. + </para> + </listitem> + </varlistentry> + </variablelist> +<para> +The <guilabel>Search</guilabel> tab contains finer specification for searching the text. +You can define how to search and also allows to use another special way of searching +called <emphasis><guilabel>Word substitution</guilabel></emphasis>. By substituting +one or two words the approximate text can be found as well. For example, assume you +are trying to find the text <userinput>My name is Andrea</userinput>. +</para> +<variablelist> + <varlistentry> + <term><guilabel>Equal</guilabel></term> + <listitem> + <para> + Text from database matches if it is the same as the searched string. In our example it can + be <emphasis>My name is &Andrea</emphasis> (if & is set as ignored character + in <guilabel>Characters to be ignored</guilabel> on <guilabel>Generic</guilabel> tab). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Query is contained</guilabel></term> + <listitem> + <para> + Text from database matches if the searched string is contained in it. For our example it can + be <emphasis>My name is Andrea, you know?</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Query contains</guilabel></term> + <listitem> + <para> + Text from database matches if the searched string contains it. For our example it can + be <emphasis>Andrea</emphasis>. You can use this for enumerating the possibilities to + be found. + </para> + </listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Regular Expression</guibutton></term> + <listitem> + <para> + Consider searched text as a regular expression. This is mainly used for + &kbabeldict;. You can hardly expect regular expressions in PO files. + </para> + </listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Use one word substitution</guibutton></term> + <listitem> + <para> + If the query text contains less words than specified below, it also + tries to replace one of the words in the query. In our example it will + find <emphasis>Your name is Andrea</emphasis> as well. + </para> + </listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Max number of words in the query</guibutton></term> + <listitem> + <para> + Maximal number of words in a query to enable one word substitution. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Local characters for regular expressions</guilabel></term> + <listitem> + <para> + Characters to be considered part of regular expressions. + </para> + </listitem> + </varlistentry> + </variablelist> +<note> +<para> +Two-word substitution is not implemented yet. +</para> +</note> +</sect2> + +<sect2 id="database-fill"> +<title>Filling the database</title> +<para> +The <guilabel>Database</guilabel> tab allows to define where is the database stored on +disk (<guilabel>Database folder</guilabel>) and if it should be used for automatic +storing of the new translations (<guibutton>Auto add entry to database</guibutton>). +In this case you should specify the author of the new translation in <guilabel>Auto added +entry author</guilabel>. +</para> +<para> +The rest of the tab allows you to fill the database from PO files that already exist. Use one +of the buttons in the middle of the dialog box. The progress of the file load will be +shown by progress bars below the buttons. The <guilabel>Repeated strings</guilabel> +button should be used in the special case where one translated string is repeated many +times, to prevent storing unnecessary copies. Here you can limit the stored strings. +</para> +<screenshot> +<screeninfo>Filling the database</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="dbcan.png" format="PNG"/> +</imageobject> +<textobject><phrase>Filling the database by existing PO-files</phrase></textobject> +</mediaobject> +</screenshot></sect2> + +<sect2 id="database-goodkeys"> +<title>Defining good keys</title> +<para> +On the <guilabel>Good keys</guilabel> tab are the thresholds to specify how to fill +the list of good keys. +<guilabel>Minimum number of query words in the key (%)</guilabel> specifies exactly that. +Text will need to contain only this per cent of the words to qualify as good key. Opposite can +be specified via <guilabel>Minimum number of words of the key also in the query (%)</guilabel>. +The length of the words can be set by <guilabel>Max length</guilabel> spinbox. +</para> +<para>Searched text typically contains number of generic words, ⪚ articles. You can +eliminate the words based on the frequency. You can discard them by +<guilabel>Discard words more frequent than</guilabel> or consider as always present by +<guilabel>frequent words are considered as in every key</guilabel>. This way the +frequent words will be almost invisible for queries. +</para> +</sect2> +</sect1> + + +<sect1 id="auxiliary"> +<title>Auxiliary PO file</title> + +<para>This searching mode is based on matching the same original +English string (the msgid) translated in some other language in an +auxillary <acronym>PO</acronym> file. It is very common for Romance +<!-- ### TODO: is "Anglo-Saxon" not too Romance or too technical for an English text? --> +languages to have similar words, similarly for Anglo-Saxon and +Slavic ones.</para> + +<para> +For example, say I wanted to translate the word +<quote>on</quote>, from <filename>kdelibs.po</filename>, into Romanian +but have no clue. I look in the same file for French and find +<foreignphrase lang="fr">actif</foreignphrase>, and in the Spanish one find +<foreignphrase lang="es">activado</foreignphrase>. So, I conclude that the best one in Romanian +will be <foreignphrase lang="ro">active</foreignphrase>. +(Of course, in English instead of <quote>on</quote> the word could have been +<quote>active</quote> or <quote>activated</quote>, +which would have made the translation process easier.) +&kbabel; automates this task. Currently you can define only one auxiliary file to search. +</para> + +<sect2 id="auxiliary-settings"> +<title>Settings</title> +<para> +You can configure this searching mode by selecting +<menuchoice> + <guisubmenu>Settings</guisubmenu> + <guisubmenu>Configure Dictionary</guisubmenu> + <guimenuitem>PO Auxiliary</guimenuitem> +</menuchoice> +from the &kbabel; menu.</para> + +<para>In the <guilabel>Configure Dictionary PO Auxiliary</guilabel> +dialog you can select the path to the auxiliary <acronym>PO</acronym> +file. To automate <acronym>PO</acronym>-file switching when you +change current edited file there are many variables delimited by +<literal>@</literal> char that are replaced by appropriate +values:</para> + +<variablelist> + <varlistentry> + <term>@PACKAGE@</term> + <listitem><para> + The name of application or package currently being translated. + For example, it can expand to kbabel, kdelibs, konqueror + and so on. + </para></listitem> + </varlistentry> + <varlistentry> + <term>@LANG@</term> + <listitem><para> + The language code. + For example can expand to: de, ro, fr etc. + </para></listitem> + </varlistentry> + <varlistentry> + <term>@DIRn@</term> + <listitem><para> + where <quote>n</quote> is a positive integer. This expands to + the <quote>n</quote>-th folder counted from the filename (right to + left). + </para></listitem> + </varlistentry> +</variablelist> + +<para>The edit line displays the actual path to the auxiliary +<acronym>PO</acronym> file. While it is best to use the +provided variables in a path it is possible to choose an absolute, +real path to an existing <acronym>PO</acronym> file. Let's take an +example.</para> + +<para>I'm Romanian and I have some knowledge about French language and +I work on &kde; translation.</para> + +<!-- ### TODO: check URL, especially the kde-l10n part --> +<para>First step is to download a very fresh +<filename>kde-l10n-fr.tar.bz2</filename> from the <ulink +url="ftp://ftp.kde.org/pub/kde/snapshots/kde-l10n">&kde; &FTP; +site</ulink> or to use the <acronym>CVS</acronym> system to put on my +hard-disk a French translation tree. I do this into +<filename>/home/clau/cvs-cvs.kde.org/kde-l10n/fr</filename>.</para> + +<para>My <acronym>PO</acronym> sources folder is in +<filename>/home/clau/cvs-cvs.kde.org/kde-l10n/ro</filename>. Do not +forget to select <guilabel>PO Auxiliary</guilabel> as the default +dictionary and check <guilabel>Automatically start search</guilabel> +on the <guilabel>Search</guilabel> tab from &kbabel;'s +<guilabel>Preferences</guilabel> dialog.</para> + +</sect2> +</sect1> + +<sect1 id="compendium"> +<!-- FIXME: examples --> +<title>PO compendium</title> + +<para>A compendium is a file containing a collection of all +translation messages (pairs of <acronym>msgid</acronym> and +<acronym>msgstr</acronym>) in a project, ⪚ in &kde;. Typically, +compendium for a given language is created by concatenating all +<acronym>PO</acronym> files of the project for the +language. Compendium can contain translated, untranslated and fuzzy +messages. Untranslated ones are ignored by this module. </para> + +<para>Similarly to Auxiliary <acronym>PO</acronym>, this searching +mode is based on matching the <quote>same</quote> original string +(<acronym>msgid</acronym>) in a compendium. Currently you can define +only one compendium file to search. </para> + +<para>This mode is very useful if you are not using the translation +database and you want to achieve consistent translation with other +translations. By the way, compendium files are much easier to share +with other translators and even other translation projects because +they can be generated for them as well. </para> + +<sect2 id="compendium-settings"> +<title>Settings</title> + +<para> +You can configure this searching mode by selecting +<menuchoice> + <guisubmenu>Settings</guisubmenu> + <guisubmenu>Configure Dictionary</guisubmenu> + <guimenuitem>PO Compendium</guimenuitem> +</menuchoice> +in &kbabel;'s menu. +</para> + +<para>In <guilabel>Configure Dictionary PO Compendium</guilabel> +dialog you can select the path to a compendium file. To automate +compendium file switching when you change the translation language, +there is a variable delimited by <literal>@</literal> char which si +replaced by appropriate value:</para> + +<variablelist> + <varlistentry> + <term>@LANG@</term> + <listitem><para> + The language code. + For example can expand to: de, ro, fr etc. + </para></listitem> + </varlistentry> +</variablelist> + +<para>In the edit line is displayed the actual path to compendium +<acronym>PO</acronym> file. While you had best use provided variables in +path, it's possible to choose an absolute, real path to an existing +<acronym>PO</acronym> file to be used as a compendium.</para> + +<!-- ### TODO: check URL, especially the kde-l10n part --> +<para>A very fresh compendium for &kde; translation into ⪚ French +you can download <filename>fr.messages.bz2</filename> from the <ulink +url="ftp://ftp.kde.org/pub/kde/snapshots/kde-l10n">&kde; &FTP; +site</ulink>. </para> + +<para>You can define how to search in the compendium using options +below the path. They are divided into two groups: text-matching +options, where you can specify how the text is compared and whether to +ignore fuzzy translations, and message-matching options, which +determine if the translation from compendium should be a substring of +searching message or vice versa.</para> + +<variablelist> + <varlistentry> + <term><guilabel>Case sensitive</guilabel></term> + <listitem> + <para> + If the matching of message in compendium should distinguish between uppercase and lowercase letters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Ignore fuzzy string</guilabel></term> + <listitem> + <para> + If the fuzzy messages in the compendium should be ignored for searching. The compendium can contain fuzzy messages, since it is typically created by concatenating the <acronym>PO</acronym> files of the project which can include fuzzy messages. Untranslated ones are ignored always (You can't search for translation in untranslated messages, right?)</para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Only whole words</guilabel></term> + <listitem> + <para> + If the matching text should start and end at the boundaries of words. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>A text matches if it <guilabel>is equal to search text</guilabel></term> + <listitem> + <para> + A text in compendium matches the search text only if it is exactly the same (of course using the options above). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>A text matches if it <guilabel>is similar to search text</guilabel></term> + <listitem> + <para> + A text in compendium matches the search text only if it is <quote>similar</quote>. Both texts are compared by short chunks of letters (<quote>3-grams</quote>) and at least half of the chunks has to be same. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>A text matches if it <guilabel>contains search text</guilabel></term> + <listitem> + <para> + A text in compendium matches the search text if it contains the search text.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>A text matches if it <guilabel>is contained in search text</guilabel></term> + <listitem> + <para> + A text in compendium matches the search text if it is contained the search text. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>A text matches if it <guilabel>contains a word of search text</guilabel></term> + <listitem> + <para> + The texts are divided to words and a text in compendium matches the search text only if it contains some word from the search text. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> +</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 +--> + diff --git a/doc/kbabel/editcopy.png b/doc/kbabel/editcopy.png Binary files differnew file mode 100644 index 00000000..c600e997 --- /dev/null +++ b/doc/kbabel/editcopy.png diff --git a/doc/kbabel/editcut.png b/doc/kbabel/editcut.png Binary files differnew file mode 100644 index 00000000..21c36739 --- /dev/null +++ b/doc/kbabel/editcut.png diff --git a/doc/kbabel/editpaste.png b/doc/kbabel/editpaste.png Binary files differnew file mode 100644 index 00000000..f6a1db8f --- /dev/null +++ b/doc/kbabel/editpaste.png diff --git a/doc/kbabel/faq.docbook b/doc/kbabel/faq.docbook new file mode 100644 index 00000000..ce8a6737 --- /dev/null +++ b/doc/kbabel/faq.docbook @@ -0,0 +1,66 @@ +<!-- <?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="faq"> +<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>Questions and Answers</title> +<qandaset> + <!-- ### FIXME: describe better the situation of Qt3. (This text sounds like being for Qt2.) --> + <qandaentry> + <question> + <para> + Why does &kbabel; show question marks instead of language specific +characters after loading a <acronym>PO</acronym> file?</para> + </question> + <answer> + <para> + The text contains characters, which can not be displayed with your system font. If you are sure, that the text contains no such characters, the file might have been corrupted somehow. In this case, mark such a question mark and press + <keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo> to find all the corrupted characters and replace them.<note> + <para> + Do not search for real question marks, because these characters are only displayed as question marks, but internally they are different characters. + </para> + </note> + Otherwise you might want to install an Unicode font, which contains all + necessary characters. + </para> + </answer> + </qandaentry> +<qandaentry> +<question> +<para> +How can I translate &kde;? +</para> +</question> +<answer> +<para> +You can look for information about how to translate KDE in the +<ulink url="http://i18n.kde.org/translation-howto/">The KDE Translation HOWTO</ulink>. +</para> +</answer> +</qandaentry> +</qandaset> +</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 +-->
\ No newline at end of file diff --git a/doc/kbabel/fileopen.png b/doc/kbabel/fileopen.png Binary files differnew file mode 100644 index 00000000..2d27efc8 --- /dev/null +++ b/doc/kbabel/fileopen.png diff --git a/doc/kbabel/filesave.png b/doc/kbabel/filesave.png Binary files differnew file mode 100644 index 00000000..14d339d8 --- /dev/null +++ b/doc/kbabel/filesave.png diff --git a/doc/kbabel/find.png b/doc/kbabel/find.png Binary files differnew file mode 100644 index 00000000..92ae8f30 --- /dev/null +++ b/doc/kbabel/find.png diff --git a/doc/kbabel/forward.png b/doc/kbabel/forward.png Binary files differnew file mode 100644 index 00000000..66315588 --- /dev/null +++ b/doc/kbabel/forward.png diff --git a/doc/kbabel/glossary.docbook b/doc/kbabel/glossary.docbook new file mode 100644 index 00000000..8138da5b --- /dev/null +++ b/doc/kbabel/glossary.docbook @@ -0,0 +1,211 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE glossary 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 --> + +<glossary id="glossary"> +<glossaryinfo> +<!-- 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 --> +</glossaryinfo> + +<title>Glossary</title> + +<glossdiv><title>A</title> + <glossentry id="gloss-auxiliary"> + <glossterm>Auxiliary file</glossterm> + <glossdef> + <para> + is a &kbabel; specific issue. It is an option for the user to + set up one <acronym>PO</acronym> file to search through for original messages. For example, + if you're a member of French team and have some Spanish or Italian + knowledge you can grab and set-up an auxiliary Spanish <acronym>PO</acronym> file + associated with the file currently being translated. + + </para> + </glossdef> + </glossentry> +</glossdiv> + +<glossdiv><title>C</title> + <glossentry id="gloss-compendium"> + <glossterm>Compendium file</glossterm> + <glossdef> + <para> + is a collection of all translations + for one language. This big <acronym>PO</acronym> file + is made by unique messages from all + applications' <acronym>PO</acronym> files. It can + be used to fill in all already translated + strings into a new yet untranslated + or partially translated <acronym>PO</acronym> file. + &kbabel; uses such a file in the <quote>PO Compendium</quote> + search engine. + </para> + </glossdef> + </glossentry> +</glossdiv> + +<glossdiv><title>F</title> + <glossentry id="fuzzy"> + <glossterm>Fuzzy</glossterm> + <glossdef> + <para> + This is a flag generated, in general, + by <command>msgmerge</command>. It shows + that a <acronym>msgstr</acronym> string + might not be a correct translation. + The translator must see and make modifications + to the string if necessary and then remove + the <quote>fuzzy</quote> flag + from the message's comment. + </para> + </glossdef> + </glossentry> +</glossdiv> + +<glossdiv><title>I</title> + <glossentry id="i18n"> + <glossterm>Internationalization</glossterm> + <acronym>i18n</acronym> + <glossdef> + <para> + is the operation by which an application + is made aware and able to support multiple + languages. The word <quote>internationalization</quote> + has 20 characters so, to shorten it, + people started to write only + the first and last characters and between them + write the number of intermediate characters (18) + forming the common abbreviation <acronym>i18n</acronym>. + </para> + <glossseealso otherterm="l10n"></glossseealso> + </glossdef> + </glossentry> +</glossdiv> + +<glossdiv><title>L</title> + <glossentry id="l10n"> + <glossterm>Localization</glossterm> + <acronym>l10n</acronym> + <glossdef> + <para> + is the operation by which an application + already internationalized is made + to process input and output in a fashion + desired by some cultural and language habits. + The word <quote>localization</quote> + has 12 characters so, to shorten it, + people started to write only + the first and last characters and between them + write the number of intermediate characters (10) + forming the common abbreviation <acronym>l10n</acronym>. + </para> + <glossseealso otherterm="i18n"></glossseealso> + </glossdef> + </glossentry> +</glossdiv> + +<glossdiv><title>M</title> + <glossentry id="mofile"> + <glossterm>MO file</glossterm> + <acronym>MO</acronym> + <glossdef> + <para> + <acronym>MO</acronym> stands for <quote>Machine Object</quote>. A <acronym>MO</acronym> file + contains binary data suitable + for reading by computers. + The contents of a <acronym>MO</acronym> file are organized as a database + to minimize the lookup time + for translated strings. <acronym>MO</acronym> files + are obtained by compiling <acronym>PO</acronym> files + using <command>msgfmt</command>. + + </para> + <glossseealso otherterm="pofile"></glossseealso> + <glossseealso otherterm="potfile"></glossseealso> + </glossdef> + </glossentry> + <glossentry id="msgid"> + <glossterm>Message ID</glossterm> + <acronym>msgid</acronym> + <glossdef> + <para> + <acronym>msgid</acronym> is the keyword + which introduces the original string in a <acronym>PO</acronym> file. + It is followed by a C-like string that spans + one or more lines. + </para> + <glossseealso otherterm="msgstr"></glossseealso> + </glossdef> + </glossentry> + <glossentry id="msgstr"> + <glossterm>Message String</glossterm> + <acronym>msgstr</acronym> + <glossdef> + <para> + <acronym>msgstr</acronym> is the keyword + which introduce the translated string in <acronym>PO</acronym> file. + It is followed by C-like string that span + on one or multiple lines. + </para> + <glossseealso otherterm="msgid"></glossseealso> + </glossdef> + </glossentry> +</glossdiv> + +<glossdiv><title>P</title> + <glossentry id="pofile"> + <glossterm>PO file</glossterm> + <acronym>PO</acronym> + <glossdef> + <para> + <acronym>PO</acronym> stands for <quote>Portable Object</quote>. <acronym>PO</acronym> files + contain sets of strings which + associate each translatable string + with its translation in a particular + language. A single <acronym>PO</acronym> file relates + to only one language. A <acronym>PO</acronym> file is + derived from a <acronym>POT</acronym> file and is + edited either by hand or using &kbabel;. + </para> + <glossseealso otherterm="potfile"></glossseealso> + <glossseealso otherterm="mofile"></glossseealso> + </glossdef> + </glossentry> + <glossentry id="potfile"> + <glossterm>POT file</glossterm> + <acronym>POT</acronym> + <glossdef> + <para> + <acronym>POT</acronym> stands for <quote>Portable Object Template</quote>. A <quote>POT</quote> file is built by extracting all the + translatable strings from application + source files. A <quote>POT</quote> file does not + contain translations into any particular language— + it is used by the translators as a template. + </para> + <glossseealso otherterm="pofile"></glossseealso> + <glossseealso otherterm="mofile"></glossseealso> + </glossdef> + </glossentry> +</glossdiv> + +</glossary> +<!-- +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 +--> diff --git a/doc/kbabel/index.docbook b/doc/kbabel/index.docbook new file mode 100644 index 00000000..51cb8661 --- /dev/null +++ b/doc/kbabel/index.docbook @@ -0,0 +1,174 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY using SYSTEM "using.docbook"> + <!ENTITY kbabeldictchapter SYSTEM "kbabeldict.docbook"> + <!ENTITY catman SYSTEM "catman.docbook"> + <!ENTITY dictionaries SYSTEM "dictionaries.docbook"> + <!ENTITY menu SYSTEM "menu.docbook"> + <!ENTITY preferences SYSTEM "preferences.docbook"> + <!ENTITY kbabelfaq SYSTEM "faq.docbook"> + <!ENTITY glossary SYSTEM "glossary.docbook"> + <!ENTITY kappname "&kbabel;"> + <!ENTITY package "kdesdk"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kbabel; Handbook</title> + +<authorgroup> +<author> +&Stanislav.Visnovsky; &Stanislav.Visnovsky.mail; +</author> +<author> +&Matthias.Kiefer; +</author> +<author> +<firstname>Nicolas</firstname> +<surname>Goutte</surname> +<email>goutte@kde.org</email> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + + +<date>2005-12-29</date> +<releaseinfo>3.5.1.03</releaseinfo> + +<abstract> +<para> +&kbabel; is a suite of of an advanced and easy to use +<acronym>PO</acronym> file editor comprising &kbabel;, a multi +functional &catalogmanager; and a dictionary for translators +&kbabeldict;. It supports many advanced features and it lets you +customize many options. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KBabel</keyword> +<keyword>catalogmanager</keyword> +<keyword>kdesdk</keyword> +<keyword>gettext</keyword> +<keyword>translation</keyword> +<keyword>i18n</keyword> +<keyword>internationalization</keyword> +<keyword>l10n</keyword> +<keyword>localization</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<important><para> +In its current state, this KBabel documentation is partially outdated. +The basic documentation was meant for KDE 3.2, +the corrections are meant for KBabel 1.11.1 of KDE 3.5.1. +</para></important> + +<para> +&kbabel; is an advanced and easy to use <acronym>PO</acronym> file +(&GNU; gettext message catalogs) editor. It has many features, that +make it easy to edit and manage your <acronym>PO</acronym> files. +This includes full navigation capabilities, extensive editing +functionality, search functions, syntax checking and statistics +function. &catalogmanager; is a file manager view, which helps you +keep an overview over your <acronym>PO</acronym> files. &kbabeldict; +allows you to translate any text using &kbabel; capabilities for +automated translation. The &kbabel; suite will help you to translate +quickly and also to keep translations consistent. +</para> + +<para> +With the &kde; project growing continuously, the number of +<acronym>PO</acronym> messages is over 47000 at the time of writing +this documentation (plus another 20000 messages used for translating +application documentation). There is a need to stay organized and +consistent across all translations. +</para> + +</chapter> + +&using; +&catman; +&kbabeldictchapter; +&dictionaries; +&preferences; +&menu; +&kbabelfaq; + + +<chapter id="credits"> +<title>Credits and License</title> + +<para> +&kbabel; +</para> +<para> +Program Copyright © 1999-2000 &Matthias.Kiefer; &Matthias.Kiefer.mail; +</para> +<para> +Contributors: +<itemizedlist> +<listitem><para>&Thomas.Diehl; &Thomas.Diehl.mail;</para> +</listitem> +<listitem><para>&Stephan.Kulow; &Stephan.Kulow.mail;</para> +</listitem> +</itemizedlist> +</para> + +<para>Documentation Copyright © 2000 &Claudiu.Costin; +&Claudiu.Costin.mail; and &Matthias.Kiefer; +&Matthias.Kiefer.mail;</para> + +<para>Update for &kde; 3.0 Copyright © 2002 &Stanislav.Visnovsky; +&Stanislav.Visnovsky.mail;</para> + +<para>Update for &kde; 3.5.1 Copyright © 2005 Nicolas Goutte +<email>goutte@kde.org</email></para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; + +</chapter> + +&glossary; + +<appendix id="mailing-list"> +<title>Mailing List For KBabel</title> + +<para> +There is a mailing list for KBabel named kbabel. +It is a mixed list for developers and for users of KBabel. +</para> + +<para> +You can subscribe it at +<ulink url="http://mail.kde.org/mailman/listinfo/kbabel/">the Mailman interface</ulink>. +</para> + +<para> +The mailing list has +<ulink url="http://mail.kde.org/pipermail/kbabel/">a public archive</ulink>. +</para> + +</appendix> + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +End: +--> diff --git a/doc/kbabel/kbabeldict.docbook b/doc/kbabel/kbabeldict.docbook new file mode 100644 index 00000000..efe70b79 --- /dev/null +++ b/doc/kbabel/kbabeldict.docbook @@ -0,0 +1,85 @@ +<!-- <?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 --> + +<!-- Note: the id attribute "using-kbabeldict" is used in KBabelDict's source code to call the help. +So if you change this id attribute, the name *must* be changed in KBabelDict's source code too! --> +<chapter id="using-kbabeldict"> +<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 &kbabeldict;</title> +<anchor id="kbabeldict"/> +<para> +&kbabeldict; is a simple interface for translation modules for +&kbabel;. It allows you to search for translations. +</para> +<screenshot> +<screeninfo>Screenshot of &kbabeldict;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="snap_kbabeldict.png" format="PNG"/> +</imageobject> +<textobject><phrase>Screenshot of &kbabeldict;</phrase></textobject> +</mediaobject> +</screenshot> +<para> +The screenshot +above does not contain settings for selected module. You can show +them using <guibutton>Show Settings</guibutton>. Preferences +widget for selected module will be shown on the +right side of the window. The &kbabeldict; +window then looks like this: +</para> +<screenshot> +<screeninfo>Screenshot of &kbabeldict;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="snap_kbabeldict2.png" format="PNG"/> +</imageobject> +<textobject><phrase>Screenshot of &kbabeldict; with shown settings</phrase></textobject> +</mediaobject> +</screenshot> +<para> +The usage is very simple. You select a module to in the +<guilabel>Search in module</guilabel> combo-box. +Then you enter the phrase to lookup and press <guibutton>Start +Search</guibutton>. All found messages are shown in the list +below, which is the same as a tool in the &kbabel; main window. +Searching can be stopped by pressing <guilabel>Stop</guilabel>. +In case you want to search in translated text, not in original English message, +you should use <guilabel>Search in translations</guilabel>. +</para> +<para> +Buttons on the bottom of the window can be used for closing &kbabeldict;, +showing/hiding the module settings or displaying a dialog with credits for +&kbabeldict; and the modules themselves. +</para> +<note> +<para> +For description of the standard modules and their settings see +<xref linkend="dictionaries"/>. +</para> +</note> +</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 +-->
\ No newline at end of file diff --git a/doc/kbabel/man-catalogmanager.1.docbook b/doc/kbabel/man-catalogmanager.1.docbook new file mode 100644 index 00000000..00d500c0 --- /dev/null +++ b/doc/kbabel/man-catalogmanager.1.docbook @@ -0,0 +1,77 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<date>2003-03-07</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>catalogmanager</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>catalogmanager</command></refname> +<refpurpose>Advanced catalog manager for &kbabel;</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>catalogmanager</command> +<group><option>--project</option> <replaceable>config-file</replaceable></group> +<group><option>KDE Generic Options</option></group> +<group><option>Qt Generic Options</option></group> + +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para>CatalogManager is part of a suite of programs for editing +gettext message files (PO-files). This suite is designed to help you +translate fast and consistently.</para> + +<para>This suite includes &kbabel;, +<application>CatalogManager</application> and &kbabeldict;. &kbabel; +is an advanced and easy to use PO-file editor with full navigational +and editing capabilities, syntax checking and +statistics. <application>CatalogManager</application> (this program) +is a multi functional catalog manager which allows you to keep track +of many PO-files at once. &kbabeldict; is a dictionary for +translators.</para> +<para>This utility is part of the &kde; Software Development Kit.</para> + +</refsect1> + +<refsect1> +<title>Options</title> + +<variablelist> +<varlistentry> +<term><option>--project</option> <replaceable>config-file</replaceable></term> +<listitem> +<para>Load the configuration from the given file.</para> +</listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>kbabel(1) kbabeldict(1)</para> + +<para>More detailed user documentation is available from <ulink +url="help:/kbabel">help:/kbabel</ulink> (either enter this +<acronym>URL</acronym> into &konqueror;, or run +<userinput><command>khelpcenter</command> +<parameter>help:/kbabel</parameter></userinput>).</para> + +</refsect1> + +</refentry> diff --git a/doc/kbabel/menu.docbook b/doc/kbabel/menu.docbook new file mode 100644 index 00000000..14c474b5 --- /dev/null +++ b/doc/kbabel/menu.docbook @@ -0,0 +1,2320 @@ +<!-- <?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="commands"> + +<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>Command Reference</title> + +<sect1 id="kbabel-menu"> +<title>The &kbabel; menu</title> + +<sect2> +<title>The File Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>O</keycap> + </keycombo> + </shortcut> + <guimenu>File</guimenu> + <guimenuitem>Open</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a PO file. If the current file + is modified you will be prompted to save it first. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>Open Recent</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a recently edited PO file from the recently-used documents menu + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>S</keycap> + </keycombo> + </shortcut> + <guimenu>File</guimenu> + <guimenuitem>Save</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Saves the current PO file. If it is not modified no action is taken. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>Save As</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Saves the current PO file under a new name + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>Save Special</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Displays the Save Settings dialog and then saves the current PO file under a new name + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>Revert</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Loads the last saved version of the current PO file + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>Mail</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Prompts for an archive filename in which to store the current PO file then opens an email composer + window with the archive as an attachment + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>New View</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a new window with the currently loaded file. + </action> + Very useful if you have to translate large + files and need to refer back to some strings. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>New Window</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a new empty window + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Q</keycap> + </keycombo> + </shortcut> + <guimenu>File</guimenu> + <guimenuitem>Quit</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Quits &kbabel; editor + </action> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Edit Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Z</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Undo</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Undoes the last edit action in the translation edit box + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;&Shift;<keycap>Z</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Redo</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Redoes the last undone edit action in the translation edit box + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>X</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Cut</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Cuts the selected text and moves it to the clipboard + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>C</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Copy</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Copies the selected text to the clipboard + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>V</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Paste</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Pastes the contents of the clipboard at the current cursor + position in the translation edit box. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Edit</guimenu> + <guimenuitem>Select All</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Selects all text in the translation edit box + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>F</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Find...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a Find dialog for searching for strings in the current PO file + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycap>F3</keycap> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Find Next</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Finds the next occurrence of a string from the previous search action + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>R</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Replace...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens the Replace dialog to search for and replace strings in the current PO file + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Delete</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Clear</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Clears the translation for the current msgid + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Space</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Copy msgid to msgstr</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Copies the original English string into the translation edit + box. This is useful when you do not need to make any changes + (or only minor changes) to the original English text (msgstr). + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;&Alt;<keycap>Space</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Copy search result to msgstr</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Copies a string found after a translation search + into the msgstr edit box. This is + very useful if you do not want to keep + re-translating the same message again and again. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>U</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Toggle Fuzzy Status</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Toggles the fuzzy status for the current entry.</action> It can be useful to turn fuzzy on, + ⪚ to mark the translation for another review. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;&Alt;<keycap>N</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Insert Next Tag</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Inserts the next tag found in the msgid into the translation, if the original English string contains markup tags + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul">&Ctrl;&Alt;<keycap>N</keycap></keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guisubmenu>Insert Tag</guisubmenu> + </menuchoice> + </term> + <listitem> + <para> + <action> + This submenu contains all markup tags found in the original English string. By selecting one of them you can insert at the current position of cursor in translated text. + translation. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Edit</guimenu> + <guimenuitem>Edit Header...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Edits the PO file header. + </action> + Actually there are many header lines, which + keep the last translated date, translator name and email, language and + translated text encoding, &etc;. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + + +<sect2> +<title>The Go Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycap>Page Up</keycap> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Previous</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Skips to the previous entry in the PO file. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycap>Page Down</keycap> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Next</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Skips to the next entry in the PO file. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Go</guimenu> + <guimenuitem>Go to...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a dialog to jump to a specific entry number within the PO file. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Go</guimenu> + <guimenuitem>First Entry</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the first entry in the PO file. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Go</guimenu> + <guimenuitem>Last Entry</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the last entry in the PO file. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;&Shift;<keycap>Page Up</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Previous fuzzy or untranslated</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the entry previous to the current one that is untranslated or + marked as fuzzy. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;&Shift;<keycap>Page Down</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Next fuzzy or untranslated</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the next entry after the current one which is untranslated or + marked as fuzzy. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>PgUp</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Previous fuzzy</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the entry previous to the current one that is marked as fuzzy. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Page Down</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Next fuzzy</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the next entry after the current one that is marked as fuzzy. + </action> + </para> + </listitem> + </varlistentry> +<varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Alt;<keycap>Page Up</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Previous untranslated</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the entry previous to the current one that is untranslated. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Alt;<keycap>Page Down</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Next untranslated</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the next entry after the current one that is untranslated. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Shift;<keycap>Page Up</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Previous error</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the previous entry that has an error. This is usually when + double-quotes are not escaped or the original string ends with a + "newline" (\n) character and the translated string does not (and vice versa). + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Shift;<keycap>Page Down</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Next error</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jumps to the next entry with an error. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Alt;<keycap>Left Arrow</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Back</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jump to last visited entry</action> in PO file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Alt;<keycap>Right Arrow</keycap> + </keycombo> + </shortcut> + <guimenu>Go</guimenu> + <guimenuitem>Forward</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Jump to previous visited entry</action> in PO file. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + + +<sect2> +<title>The Dictionaries Menu</title> +<para> +Note that this menu is dynamic: it depends on the installed dictionaries plugins. +By default are three of them. +</para> + +<variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Search Text</guimenuitem> + <guimenuitem>KDE Database Search Engine</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start searching translation for current original + English message</action> using &kde; Database Search Engine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Search Text</guimenuitem> + <guimenuitem>PO Auxiliary</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start searching translation for current original + English message</action> in <acronym>PO</acronym> file defined by user. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Search Text</guimenuitem> + <guimenuitem>PO Compendium</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start searching translation for current original + English message in compendium file (made + by merging all translated messages for + one language). + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Search Selected Text</guimenuitem> + <guimenuitem>KDE Database Search Engine</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start searching selected text</action> + using &kde; Database Search Engine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Search Selected Text</guimenuitem> + <guimenuitem>PO Auxiliary</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start searching selected text + using file defined by user. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Search Selected Text</guimenuitem> + <guimenuitem>PO Compendium</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start searching selected text + using compendium file with + all language translated messages. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Dictionaries</guimenu> + <guimenuitem>Edit Dictionary</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Allow you to edit content + of current dictionary. Useful + if you found errors in dictionary + and do not want errors to be reported + when searching and replacing + strings. + </action> + <emphasis>(Not implemented yet)</emphasis> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + + + +<sect2> +<title>The Tools Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Spelling</guimenuitem> + <guimenuitem>Spell check...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Display the spell-check configuration dialog.</action> + After you have chosen the desired options, hit + <guibutton>OK</guibutton> and the normal spell-checking + dialog will appear. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Spelling</guimenuitem> + <guimenuitem>Check All...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start spell-checking all words</action> + for an opened <acronym>PO</acronym> file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Spelling</guimenuitem> + <guimenuitem>Check From Cursor Position...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Start spell-checking + from current cursor position. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Spelling</guimenuitem> + <guimenuitem>Check Current...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Spell-check only current</action> + entry from <acronym>PO</acronym> file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Spelling</guimenuitem> + <guimenuitem>Check Marked Text...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Spell-check only + selected text in MsgStr editbox. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>T</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Validation</guimenuitem> + <guimenuitem>Check Syntax</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Check syntax</action> for current <acronym>PO</acronym> file. + Errors may appear from <acronym>CVS</acronym> merging + or users' mistakes when the translating + process is performed by hand. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>D</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Validation</guimenuitem> + <guimenuitem>Check Arguments</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When this option is selected, C-format strings in the original message and + the translation are checked to ensure the number of + format sequences and the order are consistent. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>H</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Validation</guimenuitem> + <guimenuitem>Check Accelerators</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + When this option is selected, &kbabel; <action>checks if the number +of accelerator + characters is identical in both the original and the translated + string.</action> Note that accelerator marker is & in &kde; + (but not in every programming toolkit). See the + <link linkend="preferences-project-miscellaneous">Miscellaneous</link> section + below to find out how to change a keyboard accelerator. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>K</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Validation</guimenuitem> + <guimenuitem>Look for Translated Context Info</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Some original messages are marked with + context information to mark them as being unique even + if they represent same word. This is because + many simple words, such as <quote>Save</quote>, are translated into + many languages. Context information + is marked with <literal>_:</literal>. Many + unexperienced translators translate the context information + and fill their <quote>PO</quote> files with garbage. <action>Check this box to make sure you will be warned about these errors in a file.</action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Validation</guimenuitem> + <guimenuitem>Check Plural Forms (KDE only)</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Check if the <acronym>PO</acronym> file <action>contains the correct number of translations</action> for each &kde;-specific plural form message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>J</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Validation</guimenuitem> + <guimenuitem>Check Equations</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Check whether the left side of the translated string + is the same as the left side of the original string. + Sides are delimited by an equals-sign character. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo> + <keycap>F5</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Diff</guimenuitem> + <guimenuitem>Show Diff</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Show difference found to the original translated message. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo> + <keycap>F6</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Diff</guimenuitem> + <guimenuitem>Show Original Text</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Hide difference markings and show msgid only. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Diff</guimenuitem> + <guimenuitem>Open File for Diff</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Open file to be used for difference lookup. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Diff</guimenuitem> + <guimenuitem>Diffmode</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Toggle difference mode. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Rough Translation...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Invoke rough-translation dialog for automated translation. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Catalog Manager...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Open &catalogmanager;. Read + <link linkend="using-catalogmanager">&catalogmanager;</link> section + for more details. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Settings Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Toolbar</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, the standard toolbar is displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Statusbar</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, the bottom statusbar is displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Navigation Bar</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, the navigation bar is displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Comments</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, the upper-right part of main window, + which contains current entry's comments, will be displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Tools</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, the bottom-right part of main window, + which contain search results through the + dictionary, will be displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Key Bindings...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a configure dialog for binding keys to + actions. This will let you to customize the default + key bindings to suite your needs. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Toolbars...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Standard toolbar-configuration dialog will open. You can + choose which actions will go in which toolbars and what toolbar + to customize. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Kbabel...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + All &kbabel;-specific settings go here. + Please read the <link linkend="preferences-global">&kbabel; Global Settings</link> section for specific topics. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Dictionary</guimenuitem> + <guimenuitem>KDE Database Search Engine</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Open dialog for &kde; Database Search Engine + configuration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Dictionary</guimenuitem> + <guimenuitem>PO Auxiliary</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Open dialog</action> for <acronym>PO</acronym> auxiliary file + configuration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Dictionary</guimenuitem> + <guimenuitem>PO Compendium</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Open dialog</action> for <acronym>PO</acronym> compendium file + configuration. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Help Menu</title> + +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycap>F1</keycap> + </shortcut> + <guimenu>Help</guimenu> + <guimenuitem>Contents</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Open the &kbabel; handbook. It is what + you are reading now. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo> + &Shift;<keycap>F1</keycap> + </keycombo> + </shortcut> + <guimenu>Help</guimenu> + <guimenuitem>What's This?</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Cursor change to arrow with question mark and you can click with it + on various elements on main window. A quick help window will open. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>Gettext Info</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Open the gettext manual page</action> in the &kde; Help Center. + This package of tools helps the in process of handling + <acronym>POT</acronym> and <acronym>PO</acronym> files. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>Report Bug...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + This will open a standard error-reporting dialog + </action> for &kde; + It is useful if + you experience abnormal behavior of &kbabel;. + &kbabel;'s developer will be glad to receive any comments, wishes, and + bug reports. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>About KBabel...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Open a message box which inform you about &kbabel;'s version, developer + name, and e-mail address. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>About KDE...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Open a message box which informs you about the &kde; project, + contact information, and how you can report bugs and + wishes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>About Dictionary</guimenuitem> + <guimenuitem>KDE Database Search Engine</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Display a message box with information + about the people who made the &kde; Database Search Engine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>About Dictionary</guimenuitem> + <guimenuitem>PO Auxiliary</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Display a message box with information + about the people who made searching in auxiliary file possible. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>About Dictionary</guimenuitem> + <guimenuitem>PO Compendium</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Display a message box with information + about people who made searching in compendium file possible. + </action> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> +</sect1> + +<sect1 id="kbabel-toolbars"> +<title>The &kbabel; toolbars</title> + +<sect2 id="standard-toolbar"> +<title>Standard Toolbar</title> +<variablelist> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="fileopen.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Open + </term> + <listitem> + <para>Load <acronym>PO</acronym> file in &kbabel; for editing.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="filesave.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Save + </term> + <listitem> + <para>Save current <acronym>PO</acronym> file if it is modified.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="undo.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Undo + </term> + <listitem> + <para>Undo last operation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="redo.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Redo + </term> + <listitem> + <para>Redo last operation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="editcut.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Cut + </term> + <listitem> + <para>Cut selected text and move it to the clipboard.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="editcopy.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Copy + </term> + <listitem> + <para>Copy selected text to the clipboard.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="editpaste.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Paste + </term> + <listitem> + <para>Paste text from clipboard at the current cursor position.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="find.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Find + </term> + <listitem> + <para>Find specified string in current PO-file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="previous.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Previous + </term> + <listitem> + <para>Skip to previous entry in PO-file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="next.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Next + </term> + <listitem> + <para>Skip to next entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="msgid2msgstr.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Copy <acronym>msgid</acronym> to <acronym>msgstr</acronym> + </term> + <listitem> + <para>Copy original string to translated string edit box.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="transsearch.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Search Translations + </term> + <listitem> + <para>Drop-down toolbar for searching selected text using: + &kde; Database Search Engine, <acronym>PO</acronym> auxiliary file, <acronym>PO</acronym> compendium file, + and other dictionary plugins if available.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="stop.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Stop + </term> + <listitem> + <para>Stop current search-in-progress.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="catalogmanager.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Catalog Manager + </term> + <listitem> + <para>Open Catalog Manager window.</para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2 id="navigation-toolbar"> +<title>Navigation Toolbar</title> +<variablelist> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="previous.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Previous + </term> + <listitem> + <para>Skip to previous entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="next.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Next + </term> + <listitem> + <para>Skip to next entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="top.png" format="PNG"/> +</imageobject> +</inlinemediaobject> First Entry + </term> + <listitem> + <para>Jump to first entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="bottom.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Last Entry + </term> + <listitem> + <para>Jump to last entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="prevfuzzyuntrans.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Previous fuzzy or untranslated + </term> + <listitem> + <para>Jump to previous fuzzy or untranslated entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="nextfuzzyuntrans.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Next fuzzy or untranslated + </term> + <listitem> + <para>Jump to next fuzzy or untranslated entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="prevfuzzy.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Previous fuzzy + </term> + <listitem> + <para>Jump to previous fuzzy entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="nextfuzzy.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Next fuzzy + </term> + <listitem> + <para>Jump to next fuzzy entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="prevuntranslated.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Previous untranslated + </term> + <listitem> + <para>Jump to previous untranslated entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="nextuntranslated.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Next untranslated + </term> + <listitem> + <para>Jump to next untranslated entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="preverror.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Previous error + </term> + <listitem> + <para>Jump to previous error in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="nexterror.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Next error + </term> + <listitem> + <para>Jump to next error in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="back.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Back + </term> + <listitem> + <para>Jump to last visited entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <inlinemediaobject> +<imageobject> +<imagedata fileref="forward.png" format="PNG"/> +</imageobject> +</inlinemediaobject> Forward + </term> + <listitem> + <para>Jump to previous visited entry in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2 id="status-bar"> +<title>Status Bar</title> +<variablelist> + <varlistentry> + <term>Current</term> + <listitem> + <para>Current message in edited <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Total</term> + <listitem> + <para>Total number of messages in <acronym>PO</acronym> file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Fuzzy</term> + <listitem> + <para>Number of messages marked as fuzzy. They should be revised + and translated if needed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Untranslated</term> + <listitem> + <para>Number of yet untranslated messages.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Editor status</term> + <listitem> + <para>INS - insert, and OVR - overwrite. + Same meaning like in every ordinary text editor. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>PO-file status</term> + <listitem> + <para>RO - read-only file, RW - read-write access on file. + When a file is read-only you cannot modify entries + in editor. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Progress bar</term> + <listitem> + <para> + Usually, this bar is hidden; it is displayed + only when saving is being done, or if you are searching for messages + in a PO-file, compendium, or elsewhere. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +</sect1> + +<sect1 id="catalogmanager-menu"> +<title>The &catalogmanager; menu</title> + +<sect2> +<title>The File Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Q</keycap> + </keycombo> + </shortcut> + <guimenu>File</guimenu> + <guimenuitem>Quit</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action>Quits &catalogmanager;</action> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Edit Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>F</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Find in Files...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Open Find dialog for searching for strings in a set of PO files. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>R</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Replace in Files...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Open Replace dialog for searching for and replacing strings in a set of PO files. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo> + <keycap>Escape</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Stop Searching</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Stop currently running find/replace operation. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>M</keycap> + </keycombo> + </shortcut> + <guimenu>Edit</guimenu> + <guimenuitem>Toggle Marking</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Toggle mark for the selected file. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Edit</guimenu> + <guimenuitem>Remove Marking</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Removes mark for the selected file or folder. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Edit</guimenu> + <guimenuitem>Toggle All Markings</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Toggles marks for the selected file or folder (recursively). + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Edit</guimenu> + <guimenuitem>Remove All Markings</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Remove marks for the selected file or folder (recursively). + </action> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Tools Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>S</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Statistics</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Show statistics about number of translated/untranslated/fuzzy messages + for the selected file or subtree. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <shortcut> + <keycombo action="simul"> + &Ctrl;<keycap>Y</keycap> + </keycombo> + </shortcut> + <guimenu>Tools</guimenu> + <guimenuitem>Check Syntax</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Check syntax for the selected file or subtree using msgfmt. + </action> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Settings Menu</title> +<variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Toolbar</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, standard toolbar is displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Show Statusbar</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + When checked, bottom statusbar is displayed. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Key Bindings...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Opens a configure dialog for binding keys to + actions. This will let you to customize the default + key bindings to suite your needs. + </action> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <menuchoice> + <guimenu>Settings</guimenu> + <guimenuitem>Configure Toolbars...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action> + Standard toolbar-configuration dialog will open. You can + choose which actions will go in which toolbars and what toolbar + to customize. + </action> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>The Help Menu</title> +&help.menu.documentation; +</sect2> + +</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 +--> + diff --git a/doc/kbabel/msgid2msgstr.png b/doc/kbabel/msgid2msgstr.png Binary files differnew file mode 100644 index 00000000..938ea3ce --- /dev/null +++ b/doc/kbabel/msgid2msgstr.png diff --git a/doc/kbabel/next.png b/doc/kbabel/next.png Binary files differnew file mode 100644 index 00000000..f0b977bf --- /dev/null +++ b/doc/kbabel/next.png diff --git a/doc/kbabel/nexterror.png b/doc/kbabel/nexterror.png Binary files differnew file mode 100644 index 00000000..1009eae0 --- /dev/null +++ b/doc/kbabel/nexterror.png diff --git a/doc/kbabel/nextfuzzy.png b/doc/kbabel/nextfuzzy.png Binary files differnew file mode 100644 index 00000000..5912e52d --- /dev/null +++ b/doc/kbabel/nextfuzzy.png diff --git a/doc/kbabel/nextfuzzyuntrans.png b/doc/kbabel/nextfuzzyuntrans.png Binary files differnew file mode 100644 index 00000000..fd373e2f --- /dev/null +++ b/doc/kbabel/nextfuzzyuntrans.png diff --git a/doc/kbabel/nextuntranslated.png b/doc/kbabel/nextuntranslated.png Binary files differnew file mode 100644 index 00000000..3b4f8202 --- /dev/null +++ b/doc/kbabel/nextuntranslated.png diff --git a/doc/kbabel/pref_diff.png b/doc/kbabel/pref_diff.png Binary files differnew file mode 100644 index 00000000..014ea5ef --- /dev/null +++ b/doc/kbabel/pref_diff.png diff --git a/doc/kbabel/pref_edit_appearance.png b/doc/kbabel/pref_edit_appearance.png Binary files differnew file mode 100644 index 00000000..1306704e --- /dev/null +++ b/doc/kbabel/pref_edit_appearance.png diff --git a/doc/kbabel/pref_edit_general.png b/doc/kbabel/pref_edit_general.png Binary files differnew file mode 100644 index 00000000..d1542289 --- /dev/null +++ b/doc/kbabel/pref_edit_general.png diff --git a/doc/kbabel/pref_fonts.png b/doc/kbabel/pref_fonts.png Binary files differnew file mode 100644 index 00000000..b92e1b7a --- /dev/null +++ b/doc/kbabel/pref_fonts.png diff --git a/doc/kbabel/pref_proj_catman.png b/doc/kbabel/pref_proj_catman.png Binary files differnew file mode 100644 index 00000000..1e30bb25 --- /dev/null +++ b/doc/kbabel/pref_proj_catman.png diff --git a/doc/kbabel/pref_proj_diff.png b/doc/kbabel/pref_proj_diff.png Binary files differnew file mode 100644 index 00000000..27cb370e --- /dev/null +++ b/doc/kbabel/pref_proj_diff.png diff --git a/doc/kbabel/pref_proj_file_commands.png b/doc/kbabel/pref_proj_file_commands.png Binary files differnew file mode 100644 index 00000000..fe83050f --- /dev/null +++ b/doc/kbabel/pref_proj_file_commands.png diff --git a/doc/kbabel/pref_proj_folder_commands.png b/doc/kbabel/pref_proj_folder_commands.png Binary files differnew file mode 100644 index 00000000..cf0f742f --- /dev/null +++ b/doc/kbabel/pref_proj_folder_commands.png diff --git a/doc/kbabel/pref_proj_source.png b/doc/kbabel/pref_proj_source.png Binary files differnew file mode 100644 index 00000000..278e2ebd --- /dev/null +++ b/doc/kbabel/pref_proj_source.png diff --git a/doc/kbabel/pref_search.png b/doc/kbabel/pref_search.png Binary files differnew file mode 100644 index 00000000..cdb5c6d1 --- /dev/null +++ b/doc/kbabel/pref_search.png diff --git a/doc/kbabel/pref_wizard_page1.png b/doc/kbabel/pref_wizard_page1.png Binary files differnew file mode 100644 index 00000000..b88b954d --- /dev/null +++ b/doc/kbabel/pref_wizard_page1.png diff --git a/doc/kbabel/pref_wizard_page2.png b/doc/kbabel/pref_wizard_page2.png Binary files differnew file mode 100644 index 00000000..e561cff2 --- /dev/null +++ b/doc/kbabel/pref_wizard_page2.png diff --git a/doc/kbabel/preferences.docbook b/doc/kbabel/preferences.docbook new file mode 100644 index 00000000..fbaeee10 --- /dev/null +++ b/doc/kbabel/preferences.docbook @@ -0,0 +1,1418 @@ +<!-- <?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="preferences"> +<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>Preferences</title> + + +<sect1 id="preferences-overview"> +<title>Global and project settings</title> + +<para> +From KBabel 1.10 (KDE 3.4) on, KBabel has the concept of projects and therefore +the settings have been split in two categories: +the global settings and the project settings (also called project configuration). +</para> + +<important><para> +&GNU; gettext uses a term called "project", which has nothing to do with +KBabel's projects. &GNU; gettext means by project an application which is +related to the <acronym>PO</acronym> file. For KBabel, a project is +much bigger. It can mean a set of applications, like &kde;. +</para></important> + +<para> +KBabel has <emphasis>always</emphasis> a current project, even if it is the +default project. KBabel has not mode without any project. A project is always +for KBabel's editor and KBabel's catalog manager. +</para> + + +<sect2 id="preferences-limitations"> +<title>Known limitations of the current implementation</title> + +<para> +Unfortunately the current implementation of projects has a few known problems. +</para> + +<para> +An example is that in the global settings, there is no setting for the default user, +his/her default language and other similar important global user data. It means that such +data must be entered again each time that a new project is created. +</para> + +<para> +Another problem is the new project wizard. It does not ask enough information, especially +it fails to ask for the team email address. So it is recommended to check the project +settings after having run the wizard. +</para> + +<tip><para> +Currently you cannot copy projects from inside KBabel, so apparently you cannot easily share good settings. +However you are free to copy the project outside KBabel and to load the copied project into KBabel. +</para></tip> + +</sect2> + +<sect2 id="preferences-non-kde-projects"> +<title>Using KBabel for non-&kde; projects</title> + +<para> +While &kbabel;'s defaults are oriented toward working with and for &kde;, &kbabel; can be used +to translate <acronym>PO</acronym> files of other projects. However mostly you will have to tweak the +settings to the need of your project. This is especially true for &GNU; and +&GNU;-like projects, which need quite different defaults than for &kde;. +</para> + +<para> +One problem is that &kbabel; is relatively agressive when saving <acronym>PO</acronym> files and +replaces setting of the <acronym>PO</acronym> files by settings of the projects, if not told otherwise. +This might look very strange to somebody not used to &kde;. However &kde; has 900+ +<acronym>POT</acronym> files to translate for the <acronym>GUI</acronym> messages only. +So for such a task, much automatisation is wanted. Taking time to set a project +is little compared to the time gained thereafter. Of course, as non-&kde; user, you +might be less fortunate. You need to do more settings, as the defaults are not entirely suitable +and you will not gain much by doing many translations, as &GNU; projects have typically +only one <acronym>POT</acronym> file to translate. +</para> + +</sect2> + +</sect1> + +<sect1 id="preferences-global"> +<title>&kbabel; global settings</title> + +<para> +To show the Preferences dialog choose +<menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure +KBabel...</guimenuitem></menuchoice> from &kbabel;'s menu. It uses a +structured configuration dialog which makes it very easy to find an +option without having to perform an extensive search for it. +</para> + +<sect2 id="preferences-editor"> +<title>Edit</title> +<para> +The editor preferences category is divided in 3 subwindows: +<guilabel>General</guilabel>, <guilabel>Appearance</guilabel>, +<guilabel>Spell Check</guilabel> and <guilabel>Fonts</guilabel>. +All these settings customize how the editor behaves and looks. +</para> + +<sect3 id="preferences-editor-general"> +<title>General</title> + +<screenshot> +<screeninfo>Dialog Edit General</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_edit_general.png" format="PNG"/> +</imageobject> +<textobject><phrase>Dialog Edit General</phrase></textobject> +</mediaobject> +</screenshot> + +<para>This section contains a set of checkboxes.</para> + +<para>The first checkbox in the upper side sets if the fuzzy status is +reset automatically when a character is inputted into the MsgStr +editor. When this option is disabled you have to manually choose +<menuchoice><guimenu>Edit</guimenu><guimenuitem>Unset Fuzzy Status +</guimenuitem></menuchoice> or use the <keycombo +action="simul">&Ctrl;<keycap>U</keycap></keycombo> shortcut. Note +that this means the string <literal>, fuzzy</literal> is removed from +the entry's comment.</para> + +<para>Next option allows you to enable <quote>clever</quote> editing, +where editor automatically inserts special characters escaped +correctly, ⪚ <literal>\t</literal> after pressing +<keycap>Tab</keycap> and it allows special handling of +<keycap>Enter</keycap>.</para> + +<para> +The lower checkboxes are very useful in assisting, not for the +correctness of the translation, but if the translated string +is a suitable replacement for the original. For +example, many messages represent menu items with keyboard accelerator +and C-like formatted strings whose structure must remain intact once +translated. +</para> + +<variablelist> + <varlistentry> + <term><guilabel>Check Arguments</guilabel></term> + <listitem> + <para> + When this option is selected, C-format strings in the original and + the translation are checked to ensure the number of + format sequences and the order are consistent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Check Accelerator</guilabel></term> + <listitem> +<para>When this option is selected, &kbabel; checks if the number +accelerator characters is identical in both the original and the +translated string. Note that accelerator marker is & (but not in +every programming toolkit). See the <link +linkend="preferences-project-miscellaneous">Miscellaneous</link> section below +to find how to change a keyboard accelerator.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Check Equation</guilabel></term> + <listitem> + <para> + This is a feature for the &kde; project development. + <filename>.desktop</filename> files are simply + text files which store various parameters in + <literal>value=key</literal> format. Some of + these <literal>key</literal>s are translatable. + The only restriction is to maintain the left + side of equality unchanged. Equation check + allows you to spot many errors determined + by the fuzzy <command>msgmerge</command> algorithm. + Note that there are situations where this function + generates false errors on some PO-files. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Look for Translated Context Info</guilabel></term> + <listitem> +<para> Some original messages are marked with context information to +mark them as being unique even if they represent same word. This is +because many simple words, such as <quote>Save</quote>, are translated +into many languages. Context information is marked with +<literal>_:</literal>. Many unexperienced translators translate the +context information and fill their PO files with garbage. Check this +box to make sure you will be warned about these errors in a +file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Check Plural Forms</guilabel></term> + <listitem> + <para> + If you are translating &kde; project, it uses a special kind of + syntax for specifying plural forms of messages. This check automatically + counts the number of forms in <acronym>msgstr</acronym> and + compares it with the number specified in +<link linkend="preferences-project-identity"><guilabel>Identity</guilabel></link> +tab. Incorrect number of plural forms can result in crash of an application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Beep on error</guilabel></term> + <listitem> + <para> + Your system bell will beep when you switch + on entries with errors like those described above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Change text color on error</guilabel></term> + <listitem> + <para> + This is another type of warning about + errors in current message. It is a good solution for those who are + hearing impaired or dislike bell noise. See also the + <link linkend="preferences-editor-appearance">Appearance</link> tab + to find out how to change the text color on errors. + </para> + </listitem> + </varlistentry> +</variablelist> + +</sect3> + +<sect3 id="preferences-editor-appearance"> +<title>Appearance</title> + +<screenshot> +<screeninfo>Dialog Edit Appearance</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_edit_appearance.png" format="PNG"/> +</imageobject> +<textobject><phrase>Dialog Edit Appearance</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +These options let +you configure the appearance for the message editor. In upper part there +are 4 checkboxes: +</para> + +<variablelist> + <varlistentry> + <term><guibutton>Highlight syntax</guibutton></term> + <listitem><para> + Setting this option will enable syntax highlighting for + special characters, accelerators and text background in the msgid viewer + and msgstr editor. If don't have a monochrome display or have a visual impairment, you should enable this option. +</para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Highlight background</guibutton></term> + <listitem><para> + The background will be highlighted only for existing characters in + the msgid and msgstr. This includes spaces. This is useful if you + don't want to see the surrounding quotes (see below) for the <acronym>PO</acronym> entry, and you will still + be able to observe starting and ending spaces in a text line. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Mark whitespaces with points</guibutton></term> + <listitem><para> + When you feel the need to count spaces + and background highlighting is not your taste then you can + check this option to have a point sign drawn in the middle of + whitespace characters. Note that the point is a point sign in the + center of a character box and is not a decimal point. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Show surrounding quotes</guibutton></term> + <listitem><para> + If you think that viewing the terminal characters in msgstr or + msgid's text line is better for you then check this option to view + the surrounding quotes for every text line.</para> + <para>If you are experienced editing <acronym>PO</acronym> files with + ordinary text editors you may feel safer if you can track starting and + ending double quotes in <acronym>PO</acronym> entry lines. + </para></listitem> + </varlistentry> +</variablelist> + +<para> +For the different items in edited text there are different color choices +to make editing easy. Colors can be changed by clicking on color-picker +buttons. From the 'select color' dialogs you can choose from standard +colors, custom colors or just pick a color from any part of your screen. +</para> + +<variablelist> + <varlistentry> + <term><guilabel>Background color</guilabel></term> + <listitem><para> + This sets the background color for characters in the MsgID view + and the MsgStr editor. To change the general background color + of edit boxes you must use the &kcontrolcenter;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Color for quoted characters</guilabel></term> + <listitem><para> + Here you can adjust the color for escaped characters like + (<literal>\"</literal>) double quotes or (<literal>\n</literal>) newline. </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Color for syntax errors</guilabel></term> + <listitem><para> + This is the color for the entire text entry if errors are + detected when you try to save <acronym>PO</acronym> file. Errors are + triggered by not terminating identically both <acronym>msgid</acronym> and <acronym>msgstr</acronym>, or + escaping characters incorrectly. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Color for c-format characters</guilabel></term> + <listitem><para> + This sets the color for a characters sequence like in + C language <function>printf</function> or <function>scanf</function> functions. In general these start with (<literal>%</literal>) percent char and are continued by one char. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Color for keyboard accelerators</guilabel></term> + <listitem><para> + Keyboard accelerators start with (&) <quote>ampersand</quote> + character in &kde; but if you are translating for other projects there might be an different character marking the accelerator key. +See <link linkend="preferences-project-miscellaneous">Miscellaneous</link> +section below to find how to change keyboard accelerator. + </para></listitem> + </varlistentry> +</variablelist> + +<para> The status for the current edited entry is marked by three +<acronym>LED</acronym>s. For your convenience you can choose where to +put these <acronym>LED</acronym>s—either on the statusbar or in +the editor section (between the msgid and msgstr entry). If have +difficulties viewing some colors or you want to be able to track +<acronym>LED</acronym> status changes easily without moving your eye +you can select the preferred color using the color button chooser. +</para> + +</sect3> + +</sect2> + +<sect2 id="preferences-search"> +<title>Search</title> + +<screenshot> +<screeninfo>Dialog Search</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_search.png" format="PNG"/> +</imageobject> +<textobject><phrase>Dialog Search</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +The search section allows you to customize various settings +for searching in previously translated strings. +</para> + +<para>General settings are common for all search types. If you check +the <guibutton>Automatically start search</guibutton> option then the +search is automatically started whenever you switch to another entry +in the editor. Currently, there are three possibilities you can choose +from, but since &kbabel; can use dictionary plugins the available +dictionaries depend on those installed. Using +<menuchoice><guimenuitem>Settings</guimenuitem> <guimenuitem>Configure +Dictionary</guimenuitem> <guimenuitem>...</guimenuitem></menuchoice> +you can configure every search plugin.</para> + +<para>The dictionary plugins installed by default are:</para> + +<variablelist> +<varlistentry> +<term>&kde; Database Search Engine</term> +<listitem> +<para>This new method is still in alpha stage of development + and is based on &kbabeldict; which accompanies &kbabel;. + See &kbabeldict; documentation for further info on + configuring the search engine. + </para></listitem> +</varlistentry> + +<varlistentry> +<term>PO Compendium</term> +<listitem><para>The compendium is a normal <acronym>PO</acronym> file, + which should contain a list of standard translations from your translation + team. If you don't have one, you can also use a file that contains all + the translations from your team (⪚ the <filename>$lang.messages</filename> + file in the &kde; Project, that can be found at + <ulink url="http://i18n.kde.org/po_overview/">i18n.kde.org</ulink>). + </para></listitem> +</varlistentry> + +<varlistentry> +<term>PO Auxiliary</term> +<listitem><para>The auxiliary should help you find the + context of a translation by looking up the same message in a message + catalog of the same package but translated to another language. This way + you can have a look how this message is translated in another language. + </para></listitem> +</varlistentry> +</variablelist> + +<para> +You can also start searching manually by choosing an +entry in the popup menu that appears, either by clicking +<menuchoice> +<guimenu>Dictionaries</guimenu><guimenuitem>Search Text</guimenuitem> +<guimenuitem>PO Compendium</guimenuitem></menuchoice> +or by keeping the search button on the toolbar pressed down for a while. +</para> + +</sect2> + +<sect2 id="preferences-diffmode"> +<title>Diff</title> + +<screenshot> +<screeninfo>Dialog Diff</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_diff.png" format="PNG"/> +</imageobject> +<textobject><phrase>Dialog Diff</phrase></textobject> +</mediaobject> +</screenshot> + +<para>The <guilabel>Diff</guilabel> section holds settings how to +display differences in msgids. </para> + +<para>Every difference can be displayed by two added parts and by characters removed from the text. For both you can specify the method of display and the color to be used. <guilabel>Highlighted</guilabel> means that the background of the corresponding characters will be shown in the selected color, while +<guilabel>Underlined</guilabel>(for added characters) or <guilabel>Stroked Out</guilabel> +(for removed characters) will denote the changed parts by colored lines. +</para> +<para> +Diff mode needs to find the original <acronym>msgid</acronym> to compare +with. For this purpose, &kbabel; can use the <link linkend="database">translation database</link> +if you turn in on by enabling <guilabel>Use messages from Translation Database</guilabel>. +A second possibility is to use a tree of original PO files and specifying the root of +the tree in <guilabel>Base folder for diff files</guilabel>. +</para> +</sect2> + +<sect2 id="preferences-fonts"> +<title>Fonts</title> + +<screenshot> +<screeninfo>Dialog Fonts</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_fonts.png" format="PNG"/> +</imageobject> +<textobject><phrase>Dialog Fonts</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +This is a standard &kde; font chooser dialog with a little addition. You can +select to view only fixed fonts by checking the +<guibutton>Show only fixed fonts</guibutton> option. +This is highly recommended for easy translating. The font dialog lets you set +font family, style, size and encoding. The bottom box shows a preview of the +current font for user convenience. +</para> +</sect2> + +</sect1> + +<sect1 id="preferences-project-wizard"> +<title>New Project Wizard</title> + +<sect2 id="preferences-project-wizard-basic"> +<title>Page 1</title> + +<screenshot> +<screeninfo>Project Wizard Page 1</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_wizard_page1.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Wizard Page 1</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +The first page of the wizard ask about the basic data of the project. +</para> + +<variablelist> +<varlistentry> +<term><guilabel>Project name</guilabel></term> +<listitem><para> +Enter here the name of the project, as it will be displayed in &kbabel;'s menu. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Configuration file name</guilabel></term> +<listitem><para> +Select here a file for holding your project settings. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Language</guilabel></term> +<listitem><para> +Select or enter here the language name used by this project. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Project type</guilabel></term> +<listitem><para> +Select here the type of your project. +</para></listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="preferences-project-wizard-catman"> +<title>Page 2</title> + +<screenshot> +<screeninfo>Project Wizard Page 2</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_wizard_page2.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Wizard Page 2</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +The second page of the wizard asks about settings related to the +Catalog Manager. +</para> + +<variablelist> +<varlistentry> +<term><guilabel>Base folder for PO files</guilabel></term> +<listitem><para> +Select the base folder where your PO files are. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Base folder for POT files</guilabel></term> +<listitem><para> +Select the base folder where your POT files are. +</para></listitem> +</varlistentry> +</variablelist> + +<para> +Type in or select the folders that contains all your <acronym>PO</acronym> and respectively +<acronym>POT</acronym> files. The files and the folders in these folders will then be +merged into one tree in &catalogmanager; window. +</para> + + +</sect2> + +<sect2> +<title>Checking Project Stettings</title> + +<important><para> +As written earlier in this chapter, unfortunately the wizard is very simple and +therefore fails to ask for some important settings. +</para></important> + +<para> +Now that you have <quote>finished</quote> your new project, you should verify the main settings in +<menuchoice><guimenu>Project</guimenu> <guimenuitem>Configure...</guimenuitem></menuchoice>. +Especially select the <guilabel>Identity</guilabel> page and fix the team email address in +<guilabel>Language mailing list</guilabel>. +(The default one created by the wizard from the language setting is only useful if you are part of a &GNU; project.) +</para> + +<para> +If the project settings are not for KDE, it is recommended that you check the +<guilabel>Save</guilabel> page and checks the settings there. +</para> + +</sect2> + +</sect1> + +<sect1 id="preferences-project-settings"> +<title>Project Settings</title> + +<para> To show the project setting dialog choose +<menuchoice><guimenu>Project</guimenu> <guimenuitem>Configure...</guimenuitem></menuchoice> +from &kbabel;'s or &catalogmanager;'s menu. It uses a +structured configuration dialog which makes it very easy to find an +option without having to perform an extensive search for it.</para> + +<para>The left side of the preferences dialog lists the categories of +customizable items and the right side shows the corresponding tab for +the selected category. &kbabel; keeps changes if you move between +categories, so when you're finally happy click the +<guibutton>OK</guibutton> button. At any time you can use quick +help—just click on the question mark on the title bar and, +after the cursor has changed to an arrow with a question mark, +click on a button, label, or preference entry to find out more +about it.</para> + +<note><para> +Pages for settings for &kbabel; (the editor) and for &catalogmanager; +are in the list. +</para></note> + +<sect2 id="preferences-project-identity"> +<title>Identity</title> + +<para>These settings are for &kbabel;.</para> + +<para>This section allows you to set standard fields for every +translated <acronym>PO</acronym> file. These are your name, email +address, full language name, email address for your translation team +mailing list. There is also a timezone field to track your +<quote>last modified</quote> time for <acronym>PO</acronym> files. +You can specify it as character sequence like <acronym>EEST</acronym> +or offset from <acronym>GMT</acronym> time like +0200 (&ie; for +Romania). This information is used when updating file headers. You +can find the options that control what fields in the header should be +updated in the <link linkend="preferences-project-save">Save</link> section of +the Preferences dialog.</para> + +<warning><para>Character sequences for timezones are not standardized. +So you should not use the string set here in time specification for +saving in <link linkend="preferences-project-save">Save</link> tab. You should +use <literal>%z</literal> instead.</para></warning> + +<variablelist> +<varlistentry> +<term><guilabel>Number of singular/plural forms</guilabel></term> +<listitem> +<para> Use this for setting number of plural forms for your +language. For example, it is 2 for German (one for the singular and +one for the plural form).</para> + +<note><para>This feature is currently implemented only for plural forms format used in &kde;. It does not work with &GNU; gettext plural forms.</para></note> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="preferences-project-save"> +<title>Save</title> + +<para>These settings are for &kbabel;.</para> + +<para><remark> +TODO This seems to document only the "General" tab but not the "Header" and "Copyright" ones +</remark></para> + +<para> +This section allows you to edit the options for <acronym>PO</acronym> file saving. The first +group of checkboxes controls general behavior for actions +performed in <acronym>PO</acronym> file saving. +</para> + +<variablelist> + <varlistentry> + <term><guibutton>Update header when saving</guibutton></term> + <listitem><para> +Check this button, to update the header information of the file +every time it is saved. The header normally keeps information +about the date and time the file was last updated,the last translator +etc. You can choose which information you want to update from the +<guilabel>Fields to update</guilabel> checkboxes area below. Fields +that do not exist are added to the header. If you want to add +additional fields to the header you can edit the header manually by +choosing <menuchoice><guimenu>Edit</guimenu> <guimenuitem>Edit +Header</guimenuitem></menuchoice> in the editor window. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Check syntax of file when saving</guibutton></term> + <listitem><para> +Check this to automatically check syntax of file with +<userinput><command>msgfmt</command> --statistics</userinput> when +saving a file. You will only get a message if an error occurred. You +should keep this validation enabled unless you know what you are doing. + </para></listitem> + </varlistentry> +</variablelist> + +<para>If you do not want to touch some fields in a <acronym>PO</acronym> +file header or want to force updating of specific fields, there are five +checkboxes which control this: revision date, <acronym>PO</acronym> file +language, text encoding, last translator name, charset. If a field +does not exist, it is appended to the header. If you want to add other +information to the header, you have to edit the header manually by +choosing <menuchoice><guimenu>Edit</guimenu><guimenuitem>Edit +Header</guimenuitem></menuchoice> in the editor window. Deactivate +<guibutton>Update header when saving</guibutton> above if you don't +want to have the header updated.</para> + +<para>For date and time of the header field +<emphasis>PO-Revision-Date</emphasis> you can choose one of the +formats: <guilabel>Default</guilabel>, <guilabel>Local</guilabel>, <guilabel>Custom</guilabel>.</para> + +<important><para> +You should keep the default setting of <guilabel>Default</guilabel>. The two other settings +make that the generated <acronym>PO</acronym> file is not a standard &GNU; gettext <acronym>PO</acronym> file +anymore, so this should be avoided. +</para></important> + +<itemizedlist> + <listitem><para> + <guilabel>Default</guilabel> is the format normally used in <acronym>PO</acronym> files. + </para></listitem> + <listitem><para> + <guilabel>Local</guilabel> is the format specific to your country. + </para></listitem> + <listitem><para> + <guilabel>Custom</guilabel> lets you define your own format, where you + can use the following C-like format strings: + <table> + <title>Year</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Format</entry><entry>Meaning</entry><entry>Range</entry> + </row> + </thead> + <tbody> + <row> + <entry>%y</entry><entry>year</entry><entry>00 to 99</entry> + </row> + <row> + <entry>%Y</entry><entry>year</entry><entry>0001 to 9999</entry> + </row> + </tbody> + </tgroup> + </table> + <table> + <title>Month</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Format</entry><entry>Meaning</entry><entry>Range</entry> + </row> + </thead> + <tbody> + <row> + <entry>%m</entry><entry>month of year</entry><entry>01 to 12</entry> + </row> + <row> + <entry>%f</entry><entry>month of year</entry><entry>1 to 12</entry> + </row> + <row> + <entry>%b,%h</entry><entry>month abbreviation</entry><entry>Jan to Dec</entry> + </row> + </tbody> + </tgroup> + </table> + <table> + <title>Day</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Format</entry><entry>Meaning</entry><entry>Range</entry> + </row> + </thead> + <tbody> + <row> + <entry>%j</entry><entry>day of the year</entry><entry>001 to 366</entry> + </row> + <row> + <entry>%d</entry><entry>day of month</entry><entry>01 to 31</entry> + </row> + <row> + <entry>%e</entry><entry>day of month</entry><entry>1 to 31</entry> + </row> + <row> + <entry>%a</entry><entry>weekday abbreviation</entry><entry>Sun to Sat</entry> + </row> + </tbody> + </tgroup> + </table> + <table> + <title>Hour</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Format</entry><entry>Meaning</entry><entry>Range</entry> + </row> + </thead> + <tbody> + <row> + <entry>%H</entry><entry>hour</entry><entry>00 to 23</entry> + </row> + <row> + <entry>%k</entry><entry>hour</entry><entry>0 to 23</entry> + </row> + <row> + <entry>%i</entry><entry>hour</entry><entry>1 to 12</entry> + </row> + <row> + <entry>%I</entry><entry>hour</entry><entry>01 to 12</entry> + </row> + <row> + <entry>%p</entry><entry></entry><entry>AM or PM</entry> + </row> + </tbody> + </tgroup> + </table> + <table> + <title>Minute, Second, Timezone</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Format</entry><entry>Meaning</entry><entry>Range</entry> + </row> + </thead> + <tbody> + <row> + <entry>%M</entry><entry>minute</entry><entry>00 to 59</entry> + </row> + <row> + <entry>%S</entry><entry>second</entry><entry>00 to 59</entry> + </row> + <row> + <entry>%Z</entry><entry>timezone</entry><entry>(given in identity settings)</entry> + </row> + <row> + <entry>%z</entry><entry>timezone</entry><entry>(numeric offset as specified by system settings)</entry> + </row> + </tbody> + </tgroup> + </table> + </para></listitem> +</itemizedlist> + +<note><para> +The option to select the date format for the <acronym>PO</acronym> file is considered to be deprecated, +and will probably be removed in a future version of KBabel. +</para></note> + +<para>The lower group covers encoding options for <acronym>PO</acronym> +files when saving. If you work on the &kde; project you should be aware +that at least <acronym>PO</acronym> files <emphasis>must</emphasis> be UTF-8 encoded in &kde;. +Alternatively you can select the encoding corresponding to your locale. +If, for some reason, you do not want to accidentally change the current PO +file encoding, turn on <guibutton>Keep the encoding of the +file</guibutton>.</para> + +<caution><para> +For reason of informtation interchange, &GNU; gettext limits the encodings allowed for a +<acronym>PO</acronym> file. &kbabel; does not know of this restriction, so the encoding +correspondig to your locale might not be suitable. (UTF-8 is always supported by &GNU; gettext.) +</para></caution> + +</sect2> + +<sect2 id="preferences-project-spellcheck"> +<title>Spell Check</title> + +<para>These settings are for &kbabel;.</para> + +<para>Here you can set your spell checking preferences. This is of +interest if you have a dictionary file for the language you are +translating to. Below are the items to consider setting:</para> + +<variablelist> + <varlistentry> + <term><guibutton>Create root/affix combinations not in dictionary</guibutton></term> + <listitem><para> + For new words added to the personal dictionary, + the spell checker will create root/affix + combinations to match more than one word (variations). + </para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Consider run-together words as spelling errors</guibutton></term> + <listitem><para> + If this is turned on, joined words will be treated + as errors. However, such words are very common in + the German language, which have a very large number of + compound words, so it should be left turned off in that case. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Dictionary</guilabel></term> + <listitem><para> + From the popup list you can choose which dictionary to use. Note + that you must install an appropriate dictionary for your language. + Check your ispell or aspell distribution to find out if you have + one. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Encoding</guilabel></term> + <listitem> +<para> + Here you choose the encoding for your text. This option is passed + to the spellchecker, and is used as the encoding for your words + dictionary. + See the <ulink url="help:/kspell">kspell</ulink> documentation for + more details. +</para> +<note><para> +The encoding selected here is not linked to encodings of the +<acronym>PO</acronym> files. Depending on the spellchecker +(especially in the case of <command>ispell</command>), +you might not have much choice for the encoding. +(For example, a few Western European languages can only work +with <command>ispell</command> when using ISO-8859-1.) +</para></note> + </listitem> + + </varlistentry> + <varlistentry> + <term><guilabel>Client</guilabel></term> + <listitem><para> + Backend program to use for spell checking. Currently either + <command>ispell</command> (International Ispell) or aspell. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Remember ignored words</guibutton></term> + <listitem><para> + Keep track of user-ignored words when spell-checking + <acronym>PO</acronym> files. It is very convenient to ignore the abbreviations or strange letter combinations you meet in &GUI; interfaces. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>File to store ignored words</guilabel></term> + <listitem><para> + Here you can set location of the file for ignored words. Click + on the folder icon to the right of the edit box. The default is + <filename>$<envar>HOME</envar>/.kde/share/apps/kbabel/spellignores</filename>, + where <filename>$<envar>HOME</envar></filename> is your home folder. + </para></listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2 id="preferences-project-source"> +<title>Source reference</title> + +<para>These settings are for &kbabel;.</para> + +<screenshot> +<screeninfo>Project Settings, source reference</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_proj_source.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Settings, source reference</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +This dialog is for setting how KBabel should construct the full path from each source references, +which are in the comments of each entry of a <acronym>PO</acronym> file. +</para> + +<sect3> +<title>Dialog elements</title> + +<para> +In the edit line <guilabel>Base folder for source code</guilabel>, you can set a +base folder where the source code of your project is. This defines the value of the variable +<userinput>@CODEROOT@</userinput>, which is described below. +</para> + +<para> +In the group <guilabel>Path Patterns</guilabel>, you can define patterns or rules +to construct the paths with the help of a few variables: +<userinput>@CODEROOT@</userinput>, <userinput>@PACKAGEDIR@</userinput>, +<userinput>@PACKAGE@</userinput>, <userinput>@COMMENTPATH@</userinput>, +<userinput>@POFILEDIR@</userinput>, which are defined below. +</para> + +<note><para> +The variable <userinput>@PODIRFILE@</userinput> was introduced in &kbabel; version 1.11.1 (for &kde; 3.5.1). +</para></note> + +<para> +With the button <guibutton>Add</guibutton>, you can add the line from the text box +to the list of used path patterns. With the button <guibutton>Remove</guibutton>, +you can remove the selected pattern from the list. With the buttons +<guibutton>Up</guibutton> and <guibutton>Down</guibutton>, you can change the priority of +the path patterns. +</para> + +</sect3> + +<sect3> +<title>The variables</title> + +<itemizedlist> +<listitem><para> +<userinput>@CODEROOT@</userinput>: The base folder of the source code. +</para></listitem> +<listitem><para> +<userinput>@PACKAGEDIR@</userinput>: The folder of the package (i.e. <acronym>PO</acronym> file). +</para></listitem> +<listitem><para> +<userinput>@PACKAGE@</userinput>: The package name (i.e. <acronym>PO</acronym> file name without extension). +</para></listitem> +<listitem><para> +<userinput>@POFILEDIR@</userinput>: The folder of the <acronym>PO</acronym> file. +</para></listitem> +<listitem><para> +<userinput>@COMMENTPATH@</userinput>: The relative path given as source reference in the comment of an entry of the <acronym>PO</acronym> file. +</para></listitem> +</itemizedlist> + +<important><para> +The variables <userinput>@PACKAGEDIR@</userinput> and <userinput>@POFILEDIR@</userinput> have similar +meaning but not the same result. The variable <userinput>@POFILEDIR@</userinput> +will always hold the folder of <acronym>PO</acronym> file, +<userinput>@PACKAGEDIR@</userinput> might not. If the <acronym>PO</acronym> file was loaded +by the help of the &catalogmanager; then <userinput>@PACKAGEDIR@</userinput> has only the part of +the path, based on the <acronym>PO</acronym> base path defined for the &catalogmanager; +<link linkend="preferences-project-folders">(see below)</link>. +</para></important> + +<note><para> +The variables <userinput>@CODEROOT@</userinput> and <userinput>@POFILEDIR@</userinput> can only be used at +the beginning of a pattern to be useful. The variable <userinput>@COMMENTPATH@</userinput> can only be used at the +end of a pattern and is nearly mandatory. +The variables <userinput>@PACKAGEDIR@</userinput> and <userinput>@POFILEDIR@</userinput> +should not be used in the same pattern. The variables <userinput>@CODEROOT@</userinput> and <userinput>@POFILEDIR@</userinput> should not be used in the same pattern either. +</para></note> + +</sect3> + +<sect3> +<title>The default path patterns</title> + +<para> +From &kbabel; 1.11.1 (of &kde; 3.5.1) on, there are five default path patterns: +</para> + +<itemizedlist> +<listitem><para> +<userinput>@PACKAGEDIR@</userinput>/<userinput>@PACKAGE@</userinput>/<userinput>@COMMENTPATH@</userinput> +</para></listitem> +<listitem><para> +<userinput>@CODEROOT@</userinput>/<userinput>@PACKAGEDIR@</userinput>/<userinput>@PACKAGE@</userinput>/<userinput>@COMMENTPATH@</userinput> +</para></listitem> +<listitem><para> +<userinput>@CODEROOT@</userinput>/<userinput>@PACKAGE@</userinput>/<userinput>@COMMENTPATH@</userinput> +</para></listitem> +<listitem><para> +<userinput>@POFILEDIR@</userinput>/<userinput>@COMMENTPATH@</userinput> +</para></listitem> +<listitem><para> +<userinput>@POFILEDIR@</userinput>/../<userinput>@COMMENTPATH@</userinput> +</para></listitem> +</itemizedlist> + +<note><para> +&kde; projects need typically the third pattern. +The last pattern is typical for &GNU; projects, where the source references are related to +the parent of the directory where the PO file is. +</para></note> + +</sect3> + +<sect3> +<title>Creating New Path Patterns</title> + +<para> +In most cases the default path patterns should be enough, whatever +the project is for KDE (assuming that you have set the correct base directory) +or if the project is a &GNU; one (or structured like a &GNU; project). +</para> + +<note><para> +For &kde;, some <acronym>PO</acronym> files do not contain enough information +(including the file path and name) for &kbabel; to find the right source file +that is supposed to be refered. To fix that you would need precise path patterns +for such files, which is nearly impossible to define by the numbers of such files +in &kde;. But if you work often with such a file, may be it is worth to set +a path pattern explicitely for supporting that <acronym>PO</acronym> file. +</para></note> + +<para> +For creating your own path patterns, you can use the variables defined above, +but apart <userinput>@COMMENTPATH@</userinput> not any variable is mandatory to use. +(To be exact, <userinput>@COMMENTPATH@</userinput> is not mandatory either, +but not using it will probably lead to no result.) +</para> + +<para> +An example of path pattern could be that you want to display the source reference +of &kde;'s file desktop_kdebase.po. In that case you will probably need a path pattern like: +<userinput>@CODEROOT@</userinput>/<userinput>@PACKAGEDIR@</userinput>/kdebase/<userinput>@COMMENTPATH@</userinput> +(compared to one of the default path patterns, the sequence <userinput>@PACKAGE@</userinput> has been +replaced by kdebase). +</para> + +<para> +In case of really complex problems you can, of course, define an absolute path +without any variables beside <userinput>@COMMENTPATH@</userinput>, like for example: +/home/usr/kde-source/kdebase/<userinput>@COMMENTPATH@</userinput> assuming that +/home/usr/kde-source/kdebase is the path where the kdebase source module is. +</para> + +</sect3> + +</sect2> + +<sect2 id="preferences-project-miscellaneous"> +<title>Miscellaneous</title> + +<para>These settings are for &kbabel;.</para> + +<para> +<guilabel>Miscellaneous</guilabel> section +holds &kbabel; settings that do not fit anywhere else. +</para> + +<variablelist> + <varlistentry> + <term><guilabel>Marker for keyboard accelerator</guilabel></term> + <listitem><para> + Here you can select your own character to serve + as the keyboard accelerator indicator in a &GUI;. + By default it is & (ampersand), but in some + programming toolkits it may vary. + For example, in Gnome/GTK translations the underscore + character <quote>_</quote> + is the marker for the keyboard accelerator. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guilabel>Regular expression for context information</guilabel></term> + <listitem><para> + For inexperienced users "regular expression" may sound strange. + So you are advised to change the default value + only if you know what you are doing. Some &GUI; programming + toolkits provide their own context information description + methods. Consult an experienced developer if you + translate <acronym>PO</acronym> files other than standard &kde; files. + For the sake of completeness I will "translate" for you what the + default regular expression means: + "the text matches if it starts with _: and is followed + by one or more characters and ends with a newline". + </para></listitem> + </varlistentry> +</variablelist> +</sect2> + +<!-- Catalog Manager project settings --> + +<sect2 id="preferences-project-folders"> +<title>Project folders</title> + +<para>These settings are for &catalogmanager;.</para> + +<para> +Here are two edit lines with folder buttons. +Type in or select the folders that contains all your <acronym>PO</acronym> and respectively +<acronym>POT</acronym> files. The files and the folders in these folders will then be +merged into one tree in Catalog Manager window. +</para> + +<para> +Below you can turn on and off if: +</para> + +<variablelist> + <varlistentry> + <term><guibutton>Open files in new window</guibutton></term> + <listitem><para> + If this is activated all files that are opened from the Catalog + Manager are opened in a new window. + </para></listitem> + </varlistentry> + <varlistentry> + <term><guibutton>Kill processes on exit</guibutton></term> + <listitem><para> + If you check this, &kbabel; tries to kill the processes that are not + exited already when the program closes by sending a kill signal to them. + <note><para> + It's not guaranteed that the processes are killed. + </para></note> + </para></listitem> + </varlistentry> +<varlistentry> + <term><guibutton>Create index for file contents</guibutton></term> + <listitem><para> + If you check this, &kbabel; will create an index of contents for every + file in the tree. This index is then used in find/replace operations. + <warning><para>There is a large speed trade-off. If you enable + <guibutton>Create index for file contents</guibutton>, the updating of + file information will be much slower. On the other hand, it speeds up + find/replace operations considerably.</para></warning> + </para></listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2 id="preferences-project-folder-commands"> +<title>Folder Commands</title> + +<para>These settings are for &catalogmanager;.</para> + +<screenshot> +<screeninfo>Project Settings,folder commands</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_proj_folder_commands.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Settings, folder commands</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +Here you can insert commands you want to execute in folders from the +Catalog Manager. The commands are then shown in the submenu +<menuchoice><guimenuitem>Commands</guimenuitem></menuchoice> +in the Catalog Manager's context menu. + +</para><para> +Insert in the <guilabel>Command Label</guilabel> field the +label of the command. The label can be chosen freely and is only used to be displayed +in the menu. In the <guilabel>Command</guilabel> field insert the command you want to +have executed when selecting the corresponding menu item. Then press the <guibutton>Add</guibutton> +button to add the command to your available commands. +To edit a command, select it, press the +<guibutton>Edit</guibutton> button and press <guibutton>Add</guibutton> after you have +finished. To remove a command, select it from the list and press the +<guibutton>Remove</guibutton> button. If you want a different order in the contextual +submenu, you can use the up and down buttons. + +</para><para> +The command is executed through your default shell, so you can execute +multiple commands at once by separating them with a semicolon, and you can set environment +variables if you need to. The commands are executed in the (<acronym>PO</acronym> file) folder you have +selected in the Catalog Manager. + +</para><para> +The following strings will be replaced in a command: +</para> + +<itemizedlist> + <listitem><para> + <userinput>@PACKAGE@</userinput>: The name of the folder without path + </para></listitem> + <listitem><para> + <userinput>@PODIR@</userinput>: The name of the <acronym>PO</acronym>-folder with path + </para></listitem> + <listitem><para> + <userinput>@POTDIR@</userinput>: The name of the template folder with path + </para></listitem> +</itemizedlist> + +<para> +E.g.: If you want to execute <command>make</command> and then <command>make +install</command> you could insert in <userinput>Make install</userinput> in the +<guilabel>Name</guilabel> field, and <userinput>make; make install</userinput> +in the <guilabel>Command</guilabel> field. If you then select +<menuchoice><guimenuitem>Commands</guimenuitem> +<guimenuitem>Make install</guimenuitem></menuchoice> +from the context menu of a folder, the commands listed above will be +executed in that folder. +</para> +</sect2> + +<sect2 id="preferences-project-file-commands"> +<title>File Commands</title> + +<para>These settings are for &catalogmanager;.</para> + +<screenshot> +<screeninfo>Project Settings, file commands</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_proj_file_commands.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Settings, file commands</phrase></textobject> +</mediaobject> +</screenshot> + +<para> +Here you can insert the commands you want to execute on files from the Catalog +Manager. The commands are then shown in the submenu +<menuchoice><guimenuitem>Commands</guimenuitem></menuchoice> in the Catalog +Manager's context menu. +</para> + +<para> +Insert in the <guilabel>Command Label</guilabel> field the label of the command. The label can be +chosen freely and is only used to be displayed in the menu. In the +<guilabel>Command</guilabel> field insert the command you want to have executed when +selecting the corresponding menu item. Then press the <guibutton>Add</guibutton> button +to add the command to your available commands. To edit a command, select it, press +the <guibutton>Edit</guibutton> button and press the <guibutton>Add</guibutton> button after you have +finished. To remove a command, select it from the list and press the +<guibutton>Remove</guibutton> button. If you want a different order in the contextual +submenu, you can use the up and down buttons. + +</para><para> +The command is executed through your default shell, so you can execute +multiple commands at once by separating them with a semicolon, and you can +set environment variables, if you need. The commands are executed in the +(<acronym>PO</acronym> file) folder, in which the file, you have selected in the Catalog +Manager, is. + +</para><para> +The following strings will be replaced in a command: +</para> + +<itemizedlist> + <listitem><para> + <userinput>@PACKAGE@</userinput>: The name of the file without path and extension + </para></listitem> + <listitem><para> + <userinput>@POFILE@</userinput>: The name of the <acronym>PO</acronym> file with path and extension + </para></listitem> + <listitem><para> + <userinput>@POTFILE@</userinput>: The name of the corresponding template file + with path and extension + </para></listitem> + <listitem><para> + <userinput>@PODIR@</userinput>: The name of the folder the <acronym>PO</acronym> file is in, with path + </para></listitem> + <listitem><para> + <userinput>@POTDIR@</userinput>: The name of the folder the template file is + in, with path + </para></listitem> +</itemizedlist> +<para> +For example, if you want to merge the template file into your <acronym>PO</acronym> file you could +insert <userinput>Merge</userinput> in the <guilabel>Name</guilabel> field and +<userinput>msgmerge @POFILE@ @POTFILE@ > @PACKAGE@.new && mv @PACKAGE@.new +"@PACKAGE@.po</userinput> in the <guilabel>Command</guilabel> field. +If you then select +<menuchoice><guimenuitem>Commands</guimenuitem><guimenuitem>Merge</guimenuitem></menuchoice> +from a file's context menu, the <acronym>PO</acronym> file will be merged with its template file. +</para> +</sect2> + +<sect2 id="preferences-project-catalog-manager"> +<title>Catalog Manager</title> + +<para>These settings are for &catalogmanager;.</para> + +<screenshot> +<screeninfo>Project Settings, &catalogmanager;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_proj_catman.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Settings, &catalogmanager;</phrase></textobject> +</mediaobject> +</screenshot> + +<para>The checkboxes switches on or off the corresponding column of the &catalogmanager;'s view.</para> + +</sect2> + +<sect2 id="preferences-project-diff"> +<title>Diff</title> + +<para>These settings are for &catalogmanager;.</para> + +<screenshot> +<screeninfo>Project Settings, diff</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_proj_diff.png" format="PNG"/> +</imageobject> +<textobject><phrase>Project Settings, diff</phrase></textobject> +</mediaobject> +</screenshot> + +<para><remark>TODO</remark></para> + +</sect2> + +</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 +--> diff --git a/doc/kbabel/preverror.png b/doc/kbabel/preverror.png Binary files differnew file mode 100644 index 00000000..d589b53b --- /dev/null +++ b/doc/kbabel/preverror.png diff --git a/doc/kbabel/prevfuzzy.png b/doc/kbabel/prevfuzzy.png Binary files differnew file mode 100644 index 00000000..2e4cedfa --- /dev/null +++ b/doc/kbabel/prevfuzzy.png diff --git a/doc/kbabel/prevfuzzyuntrans.png b/doc/kbabel/prevfuzzyuntrans.png Binary files differnew file mode 100644 index 00000000..cf6f43d4 --- /dev/null +++ b/doc/kbabel/prevfuzzyuntrans.png diff --git a/doc/kbabel/previous.png b/doc/kbabel/previous.png Binary files differnew file mode 100644 index 00000000..167e39e7 --- /dev/null +++ b/doc/kbabel/previous.png diff --git a/doc/kbabel/prevuntranslated.png b/doc/kbabel/prevuntranslated.png Binary files differnew file mode 100644 index 00000000..796a4e3d --- /dev/null +++ b/doc/kbabel/prevuntranslated.png diff --git a/doc/kbabel/redo.png b/doc/kbabel/redo.png Binary files differnew file mode 100644 index 00000000..d6b3e8f1 --- /dev/null +++ b/doc/kbabel/redo.png diff --git a/doc/kbabel/roughtranslation.png b/doc/kbabel/roughtranslation.png Binary files differnew file mode 100644 index 00000000..cd96526c --- /dev/null +++ b/doc/kbabel/roughtranslation.png diff --git a/doc/kbabel/snap1.png b/doc/kbabel/snap1.png Binary files differnew file mode 100644 index 00000000..55e3c9cd --- /dev/null +++ b/doc/kbabel/snap1.png diff --git a/doc/kbabel/snap_catalogmanager.png b/doc/kbabel/snap_catalogmanager.png Binary files differnew file mode 100644 index 00000000..20aff2ec --- /dev/null +++ b/doc/kbabel/snap_catalogmanager.png diff --git a/doc/kbabel/snap_kbabeldict.png b/doc/kbabel/snap_kbabeldict.png Binary files differnew file mode 100644 index 00000000..58d9db14 --- /dev/null +++ b/doc/kbabel/snap_kbabeldict.png diff --git a/doc/kbabel/snap_kbabeldict2.png b/doc/kbabel/snap_kbabeldict2.png Binary files differnew file mode 100644 index 00000000..562862e7 --- /dev/null +++ b/doc/kbabel/snap_kbabeldict2.png diff --git a/doc/kbabel/stop.png b/doc/kbabel/stop.png Binary files differnew file mode 100644 index 00000000..1cabc6e9 --- /dev/null +++ b/doc/kbabel/stop.png diff --git a/doc/kbabel/top.png b/doc/kbabel/top.png Binary files differnew file mode 100644 index 00000000..b626bf42 --- /dev/null +++ b/doc/kbabel/top.png diff --git a/doc/kbabel/transsearch.png b/doc/kbabel/transsearch.png Binary files differnew file mode 100644 index 00000000..06d5852c --- /dev/null +++ b/doc/kbabel/transsearch.png diff --git a/doc/kbabel/undo.png b/doc/kbabel/undo.png Binary files differnew file mode 100644 index 00000000..f5ad210d --- /dev/null +++ b/doc/kbabel/undo.png 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 +--> |
