Hi Ralf, Thank you a lot for the willingness to integrate the handling of PO and POT files into Automake (first proposed in 2003: <http://sources.redhat.com/ml/automake/2003-11/msg00047.html>).
In order to test our common understanding, and to prepare for the unit tests, here is a proposed patch to the documentation. Feel free to put it on a git branch. 2010-08-15 Bruno Haible <br...@clisp.org> Document the handling of POT and PO files. * doc/automake.texi (Public Macros): Document AM_POT_TOOLS. (Private Macros): Add AM_NLS. (Internationalization): New chapter. --- doc/automake.texi.orig Sun Aug 15 22:15:54 2010 +++ doc/automake.texi Sun Aug 15 22:13:56 2010 @@ -105,6 +106,7 @@ * Directories:: Declaring subdirectories * Programs:: Building programs and libraries * Other Objects:: Other derived objects +* Internationalization:: Declaring translatable message catalogs * Other GNU Tools:: Other GNU Tools * Documentation:: Building documentation * Install:: What gets installed @@ -277,6 +279,32 @@ * Built Sources Example:: Several ways to handle built sources. +Internationalization + +* POT Files:: Declaring a POT file +* Parametrizing xgettext:: Declaring how a POT file gets created +* Message catalog translations::Declaring the translations +* Message catalog installation::Declaring how message catalogs get installed +* Other POT files details:: Rarely used settings for POT files + +Parametrizing xgettext + +* A POT file's _SOURCES:: Declaring the source files. +* A POT file's _COPYRIGHT_HOLDER:: The message catalogs' copyright holder +* A POT file's _MSGID_BUGS_ADDRESS:: Allowing translators to report bugs +* Additional xgettext options:: Fine tuning of xgettext +* Multiple xgettext invocations:: Advanced uses of xgettext + +Message catalog installation + +* A POT file's _CATALOGFORMAT:: Formats of compiled message catalogs +* A POT file's _LOCALE_CATEGORIES:: Using different locale categories + +Other POT files details + +* A POT file's _USE_MSGCTXT:: Declaring whether msgctxt is used +* A POT file's _MSGMERGE_OPTIONS:: Specifying options for msgmerge + Other GNU Tools * Emacs Lisp:: Emacs Lisp @@ -3861,6 +3889,19 @@ @command{configure} to explicitly set the correct path (if you're sure you have an @command{emacs} that supports Emacs Lisp). +...@item AM_POT_TOOLS +...@acindex AM_POT_TOOLS + +The @code{AM_POT_TOOLS} macro performs tests for the @code{POTS} primary. +See @pxref{Programming Languages, , Programming Languages, gettext, +GNU gettext tools} for a list of programming languages that support +localization through PO files. + +The @code{AM_POT_TOOLS} macro determines whether internationalization +should be used. If so, it sets the @code{USE_NLS} variable to @samp{yes}, +otherwise to @samp{no}. It also determines the right values for Makefile +variables used by the Makefile rules for the POT and PO files. + @item AM_PROG_AS @acindex AM_PROG_AS @vindex CCAS @@ -4030,6 +4071,11 @@ @code{include} statements. This macro is automatically invoked when needed; there should be no need to invoke it manually. +...@item AM_NLS +This macro determines whether internationalization should be used. If +so, it sets the @code{USE_NLS} variable to @samp{yes}, otherwise to +...@samp{no}. + @item AM_PROG_INSTALL_STRIP This is used to find a version of @code{install} that can be used to strip a program at installation time. This macro is automatically @@ -7352,6 +7398,421 @@ is converting @file{.h} files into @file{.c} files. +...@node Internationalization +...@chapter Internationalization + +An internationalized program is a program that can communicate with the +user in his native language, provided that some translation work has been +done. An internationalized program can be localized to a certain +language by translating the messages by which the program communicates +with the user. These message are grouped in files called ``message +catalogs''. + +The process of localization consists of three steps: + +...@enumerate +...@item +The developers send a file with English messages and (optionally) +some translation hints for the translators. +...@item +The translators translate these files to their respective language. +...@item +The translators send back the translated message catalogs, and the +developers integrate them in the package. +...@end enumerate + +Automake supports the message catalog format of GNU Gettext +(@pxref{Top, , Introduction, gettext, GNU gettext tools}). When the GNU +Gettext tools are in use: + +...@itemize +...@item +The file that contains the English messages and translation hints is +called a POT file (Portable Object Template) and usually named +...@code{@var{domain}.pot}. The @var{domain} is a identifier for the +translation domain. Different packages must use different @var{domain}s. +Therefore, usually, the @var{domain} is the same as the package name. + +...@item +The file that contains the translation produced by a translation team +is called a PO file (Portable Object) and usually named +...@code{@var{domai...@var{ll}.po} or +...@code{@var{domai...@var{ll}_@var{CC}.po}. Here @var{ll} is the +language code identifier according to ISO 639, and the optional @var{CC} +is the country code identifier according to ISO 3166. The optional +...@var{cc} is only needed to distinguish different dialects of the same +language, such as @code{pt_BR} (Brazilian Portuguese), which is slightly +different from @code{pt} (Portuguese). +...@end itemize + +...@menu +* POT Files:: Declaring a POT file +* Parametrizing xgettext:: Declaring how a POT file gets created +* Message catalog translations::Declaring the translations +* Message catalog installation::Declaring how message catalogs get installed +* Other POT files details:: Rarely used settings for POT files +...@end menu + +...@node POT Files +...@section POT Files + +In Automake, a message catalog template (POT file) is a primary. The +Makefile rules generated by Automake also handle all the PO files that +belong to the POT file. + +For execution, the PO files get compiled to ``compiled message +catalogs''. These a usally @code{.mo} files (MO = Machine Object). +They get installed in an appropriate subdirectory of @code{$(localedir)}. + +The declaration of an installable message catalog domain therefore looks +like this: + +...@smallexample +locale_POTS = po/maude.pot +...@end smallexample + +This declaration causes Automake to emit Makefile rules that create +the @file{po/maude.pot} file from some of the sources, and that manage +translated message catalogs @file{po/mau...@var{ll}_@var{CC}.po} in the +same directory. + +...@acindex AM_POT_TOOLS +When you use the @code{POTS} primary, you need to invoke +...@code{am_pot_tools} directly or indirectly from @file{configure.ac}. + +...@node Parametrizing xgettext +...@section Parametrizing xgettext + +The POT file gets created through an invocation of the @code{xgettext} +program +(@pxref{xgettext Invocation, , xgettext, gettext, GNU gettext tools}). + +...@menu +* A POT file's _SOURCES:: Declaring the source files. +* A POT file's _COPYRIGHT_HOLDER:: The message catalogs' copyright holder +* A POT file's _MSGID_BUGS_ADDRESS:: Allowing translators to report bugs +* Additional xgettext options:: Fine tuning of xgettext +* Multiple xgettext invocations:: Advanced uses of xgettext +...@end menu + +...@node A POT file's _SOURCES +...@subsection A POT file's _SOURCES + +...@code{xgettext} scans a set of source files. The default set of sources +is the union of all _SOURCES variables in the same @code{Makefile.am}, +except for @code{BUILT_SOURCES}. You can also specify the set of sources +explicitly, through a _SOURCES variable and optionally a +_SOURCES_EXCLUDE variable. Both variables may include wildcards. + +This example lists the source files explicitly: + +...@smallexample +locale_POTS = po/maude.pot +po_maude_pot_SOURCES = src/maude.c src/util.c +...@end smallexample + +This example uses wildcards. @code{**} stands for recursion across all +subdirectories. But note that only files known to Automake will be +selected. If you have other, unrelated files in the file system, they +will not be selected, even if they match the wildcard. + +...@smallexample +locale_POTS = po/maude.pot +po_maude_pot_SOURCES = src/**/*.c +po_maude_pot_SOURCES_EXCLUDE = src/version.c +...@end smallexample + +When a C file is automatically generated by a tool, like @code{flex} or +...@code{bison}, that doesn't introduce translatable strings by itself, +it is recommended to list in _SOURCES the real source file (ending in +...@file{.l} in the case of @code{flex}, or in @file{.y} in the case of +...@code{bison}), not the generated C file. + +...@node A POT file's _COPYRIGHT_HOLDER +...@subsection A POT file's _COPYRIGHT_HOLDER + +Every POT file needs to carry a copyright notice designating the +copyright holder, so that the translators know for whom they are doing +the translation. The copyright holder is declared like this: + +...@smallexample +locale_POTS = po/maude.pot +po_maude_pot_COPYRIGHT_HOLDER = Yoyodyne, Inc. +...@end smallexample + +The value of this variable is the copyright holder that gets inserted +into the header of the POT file. Set this to the copyright holder of the +surrounding package. (Note that the msgid strings, extracted from the +package's sources, belong to the copyright holder of the package.) +Translators are expected to transfer the copyright for their translations +to this person or entity, or to disclaim their copyright. The empty +string stands for the public domain; in this case the translators are +expected to disclaim their copyright. + +...@node A POT file's _MSGID_BUGS_ADDRESS +...@subsection A POT file's _MSGID_BUGS_ADDRESS + +It is important that translators can report problems that they find +in the English messages to be translated. A bug reporting address can +be declared like this: + +...@smallexample +locale_POTS = po/maude.pot +po_maude_pot_MSGID_BUGS_ADDRESS = bug-maude@@yoyodyne.com +...@end smallexample + +The value of this variable is the email address or URL to which the +translators shall report bugs in the untranslated strings: + +...@itemize +...@item +Strings which are not entire sentences, see the maintainer guidelines in +the GNU gettext documentation, +...@xref{preparing Strings, , Preparing Translatable Strings, gettext, +GNU gettext tools}. +...@item +Strings which use unclear terms or require additional context to be +understood. +...@item +Strings which make invalid assumptions about notation of date, time or +money. +...@item +Pluralisation problems. +...@item +Incorrect English spelling. +...@item +Incorrect formatting. +...@end itemize + +It can be your email address, or a mailing list address where translators +can write to without being subscribed, or the URL of a web page through +which the translators can contact you. + +You don't need to specify the bug reporting address here if you have +already done so through the third argument of @code{AC_INIT}, see +...@xref{initializing configure, , Initializing @code{configure}, autoconf, +The Autoconf Manual}. + +...@node Additional xgettext options +...@subsection Additional @code{xgettext} options + +Additional command-line options for the @code{xgettext} invocation can be +specified through the _XGETTEXT_OPTIONS variable. For example: + +...@smallexample +locale_POTS = po/maude.pot +po_maude_pot_XGETTEXT_OPTIONS = \ + --keyword=_ --flag=_:1:pass-c-format \ + --keyword=N_ --flag=N_:1:pass-c-format +...@end smallexample + +...@acindex AM_XGETTEXT_OPTION +Additional command-line options for the @code{xgettext} invocation can +also be specified in @file{configure.ac} or in Autoconf macros, through +the @code{AM_XGETTEXT_OPTION} macro. + +...@defmac AM_XGETTEXT_OPTION (@var{option}) + +The @code{AM_XGETTEXT_OPTION} macro registers a command-line option to be +used in the invocations of @code{xgettext} for POT files. + +For example, if you have a source file that defines a function +...@samp{error_at_line} whose fifth argument is a format string, you can use +...@smallexample +AM_XGETTEXT_OPTION([--flag=error_at_line:5:c-format]) +...@end smallexample +...@noindent +to instruct @code{xgettext} to mark all translatable strings in +...@samp{gettext} invocations that occur as fifth argument to this function +as @samp{c-format}. + +See @pxref{xgettext Invocation, , xgettext, gettext, GNU gettext tools} +for the list of options that @code{xgettext} accepts. +...@end defmac + +...@node Multiple xgettext invocations +...@subsection Multiple @code{xgettext} invocations + +If you need to construct a POT file from multiple @code{xgettext} +invocations, for example because your package has source code in +different programming languages and you need different options for +each language, the easiest way to achieve this is through intermediate +POT files that get combined into the final POT file: + +...@smallexample +locale_POTS = maude.pot +noinst_POTS = maude1.pot maude2.pot +maude_pot_SOURCES = maude1.pot maude2.pot +maude1_pot_SOURCES = maude.c +maude2_pot_SOURCES = maude.lisp +...@end smallexample + +...@node Message catalog translations +...@section Message catalog translations + +In the simplest case, you (the developer) receive translations through a +translation project, such as the Translation Project +...@url{http://translationproject.org/}, the KDE localization project +...@url{http://i18n.kde.org/}, or the GNOME localization project +...@url{http://l10n.gnome.org/}, and include them in your release tarball. +In this case, you should declare the set of translations in a _LINGUAS +variable, like this: + +...@smallexample +locale_POTS = po/maude.pot +po_maude_pot_LINGUAS = de fr de_AT nl +...@end smallexample + +This variable should contain the list of languages for which a +translation is present, using the notation @var{ll} or @var{l...@var{cc}. + +Alternatively, you can also have the translation downloaded from a +translation project when the package is built. This has the advantage +that translations that were complete after the package was released can +be included. It has two drawbacks, however: + +...@itemize +...@item +No translations can be installed if the build machine does not have a +connection to the Internet. +...@item +No translations can be installed if the GNU gettext tools are not +installed on the build machine. +...@end itemize + +To enable this mechanism, specify a _TP_URL variable or a _TP_RSYNC_URI +variable, or both. Example: + +...@smallexample +locale_POTS = po/maude.pot +po_maude_pot_TP_URL = http://translationproject.org/latest/ +po_maude_pot_TP_RSYNC_URI = translationproject.org::tp/latest/ +...@end smallexample + +Currently, only the Translation Project is supported in this way. + +...@node Message catalog installation +...@section Message catalog installation + +Normally, when you want translated message catalogs to be installed, you +specify the POT file in the @code{locale_POTS} variable. If you don't +want them installed (for example, if they are part of a test suite only), +you specify the POT file in the @code{noinst_POTS} variable. + +...@menu +* A POT file's _CATALOGFORMAT:: Formats of compiled message catalogs +* A POT file's _LOCALE_CATEGORIES:: Using different locale categories +...@end menu + +...@node A POT file's _CATALOGFORMAT +...@subsection A POT file's _CATALOGFORMAT + +Before installation or distribution, message catalogs need to be compiled +to ``compiled message catalogs''. The format of these compiled message +catalogs depends on the programming language or base runtime libraries +that your package is using. Several formats are supported: + +...@table @code +...@item mo +This is the GNU @code{.mo} format. It is used for C, C++, and many other +programming languages. +...@item qm +This is the message catalog format of the Qt library +...@url{http://qt.nokia.com/}. +...@item properties +This is the Java @code{.properties} format. For details, see +...@xref{java, , Java, gettext, GNU gettext tools}. +...@item class +This is the Java @code{.class} format. For details, see +...@xref{java, , Java, gettext, GNU gettext tools}. +...@item resources.dll +This is the message catalog format of C#. +...@item msg +This is the message catalog format of Tcl. +...@end table + +For example: + +...@smallexample +locale_POTS = po/maude.pot +po_maude_pot_CATALOGFORMAT = msg +...@end smallexample + +If you don't specify this variable, the default is @code{mo}. + +...@node A POT file's _LOCALE_CATEGORIES +...@subsection A POT file's _LOCALE_CATEGORIES + +A locale consists of multiple functional areas called ``locale +categories''. The locale category for message output is called +...@code{lc_messages}, the locale category for date and time formatting is +called @code{LC_TIME}, and so on. +(@pxref{Aspects, , Aspects in Native Language Support, gettext, +GNU gettext tools}). Message catalogs are usually used only with +the @code{LC_MESSAGES} locale category, but they can rarely also +be useful in other categories. This set of categories can be specified +through the _LOCALE_CATEGORIES variable. For example, GNU coreutils uses +its message catalogs for the @code{LC_MESSAGES} and @code{LC_TIME} +locale categories: + +...@smallexample +po_coreutils_pot_LOCALE_CATEGORIES = LC_MESSAGES LC_TIME +...@end smallexample + +This variable allows a coreutils program, when run in an environment +where the @code{LC_TIME} locale category is bound to a different locale +than the @code{LC_MESSAGE} locale category, to properly obey the +...@code{lc_time} setting. + +If not specified, this variable defaults to @code{LC_MESSAGES} only. + +...@node Other POT files details +...@section Other POT files details + +There are two more variables associated with a POT file. + +...@menu +* A POT file's _USE_MSGCTXT:: Declaring whether msgctxt is used +* A POT file's _MSGMERGE_OPTIONS:: Specifying options for msgmerge +...@end menu + +...@node A POT file's _USE_MSGCTXT +...@subsection A POT file's _USE_MSGCTXT + +...@smallexample +locale_POTS = po/maude.pot +po_maude_pot_USE_MSGCTXT = no +...@end smallexample + +This tells whether the POT file contains messages with an @code{msgctxt} +context. Possible values are ``yes'' and ``no''. Set this to yes if the +package uses functions taking also a message context, like the +...@code{pgettext} function, or if in _XGETTEXT_OPTIONS you define keywords +with a context argument. If set to yes, GNU gettext tools older than +gettext 0.15 will not be considered. The default is @code{yes}. + +...@node A POT file's _MSGMERGE_OPTIONS +...@subsection A POT file's _MSGMERGE_OPTIONS + +...@smallexample +locale_POTS = po/maude.pot +po_maude_pot_MSGMERGE_OPTIONS = +...@end smallexample + +These options get passed to @code{msgmerge}. +Useful options are in particular: + +...@table @code +...@item --previous +to keep previous msgids of translated messages, +...@item --quiet +to reduce the verbosity. +...@end table + +If this variable contains @code{--previous}, GNU gettext tools older than +gettext 0.16 will not be considered. The default is @code{--previous}. + + @node Other GNU Tools @chapter Other GNU Tools