diff options
Diffstat (limited to 'doc/gettext.info-6')
-rw-r--r-- | doc/gettext.info-6 | 1137 |
1 files changed, 1137 insertions, 0 deletions
diff --git a/doc/gettext.info-6 b/doc/gettext.info-6 new file mode 100644 index 0000000..e31199b --- /dev/null +++ b/doc/gettext.info-6 @@ -0,0 +1,1137 @@ +This is gettext.info, produced by makeinfo version 4.0 from +gettext.texi. + +INFO-DIR-SECTION GNU Gettext Utilities +START-INFO-DIR-ENTRY +* Gettext: (gettext). GNU gettext utilities. +* gettextize: (gettext)gettextize Invocation. Prepare a package for gettext. +* msgfmt: (gettext)msgfmt Invocation. Make MO files out of PO files. +* msgmerge: (gettext)msgmerge Invocation. Update two PO files into one. +* xgettext: (gettext)xgettext Invocation. Extract strings into a PO file. +END-INFO-DIR-ENTRY + + This file provides documentation for GNU `gettext' utilities. It +also serves as a reference for the free Translation Project. + + Copyright (C) 1995, 1996, 1997, 1998, 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 +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + +File: gettext.info, Node: Trans Intro 1, Next: Discussions, Prev: Trans Intro 0, Up: Translators + +Introduction 1 +============== + + This is now official, GNU is going international! Here is the +announcement submitted for the January 1995 GNU Bulletin: + + A handful of GNU packages have already been adapted and provided + with message translations for several languages. Translation + teams have begun to organize, using these packages as a starting + point. But there are many more packages and many languages for + which we have no volunteer translators. If you'd like to + volunteer to work at translating messages, please send mail to + `translation@iro.umontreal.ca' indicating what language(s) you can + work on. + + This document should answer many questions for those who are curious +about the process or would like to contribute. Please at least skim +over it, hoping to cut down a little of the high volume of e-mail +generated by this collective effort towards internationalization of +free software. + + Most free programming which is widely shared is done in English, and +currently, English is used as the main communicating language between +national communities collaborating to free software. This very document +is written in English. This will not change in the foreseeable future. + + However, there is a strong appetite from national communities for +having more software able to write using national language and habits, +and there is an on-going effort to modify free software in such a way +that it becomes able to do so. The experiments driven so far raised an +enthusiastic response from pretesters, so we believe that +internationalization of free software is dedicated to succeed. + + For suggestion clarifications, additions or corrections to this +document, please e-mail to `translation@iro.umontreal.ca'. + + +File: gettext.info, Node: Discussions, Next: Organization, Prev: Trans Intro 1, Up: Translators + +Discussions +=========== + + Facing this internationalization effort, a few users expressed their +concerns. Some of these doubts are presented and discussed, here. + + * Smaller groups + + 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, + generally seem to prefer English versions of their software. + + On the other end, people might enjoy their own language a lot, and + be very motivated at providing to themselves the pleasure of + having their beloved free software speaking their mother tongue. + They do themselves a personal favor, and do not pay that much + attention to the number of people beneficiating of their work. + + * Misinterpretation + + Other users are shy to push forward their own language, seeing in + this some kind of misplaced propaganda. Someone thought there + must be some users of the language over the networks pestering + other people with it. + + But any spoken language is worth localization, because there are + people behind the language for whom the language is important and + dear to their hearts. + + * Odd translations + + The biggest problem is to find the right translations so that + everybody can understand the messages. Translations are usually a + little odd. Some people get used to English, to the extent they + may find translations into their own language "rather pushy, + obnoxious and sometimes even hilarious." As a French speaking + man, I have the experience of those instruction manuals for goods, + so poorly translated in French in Korea or Taiwan... + + The fact is that we sometimes have to create a kind of national + computer culture, and this is not easy without the collaboration of + many people liking their mother tongue. This is why translations + are better achieved by people knowing and loving their own + language, and ready to work together at improving the results they + obtain. + + * Dependencies over the GPL or LGPL + + Some people wonder if using GNU `gettext' necessarily brings their + package under the protective wing of the GNU General Public + License or the GNU Library General Public License, when they do + not want to make their program free, or want other kinds of + freedom. The simplest answer is "normally not". + + The GNU `gettext' library, i.e. the contents of `libintl', is + covered by the GNU Library General Public License. The rest of + the GNU `gettext' package is covered by the GNU General Public + License. + + The mere marking of localizable strings in a package, or + conditional inclusion of a few lines for initialization, is not + really including GPL'ed or LGPL'ed code. However, since the + localization routines in `libintl' are under the LGPL, the LGPL + needs to be considered. It gives the right to distribute the + complete unmodified source of `libintl' even with non-free + programs. It also gives the right to use `libintl' as a shared + library, even for non-free programs. But it gives the right to + use `libintl' as a static library or to incorporate `libintl' into + another library only to free software. + + + +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). + + + +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: Programming Languages, 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". + + 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. Also, GNU +`gettext''s libintl sources consist of C sources, shell scripts, `sed' +scripts and complicated Makefile rules, which don't fit well into an +existing flat structure. For these reasons, we recommend to use +non-flat approach in this case as well. + + 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. + + +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 `gettextize' 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' or + `configure.ac' 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. + +`--intl' + Install the libintl sources in a subdirectory named `intl/'. This + libintl will be used to provide internationalization on systems + that don't have GNU libintl installed. If this option is omitted, + the call to `AM_GNU_GETTEXT' in `configure.in' should read: + `AM_GNU_GETTEXT([external])', and internationalization will not be + enabled on systems lacking GNU gettext. + +`-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) and a few auxiliary files. If + the `po/' directory already exists, it will be preserved along + with the files it contains, and only `Makefile.in.in' and the + auxiliary files will be overwritten. + + 3. Only of `--intl' has been specified: 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 +============================== + + Besides files which are automatically added through `gettextize', +there are many files needing revision for properly interacting with GNU +`gettext'. If you are closely following GNU standards for Makefile +engineering and auto-configuration, the adaptations should be easier to +achieve. Here is a point by point description of the changes needed in +each. + + So, here comes a list of files, each one followed by a description of +all alterations it needs. Many examples are taken out from the GNU +`gettext' 0.11-pre2 distribution itself. You may indeed refer to the +source code of the GNU `gettext' package, as it is intended to be a +good example and master implementation for using its own functionality. + +* Menu: + +* po/POTFILES.in:: `POTFILES.in' in `po/' +* po/LINGUAS:: `LINGUAS' in `po/' +* po/Makevars:: `Makefile' pieces in `po/' +* configure.in:: `configure.in' at top level +* config.guess:: `config.guess', `config.sub' at top level +* aclocal:: `aclocal.m4' at top level +* acconfig:: `acconfig.h' at top level +* Makefile:: `Makefile.in' at top level +* src/Makefile:: `Makefile.in' in `src/' + + +File: gettext.info, Node: po/POTFILES.in, Next: po/LINGUAS, Prev: Adjusting Files, Up: Adjusting Files + +`POTFILES.in' in `po/' +---------------------- + + The `po/' directory should receive a file named `POTFILES.in'. This +file tells which files, among all program sources, have marked strings +needing translation. Here is an example of such a file: + + # List of source files containing translatable strings. + # Copyright (C) 1995 Free Software Foundation, Inc. + + # Common library files + lib/error.c + lib/getopt.c + lib/xmalloc.c + + # Package source files + src/gettext.c + src/msgfmt.c + src/xgettext.c + +Hash-marked comments and white lines are ignored. All other lines list +those source files containing strings marked for translation (*note +Mark Keywords::), in a notation relative to the top level of your whole +distribution, rather than the location of the `POTFILES.in' file itself. + + +File: gettext.info, Node: po/LINGUAS, Next: po/Makevars, Prev: po/POTFILES.in, Up: Adjusting Files + +`LINGUAS' in `po/' +------------------ + + The `po/' directory should also receive a file named `LINGUAS'. +This file contains the list of available translations. It is a +whitespace separated list. Hash-marked comments and white lines are +ignored. Here is an example file: + + # Set of available languages. + de fr + +This example means that German and French PO files are available, so +that these languages are currently supported by your package. If you +want to further restrict, at installation time, the set of installed +languages, this should not be done by modifying the `LINGUAS' file, but +rather by using the `LINGUAS' environment variable (*note Installers::). + + +File: gettext.info, Node: po/Makevars, Next: configure.in, Prev: po/LINGUAS, Up: Adjusting Files + +`Makefile' pieces in `po/' +-------------------------- + + The `po/' directory also has a file named `Makevars'. It can be +left unmodified if your package has a single message domain and, +accordingly, a single `po/' directory. Only packages which have +multiple `po/' directories at different locations need to adjust the +three variables defined in `Makevars'. + + `po/Makevars' gets inserted into the `po/Makefile' when the latter +is created. At the same time, all files called `Rules-*' in the `po/' +directory get appended to the `po/Makefile'. They present an +opportunity to add rules for special PO files to the Makefile, without +needing to mess with `po/Makefile.in.in'. + + GNU gettext comes with a `Rules-quot' file, containing rules for +building catalogs `en@quot.po' and `en@boldquot.po'. The effect of +`en@quot.po' is that people who set their `LANGUAGE' environment +variable to `en@quot' will get messages with proper looking symmetric +Unicode quotation marks instead of abusing the ASCII grave accent and +the ASCII apostrophe for indicating quotations. To enable this catalog, +simply add `en@quot' to the `po/LINGUAS' file. The effect of +`en@boldquot.po' is that people who set `LANGUAGE' to `en@boldquot' +will get not only proper quotation marks, but also the quoted text will +be shown in a bold font on terminals and consoles. This catalog is +useful only for command-line programs, not GUI programs. To enable it, +similarly add `en@boldquot' to the `po/LINGUAS' file. + + +File: gettext.info, Node: configure.in, Next: config.guess, Prev: po/Makevars, Up: Adjusting Files + +`configure.in' at top level +--------------------------- + + `configure.in' or `configure.ac' - this is the source from which +`autoconf' generates the `configure' script. + + 1. Declare the package and version. + + This is done by a set of lines like these: + + PACKAGE=gettext + VERSION=0.11-pre2 + AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE") + AC_DEFINE_UNQUOTED(VERSION, "$VERSION") + AC_SUBST(PACKAGE) + AC_SUBST(VERSION) + + Of course, you replace `gettext' with the name of your package, + and `0.11-pre2' by its version numbers, exactly as they should + appear in the packaged `tar' file name of your distribution + (`gettext-0.11-pre2.tar.gz', here). + + 2. Check for internationalization support. + + Here is the main `m4' macro for triggering internationalization + support. Just add this line to `configure.in': + + AM_GNU_GETTEXT + + This call is purposely simple, even if it generates a lot of + configure time checking and actions. + + If you have suppressed the `intl/' subdirectory by calling + `gettextize' without `--intl' option, this call should read + + AM_GNU_GETTEXT([external]) + + 3. Have output files created. + + The `AC_OUTPUT' directive, at the end of your `configure.in' file, + needs to be modified in two ways: + + AC_OUTPUT([EXISTING CONFIGURATION FILES intl/Makefile po/Makefile.in], + [EXISTING ADDITIONAL ACTIONS]) + + The modification to the first argument to `AC_OUTPUT' asks for + substitution in the `intl/' and `po/' directories. Note the `.in' + suffix used for `po/' only. This is because the distributed file + is really `po/Makefile.in.in'. + + If you have suppressed the `intl/' subdirectory by calling + `gettextize' without `--intl' option, then you don't need to add + `intl/Makefile' to the `AC_OUTPUT' line. + + + +File: gettext.info, Node: config.guess, Next: aclocal, Prev: configure.in, Up: Adjusting Files + +`config.guess', `config.sub' at top level +----------------------------------------- + + If you don't have suppressed the `intl/' subdirectory, you need to +add the GNU `config.guess' and `config.sub' files to your distribution. +They are needed because the `intl/' directory has platform dependent +support for determining the locale's character encoding and therefore +needs to identify the platform. + + You can obtain the newest version of `config.guess' and `config.sub' +from `ftp://ftp.gnu.org/pub/gnu/config/'. Less recent versions are +also contained in the GNU `automake' and GNU `libtool' packages. + + Normally, `config.guess' and `config.sub' are put at the top level +of a distribution. But it is also possible to put them in a +subdirectory, altogether with other configuration support files like +`install-sh', `ltconfig', `ltmain.sh', `mkinstalldirs' or `missing'. +All you need to do, other than moving the files, is to add the +following line to your `configure.in'. + + AC_CONFIG_AUX_DIR([SUBDIR]) + + +File: gettext.info, Node: aclocal, Next: acconfig, Prev: config.guess, Up: Adjusting Files + +`aclocal.m4' at top level +------------------------- + + If you do not have an `aclocal.m4' file in your distribution, the +simplest is to concatenate the files `codeset.m4', `gettext.m4', +`glibc21.m4', `iconv.m4', `isc-posix.m4', `lcmessage.m4', `progtest.m4' +from GNU `gettext''s `m4/' directory into a single file. If you have +suppressed the `intl/' directory, only `gettext.m4', `iconv.m4', +`progtest.m4' need to be concatenated. + + If you already have an `aclocal.m4' file, then you will have to +merge the said macro files into your `aclocal.m4'. Note that if you +are upgrading from a previous release of GNU `gettext', you should most +probably _replace_ the macros (`AM_GNU_GETTEXT', etc.), as they usually +change a little from one release of GNU `gettext' to the next. Their +contents may vary as we get more experience with strange systems out +there. + + These macros check for the internationalization support functions +and related informations. Hopefully, once stabilized, these macros +might be integrated in the standard Autoconf set, because this piece of +`m4' code will be the same for all projects using GNU `gettext'. + + +File: gettext.info, Node: acconfig, Next: Makefile, Prev: aclocal, Up: Adjusting Files + +`acconfig.h' at top level +------------------------- + + Earlier GNU `gettext' releases required to put definitions for +`ENABLE_NLS', `HAVE_GETTEXT' and `HAVE_LC_MESSAGES', `HAVE_STPCPY', +`PACKAGE' and `VERSION' into an `acconfig.h' file. This is not needed +any more; you can remove them from your `acconfig.h' file unless your +package uses them independently from the `intl/' directory. + + +File: gettext.info, Node: Makefile, Next: src/Makefile, Prev: acconfig, Up: Adjusting Files + +`Makefile.in' at top level +-------------------------- + + Here are a few modifications you need to make to your main, top-level +`Makefile.in' file. + + 1. Add the following lines near the beginning of your `Makefile.in', + so the `dist:' goal will work properly (as explained further down): + + PACKAGE = @PACKAGE@ + VERSION = @VERSION@ + + 2. Add file `ABOUT-NLS' to the `DISTFILES' definition, so the file + gets distributed. + + 3. Wherever you process subdirectories in your `Makefile.in', be sure + you also process dir subdirectories `intl' and `po'. Special + rules in the `Makefiles' take care for the case where no + internationalization is wanted. + + If you are using Makefiles, either generated by automake, or + hand-written so they carefully follow the GNU coding standards, + the effected goals for which the new subdirectories must be + handled include `installdirs', `install', `uninstall', `clean', + `distclean'. + + Here is an example of a canonical order of processing. In this + example, we also define `SUBDIRS' in `Makefile.in' for it to be + further used in the `dist:' goal. + + SUBDIRS = doc intl lib src @POSUB@ + + Note that you must arrange for `make' to descend into the `intl' + directory before descending into other directories containing code + which make use of the `libintl.h' header file. For this reason, + here we mention `intl' before `lib' and `src'. + + 4. A delicate point is the `dist:' goal, as both `intl/Makefile' and + `po/Makefile' will later assume that the proper directory has been + set up from the main `Makefile'. Here is an example at what the + `dist:' goal might look like: + + distdir = $(PACKAGE)-$(VERSION) + dist: Makefile + rm -fr $(distdir) + mkdir $(distdir) + chmod 777 $(distdir) + for file in $(DISTFILES); do \ + ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \ + done + for subdir in $(SUBDIRS); do \ + mkdir $(distdir)/$$subdir || exit 1; \ + chmod 777 $(distdir)/$$subdir; \ + (cd $$subdir && $(MAKE) $@) || exit 1; \ + done + tar chozf $(distdir).tar.gz $(distdir) + rm -fr $(distdir) + + + +File: gettext.info, Node: src/Makefile, Prev: Makefile, Up: Adjusting Files + +`Makefile.in' in `src/' +----------------------- + + Some of the modifications made in the main `Makefile.in' will also +be needed in the `Makefile.in' from your package sources, which we +assume here to be in the `src/' subdirectory. Here are all the +modifications needed in `src/Makefile.in': + + 1. In view of the `dist:' goal, you should have these lines near the + beginning of `src/Makefile.in': + + PACKAGE = @PACKAGE@ + VERSION = @VERSION@ + + 2. If not done already, you should guarantee that `top_srcdir' gets + defined. This will serve for `cpp' include files. Just add the + line: + + top_srcdir = @top_srcdir@ + + 3. You might also want to define `subdir' as `src', later allowing + for almost uniform `dist:' goals in all your `Makefile.in'. At + list, the `dist:' goal below assume that you used: + + subdir = src + + 4. The `main' function of your program will normally call + `bindtextdomain' (see *note Triggering::), like this: + + bindtextdomain (PACKAGE, LOCALEDIR); + + To make LOCALEDIR known to the program, add the following lines to + Makefile.in: + + datadir = @datadir@ + localedir = $(datadir)/locale + DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@ + + Note that `@datadir@' defaults to `$(prefix)/share', thus + `$(localedir)' defaults to `$(prefix)/share/locale'. + + 5. You should ensure that the final linking will use `@INTLLIBS@' as + a library. An easy way to achieve this is to manage that it gets + into `LIBS', like this: + + LIBS = @INTLLIBS@ @LIBS@ + + In most packages internationalized with GNU `gettext', one will + find a directory `lib/' in which a library containing some helper + functions will be build. (You need at least the few functions + which the GNU `gettext' Library itself needs.) However some of + the functions in the `lib/' also give messages to the user which + of course should be translated, too. Taking care of this, the + support library (say `libsupport.a') should be placed before + `@INTLLIBS@' and `@LIBS@' in the above example. So one has to + write this: + + LIBS = ../lib/libsupport.a @INTLLIBS@ @LIBS@ + + 6. You should also ensure that directory `intl/' will be searched for + C preprocessor include files in all circumstances. So, you have to + manage so both `-I../intl' and `-I$(top_srcdir)/intl' will be + given to the C compiler. + + 7. Your `dist:' goal has to conform with others. Here is a + reasonable definition for it: + + distdir = ../$(PACKAGE)-$(VERSION)/$(subdir) + dist: Makefile $(DISTFILES) + for file in $(DISTFILES); do \ + ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \ + done + + + +File: gettext.info, Node: Programming Languages, Next: Conclusion, Prev: Maintainers, Up: Top + +Other Programming Languages +*************************** + + While the presentation of `gettext' focuses mostly on C and +implicitly applies to C++ as well, its scope is far broader than that: +Many programming languages, scripting languages and other textual data +like GUI resources or package descriptions can make use of the gettext +approach. + +* Menu: + +* Language Implementors:: The Language Implementor's View +* Programmers for other Languages:: The Programmer's View +* Translators for other Languages:: The Translator's View +* List of Programming Languages:: Individual Programming Languages +* List of Data Formats:: Internationalizable Data + + +File: gettext.info, Node: Language Implementors, Next: Programmers for other Languages, Prev: Programming Languages, Up: Programming Languages + +The Language Implementor's View +=============================== + + All programming and scripting languages that have the notion of +strings are eligible to supporting `gettext'. Supporting `gettext' +means the following: + + 1. You should add to the language a syntax for translatable strings. + In principle, a function call of `gettext' would do, but a + shorthand syntax helps keeping the legibility of internationalized + programs. For example, in C we use the syntax `_("string")', in + bash we use the syntax `$"string"', and in GNU awk we use the + shorthand `_"string"'. + + 2. You should arrange that evaluation of such a translatable string at + runtime calls the `gettext' function, or performs equivalent + processing. + + 3. Similarly, you should make the functions `ngettext', `dcgettext', + `dcngettext' available from within the language. These functions + are less often used, but are nevertheless necessary for particular + purposes: `ngettext' for correct plural handling, and `dcgettext' + and `dcngettext' for obeying other locale environment variables + than `LC_MESSAGES', such as `LC_TIME' or `LC_MONETARY'. For these + latter functions, you need to make the `LC_*' constants, available + in the C header `<locale.h>', referenceable from within the + language, usually either as enumeration values or as strings. + + 4. You should allow the programmer to designate a message domain, + either by making the `textdomain' function available from within + the language, or by introducing a magic variable called + `TEXTDOMAIN'. Similarly, you should allow the programmer to + designate where to search for message catalogs, by providing + access to the `bindtextdomain' function. + + 5. You should either perform a `setlocale (LC_ALL, "")' call during + the startup of your language runtime, or allow the programmer to + do so. Remember that gettext will act as a no-op if the + `LC_MESSAGES' and `LC_CTYPE' locale facets are not both set. + + 6. A programmer should have a way to extract translatable strings + from a program into a PO file. The GNU `xgettext' program is being + extended to support very different programming languages. Please + contact the GNU `gettext' maintainers to help them doing this. If + the string extractor is best integrated into your language's + parser, GNU `xgettext' can function as a front end to your string + extractor. + + 7. The language's library should have a string formatting facility + where the arguments of a format string are denoted by a positional + number or a name. This is needed because for some languages and + some messages with more than one substitutable argument, the + translation will need to output the substituted arguments in + different order. *Note c-format::. + + 8. If the language has more than one implementation, and not all of + the implementations use `gettext', but the programs should be + portable across implementations, you should provide a no-i18n + emulation, that makes the other implementations accept programs + written for yours, without actually translating the strings. + + 9. To help the programmer in the task of marking translatable strings, + which is usually performed using the Emacs PO mode, you are + welcome to contact the GNU `gettext' maintainers, so they can add + support for your language to `po-mode.el'. + + On the implementation side, three approaches are possible, with +different effects on portability and copyright: + + * You may integrate the GNU `gettext''s `intl/' directory in your + package, as described in *Note Maintainers::. This allows you to + have internationalization on all kinds of platforms. Note that + when you then distribute your package, it legally falls under the + GNU General Public License, and the GNU project will be glad about + your contribution to the Free Software pool. + + * You may link against GNU `gettext' functions if they are found in + the C library. For example, an autoconf test for `gettext()' and + `ngettext()' will detect this situation. For the moment, this test + will succeed on GNU systems and not on other platforms. No severe + copyright restrictions apply. + + * You may emulate or reimplement the GNU `gettext' functionality. + This has the advantage of full portability and no copyright + restrictions, but also the drawback that you have to reimplement + the GNU `gettext' features (such as the `LANGUAGE' environment + variable, the locale aliases database, the automatic charset + conversion, and plural handling). + + +File: gettext.info, Node: Programmers for other Languages, Next: Translators for other Languages, Prev: Language Implementors, Up: Programming Languages + +The Programmer's View +===================== + + For the programmer, the general procedure is the same as for the C +language. The Emacs PO mode supports other languages, and the GNU +`xgettext' string extractor recognizes other languages based on the +file extension or a command-line option. In some languages, +`setlocale' is not needed because it is already performed by the +underlying language runtime. + + +File: gettext.info, Node: Translators for other Languages, Next: List of Programming Languages, Prev: Programmers for other Languages, Up: Programming Languages + +The Translator's View +===================== + + The translator works exactly as in the C language case. The only +difference is that when translating format strings, she has to be aware +of the language's particular syntax for positional arguments in format +strings. + |