***KEYBINDINGS FOR PO_MODE*** NAVIGATION: MODIFICATION: b - scroll up one page _ - undo f - next fuzzy TAB or ENTER - edit entry F - previous fuzzy @ - show current entry no. w - copy msgstr g - go to entry number y - insert msgstr l - toggle limited view Backspace - flag entry fuzzy n - next entry ESC-Backspace - remove fuzzy flag o - next obsolete ctrl-? z - flag all entries fuzzy O - previous obsolete ESC-Enter - copy msgid to msgstr p - previous entry DEL - delete obsolete entry t - next translated E - edit entire file T - previous translated H - replace headers u - next untranslated ctrl-? k - cut msgstr U - previous untranslated ctrl-? l - replace from listfile ESC-# - next translator comment R - replace in msgstrs . - top justify entry # - edit translator comment space - next unfinished entry ctrl-? # - remove translator comment A - Translate w/Apertium ctrl-? A - Update Untranslated w/Apertium ctrl-? F - Update Untranslated/Use Fuzzy w/Apertium ctrl-? . - detect some ortograhpic errors COMPENDIUMS: MISC: ctrl-? a - add buffer to comp. c - compile *.po -> *.mo ctrl-? c - init. w/compendium(s) C - decompile *.mo -> *.po ctrl-? d - add dir to compendium G - grep in source dir ctrl-? p - set compendium ctrl-? s - interactive spell check + - make current translation L - list and correct misspelled words preferred in compendium M - mail team or robot / - translate single entry s - view source reference from compendium S - set source path V - validate file D - create and write diff between two po-files d - look up word in wordlist(s) I - count words and characters ctrl-? E - change encoding ctrl-? u - update po-file w/newer ctrl-? i - check in file w/RCS ctrl-? o - check out file w/RCS ctrl-? t - count number of word occurences in msgstrs \ - toggle wrapping = - po statistics ? - show this help file ***KEYBINDINGS FOR PO_EDIT_MODE*** TAB - finish editing entry ctrl-c ctrl-c - finish editing entry ctrl-c ctrl-k - discard changes ***MOUSE ACTIONS IN PO_MODE*** - left button double click: look up translation for word at mouse point in wordlist. May only work in xjed. NOTE: The question mark in the "ctrl-?" sequence refers to the binding for the letter in the "reserved key prefix" which varies with editor emulations. For Emacs and Jed emulations it is 'c' so you can exchange ctrl-? with ctrl-c in the key bindings above. In the references to keybindings that follows herein, "ctrl-c" is used. You must type ctrl-c, release both keys and then type the letter. The "esc" key can generally be substituted with the "alt" key so "esc-enter" is the same as "alt-enter" ***Important*** See section 11. Suggested Editing Work Flow 1. Installation and Customization 1.1. Installation First, of course, you need to install the Jed editor. It is packaged for every Linux-distribution, I believe, so you can just use your package manager to install it. On Debian based systems, which include Ubuntu, you would do: sudo apt-get install jed xjed which will install both the terminal and X Window versions of the editor. Copy the files po_mode.sl and po_mode.hlp to a directory in your jed library path, e.g. /usr/share/jed/lib. First make sure the permissions on the files are sufficient: chmod 0644 po_mode.sl po_mode.hlp sudo cp po_mode.sl po_mode.hlp /usr/share/jed/lib If you don't have write access to any other directories than your own home directory, then do the following: cd mkdir -p .jed cp po_mode.sl po_mode.hlp ~/.jed In your ~/.jedrc add the following lines: private variable user_libdir = dircat (getenv ("HOME"), ".jed"); set_jed_library_path (strcat (user_libdir, ",", get_jed_library_path ())); Finally, in the file ~/.jedrc or /etc/jed.conf, insert the following lines: autoload ("po_mode", "po_mode"); add_mode_for_extension ("po", "po"); add_mode_for_extension ("po", "pot"); Then upon loading a po-file into the editor, the mode will be activated automatically. 1.1.1. Optional Helper Programs: Install the following programs. You can do without them, but much functionality will be lost then: - the gettext package (msgfmt, msgcat, msgmerge, msgconv, etc.) - aspell or hunspell - the file(1) utility - rcs, the Revision Control System - wdiff, the word difference utility - grep.sl from http://jedmodes.sourceforge.net/mode/grep/ - apertium, the machine translation system plus relevant dictionaries. 1.2. Customization: You should copy/paste the following block of variables into your ~/.jedrc or /etc/jed.conf and edit their values to match your own settings. Below, the settings are exemplified with mine: %% --- User variables specific for po_mode - copy/paste begin --- variable Translator = "Morten Bo Johansen ", Team_Email = "", Language = "Danish", LangCode = "da", CountryCode = "dk", Encoding = "utf-8", SrcBaseDir = "/home/mojo/src", Apertium_Langs = "nob-dan", Spell_Prg = "aspell, Compare_With_Languages = "sv,nb,de,fr,nl", Compendium = "/home/mojo/.compendium_pomode"; %% --- User variables specific for po_mode - copy/paste end --- %% Other useful variables, paste into ~/.jedrc variable Grep_Cmd = "grep -H -n -r -i", Dabbrev_Default_Buflist = 1, Dabbrev_Look_in_Folds = 1; Explanation of the user variables: - Translator: full name and email address of you, the translator. - Language: your language - use English adjective, e.g. "German". - LangCode: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes - CountryCode: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 - Team_Email: email address of your language team. - Encoding: The default character set encoding in the header of the po-file also used as encoding in the gettext compendium. - Compendium: Path to gettext compendium file. - SrcBaseDir: The path to the directory where you usually keep the sources for the programs you translate. - Compare_With_Languages: po-files in languages that you want to compare your translations with. Comma separated list of iso country codes as listed in http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes Change the codes below to your liking. NB! This requires that the msgid numbers are in sync between all the po files. If this is not the case it can usually be accomplished by running "make update-po" in the ../po subdirectory of the sources directory This example will compare with Swedish, Norwegian Bokmål, German, French and Dutch. - Apertium_Langs: Language pair for machine translation system, Apertium E.g. "en-es" will use the English-to-Spanish pair. 1.2.1. Mode Hooks: There are two mode_hooks that may be used to control some settings relating to the po_mode and po_edit_mode buffers respectively. Thus in the file ~/.jedrc or /etc/jed.conf you might insert e.g.: define po_mode_hook () { use_dfa_syntax (1); } define po_edit_mode_hook () { ispell_change_dictionary ("deutsch"); flyspell_mode; set_abbrev_mode (1); local_setkey ("dabbrev", "\ea"); % only if you haven't set it globally } The former enables DFA syntax highlighting that conveniently draws attention to important things like blank space at beginning/end of lines and newline escape sequences. The variables in the "po_edit_mode_hook" enable spell checking "on the fly" by highlighting misspelled words in the edit buffer, if you installed flyspell.sl from http://jedmodes.sourceforge.net/mode/ispell/ "set_abbrev_mode" enables "dynamic abbreviations in the editing buffer which means that you can use a keyboard shortcut such as e.g. "alt-a" to complete a word 2. Notes On Editing (po_edit mode): Hit or on an entry to open the window with the editing buffer. When you have finished the translation, then hit again to close the editing window. You can also hit ctrl-c ctrl-c, i.e. press the control key while hitting 'c' twice. To a large extent this mode is emulating the Emacs po-mode, and as you may see from the key bindings above, the library actually contains two modes: when you read the po-file into the editor, you are in "po_mode" and the file is read-only. When you edit an entry, a new buffer is opened and you enter "po_edit_mode" where you are actually filling in the translation or editing an existing translation. The entries are either single-line or multi-line strings. Multi-line strings are always terminated at the point at which they are to be wrapped by the C-like newline escape character "\n". If there is one or more of these escape sequences in the msgid, it is a multi-line string. Thus the two types of strings may look like this: Example single-line string: msgid "" "You may also specify modifiction to the actions which will be taken. To do " "so, type an action character followed by one or more package names (or " "patterns). The action will be applied to all the packages that you list. " "The following actions are available:" Example multi-line string: msgid "" "Usage: %s [OPTION]... [FILE]...\n" "\n" "Convert FILE(s) or standard input to PostScript.\n" "\n" "Mandatory arguments to long options are mandatory for short options too.\n" "Long options marked with * require a yes/no argument, corresponding\n" "short options stand for `yes'.\n" For single-line strings, just type along with the line being wrapped at your chosen wrap point and with a single space being inserted automatically at the end of the line, so you can follow what you're typing in. For multi-line strings always use the enter-key to break the line at the point where you want the newline escape sequence "\n" to be inserted. Do not insert trailing newline escape sequences or spaces and do not escape double quotes or envelop the translation in double quotes. It is all taken care of automatically when you leave the po_edit buffer. To repeat: In general you do not need to worry about anything relating to the formatting of the message string, it is all taken care of automatically. 3. Spell Checking: Aspell and hunspell are supported. You must of course install the spell dictionaries for your language. In addition you should also install an English spell dictionary, since there are often English words in the msgstrs that should not be translated. The spell checking in this mode tries with both your own language and English, if an English dictionary is found, thus weeding out all the false English positives that would occur if spell checking was only done in your own language. Keeping your work free from misspellings is an important part of the work of a translator. You can spell check the entire po-file interactively, isolating the msgstrs from within po_mode (typing ctrl-c s). Better still, probably is to type 'L' which will pop up a list of misspelled words. You can then hit enter on one such word and correct its spelling from the resulting prompt. The word will then be corrected throughout the msgstrs of the po-file and then removed from the list. Typing '-' on a word in the list will remove the word from the list. Typing '+' on a word in the list will add the word to the spell program's personal wordlist, so it will not be seen as a misspelling in the future. 'q' closes the list window. Alternatively there is a cool mode called flyspell that will highlight misspelled words as you go ("on the fly"). See above under 1.2.1. Mode Hooks. 3.1 Check for minor ortographical or consistency errors ctrl-c . (period) will parse the file for such minor errors. Affected entries will be marked fuzzy and tagged with a translator's comment that has the "[po-lint]" label prepended to it. The comment will be removed upon unfuzzying the entry (alt-backspace). The checks are the following: - mismatch in case between first characters in msgid and msgstr - mismatch in end punctuation - mismatch in length of beginning or trailing blank space - identical adjacent words (double words) in msgstr - double space between words in msgstr - inconsistent translations of otherwise identical msgids 4. Compendiums: Compendiums are files with translatable strings and their accompanying translations. You can use them to translate a whole po-file or a single entry automatically. 4.1 Create a Compendium: A compendium can be created with the contents of the current buffer (the contents of the file you are looking at in the editor) using the shortcut "ctrl-c a". You will be asked if you want to make all the translations "immutable", i.e. they will never be overwritten when updating the compendium later. An entire directory of po-files can be added to a compendium in one fell swoop using the shortcut "ctrl-c d". Menu items are available to update compendiums with the contents of the current buffer or to update the compendium with a directory of po-files. In the latter case only files with the ".po" extension will be added and an integrity check will be done on each file before it is added to the list of files to go into the compendium. When updating the compendium, you will be asked if you want to overwrite matching entries in the compendium. Answering yes here will let translations in the updating file(s) for msgids matching those in the compendium be overwritten. Conversely, answering no will keep translations in the compendium for matching msgids intact. If you feel that a translation fetched from the compendium is annoying, you can either edit the compendium manually or you can just modify the translation to your liking and then hit '+' in po-mode, then the new translation will overwrite the old one in the compendium and be used for the future. You can also update the compendium as per above by letting the entries be overwritten when you have finished editing the file. A translation for the current entry may be fetched from the compendium by typing "/". 6. View Source Files or Grep in Source Files: In addition to viewing the source file(s) referenced in the current entry, you can also grep for a string in the source files and get a window with a listing of all files that contain that expression which you can then select for easy viewing: If you have highlighted a string, e.g. with the mouse, this string will be seached for, otherwise the word at point will be seached for. The highlighting must be done with Jed's mark_region function, i.e. you should see an 'm' on the status line. The function is bound to 'G'. I recommend putting this line into your .jedrc: variable GrepCommand = "grep -H -n -r -i"; for a recursive, case-insensitive search. You must get grep.sl from http://jedmodes.sourceforge.net/grep/ 7. View a translation in other languages Typing 'm' on an entry will open a window with translations for that entry in languages you have chosen in the configuration variable Compare_With_Languages (see above). Of course it requires that the po-files for these languages are installed. Typically you would have a source archive for the program whose po-file you are translating installed under ~/src (see the SrcBaseDir variable above). You will be asked where to look for the po-files in the other languages. They typically reside in the "/po" subdirectory of the source archive. In any case, the names of the files that you want to compare with must have the two-letter language code in them. For instance both "be.po" and "gtkam-0.2.0.be.po" will be detected if you want to compare with Belarussian. 8. Limit Display to Entries Containing Expression: If you are familiar with the mail user agent Mutt, you will probably have cherished its "limit" function whereby you can narrow the index of mail messages to a list containing a specified expression. A limit function is also useful in the context of editing po-files. The limit function in this mode lets you narrow the display to a list of entries containing a certain expression. Like for the grep function mentioned above the limit function also acts on either the word at point, a highlighted string or a typed in expression. The function is bound to 'l' by default (like in Mutt), and typing 'l' again in the limited view toggles off the limitation. It is of course useful, because it lets you see a uniform list of entries containing your expression, so you can e.g. easily compare translations containing this expression to see if it is translated consistently in all of them, or you can limit the display to similarly looking msgids in order to quickly copying translations between them. Hint: To limit to expressions that cross lines, highlight that expression across the lines and then type 'l' to limit to it. 9. Gettext Functions: Various wrapper functions using the gettext utilities are included for convenience, these are: - validation: parse po-file for syntax errors with msgfmt. Error entries will be marked fuzzy. - compile: compile current buffer into a binary mo-file with msgfmt. - decompile: decompile a binary mo-file into a po-file with msgunfmt - wrap/unwrap: wrap/unwrap entries with msgcat. - update: update current po-buffer to a newer version with msgmerge. - convert: convert character encoding with msgconv - flag all entries fuzzy with msgattrib They are all available from the menu. 10. Other convenience functions - Check in the current po-file with RCS - Write a diff file between two versions. The other version may be under RCS. - Replace a word or a string in the msgstrs. - Replace words or strings in the msgstrs from a listfile. The listfile must have the format: word/string to be replaced : word/string replacement each on a line by itself. I.e. words and replacements listed pairwise separated by a colon. The blankspace around the colon does not matter. If your own language has a closely related language then you could maintain such a file with translations of words/string from your own language to that language. E.g. a Russian translator might have a file with Russian translations of Ukranian words, since the two languages are closely related and then run a Ukranian po-file through this function, The function "Count Occurences of Words", available from the menu, is handy in determining the frequency of words in connection with maintaining such a listfile. - Translate or update po-file with the machine translation system, Apertium 11. SUGGESTED EDITING WORK FLOW a) Begin by creating a subdirectory "src" under your home directory to hold the source archives for the programs you are translating. mkdir -p $HOME/src Switch to that directory and fetch the source archive of the program you are translating, e.g. with apt-get source or any other command that will fetch the sources. Unpack, if neccesary, the source archive under $HOME/src. b) Install the machine translation system, Apertium, and all the language pairs that translate into your language. For instance for Danish, I have these installed: nno-dan nob-dan swe-dan If a po-file has already been translated into, say Norwegian Bokmål (nob), then I can load that file into Jed and type 'A' (or from the menu: Mode -> Modify -> Translate w/Apertium) to have it translated into Danish. The quality and comprehensiveness of these language pairs varies, but the Spanish language pairs in particular seem to be of both high quality and to be extremely comprehensive, so if you are a Spanish translator, it seems that you can get almost all of the work done by Apertium. A Spanish user would make sure that the language pair "en-es" was installed, then fetch the pot-file (the empty original message catalogue) for the program's messages to be translated, load it into Jed and then type 'A'. All the msgstrs will first be pre-filled with the English original msgid strings and then translated into Spanish. Same procedure should be used by anyone with a language pair that translates from English into his own language. The Translate w/Apertium function, bound to 'A' is meant to be used on a whole po or pot-file. Another Apertium function exists to update untranslated entries in a po-file with Apertium-translated entries for matching msgids that are fetched from a reference file. This function is bound to "ctrl-c A" (or from the menu: Mode -> Modify -> Update Untranslated w/Apertium). So let us say that I have a po-file that I have already partially translated into Danish and a more updated version of this po-file exists in Norwegian, then I could type "ctrl-c A", choose the Norwegian file (the reference file) from the prompt to have the untranslated entries in my own file filled out with the Norwegian translations which in turn are then translated into Danish with Apertium. A variant of this function exists whereby also fuzzy translations from the reference file are translated with Apertium and transferred to your own file. It is bound to "ctrl-c F" (or from the menu: Mode -> Modify -> Update Untranslated/Use Fuzzy w/Apertium) All entries that are translated with these two latter functions are marked fuzzy. C) Create a compendium (see above) from as many different po-files that have been translated into your language as you can find. You can get a lot from the site of the Free Translation Project. This command will get all of the Danish translations from that site and place them under the "./translationproject.org/PO-files/da" subdirectory: wget -r --no-parent --reject "index.html*" \ http://translationproject.org/PO-files/da/ Just change the trailing "da" subdirectory to your own ISO_639 country code (see section 1.2). Then open a po-file in jed/xjed and type "ctrl-c d" to add a whole directory of po-files to the compendium. You can also do it from the menu: F10 => Mode => Compendiums and Wordlists => Add Dir to Compendium You will be asked for the path to the po-files. Type in the path above. You can use TAB completion in selecting the path. Since there may be many hundreds of po-files, it may take a little time to add them because they are validated first and duplicate entries are weeded out. (For about 1600 po-files of varying sizes it takes about two minutes to add them to the compendium on my medium fast computer.) d) Open the po-file you want to translate in jed/xjed. Type "ctrl-c i" to fill out the entries with translations from the compendium you just created. You can also use the menu: F10 => Mode => Compendiums and Wordlists => Initialize w/Compendium If your po-file already contained translated entries you will be asked if you want to overwrite them. If the msgid in your po-file was identical to the msgid in the compendium, the compendium's translation will be transferred to your po-file. If there were minor differences such as punctuation and case differences, then the entry will be filled out and marked fuzzy. e) Visit the entries that were filled out and review the translations. Use 't' to go to the next translated entry and 'f' to go to the next fuzzy entry. If the entry was flagged fuzzy you may have to make a minor modifiction to the translation. After having done so remove the fuzzy flag with alt-backspace. f) If you were not satisfied with the translation from the compendium, then modify it to your liking and hit '+'. This will transfer your modified translation to the compendium (you will be asked if you want to overwrite) and at the same time the translation will be marked "immutable". That means that it will not overwritten when you update the compendium later. You can have it changed only by following the same procedure, that is modify the translation and hit '+'. g) Translate the remaining entries. Be as productive as you can by using - dynamic word completions (see above). - if there is only a little to translate in a msgid, then copy it to the msgstr with alt-enter and then modify. - use the editor's native navigation features with convenient keyboard shortcuts in the editing window, - check translations for a troublesome entry in other languages by typing 'm' (see section 7) - use the source view (bound to 's') to view the source context of the msgid if you are in doubt of its meaning. - use 'l' to limit the view to entries containing a word or an expression if there are many of those and you want to ensure that you have translated them uniformly. h) Fill out the header by typing 'H'. You must set the configuration variables in section 1.2 i) Spell check the file. I recommend using a list of misspelled words by typing 'L' and correct the misspelled words by hitting enter on them. j) Check punctuation and word case errors by typing "ctrl-c ." (ctrl-c + period). k) Validate the file, typing 'V' l) When all is translated and there are no fuzzy entries left and the file validates with no errors, then - check the file in with RCS by typing "ctrl-c i". The po-file will be checked in under the ./RCS subdirectory in the directory of the po-file itself. You can then subsequently write diffs between your current po-file and an older version in RCS by typing 'D'. Diffs such as these can be sent to the mailing list of your language team for a review. - finally, add the file to the compendium, with "ctrl-c a". You will be asked if you want to flag all the new translations "immutable" which means that they will not be overwritten on subsequent updates of the compendium. -------- Otherwise the explanation of the keybindings above should, I hope, make it clear what functionality is available. Send comments or suggestions to Morten Bo Johansen