From: Bruno Haible Date: Sun, 29 Aug 2010 15:52:27 +0000 (+0200) Subject: Internationalization documentation fixes. * doc/automake.texi (Uniform, International... X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8567e63255c7867d65754cf0e6e9f2361a4c2d93;p=thirdparty%2Fautomake.git Internationalization documentation fixes. * doc/automake.texi (Uniform, Internationalization): Add some more index entries. Reported by Ralf Wildenhues. --- diff --git a/ChangeLog b/ChangeLog index 47ec0f0a3..2623beaba 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2010-08-29 Bruno Haible + + Internationalization documentation fixes. + * doc/automake.texi (Uniform, Internationalization): Add some more + index entries. + Reported by Ralf Wildenhues. + 2010-08-29 Bruno Haible Internationalization documentation fixes. diff --git a/doc/automake.texi b/doc/automake.texi index 37fc89397..c9990d034 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -2056,6 +2056,7 @@ The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES}, @vindex SCRIPTS @vindex DATA @vindex HEADERS +@vindex POTS @vindex MANS @vindex TEXINFOS @@ -7406,6 +7407,9 @@ is converting @file{.h} files into @file{.c} files. @node Internationalization @chapter Internationalization +@cindex Internationalization +@cindex Native Language Support +@cindex Globalization An internationalized program is a program that can communicate with the user in his/her native language, provided that some translation work has been done. An internationalized program can be localized to a certain @@ -7413,6 +7417,7 @@ language by translating the messages by which the program communicates with the user. These message are grouped in files called ``message catalogs''. +@cindex Localization The process of localization consists of three steps: @enumerate @@ -7426,6 +7431,10 @@ The translators send back the translated message catalogs, and the developers integrate them in the package. @end enumerate +@cindex message catalogs +@cindex POT file +@cindex PO file +@cindex gettext Automake supports the message catalog format of GNU Gettext (@pxref{Top, , Introduction, gettext, GNU gettext tools}). When the GNU Gettext tools are in use: @@ -7438,6 +7447,7 @@ called a POT file (Portable Object Template) and usually named translation domain. Different packages must use different @var{domain}s. Therefore the @var{domain} is usually the same as the package name. +@cindex message catalogs, naming @item The file that contains the translation produced by a translation team is called a PO file (Portable Object) and usually named @@ -7461,10 +7471,13 @@ different from @code{pt} (Portuguese). @node POT Files @section POT Files +@vindex POTS +@vindex _POTS In Automake, a message catalog template (POT file) is declared through the @samp{POTS} primary. The Makefile rules generated by Automake also handle all the PO files that belong to the POT file. +@cindex message catalogs, compiled For execution, the PO files get compiled to ``compiled message catalogs''. These a usually @file{.mo} files (MO = Machine Object). They get installed in an appropriate subdirectory of @code{$(localedir)}. @@ -7488,6 +7501,8 @@ When you use the @code{POTS} primary, you need to invoke @node Parameterizing xgettext @section Parameterizing xgettext +@cindex POT file, creating +@cindex xgettext, options for The POT file gets created through an invocation of the @code{xgettext} program (@pxref{xgettext Invocation, , xgettext, gettext, GNU gettext tools}). @@ -7503,6 +7518,8 @@ program @node A POT file's _SOURCES @subsection A POT file's _SOURCES +@vindex SOURCES +@vindex _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 @@ -7536,6 +7553,10 @@ it is recommended to list in _SOURCES the real source file (ending in @node A POT file's _COPYRIGHT_HOLDER @subsection A POT file's _COPYRIGHT_HOLDER +@vindex COPYRIGHT_HOLDER +@vindex _COPYRIGHT_HOLDER +@cindex message catalogs, copyright +@cindex copyright, of message catalogs 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: @@ -7557,6 +7578,9 @@ expected to disclaim their copyright. @node A POT file's _MSGID_BUGS_ADDRESS @subsection A POT file's _MSGID_BUGS_ADDRESS +@vindex MSGID_BUGS_ADDRESS +@vindex _MSGID_BUGS_ADDRESS +@cindex POT file, bug reporting 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: @@ -7601,6 +7625,8 @@ The Autoconf Manual}. @node Additional xgettext options @subsection Additional @code{xgettext} options +@vindex XGETTEXT_OPTIONS +@vindex _XGETTEXT_OPTIONS Additional command-line options for the @code{xgettext} invocation can be specified through the _XGETTEXT_OPTIONS variable. For example: @@ -7655,6 +7681,9 @@ maude2_pot_SOURCES = maude.lisp @node Message catalog translations @section Message catalog translations +@vindex LINGUAS +@vindex _LINGUAS +@cindex message catalogs, list 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 @@ -7671,6 +7700,7 @@ po_maude_pot_LINGUAS = de fr de_AT nl This variable should contain the list of languages for which a translation is present, using the notation @var{ll} or @var{ll}_@var{CC}. +@cindex message catalogs, download 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 @@ -7685,6 +7715,10 @@ No translations can be installed if the GNU gettext tools are not installed on the build machine. @end itemize +@vindex TP_URL +@vindex _TP_URL +@vindex TP_RSYNC_URI +@vindex _TP_RSYNC_URI To enable this mechanism, specify a _TP_URL variable or a _TP_RSYNC_URI variable, or both. Example: @@ -7699,6 +7733,7 @@ Currently, only the Translation Project is supported in this way. @node Message catalog installation @section Message catalog installation +@cindex message catalogs, 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), @@ -7712,6 +7747,9 @@ you specify the POT file in the @code{noinst_POTS} variable. @node A POT file's _CATALOGFORMAT @subsection A POT file's _CATALOGFORMAT +@vindex CATALOGFORMAT +@vindex _CATALOGFORMAT +@cindex message catalogs, compiled 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 @@ -7748,6 +7786,9 @@ 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 +@vindex LOCALE_CATEGORIES +@vindex _LOCALE_CATEGORIES +@cindex 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 @@ -7784,6 +7825,8 @@ There are two more variables associated with a POT file. @node A POT file's _USE_MSGCTXT @subsection A POT file's _USE_MSGCTXT +@vindex USE_MSGCTXT +@vindex _USE_MSGCTXT @smallexample locale_POTS = po/maude.pot po_maude_pot_USE_MSGCTXT = no @@ -7799,6 +7842,9 @@ 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 +@vindex MSGMERGE_OPTIONS +@vindex _MSGMERGE_OPTIONS +@cindex msgmerge, options for @smallexample locale_POTS = po/maude.pot po_maude_pot_MSGMERGE_OPTIONS =