diff options
Diffstat (limited to 'doc/gettext.info-4')
-rw-r--r-- | doc/gettext.info-4 | 895 |
1 files changed, 484 insertions, 411 deletions
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. |