Go to the first, previous, next, last section, table of contents. -
- - -
-- --This manual is still in DRAFT state. Some sections are still -empty, or almost. We keep merging material from other sources -(essentially e-mail folders) while the proper integration of this -material is delayed. -
-In this manual, we use he when speaking of the programmer or
-maintainer, she when speaking of the translator, and they
-when speaking of the installers or end users of the translated program.
-This is only a convenience for clarifying the documentation. It is
-absolutely not meant to imply that some roles are more appropriate
-to males or females. Besides, as you might guess, GNU gettext
-is meant to be useful for people using computers, whatever their sex,
-race, religion or nationality!
-
-
-This chapter explains the goals sought in the creation
-of GNU gettext and the free Translation Project.
-Then, it explains a few broad concepts around
-Native Language Support, and positions message translation with regard
-to other aspects of national and cultural variance, as they apply to
-to programs. It also surveys those files used to convey the
-translations. It explains how the various tools interact in the
-initial generation of these files, and later, how the maintenance
-cycle should usually operate.
-
-
-Please send suggestions and corrections to: - -
- --Internet address: - bug-gnu-utils@prep.ai.mit.edu -- -
-Please include the manual's edition number and update date in your messages. - -
- - - -gettext-Usually, programs are written and documented in English, and use -English at execution time to interact with users. This is true -not only of GNU software, but also of a great deal of commercial -and free software. Using a common language is quite handy for -communication between developers, maintainers and users from all -countries. On the other hand, most people are less comfortable with -English than with their own native language, and would prefer to -use their mother tongue for day to day's work, as far as possible. -Many would simply love to see their computer screen showing -a lot less of English, and far more of their own language. - -
--However, to many people, this dream might appear so far fetched that -they may believe it is not even worth spending time thinking about -it. They have no confidence at all that the dream might ever -become true. Yet some have not lost hope, and have organized themselves. -The Translation Project is a formalization of this hope into a -workable structure, which has a good chance to get all of us nearer -the achievement of a truly multi-lingual set of programs. - -
-
-GNU gettext is an important step for the Translation Project,
-as it is an asset on which we may build many other steps. This package
-offers to programmers, translators and even users, a well integrated
-set of tools and documentation. Specifically, the GNU gettext
-utilities are a set of tools that provides a framework within which
-other free packages may produce multi-lingual messages. These tools
-include a set of conventions about how programs should be written to
-support message catalogs, a directory and file naming organization for the
-message catalogs themselves, a runtime library supporting the retrieval of
-translated messages, and a few stand-alone programs to massage in various
-ways the sets of translatable strings, or already translated strings.
-A special mode for GNU Emacs also helps ease interested parties into
-preparing these sets, or bringing them up to date.
-
-
-GNU gettext is designed to minimize the impact of
-internationalization on program sources, keeping this impact as small
-and hardly noticeable as possible. Internationalization has better
-chances of succeeding if it is very light weighted, or at least,
-appear to be so, when looking at program sources.
-
-
-The Translation Project also uses the GNU gettext
-distribution as a vehicle for documenting its structure and methods.
-This goes beyond the strict technicalities of documenting the GNU gettext
-proper. By so doing, translators will find in a single place, as
-far as possible, all they need to know for properly doing their
-translating work. Also, this supplemental documentation might also
-help programmers, and even curious users, in understanding how GNU
-gettext is related to the remainder of the Translation
-Project, and consequently, have a glimpse at the big picture.
-
-
-Two long words appear all the time when we discuss support of native -language in programs, and these words have a precise meaning, worth -being explained here, once and for all in this document. The words are -internationalization and localization. Many people, -tired of writing these long words over and over again, took the -habit of writing i18n and l10n instead, quoting the first -and last letter of each word, and replacing the run of intermediate -letters by a number merely telling how many such letters there are. -But in this manual, in the sake of clarity, we will patiently write -the names in full, each time... - -
-
-By internationalization, one refers to the operation by which a
-program, or a set of programs turned into a package, is made aware of and
-able to support multiple languages. This is a generalization process,
-by which the programs are untied from calling only English strings or
-other English specific habits, and connected to generic ways of doing
-the same, instead. Program developers may use various techniques to
-internationalize their programs. Some of these have been standardized.
-GNU gettext offers one of these standards. See section The Programmer's View.
-
-
-By localization, one means the operation by which, in a set -of programs already internationalized, one gives the program all -needed information so that it can adapt itself to handle its input -and output in a fashion which is correct for some native language and -cultural habits. This is a particularisation process, by which generic -methods already implemented in an internationalized program are used -in specific ways. The programming environment puts several functions -to the programmers disposal which allow this runtime configuration. -The formal description of specific set of cultural habits for some -country, together with all associated translations targeted to the -same native language, is called the locale for this language -or country. Users achieve localization of programs by setting proper -values to special environment variables, prior to executing those -programs, identifying which locale should be used. - -
--In fact, locale message support is only one component of the cultural -data that makes up a particular locale. There are a whole host of -routines and functions provided to aid programmers in developing -internationalized software and which allow them to access the data -stored in a particular locale. When someone presently refers to a -particular locale, they are obviously referring to the data stored -within that particular locale. Similarly, if a programmer is referring -to "accessing the locale routines", they are referring to the -complete suite of routines that access all of the locale's information. - -
--One uses the expression Native Language Support, or merely NLS, -for speaking of the overall activity or feature encompassing both -internationalization and localization, allowing for multi-lingual -interactions in a program. In a nutshell, one could say that -internationalization is the operation by which further localizations -are made possible. - -
--Also, very roughly said, when it comes to multi-lingual messages, -internationalization is usually taken care of by programmers, and -localization is usually taken care of by translators. - -
- - --For a totally multi-lingual distribution, there are many things to -translate beyond output messages. - -
- -gettext offers a complete toolset for
-translating messages output by C programs. Perl scripts and shell
-scripts will also need to be translated. Even if there are today some hooks
-by which this can be done, these hooks are not integrated as well as they
-should be.
-
-autoconf or bison, are able
-to produce other programs (or scripts). Even if the generating
-programs themselves are internationalized, the generated programs they
-produce may need internationalization on their own, and this indirect
-internationalization could be automated right from the generating
-program. In fact, quite usually, generating and generated programs
-could be internationalized independently, as the effort needed is
-fairly orthogonal.
-
-recode is able to reconstruct at execution.
-Since these descriptions are extracted from the RFC by mechanical means,
-translating them properly would require a prior translation of the RFC
-itself.
-
-gcc to allow diacriticized characters in identifiers or use
-translated keywords; `rm -i' might accept something else than
-`y' or `n' for replies, etc. Even if the program will
-eventually make most of its output in the foreign languages, one has
-to decide whether the input syntax, option values, etc., are to be
-localized or not.
-
-
-As we already stressed, translation is only one aspect of locales.
-Other internationalization aspects are not currently handled by GNU
-gettext, but perhaps may be handled in future versions. There
-are many attributes that are needed to define a country's cultural
-conventions. These attributes include beside the country's native
-language, the formatting of the date and time, the representation of
-numbers, the symbols for currency, etc. These local rules are
-termed the country's locale. The locale represents the knowledge
-needed to support the country's native attributes.
-
-
-There are a few major areas which may vary between countries and
-hence, define what a locale must describe. The following list helps
-putting multi-lingual messages into the proper context of other tasks
-related to locales, and also presents some other areas which GNU
-gettext might eventually tackle, maybe, one of these days.
-
-
-12,345.67 English -12.345,67 French -1,2345.67 Asia -- -Some programs could go further and use different unit systems, like -English units or Metric units, or even take into account variants -about how numbers are spelled in full. - -
gettext provides the means for developers and users to
-easily change the language that the software uses to communicate to
-the user.
-
-
-In the near future we see no chance that components of locale outside of
-message handling will be made available for use in other
-packages. The reason for this is that most modern systems provide
-a more or less reasonable support for at least some of the missing
-components. Another point is that the GNU libc and Linux will get
-a new and complete implementation of the whole locale functionality
-which could be adopted by system lacking a reasonable locale support.
-
-
-The letters PO in `.po' files means Portable Object, to -distinguish it from `.mo' files, where MO stands for Machine -Object. This paradigm, as well as the PO file format, is inspired -by the NLS standard developed by Uniforum, and implemented by Sun -in their Solaris system. - -
-
-PO files are meant to be read and edited by humans, and associate each
-original, translatable string of a given package with its translation
-in a particular target language. A single PO file is dedicated to
-a single target language. If a package supports many languages,
-there is one such PO file per language supported, and each package
-has its own set of PO files. These PO files are best created by
-the xgettext program, and later updated or refreshed through
-the msgmerge program. Program xgettext extracts all
-marked messages from a set of C files and initializes a PO file with
-empty translations. Program msgmerge takes care of adjusting
-PO files between releases of the corresponding sources, commenting
-obsolete entries, initializing new ones, and updating all source
-line references. Files ending with `.pot' are kind of base
-translation files found in distributions, in PO file format, and
-`.pox' files are often temporary PO files.
-
-
-MO files are meant to be read by programs, and are binary in nature.
-A few systems already offer tools for creating and handling MO files
-as part of the Native Language Support coming with the system, but the
-format of these MO files is often different from system to system,
-and non-portable. They do not necessary use `.mo' for file
-extensions, but since system libraries are also used for accessing
-these files, it works as long as the system is self-consistent about
-it. If GNU gettext is able to interface with the tools already
-provided with systems, it will consequently let these provided tools
-take care of generating the MO files. Or else, if such tools are not
-found or do not seem usable, GNU gettext will use its own ways
-and its own format for MO files. Files ending with `.gmo' are
-really MO files, when it is known that these files use the GNU format.
-
-
gettext
-The following diagram summarizes the relation between the files
-handled by GNU gettext and the tools acting on these files.
-It is followed by a somewhat detailed explanations, which you should
-read while keeping an eye on the diagram. Having a clear understanding
-of these interrelations would surely help programmers, translators
-and maintainers.
-
-
-Original C Sources ---> PO mode ---> Marked C Sources ---. - | - .---------<--- GNU gettext Library | -.--- make <---+ | -| `---------<--------------------+-----------' -| | -| .-----<--- PACKAGE.pot <--- xgettext <---' .---<--- PO Compendium -| | | ^ -| | `---. | -| `---. +---> PO mode ---. -| +----> msgmerge ------> LANG.pox --->--------' | -| .---' | -| | | -| `-------------<---------------. | -| +--- LANG.po <--- New LANG.pox <----' -| .--- LANG.gmo <--- msgfmt <---' -| | -| `---> install ---> /.../LANG/PACKAGE.mo ---. -| +---> "Hello world!" -`-------> install ---> /.../bin/PROGRAM -------' -- -
-The indication `PO mode' appears in two places in this picture, -and you may safely read it as merely meaning "hand editing", using -any editor of your choice, really. However, for those of you being -the lucky users of GNU Emacs, PO mode has been specifically created -for providing a cozy environment for editing or modifying PO files. -While editing a PO file, PO mode allows for the easy browsing of -auxiliary and compendium PO files, as well as for following references into -the set of C program sources from which PO files have been derived. -It has a few special features, among which are the interactive marking -of program strings as translatable, and the validation of PO files -with easy repositioning to PO file lines showing errors. - -
-
-As a programmer, the first step to bringing GNU gettext
-into your package is identifying, right in the C sources, those strings
-which are meant to be translatable, and those which are untranslatable.
-This tedious job can be done a little more comfortably using emacs PO
-mode, but you can use any means familiar to you for modifying your
-C sources. Beside this some other simple, standard changes are needed to
-properly initialize the translation library. See section Preparing Program Sources, for
-more information about all this.
-
-
-For newly written software the strings of course can and should be
-marked while writing the it. The gettext approach makes this
-very easy. Simply put the following lines at the beginning of each file
-or in a central header file:
-
-
-#define _(String) (String) -#define N_(String) (String) -#define textdomain(Domain) -#define bindtextdomain(Package, Directory) -- -
-Doing this allows you to prepare the sources for internationalization.
-Later when you feel ready for the step to use the gettext library
-simply remove these definitions, include `libintl.h' and link
-against `libintl.a'. That is all you have to change.
-
-
-Once the C sources have been modified, the xgettext program
-is used to find and extract all translatable strings, and create an
-initial PO file out of all these. This `package.pot' file
-contains all original program strings. It has sets of pointers to
-exactly where in C sources each string is used. All translations
-are set to empty. The letter t in `.pot' marks this as
-a Template PO file, not yet oriented towards any particular language.
-See section Invoking the xgettext Program, for more details about how one calls the
-xgettext program. If you are really lazy, you might
-be interested at working a lot more right away, and preparing the
-whole distribution setup (see section The Maintainer's View). By doing so, you
-spare yourself typing the xgettext command, as make
-should now generate the proper things automatically for you!
-
-
-The first time through, there is no `lang.po' yet, so the
-msgmerge step may be skipped and replaced by a mere copy of
-`package.pot' to `lang.pox', where lang
-represents the target language.
-
-
-Then comes the initial translation of messages. Translation in -itself is a whole matter, still exclusively meant for humans, -and whose complexity far overwhelms the level of this manual. -Nevertheless, a few hints are given in some other chapter of this -manual (see section The Translator's View). You will also find there indications -about how to contact translating teams, or becoming part of them, -for sharing your translating concerns with others who target the same -native language. - -
--While adding the translated messages into the `lang.pox' -PO file, if you do not have GNU Emacs handy, you are on your own -for ensuring that your efforts fully respect the PO file format, and quoting -conventions (see section The Format of PO Files). This is surely not an impossible task, -as this is the way many people have handled PO files already for Uniforum or -Solaris. On the other hand, by using PO mode in GNU Emacs, most details -of PO file format are taken care of for you, but you have to acquire -some familiarity with PO mode itself. Besides main PO mode commands -(see section Main PO mode Commands), you should know how to move between entries -(see section Entry Positioning), and how to handle untranslated entries -(see section Untranslated Entries). - -
--If some common translations have already been saved into a compendium -PO file, translators may use PO mode for initializing untranslated -entries from the compendium, and also save selected translations into -the compendium, updating it (see section Using Translation Compendiums). Compendium files -are meant to be exchanged between members of a given translation team. - -
--Programs, or packages of programs, are dynamic in nature: users write -bug reports and suggestion for improvements, maintainers react by -modifying programs in various ways. The fact that a package has -already been internationalized should not make maintainers shy -of adding new strings, or modifying strings already translated. -They just do their job the best they can. For the Translation -Project to work smoothly, it is important that maintainers do not -carry translation concerns on their already loaded shoulders, and that -translators be kept as free as possible of programmatic concerns. - -
-
-The only concern maintainers should have is carefully marking new
-strings as translatable, when they should be, and do not otherwise
-worry about them being translated, as this will come in proper time.
-Consequently, when programs and their strings are adjusted in various
-ways by maintainers, and for matters usually unrelated to translation,
-xgettext would construct `package.pot' files which are
-evolving over time, so the translations carried by `lang.po'
-are slowly fading out of date.
-
-
-It is important for translators (and even maintainers) to understand -that package translation is a continuous process in the lifetime of a -package, and not something which is done once and for all at the start. -After an initial burst of translation activity for a given package, -interventions are needed once in a while, because here and there, -translated entries become obsolete, and new untranslated entries -appear, needing translation. - -
-
-The msgmerge program has the purpose of refreshing an already
-existing `lang.po' file, by comparing it with a newer
-`package.pot' template file, extracted by xgettext
-out of recent C sources. The refreshing operation adjusts all
-references to C source locations for strings, since these strings
-move as programs are modified. Also, msgmerge comments out as
-obsolete, in `lang.pox', those already translated entries
-which are no longer used in the program sources (see section Obsolete Entries). It finally discovers new strings and inserts them in
-the resulting PO file as untranslated entries (see section Untranslated Entries). See section Invoking the msgmerge Program, for more information about what
-msgmerge really does.
-
-
-Whatever route or means taken, the goal is to obtain an updated -`lang.pox' file offering translations for all strings. -When this is properly achieved, this file `lang.pox' may -take the place of the previous official `lang.po' file. - -
--The temporal mobility, or fluidity of PO files, is an integral part of -the translation game, and should be well understood, and accepted. -People resisting it will have a hard time participating in the -Translation Project, or will give a hard time to other participants! In -particular, maintainers should relax and include all available official -PO files in their distributions, even if these have not recently been -updated, without banging or otherwise trying to exert pressure on the -translator teams to get the job done. The pressure should rather come -from the community of users speaking a particular language, and -maintainers should consider themselves fairly relieved of any concern -about the adequacy of translation files. On the other hand, translators -should reasonably try updating the PO files they are responsible for, -while the package is undergoing pretest, prior to an official -distribution. - -
-
-Once the PO file is complete and dependable, the msgfmt program
-is used for turning the PO file into a machine-oriented format, which
-may yield efficient retrieval of translations by the programs of the
-package, whenever needed at runtime (see section The Format of GNU MO Files). See section Invoking the msgfmt Program, for more information about all modalities of execution
-for the msgfmt program.
-
-
-Finally, the modified and marked C sources are compiled and linked
-with the GNU gettext library, usually through the operation of
-make, given a suitable `Makefile' exists for the project,
-and the resulting executable is installed somewhere users will find it.
-The MO files themselves should also be properly installed. Given the
-appropriate environment variables are set (see section Magic for End Users), the
-program should localize itself automatically, whenever it executes.
-
-
-The remainder of this manual has the purpose of explaining in depth the various -steps outlined above. - -
--
Go to the first, previous, next, last section, table of contents. - -