Go to the first, previous, next, last section, table of contents. +
+ + +
+The maintainer of a package has many responsibilities. One of them +is ensuring that the package will install easily on many platforms, +and that the magic we described earlier (see section The User's View) will work +for installers and end users. + +
+
+Of course, there are many possible ways by which GNU gettext
+might be integrated in a distribution, and this chapter does not cover
+them in all generality. Instead, it details one possible approach which
+is especially adequate for many free software distributions following GNU
+standards, or even better, Gnits standards, because GNU gettext
+is purposely for helping the internationalization of the whole GNU
+project, and as many other good free packages as possible. So, the
+maintainer's view presented here presumes that the package already has
+a `configure.in' file and uses GNU Autoconf.
+
+
+Nevertheless, GNU gettext may surely be useful for free packages
+not following GNU standards and conventions, but the maintainers of such
+packages might have to show imagination and initiative in organizing
+their distributions so gettext work for them in all situations.
+There are surely many, out there.
+
+
+Even if gettext methods are now stabilizing, slight adjustments
+might be needed between successive gettext versions, so you
+should ideally revise this chapter in subsequent releases, looking
+for changes.
+
+
+Some free software packages are distributed as tar files which unpack
+in a single directory, these are said to be flat distributions.
+Other free software packages have a one level hierarchy of subdirectories, using
+for example a subdirectory named `doc/' for the Texinfo manual and
+man pages, another called `lib/' for holding functions meant to
+replace or complement C libraries, and a subdirectory `src/' for
+holding the proper sources for the package. These other distributions
+are said to be non-flat.
+
+
+For now, we cannot say much about flat distributions. A flat
+directory structure has the disadvantage of increasing the difficulty
+of updating to a new version of GNU gettext. Also, if you have
+many PO files, this could somewhat pollute your single directory.
+In the GNU gettext distribution, the `misc/' directory
+contains a shell script named `combine-sh'. That script may
+be used for combining all the C files of the `intl/' directory
+into a pair of C files (one `.c' and one `.h'). Those two
+generated files would fit more easily in a flat directory structure,
+and you will then have to add these two files to your project.
+
+
+Maybe because GNU gettext itself has a non-flat structure,
+we have more experience with this approach, and this is what will be
+described in the remaining of this chapter. Some maintainers might
+use this as an opportunity to unflatten their package structure.
+Only later, once gained more experience adapting GNU gettext
+to flat distributions, we might add some notes about how to proceed
+in flat situations.
+
+
+There are some works which are required for using GNU gettext
+in one of your package. These works have some kind of generality
+that escape the point by point descriptions used in the remainder
+of this chapter. So, we describe them here.
+
+
m4, GNU Autoconf and GNU
+gettext are already installed at your site, and if not, proceed
+to do this first. If you got to install these things, beware that
+GNU m4 must be fully installed before GNU Autoconf is even
+configured.
+
+To further ease the task of a package maintainer the automake
+package was designed and implemented. GNU gettext now uses this
+tool and the `Makefile's in the `intl/' and `po/'
+therefore know about all the goals necessary for using automake
+and `libintl' in one project.
+
+Those four packages are only needed to you, as a maintainer; the
+installers of your own package and end users do not really need any of
+GNU m4, GNU Autoconf, GNU gettext, or GNU automake
+for successfully installing and running your package, with messages
+properly translated. But this is not completely true if you provide
+internationalized shell scripts within your own package: GNU
+gettext shall then be installed at the user site if the end users
+want to see the translation of shell script messages.
+
++It is worth adding here a few words about how the maintainer should +ideally behave with PO files submissions. As a maintainer, your role is +to authentify the origin of the submission as being the representative +of the appropriate translating teams of the Translation Project (forward +the submission to `translation@iro.umontreal.ca' in case of doubt), +to ensure that the PO file format is not severely broken and does not +prevent successful installation, and for the rest, to merely to put these +PO files in `po/' for distribution. + +
++As a maintainer, you do not have to take on your shoulders the +responsibility of checking if the translations are adequate or +complete, and should avoid diving into linguistic matters. Translation +teams drive themselves and are fully responsible of their linguistic +choices for the Translation Project. Keep in mind that translator teams are not +driven by maintainers. You can help by carefully redirecting all +communications and reports from users about linguistic matters to the +appropriate translation team, or explain users how to reach or join +their team. The simplest might be to send them the `ABOUT-NLS' file. + +
++Maintainers should never ever apply PO file bug reports +themselves, short-cutting translation teams. If some translator has +difficulty to get some of her points through her team, it should not be +an issue for her to directly negotiate translations with maintainers. +Teams ought to settle their problems themselves, if any. If you, as +a maintainer, ever think there is a real problem with a team, please +never try to solve a team's problem on your own. + +
+ + +gettextize Program
+Some files are consistently and identically needed in every package
+internationalized through GNU gettext. As a matter of
+convenience, the gettextize program puts all these files right
+in your package. This program has the following synopsis:
+
+
+gettextize [ option... ] [ directory ] ++ +
+and accepts the following options: + +
+gettext code
+available on the system, but it might disturb some mechanism the
+maintainer is used to apply to the sources. Because running
+gettextize is easy there shouldn't be problems with using copies.
+
+
+If directory is given, this is the top level directory of a
+package to prepare for using GNU gettext. If not given, it
+is assumed that the current directory is the top level directory of
+such a package.
+
+
+The program gettextize provides the following files. However,
+no existing file will be replaced unless the option --force
+(-f) is specified.
+
+
gettextize,
+if you have one handy. You may also fetch a more recent copy of file
+`ABOUT-NLS' from Translation Project sites, and from most GNU
+archive sites.
+
+gettext distribution.
+(beware the double `.in' in the file name). If the `po/'
+directory already exists, it will be preserved along with the files
+it contains, and only `Makefile.in.in' will be overwritten.
+
+gettext
+distribution. Also, if option --force (-f) is given,
+the `intl/' directory is emptied first.
+
+
+If your site support symbolic links, gettextize will not
+actually copy the files into your package, but establish symbolic
+links instead. This avoids duplicating the disk space needed in
+all packages. Merely using the `-h' option while creating the
+tar archive of your distribution will resolve each link by an
+actual copy in the distribution archive. So, to insist, you really
+should use `-h' option with tar within your dist
+goal of your main `Makefile.in'.
+
+
+It is interesting to understand that most new files for supporting
+GNU gettext facilities in one package go in `intl/'
+and `po/' subdirectories. One distinction between these two
+directories is that `intl/' is meant to be completely identical
+in all packages using GNU gettext, while all newly created
+files, which have to be different, go into `po/'. There is a
+common `Makefile.in.in' in `po/', because the `po/'
+directory needs its own `Makefile', and it has been designed so
+it can be identical in all packages.
+
+
+Besides files which are automatically added through gettextize,
+there are many files needing revision for properly interacting with
+GNU gettext. If you are closely following GNU standards for
+Makefile engineering and auto-configuration, the adaptations should
+be easier to achieve. Here is a point by point description of the
+changes needed in each.
+
+
+So, here comes a list of files, each one followed by a description of
+all alterations it needs. Many examples are taken out from the GNU
+gettext 0.10.35 distribution itself. You may indeed
+refer to the source code of the GNU gettext package, as it
+is intended to be a good example and master implementation for using
+its own functionality.
+
+
+The `po/' directory should receive a file named +`POTFILES.in'. This file tells which files, among all program +sources, have marked strings needing translation. Here is an example +of such a file: + +
+ ++# List of source files containing translatable strings. +# Copyright (C) 1995 Free Software Foundation, Inc. + +# Common library files +lib/error.c +lib/getopt.c +lib/xmalloc.c + +# Package source files +src/gettextp.c +src/msgfmt.c +src/xgettext.c ++ +
+Dashed comments and white lines are ignored. All other lines +list those source files containing strings marked for translation +(see section How Marks Appears in Sources), in a notation relative to the top level +of your whole distribution, rather than the location of the +`POTFILES.in' file itself. + +
+ + ++PACKAGE=gettext +VERSION=0.10.35 +AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE") +AC_DEFINE_UNQUOTED(VERSION, "$VERSION") +AC_SUBST(PACKAGE) +AC_SUBST(VERSION) ++ +Of course, you replace `gettext' with the name of your package, +and `0.10.35' by its version numbers, exactly as they +should appear in the packaged
tar file name of your distribution
+(`gettext-0.10.35.tar.gz', here).
+
+ALL_LINGUAS to the white separated,
+quoted list of available languages, in a single line, like this:
+
+
++ALL_LINGUAS="de fr" ++ +This example means that German and French PO files are available, so +that these languages are currently supported by your package. If you +want to further restrict, at installation time, the set of installed +languages, this should not be done by modifying
ALL_LINGUAS in
+`configure.in', but rather by using the LINGUAS environment
+variable (see section Magic for Installers).
+
+m4 macro for triggering internationalization
+support. Just add this line to `configure.in':
+
+
++AM_GNU_GETTEXT ++ +This call is purposely simple, even if it generates a lot of configure +time checking and actions. + +
AC_OUTPUT directive, at the end of your `configure.in'
+file, needs to be modified in two ways:
+
+
++AC_OUTPUT([existing configuration files intl/Makefile po/Makefile.in], +existing additional actions]) ++ +The modification to the first argument to
AC_OUTPUT asks
+for substitution in the `intl/' and `po/' directories.
+Note the `.in' suffix used for `po/' only. This is because
+the distributed file is really `po/Makefile.in.in'.
+
+
+If you do not have an `aclocal.m4' file in your distribution,
+the simplest is taking a copy of `aclocal.m4' from
+GNU gettext. But to be precise, you only need macros
+AM_LC_MESSAGES, AM_WITH_NLS and AM_GNU_GETTEXT,
+and AM_PATH_PROG_WITH_TEST, which is called by AM_WITH_NLS,
+so you may use an editor and remove macros you do not need.
+
+
+If you already have an `aclocal.m4' file, then you will have
+to merge the said macros into your `aclocal.m4'. Note that if
+you are upgrading from a previous release of GNU gettext, you
+should most probably replace the said macros, as they usually
+change a little from one release of GNU gettext to the next.
+Their contents may vary as we get more experience with strange systems
+out there.
+
+
+These macros check for the internationalization support functions
+and related informations. Hopefully, once stabilized, these macros
+might be integrated in the standard Autoconf set, because this
+piece of m4 code will be the same for all projects using GNU
+gettext.
+
+
+If you do not have an `acconfig.h' file in your distribution, the
+simplest is use take a copy of `acconfig.h' from GNU
+gettext. But to be precise, you only need the lines and comments
+for ENABLE_NLS, HAVE_CATGETS, HAVE_GETTEXT and
+HAVE_LC_MESSAGES, HAVE_STPCPY, PACKAGE and
+VERSION, so you may use an editor and remove everything else. If
+you already have an `acconfig.h' file, then you should merge the
+said definitions into your `acconfig.h'.
+
+
+Here are a few modifications you need to make to your main, top-level +`Makefile.in' file. + +
+ ++PACKAGE = @PACKAGE@ +VERSION = @VERSION@ ++ +
DISTFILES definition, so the file gets
+distributed.
+
+SUBDIRS in Makefile.in for it
+to be further used in the `dist:' goal.
+
+
++SUBDIRS = doc lib @INTLSUB@ src @POSUB@ ++ +that you will have to adapt to your own package. + +
+distdir = $(PACKAGE)-$(VERSION) +dist: Makefile + rm -fr $(distdir) + mkdir $(distdir) + chmod 777 $(distdir) + for file in $(DISTFILES); do \ + ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \ + done + for subdir in $(SUBDIRS); do \ + mkdir $(distdir)/$$subdir || exit 1; \ + chmod 777 $(distdir)/$$subdir; \ + (cd $$subdir && $(MAKE) $@) || exit 1; \ + done + tar chozf $(distdir).tar.gz $(distdir) + rm -fr $(distdir) ++ +
+Some of the modifications made in the main `Makefile.in' will +also be needed in the `Makefile.in' from your package sources, +which we assume here to be in the `src/' subdirectory. Here are +all the modifications needed in `src/Makefile.in': + +
+ ++PACKAGE = @PACKAGE@ +VERSION = @VERSION@ ++ +
top_srcdir
+gets defined. This will serve for cpp include files. Just add
+the line:
+
+
++top_srcdir = @top_srcdir@ ++ +
subdir as `src', later
+allowing for almost uniform `dist:' goals in all your
+`Makefile.in'. At list, the `dist:' goal below assume that
+you used:
+
+
++subdir = src ++ +
@INTLLIBS@ as
+a library. An easy way to achieve this is to manage that it gets into
+LIBS, like this:
+
+
++LIBS = @INTLLIBS@ @LIBS@ ++ +In most packages internationalized with GNU
gettext, one will
+find a directory `lib/' in which a library containing some helper
+functions will be build. (You need at least the few functions which the
+GNU gettext Library itself needs.) However some of the functions
+in the `lib/' also give messages to the user which of course should be
+translated, too. Taking care of this it is not enough to place the support
+library (say `libsupport.a') just between the @INTLLIBS@
+and @LIBS@ in the above example. Instead one has to write this:
+
+
++LIBS = ../lib/libsupport.a @INTLLIBS@ ../lib/libsupport.a @LIBS@ ++ +
+distdir = ../$(PACKAGE)-$(VERSION)/$(subdir) +dist: Makefile $(DISTFILES) + for file in $(DISTFILES); do \ + ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \ + done ++ +
+
Go to the first, previous, next, last section, table of contents. + +