.\"
.\"     aegis - project change supervisor
.\"     Copyright (C) 1995, 1998, 2002, 2005-2010, 2012 Peter Miller
.\"
.\"     This program is free software; you can redistribute it and/or modify
.\"     it under the terms of the GNU General Public License as published by
.\"     the Free Software Foundation; either version 3 of the License, or
.\"     (at your option) any later version.
.\"
.\"     This program is distributed in the hope that it will be useful,
.\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"     GNU General Public License for more details.
.\"
.\"     You should have received a copy of the GNU General Public License
.\"     along with this program. If not, see
.\"     <http://www.gnu.org/licenses/>.
.\"
.bp
.if t .2C
.nh 1 "Appendix I: Internationalization and Localization
.LP
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\[hy]checker over the error
messages significantly easier.)
.LP
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.
.nh 2 "The \[lq].po\[rq] Files"
.LP
The \[lq]lib/en/LC_MESSAGES\[rq] directory in the source tree contains
the various
message files needed to localize Aegis.
You will find a number of \[lq].po\[rq] files in this directory,
which translates \[lq]programmer cryptic\[rq] 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 \[lq]substitutions\[rq] 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.
.LP
The substitution mechanism is the same one as is used for
the various commands in the project \fIaegis.conf\fP file,
and so all of the substitutions described in \fIaesub\fP(5)
are available to the translator.
Note frequent use of the \fIplural\fP 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.
.LP
Ideally, the task for a translator is to take the \fI.po\fP files
and translate the \f(CWmsgstr\fP 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.
.nh 2 "Checking the Code"
.LP
There are a number of keywords you need to have for the \fIxgettext\fP program
when extracting message strings.
The \f(CWgettext\fP keyword is not used directly,
because of the substitution mechanism wrapped around it.
.TS
center,tab(;);
l l.
i18n;error_intl
io_comment_append;fatal_intl
report_error;verbose_intl
report_error;gram_error
rpt_value_error;
.TE
.LP
In general, the \fIetc/Howto.cook\fP file causes the
messages to be extracted into \f[I]i18n\[hy]tmp/*.po\fP for checking
during the build.
.nh 2 "Translators Welcome"
.LP
If \fIyou\fP are able to translate the error messages into another
language, please contact
Peter Miller <pmiller@opensource.org.au>
and he will tell you how it is done.
(Actually, he'll point you to this part of the User Guide.  :\-)
.LP
To translate the error messages, look up the
two\[hy]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 \fIxx\fP.
.LP
In the source tree, you will see a directory called
\fIlib/en/LC_MESSAGES\fP which contains some \f[CW].po\fP files.
These are the text form of the message catalogues.
You can view them with a simple text editor.
.LP
Create a new directory for your translations, and copy the English
messages into it.
.E(
mkdir lib/\fIxx\fP/LC_MESSAGES
cp lib/en/LC_MESSAGES/*.po \e
        lib/\fIxx\fP/LC_MESSAGES
.E)
Now you need to edit each of the
\f[CW]lib/\fP\fIxx\fP\f[CW]/LC_MESSAGES/*.po\fP
files, replacing the \f[CW]msgstr\fP strings with suitable translations.
Leave the \f[CW]msgid\fP 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.
.LP
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.
.LP
If you want to test your translations, you need to "compile" the
text into the binary form used by the \f[CW]gettext()\fP system
call.  This is done using the \fImsgfmt\fP(1) program from the GNU
Gettext package.  To see your new translations in action, you create a
\f(CW\*(L)/\fP\fIxx\fP\f(CW/LC_MESSAGES\fP directory and arrange for
the \fImsgfmt\fP(1) output to be placed in it.  Some of the messages
are hard to trigger, don't expect complete test coverage.
.LP
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.
.LP
When you are done translating, email the results to
Peter Miller <pmiller@opensource.org.au>
and they will be included in the next release of Aegis.


/* vim: set ts=8 sw=4 et : */