Making the Initial PO File

Invoking the xgettext Program

xgettext [option] inputfile ...

`-a'

`--extract-all'

Extract all strings.

`-c [tag]'

`--add-comments[=tag]'

Place comment block with tag (or those preceding keyword lines) in output file.

`-C'

`--c++'

Recognize C++ style comments.

`-d name'

`--default-domain=name'

Use `name.po' for output (instead of `messages.po').

`-D directory'

`--directory=directory'

Change to directory before beginning to search and scan source files. The resulting `.po' file will be written relative to the original directory, though.

`-f file'

`--files-from=file'

Read the names of the input files from file instead of getting them from the command line.

`-h'

`--help'

Display this help and exit.

`-I list'

`--input-path=list'

List of directories searched for input files.

`-j'

`--join-existing'

Join messages with existing file.

`-k word'

`--keyword[=word]'

Additonal keyword to be looked for (without word means not to use default keywords). The default keywords, which are always looked for if not explicitly disabled, are gettext, dgettext, dcgettext and gettext_noop.

`-m [string]'

`--msgstr-prefix[=string]'

Use string or "" as prefix for msgstr entries.

`-M [string]'

`--msgstr-suffix[=string]'

Use string or "" as suffix for msgstr entries.

`--no-location'

Do not write `#: filename:line' lines.

`-n'

`--add-location'

Generate `#: filename:line' lines (default).

`--omit-header'

Don't write header with `msgid ""' entry. This is useful for testing purposes because it eliminates a source of variance for generated .gmo files. We can ship some of these files in the GNU gettext package, and the result of regenerating them through msgfmt should yield the same values.

`-p dir'

`--output-dir=dir'

Output files will be placed in directory dir.

`-s'

`--sort-output'

Generate sorted output and remove duplicates.

`--strict'

Write out strict Uniforum conforming PO file.

`-v'

`--version'

Output version information and exit.

`-x file'

`--exclude-file=file'

Entries from file are not extracted.

Search path for supplementary PO files is: `/usr/local/share/nls/src/'.

If inputfile is `-', standard input is read.

This implementation of xgettext is able to process a few awkward cases, like strings in preprocessor macros, ANSI concatenation of adjacent strings, and escaped end of lines for continued strings.

C Sources Context

PO mode is particularily powerful when used with PO files created through GNU gettext utilities, as those utilities insert special comments in the PO files they generate. Some of these special comments relate the PO file entry to exactly where the untranslated string appears in the program sources.

When the translator gets to an untranslated entry, she is fairly often faced with an original string which is not as informative as it normally should, being succinct, cryptic, or otherwise ambiguous. Before chosing how to translate the string, she needs to understand better what the string really means and how tight the translation has to be. Most of times, when problems arise, the only way left to make her judgment is looking at the true program sources from where this string originated, searching for surrounding comments the programmer might have put in there, and looking around for helping clues of any kind.

Surely, when looking at program sources, the translator will receive more help if she is a fluent programmer. However, even if she is not versed in programming and feels a little lost in C code, the translator should not be shy at taking a look, once in a while. It is most probable that she will still be able to find some of the hints she needs. She will learn quickly to not feel uncomfortable in program code, paying more attention to programmer's comments, variable and function names (if he dared chosing them well), and overall organization, than to programmation itself.

The following commands are meant to help the translator at getting program source context for a PO file entry.

c

Resume the display of a program source context, or cycle through them.

M-c

Display of a program source context selected by menu.

d

Add a directory to the search path for source files.

M-d

Delete a directory from the search path for source files.

The commands c (po-cycle-reference) and M-c (po-select-reference) both open another window displaying some source program file, and already positioned in such a way that it shows an actual use of the current string to translate. By doing so, the command gives source program context for the string. But if the entry has no source context references, or if all references are unresolved along the search path for program sources, then the command diagnoses this as an error.

Even if c (or M-c) opens a new window, the cursor stays in the PO file window. If the translator really wants to get into the program source window, she ought to do it explicitly, maybe by using command o.

When c is typed for the first time, or for a PO file entry which is different of the last one used for getting source context, then the command reacts by giving the first context available for this entry, if any. If some context has already been recently displayed for the current PO file entry, and the translator wandered to do other things, typing c again will merely resume, in another window, the context last displayed. In particular, if the translator moved the cursor away from the context in the source file, the command will bring the cursor back to the context. By using c many times in a row, with no interning other commands, PO mode will cycle to the next available contexts for this particular entry, getting back to the first context once the last has been shown.

The command M-c behaves differently. Instead of cycling through references, it lets the translator choose of particular reference among many, and displays that reference. It is best used with completion, if the translator types TAB immediately after M-c, in response to the question, she will be offered a menu of all possible references, as a reminder of which are the acceptable answers. This command is useful only where there are really many contexts available for a single string to translate.

Program source files are usually found relative to where the PO file stands. As a special provision, when this fails, the file is also looked for, but relative to the directory immediately above it. Those two cases take proper care of most PO files. However, it might happen that a PO file has been moved, or is edited in a different place than its normal location. When this happens, the translator should tell PO mode in which directory normally sits the genuine PO file. Many such directories may be specified, and all together, they constitute what is called the search path for program sources. The command d (po-add-path) is used to interactively enter a new directory at the front of the search path, and the command M-d (po-delete-path) is used to select, with completion, one of the directories she does not want anymore on the search path.

Using Translation Compendiums

Compendiums are yet to be implemented.

An incoming PO mode feature will let the translator maintain a compendium of already achieved translations. A compendium is a special PO file containing a set of translations recurring in many different packages. The translator will be given commands for adding entries to her compendium, and later initializing untranslated entries, or updating already translated entries, from translations kept in the compendium. For this to work, however, the compendium would have to be normalized. See section Normalizing Strings in Entries.

Go to the first, previous, next, last section, table of contents.