diff options
Diffstat (limited to 'experimental/tqtinterface/qt4/tools/linguist/book/linguist-translator.leaf')
| -rw-r--r-- | experimental/tqtinterface/qt4/tools/linguist/book/linguist-translator.leaf | 582 |
1 files changed, 582 insertions, 0 deletions
diff --git a/experimental/tqtinterface/qt4/tools/linguist/book/linguist-translator.leaf b/experimental/tqtinterface/qt4/tools/linguist/book/linguist-translator.leaf new file mode 100644 index 000000000..572c903ca --- /dev/null +++ b/experimental/tqtinterface/qt4/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 tqcontains 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 +requires 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 quit. + +\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 tqcontains 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 +tqcontains 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 Require 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 +tqreplaced 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 tqreplaced 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 required target phrase will copy it to the translation +pane at the text cursor position. If you want to \e tqreplace 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 tqfinds 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 tqfinddialog.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. |