3.5 Special Comments preceding Keywords

In C programs strings are often used within calls of functions from the printf family. The special thing about these format strings is that they can contain format specifiers introduced with %. Assume we have the code

printf (gettext ("String `%s' has %d characters\n"), s, strlen (s));

A possible German translation for the above string might be:

"%d Zeichen lang ist die Zeichenkette `%s'"

A C programmer, even if he cannot speak German, will recognize that there is something wrong here. The order of the two format specifiers is changed but of course the arguments in the printf don't have. This will most probably lead to problems because now the length of the string is regarded as the address.

To prevent errors at runtime caused by translations the msgfmt tool can check statically whether the arguments in the original and the translation string match in type and number. If this is not the case and the `-c' option has been passed to msgfmt, msgfmt will give an error and refuse to produce a MO file. Thus consequent use of `msgfmt -c' will catch the error, so that it cannot cause cause problems at runtime.

If the word order in the above German translation would be correct one would have to write

"%2$d Zeichen lang ist die Zeichenkette `%1$s'"

The routines in msgfmt know about this special notation.

Because not all strings in a program must be format strings it is not useful for msgfmt to test all the strings in the `.po' file. This might cause problems because the string might contain what looks like a format specifier, but the string is not used in printf.

Therefore the xgettext adds a special tag to those messages it thinks might be a format string. There is no absolute rule for this, only a heuristic. In the `.po' file the entry is marked using the c-format flag in the #, comment line (see section 2.2 The Format of PO Files).

The careful reader now might say that this again can cause problems. The heuristic might guess it wrong. This is true and therefore xgettext knows about special kind of comment which lets the programmer take over the decision. If in the same line or the immediately preceding line of the gettext keyword the xgettext program find a comment containing the words xgettext:c-format it will mark the string in any case with the c-format flag. This kind of comment should be used when xgettext does not recognize the string as a format string but is really is one and it should be tested. Please note that when the comment is in the same line of the gettext keyword, it must be before the string to be translated.

This situation happens quite often. The printf function is often called with strings which do not contain a format specifier. Of course one would normally use fputs but it does happen. In this case xgettext does not recognize this as a format string but what happens if the translation introduces a valid format specifier? The printf function will try to access one of the parameter but none exists because the original code does not refer to any parameter.

xgettext of course could make a wrong decision the other way round, i.e. a string marked as a format string actually is not a format string. In this case the msgfmt might give too many warnings and would prevent translating the `.po' file. The method to prevent this wrong decision is similar to the one used above, only the comment to use must contain the string xgettext:no-c-format.

If a string is marked with c-format and this is not correct the user can find out who is responsible for the decision. See 4.1 Invoking the xgettext Program to see how the --debug option can be used for solving this problem.