1 files changed, 582 insertions, 0 deletions
diff --git a/tools/linguist/book/linguist-translator.leaf b/tools/linguist/book/linguist-translator.leaf
new file mode 100644
index 000000000..e20d7921a
--- /dev/null
+++ b/tools/linguist/book/linguist-translator.leaf
@@ -0,0 +1,582 @@
+\chapter Translators
+
+\img linguist.png
+\caption Linguist Main Window
+
+\section1 The One Minute Guide to Using Qt Linguist
+
+\index Linguist
+\index Qt Linguist
+\index Contexts!for Translation
+
+\e {Qt Linguist} is a tool for adding translations to Qt
+applications. It introduces the concept of a translation "context"
+which means a group of phrases that appear together on the screen
+e.g. in the same menu or dialog.
+
+To start, run \e {Qt Linguist}, either from the taskbar menu, or by
+double clicking the desktop icon, or type \c {linguist} (followed by
+\Key Enter) at the command line. Once \e {Qt Linguist} has started
+choose \Menu File|Open from the menu bar and select a \c .ts
+translation source file to work on.
+
+\e {Qt Linguist}'s main window is divided into four main areas. The
+left hand side contains the Context list, the top right is the Source
+text area, the middle right is the translation area and the bottom
+right is the phrases and guesses area. We'll describe them in detail
+later.
+
+Click on one of the contexts in the context list (left hand side) and
+then click on one of the phrases that appears in the Source text area
+(top right). The phrase will be copied into the translation area
+(middle right). Click under the word 'Translation' and type in the
+translation. Click \Key Ctrl+Enter (Done \& Next) to confirm that you
+have completed the translation and to move on to the next phrase that
+retquires translation.
+
+The cycle of entering a translation then pressing \Key Ctrl+Enter can
+be repeated until all the translations are done or until you finish
+the session. Linguist will attempt to fill the "phrases and guesses"
+area with possible translations from any open phrase books and any
+previous translations. Each has a keyboard shortcut, e.g.
+\Key Ctrl+1, \Key Ctrl+2, etc., which you can use to copy the
+guess into the Translation area. (Mouse users can double click a
+phrase or guess to move it into the Translation area.) At the end of
+the session choose \Menu File|Save from the menu bar and then
+\Menu File|Exit to tquit.
+
+\section1 Qt Linguist's Main Window
+
+\section2 Context List
+
+\index Contexts!for Translation
+
+This appears at the left hand side of the main window by default. The
+first column, 'Done', identifies whether or not the translations for the
+context have been done. A tick indicates that all the translations have
+been done and are valid. A question mark indicates that one or more
+translations have not been done or have failed validation. The second
+column, 'Context' is the name of the context in which the translation
+phrases appear. The third column, 'Items' shows two numbers, the first
+is the number of translations that have been done, and the second is the
+number of phrases that are in the context; if the numbers are equal then
+all the translations have been done. Note that a greyed out tick
+indicates an obsolete translation, i.e. a phrase that was translated in
+a previous version of the application but which does not occur in the
+new version.
+
+The contexts are ordered alphabetically. The phrases within each context
+are in the order in which they appear in the source program and this may
+not be the order in which they are shown on screen.
+
+The Context List is a dockable window so it can be dragged to another
+position in the main window, or dragged out of the main window to be a
+window in its own right. If you move the Context List, \e {Qt
+Linguist} will remember its position and restore it whenever you
+start the program.
+
+\section2 Source Text Area
+
+This appears at the top right of the main window by default. The first
+column, 'Done', signifies the status of the translation. A tick
+indicates that the phrase has been translated and passed validation. A
+question mark indicates that the translation has not been done. An
+exclamation mark indicates that the translation has failed validation.
+The second column 'Source text' shows the text that must be translated.
+The third column shows the translation.
+
+\e{Qt Linguist} provides three kinds of validation: accelerator,
+punctuation and phrase. If the source text contains an accelerator
+i.e. an ampersand, '\&' and the translated text does not contain an
+ampersand the translation will fail the accelerator validation.
+Similarly, if the source text ends with a particular punctuation
+mark, e.g. '?', '!' or '.' and the translation ends with a different
+punctuation mark the translation will fail the punctuation
+validation. If the source text has a translation in one of the open
+phrase books that differs from the translation used the translation
+will fail phrase validation. (See \l Validation.)
+
+The Source Text Area is a dockable window.
+
+\section2 Translation Area
+
+This area appears at the middle right of the main window by default. It
+is comprised of three vertical sections. The first section is labelled
+'Source text' below which the source text appears. The second section
+contains contextual information on a light blue background that the
+programmer has added to assist the translator. If no contextual
+information has been given this section does not appear. The third
+section is labelled 'Translation' and this is where you enter the
+translation of the source text.
+
+\section2 Phrases and Guesses Area
+
+\index Phrases!in Qt Linguist
+\index Guesses!in Qt Linguist
+
+This area appears at the bottom right of the main window by default.
+When you move to a new phrase if the phrase is in one of the phrase
+books that has been loaded the phrase will appear in this area with its
+translation. If the phrase is the same or similar to another phrase that
+has already been translated the phrase and translation will be shown in
+this area. To copy a translation from the phrases and guesses area press
+\Key F6 to move to the phrases and guesses area, use the up and down arrow
+keys to move to the phrase you want to use and press Enter to copy it.
+If you decide that you don't want to copy a phrase after all, press Esc.
+In both cases the focus will return to the Translation area.
+Alternatively, double click the translation you want to use and it will
+be copied into the translation area.
+
+The Phrases and Guesses Area is a dockable window.
+
+\section1 Common Tasks
+
+\section2 Leaving a Translation for Later
+
+If you wish to leave a translation press \Key Ctrl+L (Next Unfinished) to
+move to the next unfinished translation. An unfinished translation is
+one that either has not been translated at all or one which fails
+validation. To move to the next phrase press \Key Shift+Ctrl+L. You can also
+navigate using the Translation menu. If you want to go to a different
+context entirely, click the context you want to work on in the Context
+list, then click the source text in the Source Text area.
+
+\section2 Phrases That Retquire Multiple Translations Depending on Context
+
+\index Contexts!for Translation
+\index Comments!for Translators
+
+The same phrase may occur in two or more contexts without conflict. Once
+a phrase has been translated in one context, \e {Qt Linguist} notes
+that the translation has been made and when the translator reaches a
+later occurrence of the same phrase \e {Qt Linguist} will provide
+the previous translation as a possible translation candidate in the
+phrases and guesses area. If the
+previous translation is acceptable just click the \e {Done \& Next}
+button (press \Key Ctrl+Enter) to move on to the next unfinished phrase.
+
+If a phrase occurs more than once in a particular context it will only
+be shown once in \e {Qt Linguist}'s context list and
+the translation will be applied to every occurrence within the context.
+If the same phrase needs to be translated differently within the same
+context the programmer must provide a distinguishing comment for each of
+the phrases concerned. If such comments are used the duplicate phrases
+will appear in the context list. The programmers comments will appear in
+the translation area on a light blue background.
+
+\section2 Changing Keyboard Accelerators
+
+\index Accelerators
+\index Keyboard Accelerators
+
+A keyboard accelerator is a key combination that when pressed will
+cause an application to perform an action. Keyboard accelerators
+normally come in two forms: Alt key and Ctrl key accelerators.
+
+\index Alt Key
+
+Alt key accelerators are used for menus and buttons.  The underlining
+signifies that pressing the Alt key with the underlined letter is the
+same as clicking the menu item with the mouse.  For example, most
+applications have a \e File menu with the "F" in the word "file"
+underlined. In these applications the file menu can be invoked either by
+clicking the word "File" on the menu bar or by pressing Alt+F. The
+accelerator key which is underlined is signified by preceeding it with
+an ampersand, e.g. \e \&File. If a source phrase appears with an
+ampersand in it then the translation should also contain an ampersand,
+preferably in front of the same letter. The meaning of Alt key
+accelerators can be determined from the phrase in which the ampersand is
+embedded. The translator may need to change the letter used with the Alt
+key, e.g. if the translated phrase does not contain the original
+accelerator letter. Conflicts with other keys, i.e. having two Alt key
+accelerators using the same letter in the same context, must be avoided.
+Note that some Alt key accelerators, usually those on the menu bar, may
+apply in other contexts.
+
+\index Ctrl Key
+
+Ctrl key accelerators can exist independently of any visual control.
+They are often used to invoke actions in menus that would otherwise
+take several keystrokes or mouse clicks. They may also be used to
+perform actions that do not appear in any menu or on any button. For
+example, most applications that have a \e File menu have a submenu
+item called \e New. In many applications this will appear as "\NEW
+Ctrl+N". This menu option could be invoked by clicking \e File then
+clicking \e New with the mouse. Or you could press Alt+F then press N
+since these letters are underlined. But the same thing can be achieved
+simply by pressing \Key Ctrl+N. Accelerators that use the Ctrl key are
+shown literally in the source text, e.g. \Key Ctrl+Enter. Ctrl key
+accelerators have no phrase so the translator \index Comments!for
+Translators must rely on the programmer to add a "comment" which
+appears in the top right hand pane. This comment should explain what
+action the Ctrl key accelerator performs. Ideally Ctrl key
+accelerators are translated simply by copying them by chossing the \e
+{Begin from Source} entry in the \Menu Translations menu. However in
+some cases the letter will not make sense in the target language and
+must be changed. Whatever letter (or digit) is chosen, the translation
+should always be in the form "Ctrl+" followed by the letter or digit
+in upper case. As with Alt key accelerators, if the translator changes
+the key it must not conflict with any other Ctrl key accelerator.
+
+Later versions of \e {Qt Linguist} are expected to help the
+translator avoid accelerator conflicts.
+
+\section2 Dealing with Phrases that Contain Variables
+
+Some phrases contain variables. Variables are placeholders for items of
+text that are filled in at runtime. They are signified in the source
+text with a percent sign followed by a digit, e.g. \e {After processing
+file %1, file %2 is next in line}. In this example, \c %1 will be
+replaced at runtime with the name of the first file to be processed and
+\c %2 with the name of the next file to be processed. In the translated
+version the variables must still appear. For example a German
+translation might reverse the phrases, e.g. \e {Datei %2 wird
+bearbeitet, wenn. Datei %1 fertig ist}. Note that both variables
+are still used but their order has changed. The order in which variables
+appear does not matter; \c %1 will always be replaced by the same text
+at runtime no matter where it appears in the source text or translation
+and similarly \c %2, etc.
+
+\section2 Reusing Translations
+
+If the translated text is similar to the source text, choose the \e
+{Begin from Source} entry in the \Menu Translations menu (press \Key
+Ctrl+B) which will copy the source text into the translation area.
+
+\e {Qt Linguist} automatically lists phrases from the open phrase
+books and similar or identical phrases that have already been translated
+in the Phrases and guesses area.
+
+\section1 Creating and Using Phrase Books
+
+\index Phrases!in Qt Linguist
+\index Phrase Books
+
+\img phrasebookdialog.png
+\caption Phrase Book Dialog
+
+A \e {Qt Linguist} phrase book is a set of source phrases, target
+(translated) phrases, and optional definitions. Phrase Books are created
+independently of any application, although typically one phrase book
+will be created per application or family of applications.
+
+If the translator reaches an untranslated phrase that is the same as a
+source phrase in the phrase book, \e {Qt Linguist} will show the
+phrase book entry in the \e {Relevant phrases} panel at the bottom
+right of the main window. Phrases which have translations that conflict
+with those given in the phrase book are marked with a question mark in
+the source text pane. Phrase Books are used to provide a common set of
+translations to help ensure consistency. They can also be used to avoid
+duplication of effort since the translations for a family of
+applications can be produced once in the phrase book and the phrase book
+used for the majority of translations in each application.
+
+Before a phrase book can be edited it must be created or if it already
+exists, opened. Create a new phrase book by selecting
+\Menu {Phrase|New Phrase Book} from the menu bar. You must enter a
+filename and may change the location of the file if you wish. A newly
+created phrase book is automatically opened. Open an existing phrase
+book by choosing \Menu {Phrase|Open Phrase Book} from the menu bar.
+
+To add a new phrase click the \Button {New Phrase} button (or press
+Alt+N) and type in a new source phrase. Press Tab and type in the
+translation. Optionally press Tab and enter a definition -- this is
+useful to distinguish different translations of the same source phrase.
+This process may be repeated as often as necessary.
+
+You can delete a phrase by selecting it in the phrases list and clicking
+Remove Phrase.
+
+Click the \e Save button (press Alt+S) and then click the \e Close
+button (press Esc) once you've finished adding (and removing) phrases.
+
+When a phrase or set of phrases appears in the phrase book double
+clicking the retquired target phrase will copy it to the translation
+pane at the text cursor position. If you want to \e replace the text
+in the translation pane with the target phrase, click the translation
+pane, choose \Menu {Edit|Select All} (press \Key Alt+A) and then
+double click the target phrase.
+
+\section1 Validation
+
+\index Validation of Translations
+\index Accelerators!Validation
+\index Punctuation!Validation
+\index Phrases!Validation
+
+\e {Qt Linguist} provides three kinds of validation on translated
+phrases.
+
+\list 1
+\i \e {Accelerator validation} detects translated phrases
+that do not have an ampersand when the source phrase does and vice
+versa.
+\i \e {Punctuation validation} detects differences in the
+terminating punctuation between source and translated phrases when this
+may be significant, e.g. warns if the source phrase ends with an
+ellipsis, exclamation mark or question mark, and the translated phrase
+doesn't and vice versa.
+\i \e {Phrases validation} detects source phrases that are
+also in the phrase book but whose translation differs from that given in
+the phrase book.
+\endlist
+
+Validation may be switched on or off from the menu bar's Validation item
+or using the toolbar buttons. Phrases that fail validation are marked
+with a question mark in the source text pane. If you switch validation
+off and then switch it on later, \e{Qt Linguist} will recheck all
+phrases and mark any that fail validation.
+
+If any phrase in a context is invalid then the context itself will be
+marked with a question mark; if all the phrases in a context are done
+and are valid the context will be marked with a tick.
+
+Note that only phrases which are marked as done (with a tick) will
+appear in the application. Invalid phrases and phrases which are
+translated but not marked as done are kept in the translation source
+file but are not used by the application.
+
+\section1 Qt Linguist Reference
+
+\section2 File Types
+
+\e {Qt Linguist} makes use of three kinds of file:
+
+\index .ts Files
+\index Translation Source Files
+\index .qm Files
+\index Qt Message Files
+\index .qph Files
+\index Qt Phrase Book Files
+
+\list
+\i \c .ts \e {translation source files} \BR are human-readable XML
+files containing source phrases and their translations. These files are
+usually created and updated by \l lupdate and are specific to an
+application.
+\i \c .qm \e {Qt message files} \BR are binary files that contain
+translations used by an application at runtime. These files are
+generated by \l lrelease, but can also be generated by \e {Qt
+Linguist}.
+\i \c .qph \e {Qt phrase book files} \BR are human-readable XML
+files containing standard phrases and their translations. These files
+are created and updated by \e {Qt Linguist} and may be used by any
+number of projects and applications.
+\endlist
+
+\section2 The Menu Bar
+
+\img menubar.png
+\caption Menu Bar
+
+\list
+\i \e {File}
+    \list
+    \i \e {Open... Ctrl+O} \BR pops up an open file dialog from which a
+    translation source \c .ts file can be chosen.
+    \i \e {Save Ctrl+S} \BR saves the current translation source \c .ts file.
+    \i \e {Save As...} \BR pops up a save as file dialog so that the
+    current translation source \c .ts file may be saved with a different
+    name and/or put in a different location.
+    \i \e {Release...} \BR pops up a save as file dialog. The
+    filename entered will be a Qt message \c .qm file of the translation
+    based on the current translation source file. The release manager's
+    command line tool \l lrelease performs the same function on
+    \e all of an application's translation source files.
+    \i \e {Print... Ctrl+P} \BR pops up a print dialog. If you click
+    OK the translation source and the translations will be printed.
+    \i \e {Recently opened files} \BR shows the \c .ts files that
+    have been opened recently, click one to open it.
+    \i \e {Exit Ctrl+Q} \BR closes \e {Qt Linguist}.
+    \endlist
+
+\i \e {Edit}
+    \list
+    \i \e {Undo Ctrl+Z} \BR undoes the last editing action in the
+    translation pane.
+    \i \e {Redo Ctrl+Y} \BR redoes the last editing action in the
+    translation pane.
+    \i \e {Cut Ctrl+X} \BR deletes any highlighted text in the
+    translation pane and saves a copy to the clipboard.
+    \i \e {Copy Ctrl+C} \BR copies the highlighted text in the
+    translation pane to the clipboard.
+    \i \e {Paste Ctrl+V} \BR pastes the clipboard text into the
+    translation pane.
+\omit
+    \i \e {Delete} \BR deletes the highlighted text in the
+    translation pane.
+\endomit
+    \i \e {Select All Ctrl+A} \BR selects all the text in the
+    translation pane ready for copying or deleting.
+    \i \e {Find... Ctrl+F} \BR pops up the
+    \link {The Find Dialog} Find dialog \endlink. When the dialog pops up
+    enter the text to be found and click the \e {Find Next} button.
+    Source phrases, translations and comments may be searched.
+    \i \e {Find Next F3} \BR finds the next occurrence of the text that
+    was last entered in the Find dialog.
+    \endlist
+
+\i \e {Translation}
+    \list
+    \i \e {Prev Unfinished Ctrl+K} \BR moves to the nearest previous
+    unfinished source phrase (unfinished means untranslated or
+    translated but failed validation).
+    \i \e {Next Unfinished Ctrl+L} \BR moves to the next unfinished source
+    phrase.
+    \i \e {Prev Shift+Ctrl+K} \BR moves to the previous source phrase.
+    \i \e {Next Shift+Ctrl+L} \BR moves to the next source phrase.
+    \i \e {Done \& NextCtrl+Enter} \BR mark this phrase as 'done'
+    (translated) and move to the next unfinished source phrase.
+    \i \e {Begin from Source Ctrl+B} \BR copies the source text into
+    the translation.
+    \endlist
+
+\i \e {Validation} (See the \l Validation section)
+    \list
+    \i \e {Accelerators} \BR toggles validation on or off for Alt
+    accelerators.
+    \i \e {Ending Punctuation} \BR switches validation on or off
+    for phrase ending punctuation, e.g. ellipsis, exclamation mark,
+    question mark, etc.
+    \i \e {Phrase Matches} \BR sets validation on or off for
+    matching against translations that are in the current phrase book.
+    \endlist
+
+\i \e {Phrase} (See the section \l {Creating ... Phrase
+Books} for details.)
+    \list
+    \i \e {New Phrase Book... Ctrl+N} \BR pops up a save as file dialog.
+    You must enter a filename to be used for the phrase book and save
+    the file. Once saved you should open the phrase book to begin using
+    it.
+    \i \e {Open Phrase Book... Ctrl+H} \BR pops up an open file dialog.
+    Find and choose a phrase book to open.
+    \i \e {Close Phrase Book} \BR closes the current phrase book.
+    This will stop any further phrase validation taking place.
+    The same effect can be achieved by switching off phrase validation
+    using the Validation menu or the phrase toolbar button.
+    \i \e {Edit Phrase Book...} \BR pops up the
+    \link {The Phrase Dialog} phrase book dialog \endlink where you can
+    add, edit or delete phrases.
+    \i \e {Print Phrase Book...} \BR pops up a print dialog. If
+    you click OK the phrase book will be printed.
+    \endlist
+
+\i \e {View}
+    \list
+    \i \e {Revert Sorting} \BR puts the phrases in the source text
+    pane into their original order.
+    \i \e {Display Guesses} \BR turns the display of phrases and
+    guesses on or off.
+    \i \e {Statistics} \BR toggles the visibility of the Statistics dialog.
+    \i \e {Views} \BR toggles the visibility of the Context, Source text and
+     Phrase views.
+    \i \e {Toolbars} \BR toggles the visibility of the different toolbars.
+\omit
+    \i \e {Large Icons} \BR switches between large or standard
+    size icons on the toolbar.
+    \i \e {Text Labels} \BR toggles the use of text labels on the
+    toolbar icons.
+\endomit
+    \endlist
+
+\endlist
+
+\section2 The Toolbar
+
+\img toolbar.png
+\caption Toolbar
+
+\list
+\i \img fileopen.png
+\BR
+Pops up the open file dialog to open a new translation source \c .ts
+file.
+
+\i \img filesave.png
+\BR
+Saves the current translation source \c .ts file.
+
+\i \img fileprint.png
+\BR
+Prints the current translation source \c .ts file.
+
+\i \img phrasebookopen.png
+\BR
+Pops up the file open dialog to open a new phrase book \c .qph file.
+
+\i \img editundo.png
+\BR
+Undoes the last editing action in the translation pane.
+
+\i \img editredo.png
+\BR
+Redoes the last editing action in the translation pane.
+
+\i \img editcut.png
+\BR
+Deletes any highlighted text in the translation pane and save a copy to
+the clipboard.
+
+\i \img editcopy.png
+\BR
+Copies the highlighted text in the translation pane to the clipboard.
+
+\i \img editpaste.png
+\BR
+Pastes the clipboard text into the translation pane.
+
+\i \img editfind.png
+\BR
+Pops up the \link {The Find Dialog} Find dialog \endlink.
+
+\i \img prev.png
+\BR
+Moves to the previous source phrase.
+
+\i \img next.png
+\BR
+Moves to the next source phrase.
+
+\i \img prevunfinished.png
+\BR
+Moves to the previous unfinished source phrase.
+
+\i \img nextunfinished.png
+\BR
+Moves to the next unfinished source phrase.
+
+\i \img doneandnext.png
+\BR
+Marks the phrase as 'done' (translated) and move to the next
+unfinished source phrase.
+
+\i \img validateaccelerators.png
+\BR
+Toggles accelerator validation on and off.
+
+\i \img validatepunctuation.png
+\BR
+Toggles phrase ending punctuation validation on and off.
+
+\i \img validatephrases.png
+\BR
+Toggles phrase book validation on or off.
+\endlist
+
+\section2 The Find Dialog
+
+\img finddialog.png
+\caption The Find Dialog
+
+Choose \Menu Edit|Find from the menu bar or press \Key Ctrl+F to pop
+up the Find dialog. Press \Key F3 to repeat the last search. By
+default the source phrases, translations and comments will all be
+searched and the search will be case-insensitive. These settings can
+be changed by checking or unchecking the checkboxes to reflect your
+preferences.
+
+\section2 The Phrase Dialog
+
+This dialog is explained in the \l {Creating and Using Phrase Books}
+section.