From 823080739341685f874817d27a175ba10596f630 Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Fri, 30 Mar 2001 12:35:36 +0000 Subject: Regenerated. --- doc/gettext.info-4 | 341 ++++++++++++++++++++++++----------------------------- 1 file changed, 157 insertions(+), 184 deletions(-) (limited to 'doc/gettext.info-4') diff --git a/doc/gettext.info-4 b/doc/gettext.info-4 index bc0214e..8d710c7 100644 --- a/doc/gettext.info-4 +++ b/doc/gettext.info-4 @@ -31,6 +31,142 @@ versions, except that this permission notice may be stated in a translation approved by the Foundation.  +File: gettext.info, Node: gettext, Next: Comparison, Prev: catgets, Up: Programmers + +About `gettext' +=============== + + The definition of the `gettext' interface comes from a Uniforum +proposal and it is followed by at least one major Unix vendor (Sun) in +its last developments. It is not specified in any official standard, +though. + + The main points about this solution is that it does not follow the +method of normal file handling (open-use-close) and that it does not +burden the programmer so many task, especially the unique key handling. +Of course here is also a unique key needed, but this key is the message +itself (how long or short it is). See *Note Comparison:: for a more +detailed comparison of the two methods. + + The following section contains a rather detailed description of the +interface. We make it that detailed because this is the interface we +chose for the GNU `gettext' Library. Programmers interested in using +this library will be interested in this description. + +* Menu: + +* 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 + + +File: gettext.info, Node: Interface to gettext, Next: Ambiguities, Prev: gettext, Up: gettext + +The Interface +------------- + + The minimal functionality an interface must have is a) to select a +domain the strings are coming from (a single domain for all programs is +not reasonable because its construction and maintenance is difficult, +perhaps impossible) and b) to access a string in a selected domain. + + This is principally the description of the `gettext' interface. It +has an global domain which unqualified usages reference. Of course this +domain is selectable by the user. + + char *textdomain (const char *domain_name); + + This provides the possibility to change or query the current status +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 +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 +this by the fact that no translations are provided. + +To use a domain set by `textdomain' the function + + char *gettext (const char *msgid); + + is to be used. This is the simplest reasonable form one can imagine. +The translation of the string MSGID is returned if it is available in +the current domain. If not available the argument itself is returned. +If the argument is `NULL' the result is undefined. + + One things which should come into mind is that no explicit +dependency to the used domain is given. The current value of the +domain for the `LC_MESSAGES' locale is used. If this changes between +two executions of the same `gettext' call in the program, both calls +reference a different message catalog. + + For the easiest case, which is normally used in internationalized +packages, once at the beginning of execution a call to `textdomain' is +issued, setting the domain to a unique name, normally the package name. +In the following code all strings which have to be translated are +filtered through the gettext function. That's all, the package speaks +your language. + + +File: gettext.info, Node: Ambiguities, Next: Locating Catalogs, Prev: Interface to gettext, Up: gettext + +Solving Ambiguities +------------------- + + While this single name domain work good for most applications there +might be the need to get translations from more than one domain. Of +course one could switch between different domains with calls to +`textdomain', but this is really not convenient nor is it fast. A +possible situation could be one case discussing while this writing: all +error messages of functions in the set of common used functions should +go into a separate domain `error'. By this mean we would only need to +translate them once. + +For this reasons there are two more functions to retrieve strings: + + char *dgettext (const char *domain_name, const char *msgid); + char *dcgettext (const char *domain_name, const char *msgid, + int category); + + Both take an additional argument at the first place, which +corresponds to the argument of `textdomain'. The third argument of +`dcgettext' allows to use another locale but `LC_MESSAGES'. But I +really don't know where this can be useful. If the DOMAIN_NAME is +`NULL' or CATEGORY has an value beside the known ones, the result is +undefined. It should also be noted that this function is not part of +the second known implementation of this function family, the one found +in Solaris. + + A second ambiguity can arise by the fact, that perhaps more than one +domain has the same name. This can be solved by specifying where the +needed message catalog files can be found. + + char *bindtextdomain (const char *domain_name, + const char *dir_name); + + Calling this function binds the given domain to a file in the +specified directory (how this file is determined follows below). +Especially a file in the systems default place is not favored against +the specified file anymore (as it would be by solely using +`textdomain'). A `NULL' pointer for the DIR_NAME parameter returns the +binding associated with DOMAIN_NAME. If DOMAIN_NAME itself is `NULL' +nothing happens and a `NULL' pointer is returned. Here again as for +all the other functions is true that none of the return value must be +changed! + + It is important to remember that relative path names for the +DIR_NAME parameter can be trouble. Since the path is always computed +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: Charset conversion, Prev: Ambiguities, Up: gettext Locating Message Catalog Files @@ -211,7 +347,7 @@ purpose. An example for the us of this function is: - printf (ngettext ("%d file removed", "%d files removed", n), n); + 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 @@ -246,10 +382,10 @@ 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: +the header entry of the PO file (the one with the empty `msgid' string). +The plural form information looks like this: - nplurals=2; plural=n == 1 ? 0 : 1 + Plural-Forms: 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 @@ -272,7 +408,7 @@ Only one form: distinction between the singular and plural form. An appropriate header entry would look like this: - nplurals=1; plural=0 + Plural-Forms: nplurals=1; plural=0; Languages with this property include: @@ -289,7 +425,7 @@ 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 + Plural-Forms: nplurals=2; plural=n != 1; (Note: this uses the feature of C expressions that boolean expressions have to value zero or one.) @@ -318,7 +454,7 @@ Two forms, singular used for zero and one Exceptional case in the language family. The header entry would be: - nplurals=2; plural=n>1 + Plural-Forms: nplurals=2; plural=n>1; Languages with this property include: @@ -328,7 +464,7 @@ Two forms, singular used for zero and one Three forms, special cases for one and two The header entry would be: - nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2 + Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2; Languages with this property include: @@ -338,7 +474,8 @@ Three forms, special cases for one and two 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 + Plural-Forms: nplurals=3; \ + plural=n==1 ? 0 : n%10>=2 && n%10<=4 ? 1 : 2; Languages with this property include: @@ -348,8 +485,9 @@ Three forms, special case for one and all numbers ending in 2, 3, or 4 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 + Plural-Forms: 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.) @@ -361,7 +499,9 @@ Three forms, special case for one and some numbers ending in 2, 3, or 4 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 + Plural-Forms: nplurals=4; \ + plural=n==1 ? 0 : \ + n%10==2 ? 1 : n%10==3 || n%10==4 ? 2 : 3; Languages with this property include: @@ -635,11 +775,11 @@ self-contained. I.e., you can use it in your own programs without providing additional functions. The `Makefile' will put the header and the library in directories selected using the `$(prefix)'. - One exception of the above is found on HP-UX systems. Here the C -library does not contain the `alloca' function (and the HP compiler does -not generate it inlined). But it is not intended to rewrite the whole -library just because of this dumb system. Instead include the `alloca' -function in all package you use the `libintl.a' in. + One exception of the above is found on HP-UX 10.01 systems. Here +the C library does not contain the `alloca' function (and the HP +compiler does not generate it inlined). But it is not intended to +rewrite the whole library just because of this dumb system. Instead +include the `alloca' function in all package you use the `libintl.a' in.  File: gettext.info, Node: gettext grok, Next: Temp Programmers, Prev: Using libintl.a, Up: Programmers @@ -1013,170 +1153,3 @@ concerns. Some of these doubts are presented and discussed, here. the localization routines themselves. - -File: gettext.info, Node: Organization, Next: Information Flow, Prev: Discussions, Up: Translators - -Organization -============ - - On a larger scale, the true solution would be to organize some kind -of fairly precise set up in which volunteers could participate. I gave -some thought to this idea lately, and realize there will be some touchy -points. I thought of writing to Richard Stallman to launch such a -project, but feel it might be good to shake out the ideas between -ourselves first. Most probably that Linux International has some -experience in the field already, or would like to orchestrate the -volunteer work, maybe. Food for thought, in any case! - - I guess we have to setup something early, somehow, that will help -many possible contributors of the same language to interlock and avoid -work duplication, and further be put in contact for solving together -problems particular to their tongue (in most languages, there are many -difficulties peculiar to translating technical English). My Swedish -contributor acknowledged these difficulties, and I'm well aware of them -for French. - - This is surely not a technical issue, but we should manage so the -effort of locale contributors be maximally useful, despite the national -team layer interface between contributors and maintainers. - - The Translation Project needs some setup for coordinating language -coordinators. Localizing evolving programs will surely become a -permanent and continuous activity in the free software community, once -well started. The setup should be minimally completed and tested -before GNU `gettext' becomes an official reality. The e-mail address -`translation@iro.umontreal.ca' has been setup for receiving offers from -volunteers and general e-mail on these topics. This address reaches -the Translation Project coordinator. - -* Menu: - -* Central Coordination:: Central Coordination -* National Teams:: National Teams -* Mailing Lists:: Mailing Lists - - -File: gettext.info, Node: Central Coordination, Next: National Teams, Prev: Organization, Up: Organization - -Central Coordination --------------------- - - I also think GNU will need sooner than it thinks, that someone setup -a way to organize and coordinate these groups. Some kind of group of -groups. My opinion is that it would be good that GNU delegates this -task to a small group of collaborating volunteers, shortly. Perhaps in -`gnu.announce' a list of this national committee's can be published. - - My role as coordinator would simply be to refer to Ulrich any German -speaking volunteer interested to localization of free software -packages, and maybe helping national groups to initially organize, -while maintaining national registries for until national groups are -ready to take over. In fact, the coordinator should ease volunteers to -get in contact with one another for creating national teams, which -should then select one coordinator per language, or country -(regionalized language). If well done, the coordination should be -useful without being an overwhelming task, the time to put delegations -in place. - - -File: gettext.info, Node: National Teams, Next: Mailing Lists, Prev: Central Coordination, Up: Organization - -National Teams --------------- - - I suggest we look for volunteer coordinators/editors for individual -languages. These people will scan contributions of translation files -for various programs, for their own languages, and will ensure high and -uniform standards of diction. - - From my current experience with other people in these days, those who -provide localizations are very enthusiastic about the process, and are -more interested in the localization process than in the program they -localize, and want to do many programs, not just one. This seems to -confirm that having a coordinator/editor for each language is a good -idea. - - We need to choose someone who is good at writing clear and concise -prose in the language in question. That is hard--we can't check it -ourselves. So we need to ask a few people to judge each others' -writing and select the one who is best. - - I announce my prerelease to a few dozen people, and you would not -believe all the discussions it generated already. I shudder to think -what will happen when this will be launched, for true, officially, -world wide. Who am I to arbitrate between two Czekolsovak users -contradicting each other, for example? - - I assume that your German is not much better than my French so that -I would not be able to judge about these formulations. What I would -suggest is that for each language there is a group for people who -maintain the PO files and judge about changes. I suspect there will be -cultural differences between how such groups of people will behave. -Some will have relaxed ways, reach consensus easily, and have anyone of -the group relate to the maintainers, while others will fight to death, -organize heavy administrations up to national standards, and use strict -channels. - - The German team is putting out a good example. Right now, they are -maybe half a dozen people revising translations of each other and -discussing the linguistic issues. I do not even have all the names. -Ulrich Drepper is taking care of coordinating the German team. He -subscribed to all my pretest lists, so I do not even have to warn him -specifically of incoming releases. - - I'm sure, that is a good idea to get teams for each language working -on translations. That will make the translations better and more -consistent. - -* Menu: - -* Sub-Cultures:: Sub-Cultures -* Organizational Ideas:: Organizational Ideas - - -File: gettext.info, Node: Sub-Cultures, Next: Organizational Ideas, Prev: National Teams, Up: National Teams - -Sub-Cultures -............ - - Taking French for example, there are a few sub-cultures around -computers which developed diverging vocabularies. Picking volunteers -here and there without addressing this problem in an organized way, -soon in the project, might produce a distasteful mix of -internationalized programs, and possibly trigger endless quarrels among -those who really care. - - Keeping some kind of unity in the way French localization of -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 -`gettext' become officially published. And I suspect that this means -soon! - - -File: gettext.info, Node: Organizational Ideas, Prev: Sub-Cultures, Up: National Teams - -Organizational Ideas -.................... - - I expect the next big changes after the official release. Please -note that I use the German translation of the short GPL message. We -need to set a few good examples before the localization goes out for -true in the free software community. Here are a few points to discuss: - - * Each group should have one FTP server (at least one master). - - * The files on the server should reflect the latest version (of - course!) and it should also contain a RCS directory with the - corresponding archives (I don't have this now). - - * There should also be a ChangeLog file (this is more useful than the - RCS archive but can be generated automatically from the later by - Emacs). - - * A "core group" should judge about questionable changes (for now - this group consists solely by me but I ask some others - occasionally; this also seems to work). - - -- cgit v1.1