diff options
author | Bruno Haible <bruno@clisp.org> | 2001-02-01 19:26:04 +0000 |
---|---|---|
committer | Bruno Haible <bruno@clisp.org> | 2001-02-01 19:26:04 +0000 |
commit | 8936f71457d79963c01150e941648794d47bebba (patch) | |
tree | fbb3d2e351f2fc8c09c4e0d33dd90a4746e72cc0 /doc | |
parent | 0d1adb1a92f4f6bd88db7a5113210935ec8bdafa (diff) | |
download | external_gettext-8936f71457d79963c01150e941648794d47bebba.zip external_gettext-8936f71457d79963c01150e941648794d47bebba.tar.gz external_gettext-8936f71457d79963c01150e941648794d47bebba.tar.bz2 |
Regenerated.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile.in | 12 | ||||
-rw-r--r-- | doc/gettext.info | 191 | ||||
-rw-r--r-- | doc/gettext.info-1 | 116 | ||||
-rw-r--r-- | doc/gettext.info-2 | 68 | ||||
-rw-r--r-- | doc/gettext.info-3 | 108 | ||||
-rw-r--r-- | doc/gettext.info-4 | 895 | ||||
-rw-r--r-- | doc/gettext.info-5 | 337 | ||||
-rw-r--r-- | doc/version.texi | 2 |
8 files changed, 1066 insertions, 663 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in index 6e70e6d..9e161ab 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -61,27 +61,22 @@ host_alias = @host_alias@ host_triplet = @host@ ACLOCAL_VERSION = @ACLOCAL_VERSION@ AS = @AS@ +BUILD_INCLUDED_LIBINTL = @BUILD_INCLUDED_LIBINTL@ CATALOGS = @CATALOGS@ CATOBJEXT = @CATOBJEXT@ CC = @CC@ DATADIRNAME = @DATADIRNAME@ DLLTOOL = @DLLTOOL@ EMACS = @EMACS@ -GENCAT = @GENCAT@ GMOFILES = @GMOFILES@ GMSGFMT = @GMSGFMT@ -GT_NO = @GT_NO@ -GT_YES = @GT_YES@ -INCLUDE_LOCALE_H = @INCLUDE_LOCALE_H@ -INSTOBJEXT = @INSTOBJEXT@ -INTLDEPS = @INTLDEPS@ INTLLIBS = @INTLLIBS@ INTLOBJS = @INTLOBJS@ +INTL_LIBTOOL_SUFFIX_PREFIX = @INTL_LIBTOOL_SUFFIX_PREFIX@ LIBICONV = @LIBICONV@ LIBOBJS = @LIBOBJS@ LIBTOOL = @LIBTOOL@ LN_S = @LN_S@ -MAKEINFO = @MAKEINFO@ MKINSTALLDIRS = @MKINSTALLDIRS@ MSGFMT = @MSGFMT@ OBJDUMP = @OBJDUMP@ @@ -94,13 +89,14 @@ USE_NLS = @USE_NLS@ VERSION = @VERSION@ YACC = @YACC@ aclocaldir = @aclocaldir@ -l = @l@ lispdir = @lispdir@ AUTOMAKE_OPTIONS = 1.2 gnits SED = sed +MAKEINFO = LANG= LANGUAGE= @MAKEINFO@ + info_TEXINFOS = gettext.texi gettext_TEXINFOS = iso-apdx.texi diff --git a/doc/gettext.info b/doc/gettext.info index 51af348..b941c63 100644 --- a/doc/gettext.info +++ b/doc/gettext.info @@ -1,5 +1,5 @@ -This is Info file gettext.info, produced by Makeinfo version 1.68 from -the input file gettext.texi. +This is gettext.info, produced by makeinfo version 4.0 from +gettext.texi. INFO-DIR-SECTION GNU Gettext Utilities START-INFO-DIR-ENTRY @@ -13,7 +13,8 @@ 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. + Copyright (C) 1995, 1996, 1997, 1998, 2001 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 @@ -31,96 +32,104 @@ translation approved by the Foundation. Indirect: -gettext.info-1: 1431 -gettext.info-2: 48351 -gettext.info-3: 95765 -gettext.info-4: 145601 -gettext.info-5: 195230 +gettext.info-1: 1411 +gettext.info-2: 49199 +gettext.info-3: 97209 +gettext.info-4: 146607 +gettext.info-5: 196054 Tag Table: (Indirect) -Node: Top1431 -Node: Introduction6625 -Node: Why8481 -Node: Concepts11727 -Node: Aspects15140 -Node: Files21196 -Node: Overview23464 -Node: Basics34088 -Node: Installation34918 -Node: PO Files36652 -Node: Main PO Commands43407 -Node: Entry Positioning48351 -Node: Normalizing53603 -Node: Sources58055 -Node: Triggering59326 -Node: Mark Keywords61682 -Node: Marking65232 -Node: c-format72873 -Node: Special cases76624 -Node: Initial79487 -Node: xgettext Invocation79809 -Node: C Sources Context83036 -Node: Compendium88015 -Node: Updating88718 -Node: msgmerge Invocation89358 -Node: Translated Entries89532 -Node: Fuzzy Entries90824 -Node: Untranslated Entries93926 -Node: Obsolete Entries95765 -Node: Modifying Translations98897 -Node: Modifying Comments106715 -Node: Subedit111022 -Node: Auxiliary114800 -Node: Binaries117870 -Node: msgfmt Invocation118134 -Node: MO Files120761 -Node: Users128173 -Node: Matrix129654 -Node: Installers130857 -Node: End Users132045 -Node: Programmers132674 -Node: catgets133848 -Node: Interface to catgets135253 -Node: Problems with catgets137254 -Node: gettext138152 -Node: Interface to gettext139393 -Node: Ambiguities141735 -Node: Locating Catalogs144292 -Node: Optimized gettext145601 -Node: Comparison149189 -Node: Using libintl.a154904 -Node: gettext grok155675 -Node: Temp Programmers158534 -Node: Temp Implementations158974 -Node: Temp catgets160340 -Node: Temp WSI162027 -Node: Temp Notes164015 -Node: Translators164504 -Node: Trans Intro 0164883 -Node: Trans Intro 1167532 -Node: Discussions169396 -Node: Organization172551 -Node: Central Coordination174532 -Node: National Teams175660 -Node: Sub-Cultures178172 -Node: Organizational Ideas179091 -Node: Mailing Lists180093 -Node: Information Flow181896 -Node: Maintainers184029 -Node: Flat and Non-Flat185789 -Node: Prerequisites187550 -Node: gettextize Invocation191658 -Node: Adjusting Files195230 -Node: po/POTFILES.in196453 -Node: configure.in197394 -Node: aclocal199521 -Node: acconfig200700 -Node: Makefile201314 -Node: src/Makefile203502 -Node: Conclusion205899 -Node: History206388 -Node: References209848 -Node: Country Codes211403 +Node: Top1411 +Node: Introduction6886 +Node: Why8742 +Ref: Why-Footnote-111832 +Node: Concepts11988 +Node: Aspects15401 +Node: Files21458 +Node: Overview23726 +Node: Basics34338 +Node: Installation35168 +Node: PO Files37135 +Ref: PO Files-Footnote-144147 +Node: Main PO Commands44259 +Node: Entry Positioning49199 +Node: Normalizing54450 +Node: Sources58902 +Node: Triggering60172 +Node: Mark Keywords62528 +Node: Marking66078 +Node: c-format73719 +Node: Special cases77469 +Node: Initial80331 +Node: xgettext Invocation80653 +Node: C Sources Context84481 +Node: Compendium89460 +Node: Updating90163 +Node: msgmerge Invocation90803 +Node: Translated Entries90977 +Node: Fuzzy Entries92268 +Node: Untranslated Entries95370 +Node: Obsolete Entries97209 +Node: Modifying Translations100341 +Node: Modifying Comments108159 +Node: Subedit112466 +Node: Auxiliary116243 +Node: Binaries119313 +Node: msgfmt Invocation119577 +Node: MO Files122203 +Node: Users130289 +Node: Matrix131770 +Node: Installers132973 +Node: End Users134143 +Node: Programmers134772 +Node: catgets135946 +Node: Interface to catgets137351 +Node: Problems with catgets139352 +Node: gettext140250 +Node: Interface to gettext141708 +Node: Ambiguities144050 +Node: Locating Catalogs146607 +Ref: Locating Catalogs-Footnote-1147658 +Ref: Locating Catalogs-Footnote-2147768 +Node: Charset conversion147917 +Node: Plural forms150359 +Ref: Plural forms-Footnote-1160137 +Node: GUI program problems160229 +Node: Optimized gettext165332 +Node: Comparison166665 +Node: Using libintl.a171090 +Node: gettext grok171861 +Node: Temp Programmers174493 +Node: Temp Implementations174933 +Node: Temp catgets176299 +Node: Temp WSI177986 +Node: Temp Notes179974 +Node: Translators180463 +Node: Trans Intro 0180842 +Node: Trans Intro 1183491 +Node: Discussions185355 +Node: Organization188511 +Node: Central Coordination190492 +Node: National Teams191620 +Node: Sub-Cultures194132 +Node: Organizational Ideas195051 +Node: Mailing Lists196054 +Node: Information Flow197857 +Node: Maintainers199990 +Node: Flat and Non-Flat201749 +Node: Prerequisites203510 +Node: gettextize Invocation207619 +Node: Adjusting Files211191 +Node: po/POTFILES.in212414 +Node: configure.in213353 +Node: aclocal215479 +Node: acconfig216658 +Node: Makefile217256 +Node: src/Makefile219444 +Node: Conclusion221841 +Node: History222330 +Node: References225790 +Node: Country Codes227345 End Tag Table diff --git a/doc/gettext.info-1 b/doc/gettext.info-1 index 2718d25..e238daf 100644 --- a/doc/gettext.info-1 +++ b/doc/gettext.info-1 @@ -1,5 +1,5 @@ -This is Info file gettext.info, produced by Makeinfo version 1.68 from -the input file gettext.texi. +This is gettext.info, produced by makeinfo version 4.0 from +gettext.texi. INFO-DIR-SECTION GNU Gettext Utilities START-INFO-DIR-ENTRY @@ -13,7 +13,8 @@ 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. + Copyright (C) 1995, 1996, 1997, 1998, 2001 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 @@ -51,7 +52,7 @@ GNU `gettext' utilities * Country Codes:: ISO 639 country codes - -- The Detailed Node Listing -- + --- The Detailed Node Listing --- Introduction @@ -92,6 +93,7 @@ Updating Existing PO Files * Obsolete Entries:: Obsolete Entries * Modifying Translations:: Modifying Translations * Modifying Comments:: Modifying Comments +* Subedit:: Mode for Editing Translations * Auxiliary:: Consulting Auxiliary PO Files Producing Binary MO Files @@ -124,6 +126,9 @@ About `gettext' * Interface to gettext:: The interface * Ambiguities:: Solving ambiguities * Locating Catalogs:: Locating message catalog files +* Charset conversion:: How to request conversion to Unicode +* Plural forms:: Additional functions for handling plurals +* GUI program problems:: Another technique for solving ambiguities * Optimized gettext:: Optimization of the *gettext functions Temporary Notes for the Programmers Chapter @@ -179,16 +184,16 @@ File: gettext.info, Node: Introduction, Next: Basics, Prev: Top, Up: Top Introduction ************ - This manual is still in *DRAFT* state. Some sections are still + This manual is still in _DRAFT_ state. Some sections are still empty, or almost. We keep merging material from other sources (essentially e-mail folders) while the proper integration of this material is delayed. - In this manual, we use *he* when speaking of the programmer or -maintainer, *she* when speaking of the translator, and *they* when + In this manual, we use _he_ when speaking of the programmer or +maintainer, _she_ when speaking of the translator, and _they_ when speaking of the installers or end users of the translated program. This is only a convenience for clarifying the documentation. It is -*absolutely* not meant to imply that some roles are more appropriate to +_absolutely_ not meant to imply that some roles are more appropriate to males or females. Besides, as you might guess, GNU `gettext' is meant to be useful for people using computers, whatever their sex, race, religion or nationality! @@ -231,7 +236,7 @@ software. Using a common language is quite handy for communication between developers, maintainers and users from all countries. On the other hand, most people are less comfortable with English than with their own native language, and would prefer to use their mother tongue -for day to day's work, as far as possible. Many would simply *love* to +for day to day's work, as far as possible. Many would simply _love_ to see their computer screen showing a lot less of English, and far more of their own language. @@ -272,7 +277,7 @@ all they need to know for properly doing their translating work. Also, this supplemental documentation might also help programmers, and even curious users, in understanding how GNU `gettext' is related to the remainder of the Translation Project, and consequently, have a glimpse -at the *big picture*. +at the _big picture_. ---------- Footnotes ---------- @@ -289,7 +294,7 @@ I18n, L10n, and Such Two long words appear all the time when we discuss support of native language in programs, and these words have a precise meaning, worth being explained here, once and for all in this document. The words are -*internationalization* and *localization*. Many people, tired of +_internationalization_ and _localization_. Many people, tired of writing these long words over and over again, took the habit of writing "i18n" and "l10n" instead, quoting the first and last letter of each word, and replacing the run of intermediate letters by a number merely @@ -393,6 +398,7 @@ translate beyond output messages. Translating a manual, with the intent of later keeping up with updates, is a major undertaking in itself, generally. + As we already stressed, translation is only one aspect of locales. Other internationalization aspects are not currently handled by GNU `gettext', but perhaps may be handled in future versions. There are @@ -409,7 +415,7 @@ putting multi-lingual messages into the proper context of other tasks related to locales, and also presents some other areas which GNU `gettext' might eventually tackle, maybe, one of these days. -*Characters and Codesets* +_Characters and Codesets_ The codeset most commonly used through out the USA and most English speaking parts of the world is the ASCII codeset. However, there are many characters needed by various locales that are not found @@ -420,12 +426,12 @@ related to locales, and also presents some other areas which GNU they need to use and will need to have the appropriate character handling routines to cope with the codeset. -*Currency* +_Currency_ The symbols used vary from country to country as does the position used by the symbol. Software needs to be able to transparently display currency figures in the native mode for each locale. -*Dates* +_Dates_ The format of date varies between locales. For example, Christmas day in 1994 is written as 12/25/94 in the USA and as 25/12/94 in Australia. Other countries might use ISO 8061 dates, etc. @@ -435,7 +441,7 @@ related to locales, and also presents some other areas which GNU as AM or PM. Further, the nature and yearly extent of the Daylight Saving correction vary widely between countries. -*Numbers* +_Numbers_ Numbers can be represented differently in different locales. For example, the following numbers are all written correctly for their respective locales: @@ -448,7 +454,7 @@ related to locales, and also presents some other areas which GNU English units or Metric units, or even take into account variants about how numbers are spelled in full. -*Messages* +_Messages_ The most obvious area is the language support within a locale. This is where GNU `gettext' provides the means for developers and users to easily change the language that the software uses to @@ -582,11 +588,10 @@ C sources each string is used. All translations are set to empty. The letter `t' in `.pot' marks this as a Template PO file, not yet oriented towards any particular language. *Note xgettext Invocation::, for more details about how one calls the `xgettext' program. If you are -*really* lazy, you might be interested at working a lot more right -away, and preparing the whole distribution setup (*note -Maintainers::.). By doing so, you spare yourself typing the `xgettext' -command, as `make' should now generate the proper things automatically -for you! +_really_ lazy, you might be interested at working a lot more right +away, and preparing the whole distribution setup (*note Maintainers::). +By doing so, you spare yourself typing the `xgettext' command, as +`make' should now generate the proper things automatically for you! The first time through, there is no `LANG.po' yet, so the `msgmerge' step may be skipped and replaced by a mere copy of `PACKAGE.pot' to @@ -596,27 +601,27 @@ step may be skipped and replaced by a mere copy of `PACKAGE.pot' to itself is a whole matter, still exclusively meant for humans, and whose complexity far overwhelms the level of this manual. Nevertheless, a few hints are given in some other chapter of this manual (*note -Translators::.). You will also find there indications about how to +Translators::). You will also find there indications about how to contact translating teams, or becoming part of them, for sharing your translating concerns with others who target the same native language. While adding the translated messages into the `LANG.pox' PO file, if you do not have Emacs handy, you are on your own for ensuring that your efforts fully respect the PO file format, and quoting conventions -(*note PO Files::.). This is surely not an impossible task, as this is +(*note PO Files::). This is surely not an impossible task, as this is the way many people have handled PO files already for Uniforum or Solaris. On the other hand, by using PO mode in Emacs, most details of PO file format are taken care of for you, but you have to acquire some familiarity with PO mode itself. Besides main PO mode commands (*note -Main PO Commands::.), you should know how to move between entries -(*note Entry Positioning::.), and how to handle untranslated entries -(*note Untranslated Entries::.). +Main PO Commands::), you should know how to move between entries (*note +Entry Positioning::), and how to handle untranslated entries (*note +Untranslated Entries::). If some common translations have already been saved into a compendium PO file, translators may use PO mode for initializing untranslated entries from the compendium, and also save selected translations into -the compendium, updating it (*note Compendium::.). Compendium files -are meant to be exchanged between members of a given translation team. +the compendium, updating it (*note Compendium::). Compendium files are +meant to be exchanged between members of a given translation team. Programs, or packages of programs, are dynamic in nature: users write bug reports and suggestion for improvements, maintainers react by @@ -652,9 +657,9 @@ refreshing operation adjusts all references to C source locations for strings, since these strings move as programs are modified. Also, `msgmerge' comments out as obsolete, in `LANG.pox', those already translated entries which are no longer used in the program sources -(*note Obsolete Entries::.). It finally discovers new strings and +(*note Obsolete Entries::). It finally discovers new strings and inserts them in the resulting PO file as untranslated entries (*note -Untranslated Entries::.). *Note msgmerge Invocation::, for more +Untranslated Entries::). *Note msgmerge Invocation::, for more information about what `msgmerge' really does. Whatever route or means taken, the goal is to obtain an updated @@ -680,7 +685,7 @@ distribution. Once the PO file is complete and dependable, the `msgfmt' program is used for turning the PO file into a machine-oriented format, which may yield efficient retrieval of translations by the programs of the -package, whenever needed at runtime (*note MO Files::.). *Note msgfmt +package, whenever needed at runtime (*note MO Files::). *Note msgfmt Invocation::, for more information about all modalities of execution for the `msgfmt' program. @@ -689,7 +694,7 @@ with the GNU `gettext' library, usually through the operation of `make', given a suitable `Makefile' exists for the project, and the resulting executable is installed somewhere users will find it. The MO files themselves should also be properly installed. Given the -appropriate environment variables are set (*note End Users::.), the +appropriate environment variables are set (*note End Users::), the program should localize itself automatically, whenever it executes. The remainder of this manual has the purpose of explaining in depth @@ -735,26 +740,29 @@ like: (setq auto-mode-alist (cons '("\\.po[tx]?\\'\\|\\.po\\." . po-mode) auto-mode-alist)) - (autoload 'po-mode "po-mode") + (autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t) Later, whenever you edit some `.po', `.pot' or `.pox' file, or any file having the string `.po.' within its name, Emacs loads `po-mode.elc' (or `po-mode.el') as needed, and automatically activates -PO mode commands for the associated buffer. The string *PO* appears in +PO mode commands for the associated buffer. The string _PO_ appears in the mode line for any buffer for which PO mode is active. Many PO files may be active at once in a single Emacs session. - If you are using Emacs version 20 or better, and have already + If you are using Emacs version 20 or newer, and have already installed the appropriate international fonts on your system, you may -also manage for the these fonts to be automatically loaded and used for -displaying the translations on your Emacs screen, whenever necessary. -For this to happen, you might want to add the lines: +also tell Emacs how to determine automatically the coding system of +every PO file. This will often (but not always) cause the necessary +fonts to be loaded and used for displaying the translations on your +Emacs screen. For this to happen, add the lines: - (autoload 'po-find-file-coding-system "po-mode") (modify-coding-system-alist 'file "\\.po[tx]?\\'\\|\\.po\\." 'po-find-file-coding-system) + (autoload 'po-find-file-coding-system "po-mode") -to your `.emacs' file. +to your `.emacs' file. If, with this, you still see boxes instead of +international characters, try a different font set (via Shift Mouse +button 1). File: gettext.info, Node: PO Files, Next: Main PO Commands, Prev: Installation, Up: Basics @@ -835,6 +843,20 @@ forms of flags defined: does some more tests to check to validity of the translation. *Note msgfmt Invocation::. + A different kind of entries is used for translations which involve +plural forms. + + WHITE-SPACE + # TRANSLATOR-COMMENTS + #. AUTOMATIC-COMMENTS + #: REFERENCE... + #, FLAG... + msgid UNTRANSLATED-STRING-SINGULAR + msgid_plural UNTRANSLATED-STRING-PLURAL + msgstr[0] TRANSLATED-STRING-CASE-0 + ... + msgstr[N] TRANSLATED-STRING-CASE-N + It happens that some lines, usually whitespace or comments, follow the very last entry of a PO file. Such lines are not part of any entry, and PO mode is unable to take action on those lines. By using the PO @@ -870,11 +892,11 @@ string could have been omitted, but only if the string starting with `Here' was promoted on the first line, right after `msgid'.(1) It was not really necessary either to switch between the two last quoted strings immediately after the newline `\n', the switch could have -occurred after *any* other character, we just did it this way because +occurred after _any_ other character, we just did it this way because it is neater. One should carefully distinguish between end of lines marked as `\n' -*inside* quotes, which are part of the represented string, and end of +_inside_ quotes, which are part of the represented string, and end of lines in the PO file itself, outside string quotes, which have no incidence on the represented string. @@ -908,9 +930,9 @@ will be executed. mode line for that window. The mode line also displays how many entries of each kind are held in the PO file. For example, the string `132t+3f+10u+2o' would tell the translator that the PO mode contains -132 translated entries (*note Translated Entries::., 3 fuzzy entries -(*note Fuzzy Entries::.), 10 untranslated entries (*note Untranslated -Entries::.) and 2 obsolete entries (*note Obsolete Entries::.). +132 translated entries (*note Translated Entries::, 3 fuzzy entries +(*note Fuzzy Entries::), 10 untranslated entries (*note Untranslated +Entries::) and 2 obsolete entries (*note Obsolete Entries::). Zero-coefficients items are not shown. So, in this example, if the fuzzy entries were unfuzzied, the untranslated entries were translated and the obsolete entries were deleted, the mode line would merely @@ -942,7 +964,7 @@ for managing windows in special ways. `V' Batch validate the format of the whole PO file. - The command `U' (`po-undo') interfaces to the Emacs *undo* facility. + The command `U' (`po-undo') interfaces to the Emacs _undo_ facility. *Note Undoing Changes: (emacs)Undo. Each time `U' is typed, modifications which the translator did to the PO file are undone a little more. For the purpose of undoing, each PO mode command is @@ -968,7 +990,7 @@ got PO mode to show some source context in some other, she might discover some apparent bug in the program source that needs correction. This command allows the translator to change sex, become a programmer, and have the cursor right into the window containing the program she -(or rather *he*) wants to modify. By later getting the cursor back in +(or rather _he_) wants to modify. By later getting the cursor back in the PO file window, or by asking Emacs to edit this file once again, PO mode is then recovered. diff --git a/doc/gettext.info-2 b/doc/gettext.info-2 index 20de9bc..9048a29 100644 --- a/doc/gettext.info-2 +++ b/doc/gettext.info-2 @@ -1,5 +1,5 @@ -This is Info file gettext.info, produced by Makeinfo version 1.68 from -the input file gettext.texi. +This is gettext.info, produced by makeinfo version 4.0 from +gettext.texi. INFO-DIR-SECTION GNU Gettext Utilities START-INFO-DIR-ENTRY @@ -13,7 +13,8 @@ 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. + Copyright (C) 1995, 1996, 1997, 1998, 2001 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 @@ -78,7 +79,7 @@ select the current entry in PO mode, including commands which move by characters, lines, paragraphs, screens or pages, and search commands. However, there is a kind of standard way to display the current entry in PO mode, which usual Emacs commands moving the cursor do not -especially try to enforce. The command `.' (`po-current-entry') has +especially try to enforce. The command `.' (`po-current-entry') has the sole purpose of redisplaying the current entry properly, after the current entry has been changed by means external to PO mode, or the Emacs screen otherwise altered. @@ -94,7 +95,7 @@ If nobody feels a real need for using it, or a compulsion for writing it, we should drop this whole idea. The incentive for doing it should come from translators rather than programmers, as opinions from an experienced translator are surely more worth to me than opinions from -programmers *thinking* about how *others* should do translation. +programmers _thinking_ about how _others_ should do translation. The commands `n' (`po-next-entry') and `p' (`po-previous-entry') move the cursor the entry following, or preceding, the current one. If @@ -206,7 +207,7 @@ Emacs handy, and who would nevertheless want to handcraft their PO files in nice ways. Right now, in PO mode, strings are single line or multi-line. A -string goes multi-line if and only if it has *embedded* newlines, that +string goes multi-line if and only if it has _embedded_ newlines, that is, if it matches `[^\n]\n+[^\n]'. So, we would have: msgstr "\n\nHello, world!\n\n\n" @@ -254,7 +255,7 @@ needing translation. Presuming that your set of programs, or package, has been adjusted so all needed GNU `gettext' files are available, and your `Makefile' -files are adjusted (*note Maintainers::.), each C module having +files are adjusted (*note Maintainers::), each C module having translated C strings should contain the line: #include <libintl.h> @@ -365,7 +366,7 @@ program sources and produces PO file templates. The canonical keyword for marking translatable strings is `gettext', it gave its name to the whole GNU `gettext' package. For packages making only light use of the `gettext' keyword, macro or function, it -is easily used *as is*. However, for packages using the `gettext' +is easily used _as is_. However, for packages using the `gettext' interface more heavily, it is usually more convenient to give the main keyword a shorter, less obtrusive name. Indeed, the keyword might appear on a lot of strings all over the package, and programmers @@ -395,7 +396,7 @@ instead of merely using `#include <libintl.h>'. you add or modify a string, you will have to ask yourself if the new or altered string requires translation, and include it within `_()' if you think it should be translated. `"%s: %d"' is an example of string -*not* requiring translation! +_not_ requiring translation! File: gettext.info, Node: Marking, Next: c-format, Prev: Mark Keywords, Up: Sources @@ -490,7 +491,7 @@ translatable will be automatically skipped. tags commands. For example, regular `tags-search' or `tags-query-replace' commands may be used without disrupting the independent `,' search sequence. However, as implemented, the -*initial* `,' command (or the `,' command is used with a prefix) might +_initial_ `,' command (or the `,' command is used with a prefix) might also reinitialize the regular Emacs tags searching to the first tags file, this reinitialization might be considered spurious. @@ -512,11 +513,11 @@ PO file window, if you want command `,' for the next string, say. The `M-.' command has a few built-in speedups, so you do not have to explicitly type all keywords all the time. The first such speedup is -that you are presented with a *preferred* keyword, which you may accept +that you are presented with a _preferred_ keyword, which you may accept by merely typing `<RET>' at the prompt. The second speedup is that you may type any non-ambiguous prefix of the keyword you really mean, and the command will complete it automatically for you. This also means -that PO mode has to *know* all your possible keywords, and that it will +that PO mode has to _know_ all your possible keywords, and that it will not accept mistyped keywords. If you reply `?' to the keyword request, the command gives a list of @@ -525,9 +526,9 @@ prefixed by an argument (`C-u M-.'), it inhibits updating any program source or PO file buffer, and does some simple keyword management instead. In this case, the command asks for a keyword, written in full, which becomes a new allowed keyword for later `M-.' commands. -Moreover, this new keyword automatically becomes the *preferred* +Moreover, this new keyword automatically becomes the _preferred_ keyword for later commands. By typing an already known keyword in -response to `C-u M-.', one merely changes the *preferred* keyword and +response to `C-u M-.', one merely changes the _preferred_ keyword and does nothing more. All keywords known for `M-.' are recognized by the `,' command when @@ -584,7 +585,7 @@ format specifier, but the string is not used in `printf'. Therefore the `xgettext' adds a special tag to those messages it thinks might be a format string. There is no absolute rule for this, only a heuristic. In the `.po' file the entry is marked using the -`c-format' flag in the `#,' comment line (*note PO Files::.). +`c-format' flag in the `#,' comment line (*note PO Files::). The careful reader now might say that this again can cause problems. The heuristic might guess it wrong. This is true and therefore @@ -645,7 +646,7 @@ this. Consider the following case: While it is no problem to mark the string `"a default message"' it is not possible to mark the string initializers for `messages'. What is to be done? We have to fulfill two tasks. First we have to mark the -strings so that the `xgettext' program (*note xgettext Invocation::.) +strings so that the `xgettext' program (*note xgettext Invocation::) can find them, and second we have to translate the string at runtime before printing them. @@ -779,13 +780,23 @@ Invoking the `xgettext' Program Join messages with existing file. `-k WORD' -`--keyword[=WORD]' - Additonal keyword to be looked for (without WORD means not to use - default keywords). - - The default keywords, which are always looked for if not explicitly - disabled, are `gettext', `dgettext', `dcgettext' and - `gettext_noop'. +`--keyword[=KEYWORDSPEC]' + Additional keyword to be looked for (without KEYWORDSPEC means not + to use default keywords). + + If KEYWORDSPEC is a C identifer ID, `xgettext' looks for strings + in the first argument of each call to the function or macro ID. + If KEYWORDSPEC is of the form `ID:ARGNUM', `xgettext' looks for + strings in the ARGNUMth argument of the call. If KEYWORDSPEC is + of the form `ID:ARGNUM1,ARGNUM2', `xgettext' looks for strings in + the ARGNUM1st argument and in the ARGNUM2nd argument of the call, + and treats them as singular/plural variants for a message with + plural handling. + + The default keyword specifications, which are always looked for if + not explicitly disabled, are `gettext', `dgettext:2', + `dcgettext:2', `ngettext:1,2', `dngettext:2,3', `dcngettext:2,3', + and `gettext_noop'. `-m [STRING]' `--msgstr-prefix[=STRING]' @@ -858,7 +869,7 @@ better what the string really means and how tight the translation has to be. Most of times, when problems arise, the only way left to make her judgment is looking at the true program sources from where this string originated, searching for surrounding comments the programmer -might have put in there, and looking around for helping clues of *any* +might have put in there, and looking around for helping clues of _any_ kind. Surely, when looking at program sources, the translator will receive @@ -985,11 +996,10 @@ Translated Entries ================== Each PO file entry for which the `msgstr' field has been filled with -a translation, and which is not marked as fuzzy (*note Fuzzy -Entries::.), is a said to be a "translated" entry. Only translated -entries will later be compiled by GNU `msgfmt' and become usable in -programs. Other entry types will be excluded; translation will not -occur for them. +a translation, and which is not marked as fuzzy (*note Fuzzy Entries::), +is a said to be a "translated" entry. Only translated entries will +later be compiled by GNU `msgfmt' and become usable in programs. Other +entry types will be excluded; translation will not occur for them. Some commands are more specifically related to translated entry processing. diff --git a/doc/gettext.info-3 b/doc/gettext.info-3 index cd5db2b..f25894d 100644 --- a/doc/gettext.info-3 +++ b/doc/gettext.info-3 @@ -1,5 +1,5 @@ -This is Info file gettext.info, produced by Makeinfo version 1.68 from -the input file gettext.texi. +This is gettext.info, produced by makeinfo version 4.0 from +gettext.texi. INFO-DIR-SECTION GNU Gettext Utilities START-INFO-DIR-ENTRY @@ -13,7 +13,8 @@ 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. + Copyright (C) 1995, 1996, 1997, 1998, 2001 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 @@ -171,7 +172,7 @@ string, so turning the entry into an untranslated one. But while doing so, its previous contents is put apart in a special place, known as the kill ring. The command `w' (`po-kill-ring-save-msgstr') has also the effect of taking a copy of the translation onto the kill ring, but it -otherwise leaves the entry alone, and does *not* remove the translation +otherwise leaves the entry alone, and does _not_ remove the translation from the entry. Both commands use exactly the Emacs kill ring, which is shared between buffers, and which is well known already to Emacs lovers. @@ -232,9 +233,9 @@ slight variant of the translation exists, she immediately uses `m' to mark the current entry location, then starts chasing obsolete entries with `o', hoping to find some translation corresponding to the unmodified string. Once found, she uses the `<DEL>' command for -deleting the obsolete entry, knowing that `<DEL>' also *kills* the +deleting the obsolete entry, knowing that `<DEL>' also _kills_ the translation, that is, pushes the translation on the kill ring. Then, -`r' returns to the initial untranslated entry, `y' then *yanks* the +`r' returns to the initial untranslated entry, `y' then _yanks_ the saved translation right into the `msgstr' field. The translator is then free to use `<RET>' for fine tuning the translation contents, and maybe to later use `u', then `m' again, for going on with the next @@ -259,7 +260,7 @@ delete, or modify at will. These comments may be useful to herself when she returns to this PO file after a while. Comments not having whitespace after the initial `#', for example, -those beginning with `#.' or `#:', are *not* translator comments, they +those beginning with `#.' or `#:', are _not_ translator comments, they are exclusively created by other `gettext' tools. So, the commands below will never alter such system added comments, they are not meant for the translator to modify. *Note PO Files::. @@ -311,7 +312,7 @@ When this command is immediately repeated, the comments just inserted are withdrawn, and replaced by other strings taken along the kill ring. On the kill ring, all strings have the same nature. There is no -distinction between *translation* strings and *translator comments* +distinction between _translation_ strings and _translator comments_ strings. So, for example, let's presume the translator has just finished editing a translation, and wants to create a new translator comment to document why the previous translation was not good, just to @@ -369,7 +370,7 @@ effect of last edition. already achieved in other languages, directly while editing the current translation. This may be quite convenient when the translator is fluent at many languages, but of course, only makes sense when such completed -auxiliary PO files are already available to her (*note Auxiliary::.). +auxiliary PO files are already available to her (*note Auxiliary::). Functions found on `po-subedit-mode-hook', if any, are executed after the string has been inserted in the edit buffer. @@ -386,7 +387,7 @@ not really part of the string. On exiting the editing window with added after it. If the translator adds characters after the terminating `<', it looses its delimiting property and integrally becomes part of the string. If she removes the delimiting `<', then -the edited string is taken *as is*, with all trailing newlines, even if +the edited string is taken _as is_, with all trailing newlines, even if invisible. Also, if the translated string ought to end itself with a genuine `<', then the delimiting `<' may not be removed; so the string should appear, in the editing window, as ending with two `<' in a row. @@ -396,7 +397,7 @@ may move the cursor back into the PO file buffer and freely move to other entries, browsing at will. If, with an edition pending, the translator wanders in the PO file buffer, she may decide to start modifying another entry. Each entry being edited has its own subedit -buffer. It is possible to simultaneously edit the translation *and* +buffer. It is possible to simultaneously edit the translation _and_ the comment of a single entry, or to edit entries in different PO files, all at once. Typing `<RET>' on a field already being edited merely resume that particular edit. Yet, the translator should better @@ -461,7 +462,7 @@ entry, and if yes, this entry becomes current. Otherwise, the cursor of the selected file is left undisturbed. For all this to work fully, auxiliary PO files will have to be -normalized, in that way that `msgid' fields should be written *exactly* +normalized, in that way that `msgid' fields should be written _exactly_ the same way. It is possible to write `msgid' fields in various ways for representing the same string, different writing would break the proper behaviour of the auxiliary file commands of PO mode. This is not @@ -517,7 +518,7 @@ Invoking the `msgfmt' Program already present. We find this behaviour of Sun's implementation rather silly and so - by default this mode is *not* selected. + by default this mode is _not_ selected. `-v' `--verbose' @@ -543,7 +544,7 @@ Invoking the `msgfmt' Program function. So solve this problem the programmer can dictate the decision to - the `xgettext' program (*note c-format::.). The translator should + the `xgettext' program (*note c-format::). The translator should not consider removing the flag from the <#,> line. This "fix" would be reversed again as soon as `msgmerge' is called the next time. @@ -597,7 +598,7 @@ the same index. search, for when the MO file does not contain an hashing table, or for when it is not practical to use the hashing table provided in the MO file. This also has another advantage, as the empty string in a PO -file GNU `gettext' is usually *translated* into some system information +file GNU `gettext' is usually _translated_ into some system information attached to that particular MO file, and the empty string necessarily becomes the first in both the original and translated tables, making the system information very easy to find. @@ -605,7 +606,7 @@ the system information very easy to find. The size S of the hash table can be zero. In this case, the hash table itself is not contained in the MO file. Some people might prefer this because a precomputed hashing table takes disk space, and does not -win *that* much speed. The hash table contains indices to the sorted +win _that_ much speed. The hash table contains indices to the sorted array of strings in the MO file. Conflict resolution is done by double hashing. The precise hashing algorithm used is fairly dependent of GNU `gettext' code, and is not documented here. @@ -618,12 +619,23 @@ each string is separately aligned so it starts at an offset which is a multiple of the alignment value. On some RISC machines, a correct alignment will speed things up. + Plural forms are stored by letting the plural of the original string +follow the singular of the original string, separated through a <NUL> +byte. The length which appears in the string descriptor includes both. +However, only the singular of the original string takes part in the +hash table lookup. The plural variants of the translation are all +stored consecutively, separated through a <NUL> byte. Here also, the +length in the string descriptor includes all of them. + Nothing prevents a MO file from having embedded <NUL>s in strings. However, the program interface currently used already presumes that strings are <NUL> terminated, so embedded <NUL>s are somewhat useless. But MO file format is general enough so other interfaces would be later possible, if for example, we ever want to implement wide characters -right in MO files, where <NUL> bytes may accidently appear. +right in MO files, where <NUL> bytes may accidently appear. (No, we +don't want to have wide characters in MO files. They would make the +file unnecessarily large, and the `wchar_t' type being platform +dependent, MO files would be platform dependent as well.) This particular issue has been strongly debated in the GNU `gettext' development forum, and it is expectable that MO file format will evolve @@ -692,7 +704,7 @@ should feel some kind of astonished pleasure, seeing the effect of that strange kind of magic that just makes their own native language appear everywhere on their screens. As for naive users, they would ideally have no special pleasure about it, merely taking their own language for -*granted*, and becoming rather unhappy otherwise. +_granted_, and becoming rather unhappy otherwise. So, let's try to describe here how we would like the magic to operate, as we want the users' view to be the simplest, among all ways @@ -747,14 +759,14 @@ Magic for Installers By default, packages fully using GNU `gettext', internally, are installed in such a way that they to allow translation of messages. At -*configuration* time, those packages should automatically detect -whether the underlying host system provides usable `catgets' or -`gettext' functions. If neither is present, the GNU `gettext' library -should be automatically prepared and used. Installers may use special -options at configuration time for changing this behavior. The command -`./configure --with-included-gettext' bypasses system `catgets' or -`gettext' to use GNU `gettext' instead, while `./configure ---disable-nls' produces program totally unable to translate messages. +_configuration_ time, those packages should automatically detect +whether the underlying host system already provides the GNU `gettext' +functions. If not, the GNU `gettext' library should be automatically +prepared and used. Installers may use special options at configuration +time for changing this behavior. The command `./configure +--with-included-gettext' bypasses system `gettext' to use the included +GNU `gettext' instead, while `./configure --disable-nls' produces +programs totally unable to translate messages. Internationalized packages have usually many `LL.po' files. Unless translations are disabled, all those available are installed together @@ -770,7 +782,7 @@ Magic for End Users =================== We consider here those packages using GNU `gettext' internally, and -for which the installers did not disable translation at *configure* +for which the installers did not disable translation at _configure_ time. Then, users only have to set the `LANG' environment variable to the appropriate `LL' prior to using the programs in the package. *Note Matrix::. For example, let's presume a German site. At the shell @@ -829,7 +841,7 @@ transfering the rights on Unix(tm) they at last came to X/Open, the very same who published this specifications. This leads me to making the prediction that this interface will be in future Unix standards (e.g. Spec1170) and therefore part of all Unix implementation -(implementations, which are *allowed* to wear this name). +(implementations, which are _allowed_ to wear this name). * Menu: @@ -876,7 +888,7 @@ three-stage addressing: The fourth argument is not used to address the translation. It is given as a default value in case when one of the addressing stages fail. One important thing to remember is that although the return type -of catgets is `char *' the resulting string *must not* be changed. It +of catgets is `char *' the resulting string _must not_ be changed. It should better `const char *', but the standard is published in 1988, one year before ANSI C. @@ -932,6 +944,9 @@ this library will be interested in this description. * Interface to gettext:: The interface * Ambiguities:: Solving ambiguities * Locating Catalogs:: Locating message catalog files +* Charset conversion:: How to request conversion to Unicode +* Plural forms:: Additional functions for handling plurals +* GUI program problems:: Another technique for solving ambiguities * Optimized gettext:: Optimization of the *gettext functions @@ -956,7 +971,7 @@ of the current global domain of the `LC_MESSAGE' category. The argument is a null-terminated string, whose characters must be legal in the use in filenames. If the DOMAIN_NAME argument is `NULL', the function return the current value. If no value has been set before, -the name of the default domain is returned: *messages*. Please note +the name of the default domain is returned: _messages_. Please note that although the return value of `textdomain' is of type `char *' no changing is allowed. It is also important to know that no checks of the availability are made. If the name is not available you will see @@ -1037,36 +1052,3 @@ relative to the current directory different results will be achieved when the program executes a `chdir' command. Relative paths should always be avoided to avoid dependencies and unreliabilities. - -File: gettext.info, Node: Locating Catalogs, Next: Optimized gettext, Prev: Ambiguities, Up: gettext - -Locating Message Catalog Files ------------------------------- - - Because many different languages for many different packages have to -be stored we need some way to add these information to file message -catalog files. The way usually used in Unix environments is have this -encoding in the file name. This is also done here. The directory name -given in `bindtextdomain's second argument (or the default directory), -followed by the value and name of the locale and the domain name are -concatenated: - - DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo - - The default value for DIR_NAME is system specific. For the GNU -library, and for packages adhering to its conventions, it's: - /usr/local/share/locale - -LOCALE is the value of the locale whose name is this `LC_CATEGORY'. -For `gettext' and `dgettext' this locale is always `LC_MESSAGES'. -`dcgettext' specifies the locale by the third argument.(1) (2) - - ---------- Footnotes ---------- - - (1) Some system, eg Ultrix, don't have `LC_MESSAGES'. Here we use a -more or less arbitrary value for it. - - (2) When the system does not support `setlocale' its behavior in -setting the locale values is simulated by looking at the environment -variables. - diff --git a/doc/gettext.info-4 b/doc/gettext.info-4 index 21f46dd..0bb950e 100644 --- a/doc/gettext.info-4 +++ b/doc/gettext.info-4 @@ -1,5 +1,5 @@ -This is Info file gettext.info, produced by Makeinfo version 1.68 from -the input file gettext.texi. +This is gettext.info, produced by makeinfo version 4.0 from +gettext.texi. INFO-DIR-SECTION GNU Gettext Utilities START-INFO-DIR-ENTRY @@ -13,7 +13,8 @@ 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. + Copyright (C) 1995, 1996, 1997, 1998, 2001 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 @@ -30,7 +31,460 @@ versions, except that this permission notice may be stated in a translation approved by the Foundation. -File: gettext.info, Node: Optimized gettext, Prev: Locating Catalogs, Up: gettext +File: gettext.info, Node: Locating Catalogs, Next: Charset conversion, Prev: Ambiguities, Up: gettext + +Locating Message Catalog Files +------------------------------ + + Because many different languages for many different packages have to +be stored we need some way to add these information to file message +catalog files. The way usually used in Unix environments is have this +encoding in the file name. This is also done here. The directory name +given in `bindtextdomain's second argument (or the default directory), +followed by the value and name of the locale and the domain name are +concatenated: + + DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo + + The default value for DIR_NAME is system specific. For the GNU +library, and for packages adhering to its conventions, it's: + /usr/local/share/locale + +LOCALE is the value of the locale whose name is this `LC_CATEGORY'. +For `gettext' and `dgettext' this locale is always `LC_MESSAGES'. +`dcgettext' specifies the locale by the third argument.(1) (2) + + ---------- Footnotes ---------- + + (1) Some system, eg Ultrix, don't have `LC_MESSAGES'. Here we use a +more or less arbitrary value for it. + + (2) When the system does not support `setlocale' its behavior in +setting the locale values is simulated by looking at the environment +variables. + + +File: gettext.info, Node: Charset conversion, Next: Plural forms, Prev: Locating Catalogs, Up: gettext + +How to specify the output character set `gettext' uses +------------------------------------------------------ + + `gettext' not only looks up a translation in a message catalog. It +also converts the translation on the fly to the desired output character +set. This is useful if the user is working in a different character set +than the translator who created the message catalog, because it avoids +distributing variants of message catalogs which differ only in the +character set. + + The output character set is, by default, the value of `nl_langinfo +(CODESET)', which depends on the `LC_CTYPE' part of the current locale. +But programs which store strings in a locale independent way (e.g. +UTF-8) can request that `gettext' and related functions return the +translations in that encoding, by use of the `bind_textdomain_codeset' +function. + + Note that the MSGID argument to `gettext' is not subject to +character set conversion. Also, when `gettext' does not find a +translation for MSGID, it returns MSGID unchanged - independently of +the current output character set. It is therefore recommended that all +MSGIDs be US-ASCII strings. + + - Function: char * bind_textdomain_codeset (const char *DOMAINNAME, + const char *CODESET) + The `bind_textdomain_codeset' function can be used to specify the + output character set for message catalogs for domain DOMAINNAME. + The CODESET argument must be a valid codeset name which can be used + for the `iconv_open' function, or a null pointer. + + If the CODESET parameter is the null pointer, + `bind_textdomain_codeset' returns the currently selected codeset + for the domain with the name DOMAINNAME. It returns `NULL' if no + codeset has yet been selected. + + The `bind_textdomain_codeset' function can be used several times. + If used multiple times with the same DOMAINNAME argument, the + later call overrides the settings made by the earlier one. + + The `bind_textdomain_codeset' function returns a pointer to a + string containing the name of the selected codeset. The string is + allocated internally in the function and must not be changed by the + user. If the system went out of core during the execution of + `bind_textdomain_codeset', the return value is `NULL' and the + global variable ERRNO is set accordingly. + + +File: gettext.info, Node: Plural forms, Next: GUI program problems, Prev: Charset conversion, Up: gettext + +Additional functions for plural forms +------------------------------------- + + The functions of the `gettext' family described so far (and all the +`catgets' functions as well) have one problem in the real world which +have been neglected completely in all existing approaches. What is +meant here is the handling of plural forms. + + Looking through Unix source code before the time anybody thought +about internationalization (and, sadly, even afterwards) one can often +find code similar to the following: + + printf ("%d file%s deleted", n, n == 1 ? "" : "s"); + +After the first complaints from people internationalizing the code +people either completely avoided formulations like this or used strings +like `"file(s)"'. Both look unnatural and should be avoided. First +tries to solve the problem correctly looked like this: + + if (n == 1) + printf ("%d file deleted", n); + else + printf ("%d files deleted", n); + + But this does not solve the problem. It helps languages where the +plural form of a noun is not simply constructed by adding an `s' but +that is all. Once again people fell into the trap of believing the +rules their language is using are universal. But the handling of plural +forms differs widely between the language families. For example, Rafal +Maszkowski `<rzm@mat.uni.torun.pl>' reports: + + In Polish we use e.g. plik (file) this way: + 1 plik + 2,3,4 pliki + 5-21 pliko'w + 22-24 pliki + 25-31 pliko'w + and so on (o' means 8859-2 oacute which should be rather okreska, + similar to aogonek). + + There are two things which can differ between languages (and even +inside language families); + + * The form how plural forms are build differs. This is a problem + with language which have many irregularities. German, for + instance, is a drastic case. Though English and German are part + of the same language family (Germanic), the almost regular forming + of plural noun forms (appending an `s') is hardly found in German. + + * The number of plural forms differ. This is somewhat surprising for + those who only have experiences with Romanic and Germanic languages + since here the number is the same (there are two). + + But other language families have only one form or many forms. More + information on this in an extra section. + + The consequence of this is that application writers should not try to +solve the problem in their code. This would be localization since it is +only usable for certain, hardcoded language environments. Instead the +extended `gettext' interface should be used. + + These extra functions are taking instead of the one key string two +strings and an numerical argument. The idea behind this is that using +the numerical argument and the first string as a key, the implementation +can select using rules specified by the translator the right plural +form. The two string arguments then will be used to provide a return +value in case no message catalog is found (similar to the normal +`gettext' behavior). In this case the rules for Germanic language is +used and it is assumed that the first string argument is the singular +form, the second the plural form. + + This has the consequence that programs without language catalogs can +display the correct strings only if the program itself is written using +a Germanic language. This is a limitation but since the GNU C library +(as well as the GNU `gettext' package) are written as part of the GNU +package and the coding standards for the GNU project require program +being written in English, this solution nevertheless fulfills its +purpose. + + - Function: char * ngettext (const char *MSGID1, const char *MSGID2, + unsigned long int N) + The `ngettext' function is similar to the `gettext' function as it + finds the message catalogs in the same way. But it takes two + extra arguments. The MSGID1 parameter must contain the singular + form of the string to be converted. It is also used as the key + for the search in the catalog. The MSGID2 parameter is the plural + form. The parameter N is used to determine the plural form. If no + message catalog is found MSGID1 is returned if `n == 1', otherwise + `msgid2'. + + An example for the us of this function is: + + printf (ngettext ("%d file removed", "%d files removed", n), n); + + Please note that the numeric value N has to be passed to the + `printf' function as well. It is not sufficient to pass it only to + `ngettext'. + + - Function: char * dngettext (const char *DOMAIN, const char *MSGID1, + const char *MSGID2, unsigned long int N) + The `dngettext' is similar to the `dgettext' function in the way + the message catalog is selected. The difference is that it takes + two extra parameter to provide the correct plural form. These two + parameters are handled in the same way `ngettext' handles them. + + - Function: char * dcngettext (const char *DOMAIN, const char *MSGID1, + const char *MSGID2, unsigned long int N, int CATEGORY) + The `dcngettext' is similar to the `dcgettext' function in the way + the message catalog is selected. The difference is that it takes + two extra parameter to provide the correct plural form. These two + parameters are handled in the same way `ngettext' handles them. + + Now, how do these functions solve the problem of the plural forms? +Without the input of linguists (which was not available) it was not +possible to determine whether there are only a few different forms in +which plural forms are formed or whether the number can increase with +every new supported language. + + Therefore the solution implemented is to allow the translator to +specify the rules of how to select the plural form. Since the formula +varies with every language this is the only viable solution except for +hardcoding the information in the code (which still would require the +possibility of extensions to not prevent the use of new languages). The +details are explained in the GNU `gettext' manual. Here only a a bit +of information is provided. + + The information about the plural form selection has to be stored in +the header entry (the one with the empty (`msgid' string). There should +be something like: + + nplurals=2; plural=n == 1 ? 0 : 1 + + The `nplurals' value must be a decimal number which specifies how +many different plural forms exist for this language. The string +following `plural' is an expression which is using the C language +syntax. Exceptions are that no negative number are allowed, numbers +must be decimal, and the only variable allowed is `n'. This expression +will be evaluated whenever one of the functions `ngettext', +`dngettext', or `dcngettext' is called. The numeric value passed to +these functions is then substituted for all uses of the variable `n' in +the expression. The resulting value then must be greater or equal to +zero and smaller than the value given as the value of `nplurals'. + +The following rules are known at this point. The language with families +are listed. But this does not necessarily mean the information can be +generalized for the whole family (as can be easily seen in the table +below).(1) + +Only one form: + Some languages only require one single form. There is no + distinction between the singular and plural form. And appropriate + header entry would look like this: + + nplurals=1; plural=0 + + Languages with this property include: + + Finno-Ugric family + Hungarian + + Asian family + Japanese + + Turkic/Altaic family + Turkish + +Two forms, singular used for one only + This is the form used in most existing programs since it is what + English is using. A header entry would look like this: + + nplurals=2; plural=n != 1 + + (Note: this uses the feature of C expressions that boolean + expressions have to value zero or one.) + + Languages with this property include: + + Germanic family + Danish, Dutch, English, German, Norwegian, Swedish + + Finno-Ugric family + Finnish + + Latin/Greek family + Greek + + Semitic family + Hebrew + + Romanic family + Italian, Spanish + + Artificial + Esperanto + +Two forms, singular used for zero and one + Exceptional case in the language family. The header entry would + be: + + nplurals=2; plural=n>1 + + Languages with this property include: + + Romanic family + French + +Three forms, special cases for one and two + The header entry would be: + + nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2 + + Languages with this property include: + + Celtic + Gaeilge + +Three forms, special case for one and all numbers ending in 2, 3, or 4 + The header entry would look like this: + + nplurals=3; plural=n==1 ? 0 : n%10>=2 && n%10<=4 ? 1 : 2 + + Languages with this property include: + + Slavic family + Russian + +Three forms, special case for one and some numbers ending in 2, 3, or 4 + The header entry would look like this: + + nplurals=3; plural=n==1 ? 0 : \ + n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2 + + (Continuation in the next line is possible.) + + Languages with this property include: + + Slavic family + Polish + +Four forms, special case for one and all numbers ending in 2, 3, or 4 + The header entry would look like this: + + nplurals=4; plural=n==1 ? 0 : n%10==2 ? 1 : n%10==3 || n%10==4 ? 2 : 3 + + Languages with this property include: + + Slavic family + Slovenian + + ---------- Footnotes ---------- + + (1) Additions are welcome. Send appropriate information to +<bug-glibc-manual@gnu.org>. + + +File: gettext.info, Node: GUI program problems, Next: Optimized gettext, Prev: Plural forms, Up: gettext + +How to use `gettext' in GUI programs +------------------------------------ + + One place where the `gettext' functions, if used normally, have big +problems is within programs with graphical user interfaces (GUIs). The +problem is that many of the strings which have to be translated are very +short. They have to appear in pull-down menus which restricts the +length. But strings which are not containing entire sentences or at +least large fragments of a sentence may appear in more than one +situation in the program but might have different translations. This is +especially true for the one-word strings which are frequently used in +GUI programs. + + As a consequence many people say that the `gettext' approach is +wrong and instead `catgets' should be used which indeed does not have +this problem. But there is a very simple and powerful method to handle +these kind of problems with the `gettext' functions. + +As as example consider the following fictional situation. A GUI program +has a menu bar with the following entries: + + +------------+------------+--------------------------------------+ + | File | Printer | | + +------------+------------+--------------------------------------+ + | Open | | Select | + | New | | Open | + +----------+ | Connect | + +----------+ + + To have the strings `File', `Printer', `Open', `New', `Select', and +`Connect' translated there has to be at some point in the code a call +to a function of the `gettext' family. But in two places the string +passed into the function would be `Open'. The translations might not +be the same and therefore we are in the dilemma described above. + + One solution to this problem is to artificially enlengthen the +strings to make them unambiguous. But what would the program do if no +translation is available? The enlengthened string is not what should be +printed. So we should use a little bit modified version of the +functions. + + To enlengthen the strings a uniform method should be used. E.g., in +the example above the strings could be chosen as + + Menu|File + Menu|Printer + Menu|File|Open + Menu|File|New + Menu|Printer|Select + Menu|Printer|Open + Menu|Printer|Connect + + Now all the strings are different and if now instead of `gettext' +the following little wrapper function is used, everything works just +fine: + + char * + sgettext (const char *msgid) + { + char *msgval = gettext (msgid); + if (msgval == msgid) + msgval = strrchr (msgid, '|') + 1; + return msgval; + } + + What this little function does is to recognize the case when no +translation is available. This can be done very efficiently by a +pointer comparison since the return value is the input value. If there +is no translation we know that the input string is in the format we used +for the Menu entries and therefore contains a `|' character. We simply +search for the last occurrence of this character and return a pointer +to the character following it. That's it! + + If one now consistently uses the enlengthened string form and +replaces the `gettext' calls with calls to `sgettext' (this is normally +limited to very few places in the GUI implementation) then it is +possible to produce a program which can be internationalized. + + The other `gettext' functions (`dgettext', `dcgettext' and the +`ngettext' equivalents) can and should have corresponding functions as +well which look almost identical, except for the parameters and the +call to the underlying function. + + Now there is of course the question why such functions do not exist +in the GNU gettext package? There are two parts of the answer to this +question. + + * They are easy to write and therefore can be provided by the + project they are used in. This is not an answer by itself and + must be seen together with the second part which is: + + * There is no way the gettext package can contain a version which + can work everywhere. The problem is the selection of the + character to separate the prefix from the actual string in the + enlenghtened string. The examples above used `|' which is a quite + good choice because it resembles a notation frequently used in + this context and it also is a character not often used in message + strings. + + But what if the character is used in message strings. Or if the + chose character is not available in the character set on the + machine one compiles (e.g., `|' is not required to exist for + ISO C; this is why the `iso646.h' file exists in ISO C programming + environments). + + There is only one more comment to be said. The wrapper function +above require that the translations strings are not enlengthened +themselves. This is only logical. There is no need to disambiguate +the strings (since they are never used as keys for a search) and one +also saves quite some memory and disk space by doing this. + + +File: gettext.info, Node: Optimized gettext, Prev: GUI program problems, Up: gettext Optimization of the *gettext functions -------------------------------------- @@ -62,51 +516,12 @@ string is always the same. One way to use this is: } But this solution is not usable in all situation (e.g. when the locale -selection changes) nor is it good readable. - - The GNU C compiler, version 2.7 and above, provide another solution -for this. To describe this we show here some lines of the -`intl/libgettext.h' file. For an explanation of the expression command -block see *Note Statements and Declarations in Expressions: -(gcc)Statement Exprs. - - # if defined __GNUC__ && __GNUC__ == 2 && __GNUC_MINOR__ >= 7 - extern int _nl_msg_cat_cntr; - # define dcgettext(domainname, msgid, category) \ - (__extension__ \ - ({ \ - char *result; \ - if (__builtin_constant_p (msgid)) \ - { \ - static char *__translation__; \ - static int __catalog_counter__; \ - if (! __translation__ \ - || __catalog_counter__ != _nl_msg_cat_cntr) \ - { \ - __translation__ = \ - dcgettext__ ((domainname), (msgid), (category)); \ - __catalog_counter__ = _nl_msg_cat_cntr; \ - } \ - result = __translation__; \ - } \ - else \ - result = dcgettext__ ((domainname), (msgid), (category)); \ - result; \ - })) - # endif - - The interesting thing here is the `__builtin_constant_p' predicate. -This is evaluated at compile time and so optimization can take place -immediately. Here two cases are distinguished: the argument to -`gettext' is not a constant value in which case simply the function -`dcgettext__' is called, the real implementation of the `dcgettext' -function. +selection changes) nor does it lead to legible code. - If the string argument *is* constant we can reuse the once gained -translation when the locale selection has not changed. This is exactly -what is done here. The `_nl_msg_cat_cntr' variable is defined in the -`loadmsgcat.c' which is available in `libintl.a' and is changed -whenever a new message catalog is loaded. + For this reason, GNU `gettext' caches previous translation results. +When the same translation is requested twice, with no new message +catalogs being loaded in between, `gettext' will, the second time, find +the result through a single cache lookup. File: gettext.info, Node: Comparison, Next: Using libintl.a, Prev: gettext, Up: Programmers @@ -130,9 +545,9 @@ beginning of each source file (or in a central header file) we define Even this definition can be avoided when the system supports the `gettext' function in its C library. When we compile this code the result is the same as if no NLS code is used. When you take a look at -the GNU `gettext' code you will see that we use `_("...")' instead of +the GNU `gettext' code you will see that we use `_("...")' instead of `gettext("...")'. This reduces the number of additional characters per -translatable string to *3* (in words: three). +translatable string to _3_ (in words: three). When now a production version of the program is needed we simply replace the definition @@ -150,7 +565,7 @@ program which does not depend on translations to be available, but which can use any that becomes available. The same procedure can be done for the `gettext_noop' invocations -(*note Special cases::.). First you can define `gettext_noop' to a +(*note Special cases::). First you can define `gettext_noop' to a no-op macro and later use the definition from `libintl.h'. Because this name is not used in Suns implementation of `libintl.h', you should consider the following code for your project: @@ -206,41 +621,9 @@ be very easy: is difficult one can also consider changing one of the conflicting string a little bit. But it is not impossible to overcome. - Translator note: It is perhaps appropriate here to tell those English -speaking programmers that the plural form of a noun cannot be formed by -appending a single `s'. Most other languages use different methods. -Even the above form is not general enough to cope with all languages. -Rafal Maszkowski <rzm@mat.uni.torun.pl> reports: - - In Polish we use e.g. plik (file) this way: - 1 plik - 2,3,4 pliki - 5-21 pliko'w - 22-24 pliki - 25-31 pliko'w - and so on (o' means 8859-2 oacute which should be rather okreska, - similar to aogonek). - - A workable approach might be to consider methods like the one used -for `LC_TIME' in the POSIX.2 standard. The value of the `alt_digits' -field can be up to 100 strings which represent the numbers 1 to 100. -Using this in a situation of an internationalized program means that an -array of translatable strings should be indexed by the number which -should represent. A small example: - - void - print_month_info (int month) - { - const char *month_pos[12] = - { N_("first"), N_("second"), N_("third"), N_("fourth"), - N_("fifth"), N_("sixth"), N_("seventh"), N_("eighth"), - N_("ninth"), N_("tenth"), N_("eleventh"), N_("twelfth") }; - printf (_("%s is the %s month\n"), nl_langinfo (MON_1 + month), - _(month_pos[month])); - } - -It should be obvious that this method is only reasonable for small -ranges of numbers. + `catgets' allows same original entry to have different translations, +but `gettext' has another, scalable approach for solving ambiguities of +this kind: *Note Ambiguities::. File: gettext.info, Node: Using libintl.a, Next: gettext grok, Prev: Comparison, Up: Programmers @@ -277,10 +660,7 @@ is a list comments: need to know how the used language is determined while executing the `gettext' function. The method which is presented here only works correctly with the GNU implementation of the `gettext' - functions. It is not possible with underlying `catgets' functions - or `gettext' functions from the systems C library. The exception - is of course the GNU C Library which uses the GNU `gettext' - Library for message handling. + functions. In the function `dcgettext' at every call the current setting of the highest priority environment variable is determined and used. @@ -309,7 +689,7 @@ is a list comments: the calling of the `dcgettext' function as long as no new catalog is loaded. But if `dcgettext' is not called the program also cannot find the `LANGUAGE' variable be changed (*note Optimized - gettext::.). A solution for this is very easy. Include the + gettext::). A solution for this is very easy. Include the following code in the language switching function. /* Change language. */ @@ -327,6 +707,7 @@ is a list comments: to select the language at runtime. Non-interactive programs (like all these little Unix tools) should never need this. + File: gettext.info, Node: Temp Programmers, Prev: gettext grok, Up: Programmers @@ -421,19 +802,19 @@ routines (catgets) for all other software. Bloated? recommend? At least for Linux, we need to attract as many software developers as possible. Hence we need to make it as easy for them to port their software as possible. Which means supporting `catgets'. We -will be implementing the `glocale' code within our `libc', but does +will be implementing the `libintl' code within our `libc', but does this mean we also have to incorporate another message catalog access scheme within our `libc' as well? And what about people who are going -to be using the `glocale' + non-`catgets' routines. When they port +to be using the `libintl' + non-`catgets' routines. When they port their software to other platforms, they're now going to have to include -the front-end (`glocale') code plus the back-end code (the non-`catgets' +the front-end (`libintl') code plus the back-end code (the non-`catgets' access routines) with their software instead of just including the -`glocale' code with their software. +`libintl' code with their software. Message catalog support is however only the tip of the iceberg. What about the data for the other locale categories. They also have a number of deficiencies. Are we going to abandon them as well and -develop another duplicate set of routines (should `glocale' expand +develop another duplicate set of routines (should `libintl' expand beyond message catalog support)? Like many parts of Unix that can be improved upon, we're stuck with @@ -478,7 +859,7 @@ Introduction 0 way to get maintainers, translators and users all together, so free software will gradually become able to speak many native languages. - The GNU `gettext' tool set contains *everything* maintainers need + The GNU `gettext' tool set contains _everything_ maintainers need for internationalizing their packages for messages. It also contains quite useful tools for helping translators at localizing messages to their native language, once a package has already been @@ -487,13 +868,13 @@ internationalized. To achieve the Translation Project, we need many interested people who like their own language and write it well, and who are also able to synergize with other translators speaking the same language. If you'd -like to volunteer to *work* at translating messages, please send mail +like to volunteer to _work_ at translating messages, please send mail to your translating team. Each team has its own mailing list, courtesy of Linux International. You may reach your translating team at the address `LL@li.org', replacing LL by the two-letter ISO 639 code for your language. -Language codes are *not* the same as country codes given in ISO 3166. +Language codes are _not_ the same as country codes given in ISO 3166. The following translating teams exist: Chinese `zh', Czech `cs', Danish `da', Dutch `nl', Esperanto `eo', @@ -510,7 +891,7 @@ body: subscribe - Keep in mind that team members should be interested in *working* at + Keep in mind that team members should be interested in _working_ at translations, or at solving translational difficulties, rather than merely lurking around. If your team does not exist yet and you want to start one, please write to `translation@iro.umontreal.ca'; you will @@ -578,7 +959,7 @@ concerns. Some of these doubts are presented and discussed, here. Some languages are not spoken by a very large number of people, so people speaking them sometimes consider that there may not be all that much demand such versions of free software packages. - Moreover, many people being *into computers*, in some countries, + Moreover, many people being _into computers_, in some countries, generally seem to prefer English versions of their software. On the other end, people might enjoy their own language a lot, and @@ -632,6 +1013,7 @@ concerns. Some of these doubts are presented and discussed, here. assembling a package prepared for localization, but not providing the localization routines themselves. + File: gettext.info, Node: Organization, Next: Information Flow, Prev: Discussions, Up: Translators @@ -769,7 +1151,7 @@ those who really care. internationalized programs is achieved is a difficult (and delicate) job. Knowing the latin character of French people (:-), if we take this the wrong way, we could end up nowhere, or spoil a lot of energies. -Maybe we should begin to address this problem seriously *before* GNU +Maybe we should begin to address this problem seriously _before_ GNU `gettext' become officially published. And I suspect that this means soon! @@ -798,313 +1180,4 @@ true in the free software community. Here are a few points to discuss: this group consists solely by me but I ask some others occasionally; this also seems to work). - -File: gettext.info, Node: Mailing Lists, Prev: National Teams, Up: Organization - -Mailing Lists -------------- - - If we get any inquiries about GNU `gettext', send them on to: - - `translation@iro.umontreal.ca' - - The `*-pretest' lists are quite useful to me, maybe the idea could -be generalized to many GNU, and non-GNU packages. But each maintainer -his/her way! - - Franc,ois, we have a mechanism in place here at `gnu.ai.mit.edu' to -track teams, support mailing lists for them and log members. We have a -slight preference that you use it. If this is OK with you, I can get -you clued in. - - Things are changing! A few years ago, when Daniel Fekete and I -asked for a mailing list for GNU localization, nested at the FSF, we -were politely invited to organize it anywhere else, and so did we. For -communicating with my pretesters, I later made a handful of mailing -lists located at iro.umontreal.ca and administrated by `majordomo'. -These lists have been *very* dependable so far... - - I suspect that the German team will organize itself a mailing list -located in Germany, and so forth for other countries. But before they -organize for true, it could surely be useful to offer mailing lists -located at the FSF to each national team. So yes, please explain me -how I should proceed to create and handle them. - - We should create temporary mailing lists, one per country, to help -people organize. Temporary, because once regrouped and structured, it -would be fair the volunteers from country bring back *their* list in -there and manage it as they want. My feeling is that, in the long run, -each team should run its own list, from within their country. There -also should be some central list to which all teams could subscribe as -they see fit, as long as each team is represented in it. - - -File: gettext.info, Node: Information Flow, Prev: Organization, Up: Translators - -Information Flow -================ - - There will surely be some discussion about this messages after the -packages are finally released. If people now send you some proposals -for better messages, how do you proceed? Jim, please note that right -now, as I put forward nearly a dozen of localizable programs, I receive -both the translations and the coordination concerns about them. - - If I put one of my things to pretest, Ulrich receives the -announcement and passes it on to the German team, who make last minute -revisions. Then he submits the translation files to me *as the -maintainer*. For free packages I do not maintain, I would not even -hear about it. This scheme could be made to work for the whole -Translation Project, I think. For security reasons, maybe Ulrich -(national coordinators, in fact) should update central registry kept at -the Translation Project (Jim, me, or Len's recruits) once in a while. - - In December/January, I was aggressively ready to internationalize -all of GNU, giving myself the duty of one small GNU package per week or -so, taking many weeks or months for bigger packages. But it does not -work this way. I first did all the things I'm responsible for. I've -nothing against some missionary work on other maintainers, but I'm also -loosing a lot of energy over it--same debates over again. - - And when the first localized packages are released we'll get a lot of -responses about ugly translations :-). Surely, and we need to have -beforehand a fairly good idea about how to handle the information flow -between the national teams and the package maintainers. - - Please start saving somewhere a quick history of each PO file. I -know for sure that the file format will change, allowing for comments. -It would be nice that each file has a kind of log, and references for -those who want to submit comments or gripes, or otherwise contribute. -I sent a proposal for a fast and flexible format, but it is not -receiving acceptance yet by the GNU deciders. I'll tell you when I -have more information about this. - - -File: gettext.info, Node: Maintainers, Next: Conclusion, Prev: Translators, Up: Top - -The Maintainer's View -********************* - - 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 (*note Users::.) 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. - -* Menu: - -* Flat and Non-Flat:: Flat or Non-Flat Directory Structures -* Prerequisites:: Prerequisite Works -* gettextize Invocation:: Invoking the `gettextize' Program -* Adjusting Files:: Files You Must Create or Alter - - -File: gettext.info, Node: Flat and Non-Flat, Next: Prerequisites, Prev: Maintainers, Up: Maintainers - -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". - - 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. - - -File: gettext.info, Node: Prerequisites, Next: gettextize Invocation, Prev: Flat and Non-Flat, Up: Maintainers - -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. - - * Before attempting to use you should install some other packages - first. Ensure that recent versions of GNU `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. - - * Your package should use Autoconf and have a `configure.in' file. - If it does not, you have to learn how. The Autoconf documentation - is quite well written, it is a good idea that you print it and get - familiar with it. - - * Your C sources should have already been modified according to - instructions given earlier in this manual. *Note Sources::. - - * Your `po/' directory should receive all PO files submitted to you - by the translator teams, each having `LL.po' as a name. This is - not usually easy to get translation work done before your package - gets internationalized and available! Since the cycle has to - start somewhere, the easiest for the maintainer is to start with - absolutely no PO files, and wait until various translator teams - get interested in your package, and submit PO files. - - 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. - - -File: gettext.info, Node: gettextize Invocation, Next: Adjusting Files, Prev: Prerequisites, Up: Maintainers - -Invoking the `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: - -`-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. - -`-h' -`--help' - Display this help and exit. - -`--version' - Output version information and exit. - - 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. - - 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). If the `po/' directory already - exists, it will be preserved along with the files it contains, and - only `Makefile.in.in' will be overwritten. - - 3. 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. - - - 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. diff --git a/doc/gettext.info-5 b/doc/gettext.info-5 index 0279fa5..61a1c7f 100644 --- a/doc/gettext.info-5 +++ b/doc/gettext.info-5 @@ -1,5 +1,5 @@ -This is Info file gettext.info, produced by Makeinfo version 1.68 from -the input file gettext.texi. +This is gettext.info, produced by makeinfo version 4.0 from +gettext.texi. INFO-DIR-SECTION GNU Gettext Utilities START-INFO-DIR-ENTRY @@ -13,7 +13,8 @@ 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. + Copyright (C) 1995, 1996, 1997, 1998, 2001 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 @@ -30,6 +31,317 @@ versions, except that this permission notice may be stated in a translation approved by the Foundation. +File: gettext.info, Node: Mailing Lists, Prev: National Teams, Up: Organization + +Mailing Lists +------------- + + If we get any inquiries about GNU `gettext', send them on to: + + `translation@iro.umontreal.ca' + + The `*-pretest' lists are quite useful to me, maybe the idea could +be generalized to many GNU, and non-GNU packages. But each maintainer +his/her way! + + Franc,ois, we have a mechanism in place here at `gnu.ai.mit.edu' to +track teams, support mailing lists for them and log members. We have a +slight preference that you use it. If this is OK with you, I can get +you clued in. + + Things are changing! A few years ago, when Daniel Fekete and I +asked for a mailing list for GNU localization, nested at the FSF, we +were politely invited to organize it anywhere else, and so did we. For +communicating with my pretesters, I later made a handful of mailing +lists located at iro.umontreal.ca and administrated by `majordomo'. +These lists have been _very_ dependable so far... + + I suspect that the German team will organize itself a mailing list +located in Germany, and so forth for other countries. But before they +organize for true, it could surely be useful to offer mailing lists +located at the FSF to each national team. So yes, please explain me +how I should proceed to create and handle them. + + We should create temporary mailing lists, one per country, to help +people organize. Temporary, because once regrouped and structured, it +would be fair the volunteers from country bring back _their_ list in +there and manage it as they want. My feeling is that, in the long run, +each team should run its own list, from within their country. There +also should be some central list to which all teams could subscribe as +they see fit, as long as each team is represented in it. + + +File: gettext.info, Node: Information Flow, Prev: Organization, Up: Translators + +Information Flow +================ + + There will surely be some discussion about this messages after the +packages are finally released. If people now send you some proposals +for better messages, how do you proceed? Jim, please note that right +now, as I put forward nearly a dozen of localizable programs, I receive +both the translations and the coordination concerns about them. + + If I put one of my things to pretest, Ulrich receives the +announcement and passes it on to the German team, who make last minute +revisions. Then he submits the translation files to me _as the +maintainer_. For free packages I do not maintain, I would not even +hear about it. This scheme could be made to work for the whole +Translation Project, I think. For security reasons, maybe Ulrich +(national coordinators, in fact) should update central registry kept at +the Translation Project (Jim, me, or Len's recruits) once in a while. + + In December/January, I was aggressively ready to internationalize +all of GNU, giving myself the duty of one small GNU package per week or +so, taking many weeks or months for bigger packages. But it does not +work this way. I first did all the things I'm responsible for. I've +nothing against some missionary work on other maintainers, but I'm also +loosing a lot of energy over it--same debates over again. + + And when the first localized packages are released we'll get a lot of +responses about ugly translations :-). Surely, and we need to have +beforehand a fairly good idea about how to handle the information flow +between the national teams and the package maintainers. + + Please start saving somewhere a quick history of each PO file. I +know for sure that the file format will change, allowing for comments. +It would be nice that each file has a kind of log, and references for +those who want to submit comments or gripes, or otherwise contribute. +I sent a proposal for a fast and flexible format, but it is not +receiving acceptance yet by the GNU deciders. I'll tell you when I +have more information about this. + + +File: gettext.info, Node: Maintainers, Next: Conclusion, Prev: Translators, Up: Top + +The Maintainer's View +********************* + + 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 (*note Users::) 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. + +* Menu: + +* Flat and Non-Flat:: Flat or Non-Flat Directory Structures +* Prerequisites:: Prerequisite Works +* gettextize Invocation:: Invoking the `gettextize' Program +* Adjusting Files:: Files You Must Create or Alter + + +File: gettext.info, Node: Flat and Non-Flat, Next: Prerequisites, Prev: Maintainers, Up: Maintainers + +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". + + 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. + + +File: gettext.info, Node: Prerequisites, Next: gettextize Invocation, Prev: Flat and Non-Flat, Up: Maintainers + +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. + + * Before attempting to use you should install some other packages + first. Ensure that recent versions of GNU `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. + + * Your package should use Autoconf and have a `configure.in' file. + If it does not, you have to learn how. The Autoconf documentation + is quite well written, it is a good idea that you print it and get + familiar with it. + + * Your C sources should have already been modified according to + instructions given earlier in this manual. *Note Sources::. + + * Your `po/' directory should receive all PO files submitted to you + by the translator teams, each having `LL.po' as a name. This is + not usually easy to get translation work done before your package + gets internationalized and available! Since the cycle has to + start somewhere, the easiest for the maintainer is to start with + absolutely no PO files, and wait until various translator teams + get interested in your package, and submit PO files. + + + 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. + + +File: gettext.info, Node: gettextize Invocation, Next: Adjusting Files, Prev: Prerequisites, Up: Maintainers + +Invoking the `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: + +`-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. + +`-h' +`--help' + Display this help and exit. + +`--version' + Output version information and exit. + + 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. + + 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). If the `po/' directory already + exists, it will be preserved along with the files it contains, and + only `Makefile.in.in' will be overwritten. + + 3. 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. + + + 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. + + File: gettext.info, Node: Adjusting Files, Prev: gettextize Invocation, Up: Maintainers Files You Must Create or Alter @@ -76,15 +388,14 @@ needing translation. Here is an example of such a file: lib/xmalloc.c # Package source files - src/gettextp.c + src/gettext.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. +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 @@ -120,7 +431,7 @@ File: gettext.info, Node: configure.in, Next: aclocal, Prev: po/POTFILES.in, 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::.). + environment variable (*note Installers::). 3. Check for internationalization support. @@ -162,7 +473,7 @@ 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 +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. @@ -180,10 +491,10 @@ File: gettext.info, Node: acconfig, Next: Makefile, Prev: aclocal, Up: Adjus 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'. +`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 diff --git a/doc/version.texi b/doc/version.texi index c250ceb..947f5f7 100644 --- a/doc/version.texi +++ b/doc/version.texi @@ -1,3 +1,3 @@ -@set UPDATED 7 January 2001 +@set UPDATED 31 January 2001 @set EDITION 0.10.36 @set VERSION 0.10.36 |