Appendix D.  Internationalization and Localization

Table of Contents

1. The “.po” Files
2. Checking the Code
3. Translators Welcome

The Aegis source code has been internationalized, which is the process of modifying the original source code to permit error messages and other text to be presented in a language other than the author's native English. This was a large and often painful task, but it allows a degree of customization of error messages and other behaviours which would not have been otherwise possible. (It also makes the job of running a spell-checker over the error messages significantly easier.)

Localization is the process of translating the error messages and other text into various different languages or nationalities. This appendix is primarily aimed at localizers of Aegis.

1. The “.po” Files

The “lib/en/LC_MESSAGES” directory in the source tree contains the various message files needed to localize Aegis. You will find a number of “.po” files in this directory, which translates “programmer cryptic” into English. You will see that each message has a comment attached, describing the message and the context in which it is used. Many messages also have “substitutions” described, which are strings similar to shell variables which may be substituted into the message - such as the file name for messages which have something to do with a specific file.

The substitution mechanism is the same one as is used for the various commands in the project aegis.conf file, and so all of the substitutions described in aesub(5) are available to the translator. Note frequent use of the plural substitution, which allows grammatically correct error messages to be issued when faced with the singular/plural dichotomy. Other substitutions include the login name of the executing user, names of projects, number and state of changes, etc.

Ideally, the task for a translator is to take the .po files and translate the msgstr lines into the appropriate language. The job will, of course, not be that simple and so references into the code have been included, so that you can read the code should context be necessary to correctly translate the message.

2. Checking the Code

There are a number of keywords you need to have for the xgettext program when extracting message strings. The gettext keyword is not used directly, because of the substitution mechanism wrapped around it.

i18nerror_intl
io_comment_appendfatal_intl
report_errorverbose_intl
report_errorgram_error
rpt_value_error 

In general, the etc/Howto.cook file causes the messages to be extracted into i18n-tmp/*.po for checking during the build.

3. Translators Welcome

If you are able to translate the error messages into another language, please contact Peter Miller <millerp@canb.auug.org.au> and he will tell you how it is done. (Actually, he'll point you to this part of the User Guide. :-)

To translate the error messages, look up the two-letter abbreviation (http://www.w3.org/WAI/ER/IG/ert/iso639.htm) of the language you are going to translate the error messages to. The rest of these instructions will call it xx.

In the source tree, you will see a directory called lib/en/LC_MESSAGES which contains some .po files. These are the text form of the message catalogues. You can view them with a simple text editor.

Create a new directory for your translations, and copy the English messages into it.

mkdir lib/xx/LC_MESSAGES
cp lib/en/LC_MESSAGES/*.po \
	lib/xx/LC_MESSAGES

Now you need to edit each of the lib/xx/LC_MESSAGES/*.po files, replacing the msgstr strings with suitable translations. Leave the msgid strings and the comments untranslated. These are text files, you can edit them with a simple text editor. GNU Emacs has a PO mode to make this easier.

The GNU Gettext (http://www.gnu.org/directory/gettext.html) sources have fairly good documentation (http://www.gnu.org/manual/gettext/index.html) about this process.

If you want to test your translations, you need to "compile" the text into the binary form used by the gettext() system call. This is done using the msgfmt(1) program from the GNU Gettext package. To see your new translations in action, you create a /opt/aegis/lib/xx/LC_MESSAGES directory and arrange for the msgfmt(1) output to be placed in it. Some of the messages are hard to trigger, don't expect complete test coverage.

There are almost 600 error messages. If you average 1 message every 2 minutes, this is approximately 20 hours work. The German translation, for example, required around 12 hours.

When you are done translating, email the results to Peter Miller <millerp@canb.auug.org.au> and they will be included in the next release of Aegis.