Go to the first, previous, next, last section, table of contents. -
- - -
-For the programmer, changes to the C source code fall into three
-categories. First, you have to make the localization functions
-known to all modules needing message translation. Second, you should
-properly trigger the operation of GNU gettext when the program
-initializes, usually from the main function. Last, you should
-identify and especially mark all constant strings in your program
-needing translation.
-
-
-Presuming that your set of programs, or package, has been adjusted
-so all needed GNU gettext files are available, and your
-`Makefile' files are adjusted (see section The Maintainer's View), each C module
-having translated C strings should contain the line:
-
-
-#include <libintl.h> -- -
-The remaining changes to your C sources are discussed in the further -sections of this chapter. - -
- - - -gettext Operations-The initialization of locale data should be done with more or less -the same code in every program, as demonstrated below: - -
- -
-int
-main (argc, argv)
- int argc;
- char argv;
-{
- ...
- setlocale (LC_ALL, "");
- bindtextdomain (PACKAGE, LOCALEDIR);
- textdomain (PACKAGE);
- ...
-}
-
-
-
-PACKAGE and LOCALEDIR should be provided either by
-`config.h' or by the Makefile. For now consult the gettext
-sources for more information.
-
-
-The use of LC_ALL might not be appropriate for you.
-LC_ALL includes all locale categories and especially
-LC_CTYPE. This later category is responsible for determining
-character classes with the isalnum etc. functions from
-`ctype.h' which could especially for programs, which process some
-kind of input language, be wrong. For example this would mean that a
-source code using the @,{c} (c-cedilla character) is runnable in
-France but not in the U.S.
-
-
-Some systems also have problems with parsing number using the
-scanf functions if an other but the LC_ALL locale is used.
-The standards say that additional formats but the one known in the
-"C" locale might be recognized. But some systems seem to reject
-numbers in the "C" locale format. In some situation, it might
-also be a problem with the notation itself which makes it impossible to
-recognize whether the number is in the "C" locale or the local
-format. This can happen if thousands separator characters are used.
-Some locales define this character according to the national
-conventions to '.' which is the same character used in the
-"C" locale to denote the decimal point.
-
-
-So it is sometimes necessary to replace the LC_ALL line in the
-code above by a sequence of setlocale lines
-
-
-{
- ...
- setlocale (LC_TIME, "");
- setlocale (LC_MESSAGES, "");
- ...
-}
-
-
-
-or to switch for and back to the character class in question. On all
-POSIX conformant systems the locale categories LC_CTYPE,
-LC_COLLATE, LC_MONETARY, LC_NUMERIC, and
-LC_TIME are available. On some modern systems there is also a
-locale LC_MESSAGES which is called on some old, XPG2 compliant
-systems LC_RESPONSES.
-
-
-All strings requiring translation should be marked in the C sources. Marking
-is done in such a way that each translatable string appears to be
-the sole argument of some function or preprocessor macro. There are
-only a few such possible functions or macros meant for translation,
-and their names are said to be marking keywords. The marking is
-attached to strings themselves, rather than to what we do with them.
-This approach has more uses. A blatant example is an error message
-produced by formatting. The format string needs translation, as
-well as some strings inserted through some `%s' specification
-in the format, while the result from sprintf may have so many
-different instances that it is impractical to list them all in some
-`error_string_out()' routine, say.
-
-
-This marking operation has two goals. The first goal of marking -is for triggering the retrieval of the translation, at run time. -The keyword are possibly resolved into a routine able to dynamically -return the proper translation, as far as possible or wanted, for the -argument string. Most localizable strings are found in executable -positions, that is, attached to variables or given as parameters to -functions. But this is not universal usage, and some translatable -strings appear in structured initializations. See section Special Cases of Translatable Strings. - -
-
-The second goal of the marking operation is to help xgettext
-at properly extracting all translatable strings when it scans a set
-of program sources and produces PO file templates.
-
-
-The canonical keyword for marking translatable strings is
-`gettext', it gave its name to the whole GNU gettext
-package. For packages making only light use of the `gettext'
-keyword, macro or function, it is easily used as is. However,
-for packages using the gettext interface more heavily, it
-is usually more convenient to give the main keyword a shorter, less
-obtrusive name. Indeed, the keyword might appear on a lot of strings
-all over the package, and programmers usually do not want nor need
-their program sources to remind them forcefully, all the time, that they
-are internationalized. Further, a long keyword has the disadvantage
-of using more horizontal space, forcing more indentation work on
-sources for those trying to keep them within 79 or 80 columns.
-
-
-Many packages use `_' (a simple underline) as a keyword,
-and write `_("Translatable string")' instead of `gettext
-("Translatable string")'. Further, the coding rule, from GNU standards,
-wanting that there is a space between the keyword and the opening
-parenthesis is relaxed, in practice, for this particular usage.
-So, the textual overhead per translatable string is reduced to
-only three characters: the underline and the two parentheses.
-However, even if GNU gettext uses this convention internally,
-it does not offer it officially. The real, genuine keyword is truly
-`gettext' indeed. It is fairly easy for those wanting to use
-`_' instead of `gettext' to declare:
-
-
-#include <libintl.h> -#define _(String) gettext (String) -- -
-instead of merely using `#include <libintl.h>'. - -
--Later on, the maintenance is relatively easy. If, as a programmer, -you add or modify a string, you will have to ask yourself if the -new or altered string requires translation, and include it within -`_()' if you think it should be translated. `"%s: %d"' is -an example of string not requiring translation! - -
- - --In PO mode, one set of features is meant more for the programmer than -for the translator, and allows him to interactively mark which strings, -in a set of program sources, are translatable, and which are not. -Even if it is a fairly easy job for a programmer to find and mark -such strings by other means, using any editor of his choice, PO mode -makes this work more comfortable. Further, this gives translators -who feel a little like programmers, or programmers who feel a little -like translators, a tool letting them work at marking translatable -strings in the program sources, while simultaneously producing a set of -translation in some language, for the package being internationalized. - -
--The set of program sources, targetted by the PO mode commands describe -here, should have an Emacs tags table constructed for your project, -prior to using these PO file commands. This is easy to do. In any -shell window, change the directory to the root of your project, then -execute a command resembling: - -
- --etags src/*.[hc] lib/*.[hc] -- -
-presuming here you want to process all `.h' and `.c' files -from the `src/' and `lib/' directories. This command will -explore all said files and create a `TAGS' file in your root -directory, somewhat summarizing the contents using a special file -format Emacs can understand. - -
-
-For packages following the GNU coding standards, there is
-a make goal tags or TAGS which construct the tag files in
-all directories and for all files containing source code.
-
-
-Once your `TAGS' file is ready, the following commands assist -the programmer at marking translatable strings in his set of sources. -But these commands are necessarily driven from within a PO file -window, and it is likely that you do not even have such a PO file yet. -This is not a problem at all, as you may safely open a new, empty PO -file, mainly for using these commands. This empty PO file will slowly -fill in while you mark strings as translatable in your program sources. - -
-
-The , (po-tags-search) command search for the next
-occurrence of a string which looks like a possible candidate for
-translation, and displays the program source in another Emacs window,
-positioned in such a way that the string is near the top of this other
-window. If the string is too big to fit whole in this window, it is
-positioned so only its end is shown. In any case, the cursor
-is left in the PO file window. If the shown string would be better
-presented differently in different native languages, you may mark it
-using M-, or M-.. Otherwise, you might rather ignore it
-and skip to the next string by merely repeating the , command.
-
-
-A string is a good candidate for translation if it contains a sequence -of three or more letters. A string containing at most two letters in -a row will be considered as a candidate if it has more letters than -non-letters. The command disregards strings containing no letters, -or isolated letters only. It also disregards strings within comments, -or strings already marked with some keyword PO mode knows (see below). - -
--If you have never told Emacs about some `TAGS' file to use, the -command will request that you specify one from the minibuffer, the -first time you use the command. You may later change your `TAGS' -file by using the regular Emacs command M-x visit-tags-table, -which will ask you to name the precise `TAGS' file you want -to use. See section `Tag Tables' in The Emacs Editor. - -
--Each time you use the , command, the search resumes from where it was -left by the previous search, and goes through all program sources, -obeying the `TAGS' file, until all sources have been processed. -However, by giving a prefix argument to the command (C-u -,), you may request that the search be restarted all over again -from the first program source; but in this case, strings that you -recently marked as translatable will be automatically skipped. - -
-
-Using this , command does not prevent using of other regular
-Emacs tags commands. For example, regular tags-search or
-tags-query-replace commands may be used without disrupting the
-independent , search sequence. However, as implemented, the
-initial , command (or the , command is used with a
-prefix) might also reinitialize the regular Emacs tags searching to the
-first tags file, this reinitialization might be considered spurious.
-
-
-The M-, (po-mark-translatable) command will mark the
-recently found string with the `_' keyword. The M-.
-(po-select-mark-and-mark) command will request that you type
-one keyword from the minibuffer and use that keyword for marking
-the string. Both commands will automatically create a new PO file
-untranslated entry for the string being marked, and make it the
-current entry (making it easy for you to immediately proceed to its
-translation, if you feel like doing it right away). It is possible
-that the modifications made to the program source by M-, or
-M-. render some source line longer than 80 columns, forcing you
-to break and re-indent this line differently. You may use the O
-command from PO mode, or any other window changing command from
-GNU Emacs, to break out into the program source window, and do any
-needed adjustments. You will have to use some regular Emacs command
-to return the cursor to the PO file window, if you want command
-, for the next string, say.
-
-
-The M-. command has a few built-in speedups, so you do not -have to explicitly type all keywords all the time. The first such -speedup is that you are presented with a preferred keyword, -which you may accept by merely typing RET at the prompt. -The second speedup is that you may type any non-ambiguous prefix of the -keyword you really mean, and the command will complete it automatically -for you. This also means that PO mode has to know all -your possible keywords, and that it will not accept mistyped keywords. - -
--If you reply ? to the keyword request, the command gives a -list of all known keywords, from which you may choose. When the -command is prefixed by an argument (C-u M-.), it inhibits -updating any program source or PO file buffer, and does some simple -keyword management instead. In this case, the command asks for a -keyword, written in full, which becomes a new allowed keyword for -later M-. commands. Moreover, this new keyword automatically -becomes the preferred keyword for later commands. By typing -an already known keyword in response to C-u M-., one merely -changes the preferred keyword and does nothing more. - -
--All keywords known for M-. are recognized by the , command -when scanning for strings, and strings already marked by any of those -known keywords are automatically skipped. If many PO files are opened -simultaneously, each one has its own independent set of known keywords. -There is no provision in PO mode, currently, for deleting a known -keyword, you have to quit the file (maybe using q) and reopen -it afresh. When a PO file is newly brought up in an Emacs window, only -`gettext' and `_' are known as keywords, and `gettext' -is preferred for the M-. command. In fact, this is not useful to -prefer `_', as this one is already built in the M-, command. - -
- - -
-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 a
-warning will be given and the error cannot causes 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 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. A string marked as a format string is not really 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 section Invoking the xgettext Program to see how the --debug option can be used for solving
-this problem.
-
-
-The attentive reader might now point out that it is not always possible
-to mark translatable string with gettext or something like this.
-Consider the following case:
-
-
-{
- static const char *messages[] = {
- "some very meaningful message",
- "and another one"
- };
- const char *string;
- ...
- string
- = index > 1 ? "a default message" : messages[index];
-
- fputs (string);
- ...
-}
-
-
-
-While it is no problem to mark the string "a default message" it
-is not possible to mark the string initializers for messages.
-What is to be done? We have to fulfil two tasks. First we have to mark the
-strings so that the xgettext program (see section Invoking the xgettext Program)
-can find them, and second we have to translate the string at runtime
-before printing them.
-
-
-The first task can be fulfilled by creating a new keyword, which names a -no-op. For the second we have to mark all access points to a string -from the array. So one solution can look like this: - -
- -
-#define gettext_noop(String) (String)
-
-{
- static const char *messages[] = {
- gettext_noop ("some very meaningful message"),
- gettext_noop ("and another one")
- };
- const char *string;
- ...
- string
- = index > 1 ? gettext ("a default message") : gettext (messages[index]);
-
- fputs (string);
- ...
-}
-
-
-
-Please convince yourself that the string which is written by
-fputs is translated in any case. How to get xgettext know
-the additional keyword gettext_noop is explained in section Invoking the xgettext Program.
-
-
-The above is of course not the only solution. You could also come along -with the following one: - -
- -
-#define gettext_noop(String) (String)
-
-{
- static const char *messages[] = {
- gettext_noop ("some very meaningful message",
- gettext_noop ("and another one")
- };
- const char *string;
- ...
- string
- = index > 1 ? gettext_noop ("a default message") : messages[index];
-
- fputs (gettext (string));
- ...
-}
-
-
-
-But this has some drawbacks. First the programmer has to take care that
-he uses gettext_noop for the string "a default message".
-A use of gettext could have in rare cases unpredictable results.
-The second reason is found in the internals of the GNU gettext
-Library which will make this solution less efficient.
-
-
-One advantage is that you need not make control flow analysis to make -sure the output is really translated in any case. But this analysis is -generally not very difficult. If it should be in any situation you can -use this second method in this situation. - -
--
Go to the first, previous, next, last section, table of contents. - -