3. How to use it

To produce a translatable program, do the following

• Replace all string message with MSG_U or MSG_B macros, giving each message a unique ID.
• include (#include) the .m file in each source file using the MSG_x macros. This file is generally named directory.m where directory is the name of the current directory.
• Create a file _dict.c. The content of this file is shown below.
• Use "make msg" to extract the messages. This produces/updates the dictionary file directory.dic and produces the include file directory.m.
• Compile and link your program.
• Use "make msg.eng" to produce the English binary dictionary. The file produced should be placed where your program expects it.

We will now describe further the different steps involved.

3.1 The make msg command and msgscan utility

The make msg command invokes the msgscan utility. This utility scan a set of C or C++ source file, updates a dictionary file and produces one include file.

Here is the command use to update the dictionary of the sub-project uucp of the Linuxconf project.

                ../translate/msgscan uucp \
                        ../messages/sources/uucp.dic uucp.m EF *.c
        

The first argument is the name of the dictionary. The second argument is the path of the dictionary file. As you see, dictionary file are kept in a single directory for all projects. They are seldom. This eases the works of translators. The third argument is the path of the include file, which is produced in the current directory.

The fourth argument is the letter tags used to identify messages defined with the macro MSG_U and MSG_B. Messages defined with MSG_U will be tagged with the letter E (English) and messages defined with MSG_B will be tagged with E for the first value and F (French) for the second.

3.2 The _dict.c file

It is good practice to place the DICTIONARY_REQUEST macro in a file _dict.c. There is generally one such a file per directory. Its contents is generally:

        #include "this_directory.m"
        #include <translat.h>
        DICTIONARY_REQUEST
        

At least this dependency should be placed in your makefile

        _dict.o: _dict.c this_directory.m
        

This will ensure that each time you update your dictionary (and the m header file), _dict.c will be recompile, ensuring proper recording of the dictionary revision and number of message. This will avoid executing a program with an obsolete or incompatible binary dictionary.

Given that _dict.c is small, the compilation is pretty short.

3.3 The msgcomp utility

Once you have compiled and linked your program, you must "compiled" all the dictionaries used in your program into one binary dictionary. This is done by the msgcomp utility. Here is the command used when doing "make msg.eng" for the Linuxconf project. This produces the English binary dictionary.

    ../translate/msgcomp -p../messages/sources/ \
        /tmp/linuxconf-msg-1.3.eng eE \
        askrunlevel dialog dnsconf fstab \
        misc main netconf mailconf uucp userconf
        

This commands take all dictionaries for sub-projects askrunlevel dialog dnsconf fstab misc main netconf mailconf uucp and userconf and produce a single binary dictionary.

The -p option tells msgcomp to look for those dic files ( askrunlevel.dic dialog.dic ...) in the directory ../messages/sources/.

The argument /tmp/linuxconf-msg-1.3.eng is the file to produce. The argument eE instructs msgcomp to extract message's values with the 'e' tag. If there is no such value for a given message, the value with the 'E' tag will be used.

Convention used for tags

Dictionary file contain the definition for all messages. Each messages may have different values, identified by a tag letter. When messages are extracted by msgscan, it is instructed to associate values with given tags. By convention, we use upper case letter to identify message's value extracted from the source code. Lower case value are used by translators.

We assume here that programmers are bad writers. We let them give their best shots for messages and we are allowed to override their work without overwriting it. By giving precedence to 'e' tags over 'E' we are saying that translators work override the work of programmers, but we are not forcing the translators to rewrite everything.

3.4 The msgclean utility

The msgscan utility maintains dictionary. At some point some messages may become obsolete (Unused in any source files). The msgclean is used to clean messages without values in the dic file.

For the Linuxconf project, the make target msg.clean is defined for that purpose.

Be aware that applying msgclean on a dictionary file with obsolete message has an important side effect. Some message being deleted, the numbering of all following message will be changed. All source using the m include file should be recompiled.

To avoid problems, the msgclean utility automaticly increases the revision number of the dictionary. This prevents using a dictionary with an incompatible program.