From 43a1454038bf0d52dba9c99a797b3ae499fc1423 Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Fri, 30 Nov 2001 15:22:56 +0000 Subject: Regenerated. --- doc/gettext_12.html | 800 ++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 711 insertions(+), 89 deletions(-) (limited to 'doc/gettext_12.html') diff --git a/doc/gettext_12.html b/doc/gettext_12.html index e069839..79e900b 100644 --- a/doc/gettext_12.html +++ b/doc/gettext_12.html @@ -1,160 +1,782 @@ - + -GNU gettext utilities - 12 Concluding Remarks +GNU gettext utilities - 12 The Maintainer's View -Go to the first, previous, next, last section, table of contents. +Go to the first, previous, next, last section, table of contents.

-

12 Concluding Remarks

+

12 The Maintainer's View

-We would like to conclude this GNU gettext manual by presenting -an history of the Translation Project so far. We finally give -a few pointers for those who want to do further research or readings -about Native Language Support matters. +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 9 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. + +

+ + + +

12.1 Flat or Non-Flat Directory Structures

+ +

+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. + +

+

+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. +Also, GNU gettext's libintl sources consist of C sources, shell +scripts, sed scripts and complicated Makefile rules, which don't +fit well into an existing flat structure. For these reasons, we +recommend to use non-flat approach in this case as well. + +

+

+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. + +

+ + +

12.2 Prerequisite Works

+ +

+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. + +

+ + + +

+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. + +

+ + +

12.3 Invoking the gettextize Program

-Internationalization concerns and algorithms have been informally -and casually discussed for years in GNU, sometimes around GNU -libc, maybe around the incoming Hurd, or otherwise -(nobody clearly remembers). And even then, when the work started for -real, this was somewhat independently of these previous discussions. +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: + +

+
+ +
`-c´ +
+
`--copy´ +
+Copy the needed files instead of making symbolic links. Using links +would allow the package to always use the latest 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. + +
`-f´ +
+
`--force´ +
+Force replacement of files which already exist. + +
`--intl´ +
+Install the libintl sources in a subdirectory named `intl/´. +This libintl will be used to provide internationalization on systems +that don't have GNU libintl installed. If this option is omitted, +the call to AM_GNU_GETTEXT in `configure.in´ should read: +`AM_GNU_GETTEXT([external])´, and internationalization will not +be enabled on systems lacking GNU gettext. + +
`-h´ +
+
`--help´ +
+Display this help and exit. + +
`--version´ +
+Output version information and exit. + +
+

-This all began in July 1994, when Patrick D'Cruze had the idea and -initiative of internationalizing version 3.9.2 of GNU fileutils. -He then asked Jim Meyering, the maintainer, how to get those changes -folded into an official release. That first draft was full of -#ifdefs and somewhat disconcerting, and Jim wanted to find -nicer ways. Patrick and Jim shared some tries and experimentations -in this area. Then, feeling that this might eventually have a deeper -impact on GNU, Jim wanted to know what standards were, and contacted -Richard Stallman, who very quickly and verbally described an overall -design for what was meant to become glocale, at that time. +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.

-Jim implemented glocale and got a lot of exhausting feedback -from Patrick and Richard, of course, but also from Mitchum DSouza -(who wrote a catgets-like package), Roland McGrath, maybe David -MacKenzie, Fran@,{c}ois Pinard, and Paul Eggert, all pushing and -pulling in various directions, not always compatible, to the extent -that after a couple of test releases, glocale was torn apart. +The program gettextize provides the following files. However, +no existing file will be replaced unless the option --force +(-f) is specified.

+ +
    +
  1. + +The `ABOUT-NLS´ file is copied in the main directory of your package, +the one being at the top level. This file gives the main indications +about how to install and use the Native Language Support features +of your program. You might elect to use a more recent copy of this +`ABOUT-NLS´ file than the one provided through 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. + +
  2. + +A `po/´ directory is created for eventually holding +all translation files, but initially only containing the file +`po/Makefile.in.in´ from the GNU gettext distribution. +(beware the double `.in´ in the file name) and a few auxiliary +files. If the `po/´ directory already exists, it will be preserved +along with the files it contains, and only `Makefile.in.in´ and +the auxiliary files will be overwritten. + +
  3. + +Only of `--intl´ has been specified: +A `intl/´ directory is created and filled with most of the files +originally in the `intl/´ directory of the GNU gettext +distribution. Also, if option --force (-f) is given, +the `intl/´ directory is emptied first. + +
+

-While Jim took some distance and time and became dad for a second -time, Roland wanted to get GNU libc internationalized, and -got Ulrich Drepper involved in that project. Instead of starting -from glocale, Ulrich rewrote something from scratch, but -more conformant to the set of guidelines who emerged out of the -glocale effort. Then, Ulrich got people from the previous -forum to involve themselves into this new project, and the switch -from glocale to what was first named msgutils, renamed -nlsutils, and later gettext, became officially accepted -by Richard in May 1995 or so. +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´.

-Let's summarize by saying that Ulrich Drepper wrote GNU gettext -in April 1995. The first official release of the package, including -PO mode, occurred in July 1995, and was numbered 0.7. Other people -contributed to the effort by providing a discussion forum around -Ulrich, writing little pieces of code, or testing. These are quoted -in the THANKS file which comes with the GNU gettext -distribution. +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.

+ + +

12.4 Files You Must Create or Alter

+

-While this was being done, Fran@,{c}ois adapted half a dozen of -GNU packages to glocale first, then later to gettext, -putting them in pretest, so providing along the way an effective -user environment for fine tuning the evolving tools. He also took -the responsibility of organizing and coordinating the Translation -Project. After nearly a year of informal exchanges between people from -many countries, translator teams started to exist in May 1995, through -the creation and support by Patrick D'Cruze of twenty unmoderated -mailing lists for that many native languages, and two moderated -lists: one for reaching all teams at once, the other for reaching -all willing maintainers of internationalized free software 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.

-Fran@,{c}ois also wrote PO mode in June 1995 with the collaboration -of Greg McGary, as a kind of contribution to Ulrich's package. -He also gave a hand with the GNU gettext Texinfo manual. +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.11-pre2 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.

-

12.2 Related Readings

+ +

12.4.1 `POTFILES.in´ in `po/´

-Eugene H. Dorr (`dorre@well.com') maintains an interesting -bibliography on internationalization matters, called -Internationalization Reference List, which is available as: +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: + +

-ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt
+# 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/gettext.c
+src/msgfmt.c
+src/xgettext.c

-Michael Gschwind (`mike@vlsivie.tuwien.ac.at') maintains a -Frequently Asked Questions (FAQ) list, entitled Programming for -Internationalisation. This FAQ discusses writing programs which -can handle different language conventions, character sets, etc.; -and is applicable to all character set encodings, with particular -emphasis on ISO 8859-1. It is regularly published in Usenet -groups `comp.unix.questions', `comp.std.internat', -`comp.software.international', `comp.lang.c', -`comp.windows.x', `comp.std.c', `comp.answers' -and `news.answers'. The home location of this document is: +Hash-marked comments and white lines are ignored. All other lines +list those source files containing strings marked for translation +(see section 3.2 How Marks Appear in Sources), in a notation relative to the top level +of your whole distribution, rather than the location of the +`POTFILES.in´ file itself. + +

+ + +

12.4.2 `LINGUAS´ in `po/´

+ +

+The `po/´ directory should also receive a file named +`LINGUAS´. This file contains the list of available translations. +It is a whitespace separated list. Hash-marked comments and white lines +are ignored. Here is an example file: + +

-ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming
+# Set of available languages.
+de fr

-Patrick D'Cruze (`pdcruze@li.org') wrote a tutorial about NLS -matters, and Jochen Hein (`Hein@student.tu-clausthal.de') took -over the responsibility of maintaining it. It may be found as: +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 the `LINGUAS´ file, +but rather by using the LINGUAS environment variable +(see section 9.2 Magic for Installers). + +

+ + +

12.4.3 `Makefile´ pieces in `po/´

+ +

+The `po/´ directory also has a file named `Makevars´. +It can be left unmodified if your package has a single message domain +and, accordingly, a single `po/´ directory. Only packages which +have multiple `po/´ directories at different locations need to +adjust the three variables defined in `Makevars´. + +

+

+`po/Makevars´ gets inserted into the `po/Makefile´ when the +latter is created. At the same time, all files called `Rules-*´ in the +`po/´ directory get appended to the `po/Makefile´. They present +an opportunity to add rules for special PO files to the Makefile, without +needing to mess with `po/Makefile.in.in´. + +

+

+GNU gettext comes with a `Rules-quot´ file, containing rules for +building catalogs `en@quot.po´ and `en@boldquot.po´. The +effect of `en@quot.po´ is that people who set their LANGUAGE +environment variable to `en@quot´ will get messages with proper +looking symmetric Unicode quotation marks instead of abusing the ASCII +grave accent and the ASCII apostrophe for indicating quotations. To +enable this catalog, simply add en@quot to the `po/LINGUAS´ +file. The effect of `en@boldquot.po´ is that people who set +LANGUAGE to `en@boldquot´ will get not only proper quotation +marks, but also the quoted text will be shown in a bold font on terminals +and consoles. This catalog is useful only for command-line programs, not +GUI programs. To enable it, similarly add en@boldquot to the +`po/LINGUAS´ file. + +

+ + +

12.4.4 `configure.in´ at top level

+ +

+`configure.in´ or `configure.ac´ - this is the source from which +autoconf generates the `configure´ script. + +

+ +
    +
  1. Declare the package and version. + +This is done by a set of lines like these: + + +
    +PACKAGE=gettext
+VERSION=0.11-pre2
+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.11-pre2´ by its version numbers, exactly as they +should appear in the packaged tar file name of your distribution +(`gettext-0.11-pre2.tar.gz´, here). + +
  2. Check for internationalization support. + +Here is the main 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. + +If you have suppressed the `intl/´ subdirectory by calling +gettextize without `--intl´ option, this call should read + + +
    +AM_GNU_GETTEXT([external])
+
    + +
  3. Have output files created. + +The AC_OUTPUT directive, at the end of your `configure.in´ +file, needs to be modified in two ways: + 
    -ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/...
-     ...locale-tutorial-0.8.txt.gz
+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 have suppressed the `intl/´ subdirectory by calling +gettextize without `--intl´ option, then you don't need to +add intl/Makefile to the AC_OUTPUT line. + +
+ + + +

12.4.5 `config.guess´, `config.sub´ at top level

+ +

+If you don't have suppressed the `intl/´ subdirectory, +you need to add the GNU `config.guess´ and `config.sub´ files +to your distribution. They are needed because the `intl/´ directory +has platform dependent support for determining the locale's character +encoding and therefore needs to identify the platform. + +

+

+You can obtain the newest version of `config.guess´ and +`config.sub´ from `ftp://ftp.gnu.org/pub/gnu/config/´. +Less recent versions are also contained in the GNU automake and +GNU libtool packages. + +

-This site is mirrored in: +Normally, `config.guess´ and `config.sub´ are put at the +top level of a distribution. But it is also possible to put them in a +subdirectory, altogether with other configuration support files like +`install-sh´, `ltconfig´, `ltmain.sh´, +`mkinstalldirs´ or `missing´. All you need to do, other than +moving the files, is to add the following line to your +`configure.in´. + +

-ftp://ftp.ibp.fr/pub/linux/sunsite/
+AC_CONFIG_AUX_DIR([subdir])
+ + +

12.4.6 `aclocal.m4´ at top level

+ +

+If you do not have an `aclocal.m4´ file in your distribution, +the simplest is to concatenate the files `codeset.m4´, +`gettext.m4´, `glibc21.m4´, `iconv.m4´, `isc-posix.m4´, +`lcmessage.m4´, `progtest.m4´ from GNU gettext's +`m4/´ directory into a single file. If you have suppressed the +`intl/´ directory, only `gettext.m4´, `iconv.m4´, +`progtest.m4´ need to be concatenated. + +

+

+If you already have an `aclocal.m4´ file, then you will have +to merge the said macro files into your `aclocal.m4´. Note that if +you are upgrading from a previous release of GNU gettext, you +should most probably replace the macros (AM_GNU_GETTEXT, +etc.), 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. + +

+ + +

12.4.7 `acconfig.h´ at top level

+

-A French version of the same tutorial should be findable at: +Earlier GNU gettext releases required to put definitions for +ENABLE_NLS, HAVE_GETTEXT and HAVE_LC_MESSAGES, +HAVE_STPCPY, PACKAGE and VERSION into an +`acconfig.h´ file. This is not needed any more; you can remove +them from your `acconfig.h´ file unless your package uses them +independently from the `intl/´ directory. + +

+ + +

12.4.8 `Makefile.in´ at top level

+ +

+Here are a few modifications you need to make to your main, top-level +`Makefile.in´ file. + +

+ +
    +
  1. + +Add the following lines near the beginning of your `Makefile.in´, +so the `dist:´ goal will work properly (as explained further down): + + +
    +PACKAGE = @PACKAGE@
+VERSION = @VERSION@
+
    + +
  2. + +Add file `ABOUT-NLS´ to the DISTFILES definition, so the file gets +distributed. + +
  3. + +Wherever you process subdirectories in your `Makefile.in´, be sure +you also process dir subdirectories `intl´ and `po´. Special +rules in the `Makefiles´ take care for the case where no +internationalization is wanted. + +If you are using Makefiles, either generated by automake, or hand-written +so they carefully follow the GNU coding standards, the effected goals for +which the new subdirectories must be handled include `installdirs´, +`install´, `uninstall´, `clean´, `distclean´. + +Here is an example of a canonical order of processing. In this +example, we also define SUBDIRS in Makefile.in for it +to be further used in the `dist:´ goal. + + +
    +SUBDIRS = doc intl lib src @POSUB@
+
    + +Note that you must arrange for `make´ to descend into the +intl directory before descending into other directories containing +code which make use of the libintl.h header file. For this +reason, here we mention intl before lib and src. + +
  4. + +A delicate point is the `dist:´ goal, as both +`intl/Makefile´ and `po/Makefile´ will later assume that the +proper directory has been set up from the main `Makefile´. Here is +an example at what the `dist:´ goal might look like: + 
    -ftp://ftp.ibp.fr/pub/linux/french/docs/
+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)
    +
+ + + +

12.4.9 `Makefile.in´ in `src/´

+

-together with French translations of many Linux-related documents. +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´:

+ +
    +
  1. + +In view of the `dist:´ goal, you should have these lines near the +beginning of `src/Makefile.in´: + + +
    +PACKAGE = @PACKAGE@
+VERSION = @VERSION@
+
    + +
  2. + +If not done already, you should guarantee that top_srcdir +gets defined. This will serve for cpp include files. Just add +the line: + + +
    +top_srcdir = @top_srcdir@
+
    + +
  3. + +You might also want to define 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
+
    + +
  4. + +The main function of your program will normally call +bindtextdomain (see see section 3.1 Triggering gettext Operations), like this: + + +
    +bindtextdomain (PACKAGE, LOCALEDIR);
+
    + +To make LOCALEDIR known to the program, add the following lines to +Makefile.in: + + +
    +datadir = @datadir@
+localedir = $(datadir)/locale
+DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@
+
    + +Note that @datadir@ defaults to `$(prefix)/share´, thus +$(localedir) defaults to `$(prefix)/share/locale´. + +
  5. + +You should ensure that the final linking will use @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, the support library (say +`libsupport.a´) should be placed before @INTLLIBS@ and +@LIBS@ in the above example. So one has to write this: + + +
    +LIBS = ../lib/libsupport.a @INTLLIBS@ @LIBS@
+
    + +
  6. + +You should also ensure that directory `intl/´ will be searched for +C preprocessor include files in all circumstances. So, you have to +manage so both `-I../intl´ and `-I$(top_srcdir)/intl´ will +be given to the C compiler. + +
  7. + +Your `dist:´ goal has to conform with others. Here is a +reasonable definition for it: + + +
    +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. +Go to the first, previous, next, last section, table of contents. -- cgit v1.1