diff options
Diffstat (limited to 'doc/gettext.info-5')
| -rw-r--r-- | doc/gettext.info-5 | 852 |
1 files changed, 852 insertions, 0 deletions
diff --git a/doc/gettext.info-5 b/doc/gettext.info-5 new file mode 100644 index 0000000..0279fa5 --- /dev/null +++ b/doc/gettext.info-5 @@ -0,0 +1,852 @@ +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. + + |