path: root/doc/gettext.info-5

This is Info file gettext.info, produced by Makeinfo version 1.68 from
the input file gettext.texi.

INFO-DIR-SECTION GNU Gettext Utilities
START-INFO-DIR-ENTRY
* Gettext: (gettext).                           GNU gettext utilities.
* gettextize: (gettext)gettextize Invocation.   Prepare a package for gettext.
* msgfmt: (gettext)msgfmt Invocation.           Make MO files out of PO files.
* msgmerge: (gettext)msgmerge Invocation.       Update two PO files into one.
* xgettext: (gettext)xgettext Invocation.       Extract strings into a PO file.
END-INFO-DIR-ENTRY

   This file provides documentation for GNU `gettext' utilities.  It
also serves as a reference for the free Translation Project.

   Copyright (C) 1995, 1996, 1997, 1998 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.


File: gettext.info,  Node: Adjusting Files,  Prev: gettextize Invocation,  Up: Maintainers

Files You Must Create or Alter
==============================

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

* Menu:

* po/POTFILES.in::              `POTFILES.in' in `po/'
* configure.in::                `configure.in' at top level
* aclocal::                     `aclocal.m4' at top level
* acconfig::                    `acconfig.h' at top level
* Makefile::                    `Makefile.in' at top level
* src/Makefile::                `Makefile.in' in `src/'


File: gettext.info,  Node: po/POTFILES.in,  Next: configure.in,  Prev: Adjusting Files,  Up: Adjusting Files

`POTFILES.in' in `po/'
----------------------

   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 (*note
Mark Keywords::.), in a notation relative to the top level of your
whole distribution, rather than the location of the `POTFILES.in' file
itself.


File: gettext.info,  Node: configure.in,  Next: aclocal,  Prev: po/POTFILES.in,  Up: Adjusting Files

`configure.in' at top level
---------------------------

  1. Declare the package and version.

     This is done by a set of lines like these:

          PACKAGE=gettext
          VERSION=0.10.36
          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.36' by its version numbers, exactly as they should
     appear in the packaged `tar' file name of your distribution
     (`gettext-0.10.36.tar.gz', here).

  2. Declare the available translations.

     This is done by defining `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 (*note Installers::.).

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

  4. Have output files created.

     The `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'.



File: gettext.info,  Node: aclocal,  Next: acconfig,  Prev: configure.in,  Up: Adjusting Files

`aclocal.m4' at top level
-------------------------

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


File: gettext.info,  Node: acconfig,  Next: Makefile,  Prev: aclocal,  Up: Adjusting Files

`acconfig.h' at top level
-------------------------

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


File: gettext.info,  Node: Makefile,  Next: src/Makefile,  Prev: acconfig,  Up: Adjusting Files

`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 lib @INTLSUB@ src @POSUB@

     that you will have to adapt to your own package.

  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:

          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)



File: gettext.info,  Node: src/Makefile,  Prev: Makefile,  Up: Adjusting Files

`Makefile.in' in `src/'
-----------------------

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

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

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



File: gettext.info,  Node: Conclusion,  Next: Country Codes,  Prev: Maintainers,  Up: Top

Concluding Remarks
******************

   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.

* Menu:

* History::                     History of GNU `gettext'
* References::                  Related Readings


File: gettext.info,  Node: History,  Next: References,  Prev: Conclusion,  Up: Conclusion

History of GNU `gettext'
========================

   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.

   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
`#ifdef's 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.

   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,
Franc,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.

   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.

   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.

   While this was being done, Franc,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.

   Franc,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.


File: gettext.info,  Node: References,  Prev: History,  Up: Conclusion

Related Readings
================

   Eugene H. Dorr (`dorre@well.com') maintains an interesting
bibliography on internationalization matters, called
`Internationalization Reference List', which is available as:
     ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt

   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:
     ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming

   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:
     ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/...
          ...locale-tutorial-0.8.txt.gz

This site is mirrored in:
     ftp://ftp.ibp.fr/pub/linux/sunsite/

   A French version of the same tutorial should be findable at:
     ftp://ftp.ibp.fr/pub/linux/french/docs/

together with French translations of many Linux-related documents.


File: gettext.info,  Node: Country Codes,  Prev: Conclusion,  Up: Top

Country Codes
*************

   The ISO 639 standard defines two character codes for many countries.
All abreviations for countries or languages used in the Translation
Project should come from this standard.

`aa'
     Afar.

`ab'
     Abkhazian.

`af'
     Afrikaans.

`am'
     Amharic.

`ar'
     Arabic.

`as'
     Assamese.

`ay'
     Aymara.

`az'
     Azerbaijani.

`ba'
     Bashkir.

`be'
     Byelorussian.

`bg'
     Bulgarian.

`bh'
     Bihari.

`bi'
     Bislama.

`bn'
     Bengali; Bangla.

`bo'
     Tibetan.

`br'
     Breton.

`ca'
     Catalan.

`co'
     Corsican.

`cs'
     Czech.

`cy'
     Welsh.

`da'
     Danish.

`de'
     German.

`dz'
     Bhutani.

`el'
     Greek.

`en'
     English.

`eo'
     Esperanto.

`es'
     Spanish.

`et'
     Estonian.

`eu'
     Basque.

`fa'
     Persian.

`fi'
     Finnish.

`fj'
     Fiji.

`fo'
     Faroese.

`fr'
     French.

`fy'
     Frisian.

`ga'
     Irish.

`gd'
     Scots Gaelic.

`gl'
     Galician.

`gn'
     Guarani.

`gu'
     Gujarati.

`ha'
     Hausa.

`he'
     Hebrew (formerly iw).

`hi'
     Hindi.

`hr'
     Croatian.

`hu'
     Hungarian.

`hy'
     Armenian.

`ia'
     Interlingua.

`id'
     Indonesian (formerly in).

`ie'
     Interlingue.

`ik'
     Inupiak.

`is'
     Icelandic.

`it'
     Italian.

`iu'
     Inuktitut.

`ja'
     Japanese.

`jw'
     Javanese.

`ka'
     Georgian.

`kk'
     Kazakh.

`kl'
     Greenlandic.

`km'
     Cambodian.

`kn'
     Kannada.

`ko'
     Korean.

`ks'
     Kashmiri.

`ku'
     Kurdish.

`ky'
     Kirghiz.

`la'
     Latin.

`ln'
     Lingala.

`lo'
     Laothian.

`lt'
     Lithuanian.

`lv'
     Latvian, Lettish.

`mg'
     Malagasy.

`mi'
     Maori.

`mk'
     Macedonian.

`ml'
     Malayalam.

`mn'
     Mongolian.

`mo'
     Moldavian.

`mr'
     Marathi.

`ms'
     Malay.

`mt'
     Maltese.

`my'
     Burmese.

`na'
     Nauru.

`ne'
     Nepali.

`nl'
     Dutch.

`no'
     Norwegian.

`oc'
     Occitan.

`om'
     (Afan) Oromo.

`or'
     Oriya.

`pa'
     Punjabi.

`pl'
     Polish.

`ps'
     Pashto, Pushto.

`pt'
     Portuguese.

`qu'
     Quechua.

`rm'
     Rhaeto-Romance.

`rn'
     Kirundi.

`ro'
     Romanian.

`ru'
     Russian.

`rw'
     Kinyarwanda.

`sa'
     Sanskrit.

`sd'
     Sindhi.

`sg'
     Sangro.

`sh'
     Serbo-Croatian.

`si'
     Sinhalese.

`sk'
     Slovak.

`sl'
     Slovenian.

`sm'
     Samoan.

`sn'
     Shona.

`so'
     Somali.

`sq'
     Albanian.

`sr'
     Serbian.

`ss'
     Siswati.

`st'
     Sesotho.

`su'
     Sundanese.

`sv'
     Swedish.

`sw'
     Swahili.

`ta'
     Tamil.

`te'
     Telugu.

`tg'
     Tajik.

`th'
     Thai.

`ti'
     Tigrinya.

`tk'
     Turkmen.

`tl'
     Tagalog.

`tn'
     Setswana.

`to'
     Tonga.

`tr'
     Turkish.

`ts'
     Tsonga.

`tt'
     Tatar.

`tw'
     Twi.

`ug'
     Uighur.

`uk'
     Ukrainian.

`ur'
     Urdu.

`uz'
     Uzbek.

`vi'
     Vietnamese.

`vo'
     Volapuk.

`wo'
     Wolof.

`xh'
     Xhosa.

`yi'
     Yiddish (formerly ji).

`yo'
     Yoruba.

`za'
     Zhuang.

`zh'
     Chinese.

`zu'
     Zulu.