Geek Gadgets 1

home *** CD-ROM | disk | FTP | other *** search

/ Geek Gadgets 1 / ADE-1.bin / ade-bin / info / gettext.info-1 < prev next >

Wrap

GNU Info File | 1996-10-12 | 45.3 KB | 952 lines

This is Info file gettext.info, produced by Makeinfo-1.64 from the input file /ade-src/fsf/gettext/doc/gettext.texi. START-INFO-DIR-ENTRY * Gettext Utilities: (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. Copyright (C) 1995 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: Top, Next: Introduction, Prev: (dir), Up: (dir) GNU `gettext' utilities *********************** * Menu: * Introduction:: Introduction * Basics:: PO Files and PO Mode Basics * Sources:: Preparing Program Sources * Initial:: Making the Initial PO File * Updating:: Updating Existing PO Files * Binaries:: Producing Binary MO Files * Users:: The User's View * Programmers:: The Programmer's View * Translators:: The Translator's View * Maintainers:: The Maintainer's View * Conclusion:: Concluding Remarks * Country Codes:: ISO 639 country codes -- The Detailed Node Listing -- Introduction * Why:: The Purpose of GNU `gettext' * Concepts:: I18n, L10n, and Such * Aspects:: Aspects in Native Language Support * Files:: Files Conveying Translations * Overview:: Overview of GNU `gettext' PO Files and PO Mode Basics * Installation:: Completing GNU `gettext' Installation * PO Files:: The Format of PO Files * Main PO Commands:: Main Commands * Entry Positioning:: Entry Positioning * Normalizing:: Normalizing Strings in Entries Preparing Program Sources * Triggering:: Triggering `gettext' Operations * Mark Keywords:: How Marks Appears in Sources * Marking:: Marking Translatable Strings * c-format:: Telling something about the following string * Special cases:: Special Cases of Translatable Strings Making the Initial PO File * xgettext Invocation:: Invoking the `xgettext' Program * C Sources Context:: C Sources Context * Compendium:: Using Translation Compendiums Updating Existing PO Files * msgmerge Invocation:: Invoking the `msgmerge' Program * Fuzzy Entries:: Fuzzy translated Entries * Untranslated Entries:: Untranslated Entries * Obsolete Entries:: Obsolete Entries * Modifying Translations:: Modifying Translations * Modifying Comments:: Modifying Comments * Auxiliary:: Consulting Auxiliary PO Files Producing Binary MO Files * msgfmt Invocation:: Invoking the `msgfmt' Program * MO Files:: The Format of GNU MO Files The User's View * Matrix:: The Current `NLS' Matrix for GNU * Installers:: Magic for Installers * End Users:: Magic for End Users The Programmer's View * catgets:: About `catgets' * gettext:: About `gettext' * Comparison:: Comparing the two interfaces * Using libintl.a:: Using libintl.a in own programs * gettext grok:: Being a `gettext' grok * Temp Programmers:: Temporary Notes for the Programmers Chapter About `catgets' * Interface to catgets:: The interface * Problems with catgets:: Problems with the `catgets' interface?! About `gettext' * Interface to gettext:: The interface * Ambiguities:: Solving ambiguities * Locating Catalogs:: Locating message catalog files * Optimized gettext:: Optimization of the *gettext functions Temporary Notes for the Programmers Chapter * Temp Implementations:: Temporary - Two Possible Implementations * Temp catgets:: Temporary - About `catgets' * Temp WSI:: Temporary - Why a single implementation * Temp Notes:: Temporary - Notes The Translator's View * Trans Intro 0:: Introduction 0 * Trans Intro 1:: Introduction 1 * Discussions:: Discussions * Organization:: Organization * Information Flow:: Information Flow Organization * Central Coordination:: Central Coordination * National Teams:: National Teams * Mailing Lists:: Mailing Lists National Teams * Sub-Cultures:: Sub-Cultures * Organizational Ideas:: Organizational Ideas The Maintainer's View * 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 Files You Must Create or Alter * po/POTFILES:: `POTFILES' in `po/' * configure.in:: `configure.in' 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/' Concluding Remarks * History:: History of GNU `gettext' * References:: Related Readings File: gettext.info, Node: Introduction, Next: Basics, Prev: Top, Up: Top Introduction ************ 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'. 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. * Menu: * Why:: The Purpose of GNU `gettext' * Concepts:: I18n, L10n, and Such * Aspects:: Aspects in Native Language Support * Files:: Files Conveying Translations * Overview:: Overview of GNU `gettext' File: gettext.info, Node: Why, Next: Concepts, Prev: Introduction, Up: Introduction The Purpose of GNU `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 GNU 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 GNU 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 GNU 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 GNU Emacs mode 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 GNU 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 GNU Translation Project, and consequently, have a glimpse at the *big picture*. File: gettext.info, Node: Concepts, Next: Aspects, Prev: Why, Up: Introduction I18n, L10n, and Such ==================== Two long words appear all the time when we discuss support of native language in programs, and these words have a precise meaning, worth being explained here, once and for all in this document. The words are *internationalization* and *localization*. Many people, tired of 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. *Note Programmers::. 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. File: gettext.info, Node: Aspects, Next: Files, Prev: Concepts, Up: Introduction Aspects in Native Language Support ================================== For a totally multi-lingual distribution, there are many things to translate beyond output messages. * As of today, GNU `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. * Some programs, like `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. * A few programs include textual tables which might need translation themselves, independently of the strings contained in the program itself. For example, RFC 1345 gives an English description for each character which GNU `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. * Almost all programs accept options, which are often worded out so to be descriptive for the English readers; one might want to consider offering translated versions for program options as well. * Many programs read, interpret, compile, or are somewhat driven by input files which are texts containing keywords, identifiers, or replies which are inherently translatable. For example, one may want `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. * The manual accompanying a package, as well as all documentation files in the distribution, could surely be translated, too. Translating a manual, with the intent of later keeping up with updates, is a major undertaking in itself, generally. As we already stressed, translation is only one aspect of locales. Other internationalization aspects are not currently handled by GNU `gettext', but perhaps may be handled in future versions. There are 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. *Characters and Codesets* The codeset most commonly used through out the USA and most English speaking parts of the world is the ASCII codeset. However, there are many characters needed by various locales that are not found within this codeset. The 8-bit ISO 8859-1 code set has most of the special characters needed to handle the major European languages. However, in many cases, the ISO 8859-1 font is not adequate. Hence each locale will need to specify which codeset they need to use and will need to have the appropriate character handling routines to cope with the codeset. *Currency* The symbols used vary from country to country as does the position used by the symbol. Software needs to be able to transparently display currency figures in the native mode for each locale. *Dates* The format of date varies between locales. For example, Christmas day in 1994 is written as 12/25/94 in the USA and as 25/12/94 in Australia. Other countries might use ISO 8061 dates, etc. Time of the day may be noted as HH:MM, HH.MM, or otherwise. Some locales require time to be specified in 24-hour mode rather than as AM or PM. Further, the nature and yearly extent of the Daylight Saving correction vary widely between countries. *Numbers* Numbers can be represented differently in different locales. For example, the following numbers are all written correctly for their respective locales: 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. *Messages* The most obvious area is the language support within a locale. This is where GNU `gettext' provides the means for developers and users to easily change the language that the software uses to 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 GNU 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. File: gettext.info, Node: Files, Next: Overview, Prev: Aspects, Up: Introduction Files Conveying Translations ============================ 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. File: gettext.info, Node: Overview, Prev: Files, Up: Introduction Overview of GNU `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 validatation 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. *Note 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. *Note xgettext Invocation::, for more details about how one calls the `xgettext' program. If you are *really* lazy, you might be interested at working a lot more right away, and preparing the whole distribution setup (*note Maintainers::.). By doing so, you spare yourself typing the `xgettext' command, as `make' should now generate the proper things automatically for you! 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 (*note Translators::.). You will also find there indications about how to contact translating teams, or becoming part of them, for sharing your translating concerns with others who target the same native language. While adding the translated messages into the `LANG.pox' PO file, if you do not have GNU Emacs handy, you are on your own for ensuring that your efforts fully respect the PO file format, and quoting conventions (*note PO Files::.). This is surely not an impossible task, as this is 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 (*note Main PO Commands::.), you should know how to move between entries (*note Entry Positioning::.), and how to handle untranslated entries (*note Untranslated Entries::.). If some common translations have already been saved into a compendium PO file, translators may use PO mode for initializing untranslated entries from the compendium, and also save selected translations into the compendium, updating it (*note Compendium::.). Compendium files are meant to be exchanged between members of a given translation team. 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 GNU 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 (*note Obsolete Entries::.. It finally discovers new strings and inserts them in the resulting PO file as untranslated entries (*note Untranslated Entries::.. *Note msgmerge Invocation::, for more 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 GNU 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 (*note MO Files::.). *Note msgfmt Invocation::, 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 (*note 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. File: gettext.info, Node: Basics, Next: Sources, Prev: Introduction, Up: Top PO Files and PO Mode Basics *************************** The GNU `gettext' toolset helps programmers and translators at producing, updating and using translation files, mainly those PO files which are textual, editable files. This chapter stresses the format of PO files, and contains a PO mode starter. PO mode description is spread throughout this manual instead of being concentrated in one place. Here we present only the basics of PO mode. * Menu: * Installation:: Completing GNU `gettext' Installation * PO Files:: The Format of PO Files * Main PO Commands:: Main Commands * Entry Positioning:: Entry Positioning * Normalizing:: Normalizing Strings in Entries File: gettext.info, Node: Installation, Next: PO Files, Prev: Basics, Up: Basics Completing GNU `gettext' Installation ===================================== Once you have received, unpacked, configured and compiled the GNU `gettext' distribution, the `make install' command puts in place the programs `xgettext', `msgfmt', `gettext', and `msgmerge', as well as their available message catalogs. To top off a comfortable installation, you might also want to make the PO mode available to your GNU Emacs users. During the installation of the PO mode, you might want modify your file `.emacs', once and for all, so it contains a few lines looking like: (setq auto-mode-alist (cons '("\\.po[tx]?\\'\\|\\.po\\." . po-mode) auto-mode-alist)) (autoload 'po-mode "po-mode") Later, whenever you edit some `.po', `.pot' or `.pox' file, or any file having the string `.po.' within its name, Emacs loads `po-mode.elc' (or `po-mode.el') as needed, and automatically activates PO mode commands for the associated buffer. The string *PO* appears in the mode line for any buffer for which PO mode is active. Many PO files may be active at once in a single Emacs session. File: gettext.info, Node: PO Files, Next: Main PO Commands, Prev: Installation, Up: Basics The Format of PO Files ====================== A PO file is made up of many entries, each entry holding the relation between an original untranslated string and its corresponding translation. All entries in a given PO file usually pertain to a single project, and all translations are expressed in a single target language. One PO file "entry" has the following schematic structure: WHITE-SPACE # TRANSLATOR-COMMENTS #. AUTOMATIC-COMMENTS #: REFERENCE... #, FLAG... msgid UNTRANSLATED-STRING msgstr TRANSLATED-STRING The general structure of a PO file should be well understood by the translator. When using PO mode, very little has to be known about the format details, as PO mode takes care of them for her. Entries begin with some optional white space. Usually, when generated through GNU `gettext' tools, there is exactly one blank line between entries. Then comments follow, on lines all starting with the character `#'. There are two kinds of comments: those which have some white space immediately following the `#', which comments are created and maintained exclusively by the translator, and those which have some non-white character just after the `#', which comments are created and maintained automatically by GNU `gettext' tools. All comments, of either kind, are optional. After white space and comments, entries show two strings, giving first the untranslated string as it appears in the original program sources, and then, the translation of this string. The original string is introduced by the keyword `msgid', and the translation, by `msgstr'. The two strings, untranslated and translated, are quoted in various ways in the PO file, using `"' delimiters and `\' escapes, but the translator does not really have to pay attention to the precise quoting format, as PO mode fully intend to take care of quoting for her. The `msgid' strings, as well as automatic comments, are produced and managed by other GNU `gettext' tools, and PO mode does not provide means for the translator to alter these. The most she can do is merely deleting them, and only by deleting the whole entry. On the other hand, the `msgstr' string, as well as translator comments, are really meant for the translator, and PO mode gives her the full control she needs. The comment lines beginning with `#,' are special because they are not completely ignored by the programs as comments generally are. The comma separated list of FLAGs is used by the `msgfmt' program to give the user some better disgnostic messages. Currently there are two forms of flags defined: `fuzzy' This flag can be generated by the `msgmerge' program or it can be inserted by the translator herself. It shows that the `msgstr' string might not be a correct translation (anymore). Only the translator can judge if the translation requires further modification, or is acceptable as is. Once satisfied with the translation, she then removes this `fuzzy' attribute. The `msgmerge' programs inserts this when it combined the `msgid' and `msgstr' entries after fuzzy search only. *Note Fuzzy Entries::. `c-format' `no-c-format' These flags should not be added by a human. Instead only the `xgettext' program adds them. In an automatized PO file processing system as proposed here the user changes would be thrown away again as soon as the `xgettext' program generates a new template file. In case the `c-format' flag is given for a string the `msgfmt' does some more tests to check to validity of the translation. *Note msgfmt Invocation::. It happens that some lines, usually whitespace or comments, follow the very last entry of a PO file. Such lines are not part of any entry, and PO mode is unable to take action on those lines. By using the PO mode function `M-x po-normalize', the translator may get rid of those spurious lines. *Note Normalizing::. The remainder of this section may be safely skipped by those using PO mode, yet it may be interesting for everybody to have a better idea of the precise format of a PO file. On the other hand, those not having GNU Emacs handy should carefully continue reading on. Each of UNTRANSLATED-STRING and TRANSLATED-STRING respects the C syntax for a character string, including the surrounding quotes and imbedded backslashed escape sequences. When the time comes to write multi-line strings, one should not use escaped newlines. Instead, a closing quote should follow the last character on the line to be continued, and an opening quote should resume the string at the beginning of the following PO file line. For example: msgid "" "Here is an example of how one might continue a very long string\n" "for the common case the string represents multi-line output.\n" In this example, the empty string is used on the first line, to allow better alignment of the `H' from the word `Here' over the `f' from the word `for'. In this example, the `msgid' keyword is followed by three strings, which are meant to be concatenated. Concatenating the empty string does not change the resulting overall string, but it is a way for us to comply with the necessity of `msgid' to be followed by a string on the same line, while keeping the multi-line presentation left-justified, as we find this to be a cleaner disposition. The empty string could have been omitted, but only if the string starting with `Here' was promoted on the first line, right after `msgid'.(1) It was not really necessary either to switch between the two last quoted strings immediately after the newline `\n', the switch could have occurred after *any* other character, we just did it this way because it is neater. One should carefully distinguish between end of lines marked as `\n' *inside* quotes, which are part of the represented string, and end of lines in the PO file itself, outside string quotes, which have no incidence on the represented string. Outside strings, white lines and comments may be used freely. Comments start at the beginning of a line with `#' and extend until the end of the PO file line. Comments written by translators should have the initial `#' immediately followed by some white space. If the `#' is not immediately followed by white space, this comment is most likely generated and managed by specialized GNU tools, and might disappear or be replaced unexpectedly when the PO file is given to `msgmerge'. ---------- Footnotes ---------- (1) This limitation is not imposed by GNU `gettext', but comes from the `msgfmt' implementation on Solaris. File: gettext.info, Node: Main PO Commands, Next: Entry Positioning, Prev: PO Files, Up: Basics Main PO mode Commands ===================== After setting up Emacs with something similar to the lines in *Note Installation::, PO mode is activated for a window when Emacs finds a PO file in that window. This puts the window read-only and establishes a po-mode-map, which is a genuine Emacs mode, in a way that is not derived from text mode in any way. The main PO commands are those which do not fit into the other categories of subsequent sections. These allow for quitting PO mode or for managing windows in special ways. `u' Undo last modification to the PO file. `q' Quit processing and save the PO file. `o' Temporary leave the PO file window. `h' Show help about PO mode. `=' Give some PO file statistics. `v' Batch validate the format of the whole PO file. The command `U' (`po-undo') interfaces to the GNU Emacs *undo* facility. *Note Undoing Changes: (emacs)Undo. Each time `U' is typed, modifications which the translator did to the PO file are undone a little more. For the purpose of undoing, each PO mode command is atomic. This is especially true for the `RET' command: the whole edition made by using a single use of this command is undone at once, even if the edition itself implied several actions. However, while in the editing window, one can undo the edition work quite parsimoniously. The command `Q' (`po-quit') is used when the translator is done with the PO file. If the file has been modified, it is saved to disk first. However, prior to all this, the command checks if some untranslated message remains in the PO file and, if yes, the translator is asked if she really wants to leave off working with this PO file. This is the preferred way of getting rid of an Emacs PO file buffer. Merely killing it through the usual command `C-x k' (`kill-buffer'), say, has the untidy effect of leaving a PO internal work buffer behind. The command `O' (`po-other-window') is another, softer way, to leave PO mode, temporarily. It just moves the cursor to some other Emacs window, and pops one if necessary. For example, if the translator just got PO mode to show some source context in some other, she might discover some apparent bug in the program source that needs correction. This command allows the translator to change sex, become a programmer, and have the cursor right into the window containing the program she (or rather *he*) wants to modify. By later getting the cursor back in the PO file window, or by asking Emacs to edit this file once again, PO mode is then recovered. The command `h' (`po-help') displays a summary of all available PO mode commands. The translator should then type any character to resume normal PO mode operations. The command `?' has the same effect as `h'. The command `=' (`po-statistics') computes the total number of entries in the PO file, the ordinal of the current entry (counted from 1), the number of untranslated entries, the number of obsolete entries, and displays all these numbers. The command `V' (`po-validate') launches `msgfmt' in verbose mode over the current PO file. This command first offers to save the current PO file on disk. The `msgfmt' tool, from GNU `gettext', has the purpose of creating a MO file out of a PO file, and PO mode uses the features of this program for checking the overall format of a PO file, as well as all individual entries. The program `msgfmt' runs asynchronously with Emacs, so the translator regains control immediately while her PO file is being studied. Error output is collected in the GNU Emacs `*compilation*' buffer, displayed in another window. The regular GNU Emacs command `C-x`' (`next-error'), as well as other usual compile commands, allow the translator to reposition quickly to the offending parts of the PO file. Once the cursor is on the line in error, the translator may decide on any PO mode action which would help correcting the error.