3 <!-- This HTML file has been created by texi2html 1.52b
4 from gettext.texi on 6 June 2010 -->
6 <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
7 <TITLE>GNU gettext utilities - 1 Introduction</TITLE>
10 Go to the first, previous, <A HREF="gettext_2.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
15 <H1><A NAME="SEC1" HREF="gettext_toc.html#TOC1">1 Introduction</A></H1>
18 This chapter explains the goals sought in the creation
19 of GNU <CODE>gettext</CODE> and the free Translation Project.
20 Then, it explains a few broad concepts around
21 Native Language Support, and positions message translation with regard
22 to other aspects of national and cultural variance, as they apply
23 to programs. It also surveys those files used to convey the
24 translations. It explains how the various tools interact in the
25 initial generation of these files, and later, how the maintenance
26 cycle should usually operate.
33 In this manual, we use <EM>he</EM> when speaking of the programmer or
34 maintainer, <EM>she</EM> when speaking of the translator, and <EM>they</EM>
35 when speaking of the installers or end users of the translated program.
36 This is only a convenience for clarifying the documentation. It is
37 <EM>absolutely</EM> not meant to imply that some roles are more appropriate
38 to males or females. Besides, as you might guess, GNU <CODE>gettext</CODE>
39 is meant to be useful for people using computers, whatever their sex,
40 race, religion or nationality!
45 Please send suggestions and corrections to:
51 bug-gnu-gettext@gnu.org
55 Please include the manual's edition number and update date in your messages.
61 <H2><A NAME="SEC2" HREF="gettext_toc.html#TOC2">1.1 The Purpose of GNU <CODE>gettext</CODE></A></H2>
64 Usually, programs are written and documented in English, and use
65 English at execution time to interact with users. This is true
66 not only of GNU software, but also of a great deal of proprietary
67 and free software. Using a common language is quite handy for
68 communication between developers, maintainers and users from all
69 countries. On the other hand, most people are less comfortable with
70 English than with their own native language, and would prefer to
71 use their mother tongue for day to day's work, as far as possible.
72 Many would simply <EM>love</EM> to see their computer screen showing
73 a lot less of English, and far more of their own language.
78 However, to many people, this dream might appear so far fetched that
79 they may believe it is not even worth spending time thinking about
80 it. They have no confidence at all that the dream might ever
81 become true. Yet some have not lost hope, and have organized themselves.
82 The Translation Project is a formalization of this hope into a
83 workable structure, which has a good chance to get all of us nearer
84 the achievement of a truly multi-lingual set of programs.
88 GNU <CODE>gettext</CODE> is an important step for the Translation Project,
89 as it is an asset on which we may build many other steps. This package
90 offers to programmers, translators and even users, a well integrated
91 set of tools and documentation. Specifically, the GNU <CODE>gettext</CODE>
92 utilities are a set of tools that provides a framework within which
93 other free packages may produce multi-lingual messages. These tools
101 A set of conventions about how programs should be written to support
106 A directory and file naming organization for the message catalogs
111 A runtime library supporting the retrieval of translated messages.
115 A few stand-alone programs to massage in various ways the sets of
116 translatable strings, or already translated strings.
120 A library supporting the parsing and creation of files containing
125 A special mode for Emacs<A NAME="DOCF1" HREF="gettext_foot.html#FOOT1">(1)</A> which helps preparing these sets
126 and bringing them up to date.
130 GNU <CODE>gettext</CODE> is designed to minimize the impact of
131 internationalization on program sources, keeping this impact as small
132 and hardly noticeable as possible. Internationalization has better
133 chances of succeeding if it is very light weighted, or at least,
134 appear to be so, when looking at program sources.
138 The Translation Project also uses the GNU <CODE>gettext</CODE> distribution
139 as a vehicle for documenting its structure and methods. This goes
140 beyond the strict technicalities of documenting the GNU <CODE>gettext</CODE>
141 proper. By so doing, translators will find in a single place, as
142 far as possible, all they need to know for properly doing their
143 translating work. Also, this supplemental documentation might also
144 help programmers, and even curious users, in understanding how GNU
145 <CODE>gettext</CODE> is related to the remainder of the Translation
146 Project, and consequently, have a glimpse at the <EM>big picture</EM>.
151 <H2><A NAME="SEC3" HREF="gettext_toc.html#TOC3">1.2 I18n, L10n, and Such</A></H2>
156 Two long words appear all the time when we discuss support of native
157 language in programs, and these words have a precise meaning, worth
158 being explained here, once and for all in this document. The words are
159 <EM>internationalization</EM> and <EM>localization</EM>. Many people,
160 tired of writing these long words over and over again, took the
161 habit of writing <EM>i18n</EM> and <EM>l10n</EM> instead, quoting the first
162 and last letter of each word, and replacing the run of intermediate
163 letters by a number merely telling how many such letters there are.
164 But in this manual, in the sake of clarity, we will patiently write
165 the names in full, each time...
170 By <EM>internationalization</EM>, one refers to the operation by which a
171 program, or a set of programs turned into a package, is made aware of and
172 able to support multiple languages. This is a generalization process,
173 by which the programs are untied from calling only English strings or
174 other English specific habits, and connected to generic ways of doing
175 the same, instead. Program developers may use various techniques to
176 internationalize their programs. Some of these have been standardized.
177 GNU <CODE>gettext</CODE> offers one of these standards. See section <A HREF="gettext_11.html#SEC178">11 The Programmer's View</A>.
182 By <EM>localization</EM>, one means the operation by which, in a set
183 of programs already internationalized, one gives the program all
184 needed information so that it can adapt itself to handle its input
185 and output in a fashion which is correct for some native language and
186 cultural habits. This is a particularisation process, by which generic
187 methods already implemented in an internationalized program are used
188 in specific ways. The programming environment puts several functions
189 to the programmers disposal which allow this runtime configuration.
190 The formal description of specific set of cultural habits for some
191 country, together with all associated translations targeted to the
192 same native language, is called the <EM>locale</EM> for this language
193 or country. Users achieve localization of programs by setting proper
194 values to special environment variables, prior to executing those
195 programs, identifying which locale should be used.
199 In fact, locale message support is only one component of the cultural
200 data that makes up a particular locale. There are a whole host of
201 routines and functions provided to aid programmers in developing
202 internationalized software and which allow them to access the data
203 stored in a particular locale. When someone presently refers to a
204 particular locale, they are obviously referring to the data stored
205 within that particular locale. Similarly, if a programmer is referring
206 to “accessing the locale routines”, they are referring to the
207 complete suite of routines that access all of the locale's information.
214 One uses the expression <EM>Native Language Support</EM>, or merely NLS,
215 for speaking of the overall activity or feature encompassing both
216 internationalization and localization, allowing for multi-lingual
217 interactions in a program. In a nutshell, one could say that
218 internationalization is the operation by which further localizations
223 Also, very roughly said, when it comes to multi-lingual messages,
224 internationalization is usually taken care of by programmers, and
225 localization is usually taken care of by translators.
230 <H2><A NAME="SEC4" HREF="gettext_toc.html#TOC4">1.3 Aspects in Native Language Support</A></H2>
234 For a totally multi-lingual distribution, there are many things to
235 translate beyond output messages.
242 As of today, GNU <CODE>gettext</CODE> offers a complete toolset for
243 translating messages output by C programs. Perl scripts and shell
244 scripts will also need to be translated. Even if there are today some hooks
245 by which this can be done, these hooks are not integrated as well as they
250 Some programs, like <CODE>autoconf</CODE> or <CODE>bison</CODE>, are able
251 to produce other programs (or scripts). Even if the generating
252 programs themselves are internationalized, the generated programs they
253 produce may need internationalization on their own, and this indirect
254 internationalization could be automated right from the generating
255 program. In fact, quite usually, generating and generated programs
256 could be internationalized independently, as the effort needed is
261 A few programs include textual tables which might need translation
262 themselves, independently of the strings contained in the program
263 itself. For example, RFC 1345 gives an English description for each
264 character which the <CODE>recode</CODE> program is able to reconstruct at execution.
265 Since these descriptions are extracted from the RFC by mechanical means,
266 translating them properly would require a prior translation of the RFC
271 Almost all programs accept options, which are often worded out so to
272 be descriptive for the English readers; one might want to consider
273 offering translated versions for program options as well.
277 Many programs read, interpret, compile, or are somewhat driven by
278 input files which are texts containing keywords, identifiers, or
279 replies which are inherently translatable. For example, one may want
280 <CODE>gcc</CODE> to allow diacriticized characters in identifiers or use
281 translated keywords; <SAMP>‘rm -i’</SAMP> might accept something else than
282 <SAMP>‘y’</SAMP> or <SAMP>‘n’</SAMP> for replies, etc. Even if the program will
283 eventually make most of its output in the foreign languages, one has
284 to decide whether the input syntax, option values, etc., are to be
289 The manual accompanying a package, as well as all documentation files
290 in the distribution, could surely be translated, too. Translating a
291 manual, with the intent of later keeping up with updates, is a major
292 undertaking in itself, generally.
297 As we already stressed, translation is only one aspect of locales.
298 Other internationalization aspects are system services and are handled
299 in GNU <CODE>libc</CODE>. There
300 are many attributes that are needed to define a country's cultural
301 conventions. These attributes include beside the country's native
302 language, the formatting of the date and time, the representation of
303 numbers, the symbols for currency, etc. These local <EM>rules</EM> are
304 termed the country's locale. The locale represents the knowledge
305 needed to support the country's native attributes.
310 There are a few major areas which may vary between countries and
311 hence, define what a locale must describe. The following list helps
312 putting multi-lingual messages into the proper context of other tasks
313 related to locales. See the GNU <CODE>libc</CODE> manual for details.
318 <DT><EM>Characters and Codesets</EM>
325 The codeset most commonly used through out the USA and most English
326 speaking parts of the world is the ASCII codeset. However, there are
327 many characters needed by various locales that are not found within
328 this codeset. The 8-bit ISO 8859-1 code set has most of the special
329 characters needed to handle the major European languages. However, in
330 many cases, choosing ISO 8859-1 is nevertheless not adequate: it
331 doesn't even handle the major European currency. Hence each locale
332 will need to specify which codeset they need to use and will need
333 to have the appropriate character handling routines to cope with
336 <DT><EM>Currency</EM>
341 The symbols used vary from country to country as does the position
342 used by the symbol. Software needs to be able to transparently
343 display currency figures in the native mode for each locale.
350 The format of date varies between locales. For example, Christmas day
351 in 1994 is written as 12/25/94 in the USA and as 25/12/94 in Australia.
352 Other countries might use ISO 8601 dates, etc.
354 Time of the day may be noted as <VAR>hh</VAR>:<VAR>mm</VAR>, <VAR>hh</VAR>.<VAR>mm</VAR>,
355 or otherwise. Some locales require time to be specified in 24-hour
356 mode rather than as AM or PM. Further, the nature and yearly extent
357 of the Daylight Saving correction vary widely between countries.
364 Numbers can be represented differently in different locales.
365 For example, the following numbers are all written correctly for
366 their respective locales:
376 Some programs could go further and use different unit systems, like
377 English units or Metric units, or even take into account variants
378 about how numbers are spelled in full.
380 <DT><EM>Messages</EM>
385 The most obvious area is the language support within a locale. This is
386 where GNU <CODE>gettext</CODE> provides the means for developers and users to
387 easily change the language that the software uses to communicate to
394 These areas of cultural conventions are called <EM>locale categories</EM>.
395 It is an unfortunate term; <EM>locale aspects</EM> or <EM>locale feature
396 categories</EM> would be a better term, because each “locale category”
397 describes an area or task that requires localization. The concrete data
398 that describes the cultural conventions for such an area and for a particular
399 culture is also called a <EM>locale category</EM>. In this sense, a locale
400 is composed of several locale categories: the locale category describing
401 the codeset, the locale category describing the formatting of numbers,
402 the locale category containing the translated messages, and so on.
407 Components of locale outside of message handling are standardized in
408 the ISO C standard and the POSIX:2001 standard (also known as the SUSV3
409 specification). GNU <CODE>libc</CODE>
410 fully implements this, and most other modern systems provide a more
411 or less reasonable support for at least some of the missing components.
416 <H2><A NAME="SEC5" HREF="gettext_toc.html#TOC5">1.4 Files Conveying Translations</A></H2>
420 The letters PO in <TT>‘.po’</TT> files means Portable Object, to
421 distinguish it from <TT>‘.mo’</TT> files, where MO stands for Machine
422 Object. This paradigm, as well as the PO file format, is inspired
423 by the NLS standard developed by Uniforum, and first implemented by
424 Sun in their Solaris system.
428 PO files are meant to be read and edited by humans, and associate each
429 original, translatable string of a given package with its translation
430 in a particular target language. A single PO file is dedicated to
431 a single target language. If a package supports many languages,
432 there is one such PO file per language supported, and each package
433 has its own set of PO files. These PO files are best created by
434 the <CODE>xgettext</CODE> program, and later updated or refreshed through
435 the <CODE>msgmerge</CODE> program. Program <CODE>xgettext</CODE> extracts all
436 marked messages from a set of C files and initializes a PO file with
437 empty translations. Program <CODE>msgmerge</CODE> takes care of adjusting
438 PO files between releases of the corresponding sources, commenting
439 obsolete entries, initializing new ones, and updating all source
440 line references. Files ending with <TT>‘.pot’</TT> are kind of base
441 translation files found in distributions, in PO file format.
445 MO files are meant to be read by programs, and are binary in nature.
446 A few systems already offer tools for creating and handling MO files
447 as part of the Native Language Support coming with the system, but the
448 format of these MO files is often different from system to system,
449 and non-portable. The tools already provided with these systems don't
450 support all the features of GNU <CODE>gettext</CODE>. Therefore GNU
451 <CODE>gettext</CODE> uses its own format for MO files. Files ending with
452 <TT>‘.gmo’</TT> are really MO files, when it is known that these files use
458 <H2><A NAME="SEC6" HREF="gettext_toc.html#TOC6">1.5 Overview of GNU <CODE>gettext</CODE></A></H2>
464 The following diagram summarizes the relation between the files
465 handled by GNU <CODE>gettext</CODE> and the tools acting on these files.
466 It is followed by somewhat detailed explanations, which you should
467 read while keeping an eye on the diagram. Having a clear understanding
468 of these interrelations will surely help programmers, translators
474 Original C Sources ───> Preparation ───> Marked C Sources ───╮
476 ╭─────────<─── GNU gettext Library │
478 │ ╰─────────<────────────────────┬───────────────╯
480 │ ╭─────<─── PACKAGE.pot <─── xgettext <───╯ ╭───<─── PO Compendium
483 │ ╰───╮ ├───> PO editor ───╮
484 │ ├────> msgmerge ──────> LANG.po ────>────────╯ │
487 │ ╰─────────────<───────────────╮ │
488 │ ├─── New LANG.po <────────────────────╯
489 │ ╭─── LANG.gmo <─── msgfmt <───╯
491 │ ╰───> install ───> /.../LANG/PACKAGE.mo ───╮
492 │ ├───> "Hello world!"
493 ╰───────> install ───> /.../bin/PROGRAM ───────╯
499 As a programmer, the first step to bringing GNU <CODE>gettext</CODE>
500 into your package is identifying, right in the C sources, those strings
501 which are meant to be translatable, and those which are untranslatable.
502 This tedious job can be done a little more comfortably using emacs PO
503 mode, but you can use any means familiar to you for modifying your
504 C sources. Beside this some other simple, standard changes are needed to
505 properly initialize the translation library. See section <A HREF="gettext_4.html#SEC16">4 Preparing Program Sources</A>, for
506 more information about all this.
510 For newly written software the strings of course can and should be
511 marked while writing it. The <CODE>gettext</CODE> approach makes this
512 very easy. Simply put the following lines at the beginning of each file
513 or in a central header file:
518 #define _(String) (String)
519 #define N_(String) String
520 #define textdomain(Domain)
521 #define bindtextdomain(Package, Directory)
525 Doing this allows you to prepare the sources for internationalization.
526 Later when you feel ready for the step to use the <CODE>gettext</CODE> library
527 simply replace these definitions by the following:
534 #include <libintl.h>
535 #define _(String) gettext (String)
536 #define gettext_noop(String) String
537 #define N_(String) gettext_noop (String)
543 and link against <TT>‘libintl.a’</TT> or <TT>‘libintl.so’</TT>. Note that on
544 GNU systems, you don't need to link with <CODE>libintl</CODE> because the
545 <CODE>gettext</CODE> library functions are already contained in GNU libc.
546 That is all you have to change.
552 Once the C sources have been modified, the <CODE>xgettext</CODE> program
553 is used to find and extract all translatable strings, and create a
554 PO template file out of all these. This <TT>‘<VAR>package</VAR>.pot’</TT> file
555 contains all original program strings. It has sets of pointers to
556 exactly where in C sources each string is used. All translations
557 are set to empty. The letter <CODE>t</CODE> in <TT>‘.pot’</TT> marks this as
558 a Template PO file, not yet oriented towards any particular language.
559 See section <A HREF="gettext_5.html#SEC28">5.1 Invoking the <CODE>xgettext</CODE> Program</A>, for more details about how one calls the
560 <CODE>xgettext</CODE> program. If you are <EM>really</EM> lazy, you might
561 be interested at working a lot more right away, and preparing the
562 whole distribution setup (see section <A HREF="gettext_13.html#SEC211">13 The Maintainer's View</A>). By doing so, you
563 spare yourself typing the <CODE>xgettext</CODE> command, as <CODE>make</CODE>
564 should now generate the proper things automatically for you!
568 The first time through, there is no <TT>‘<VAR>lang</VAR>.po’</TT> yet, so the
569 <CODE>msgmerge</CODE> step may be skipped and replaced by a mere copy of
570 <TT>‘<VAR>package</VAR>.pot’</TT> to <TT>‘<VAR>lang</VAR>.po’</TT>, where <VAR>lang</VAR>
571 represents the target language. See section <A HREF="gettext_6.html#SEC37">6 Creating a New PO File</A> for details.
575 Then comes the initial translation of messages. Translation in
576 itself is a whole matter, still exclusively meant for humans,
577 and whose complexity far overwhelms the level of this manual.
578 Nevertheless, a few hints are given in some other chapter of this
579 manual (see section <A HREF="gettext_12.html#SEC198">12 The Translator's View</A>). You will also find there indications
580 about how to contact translating teams, or becoming part of them,
581 for sharing your translating concerns with others who target the same
586 While adding the translated messages into the <TT>‘<VAR>lang</VAR>.po’</TT>
587 PO file, if you are not using one of the dedicated PO file editors
588 (see section <A HREF="gettext_8.html#SEC55">8 Editing PO Files</A>), you are on your own
589 for ensuring that your efforts fully respect the PO file format, and quoting
590 conventions (see section <A HREF="gettext_3.html#SEC15">3 The Format of PO Files</A>). This is surely not an impossible task,
591 as this is the way many people have handled PO files around 1995.
592 On the other hand, by using a PO file editor, most details
593 of PO file format are taken care of for you, but you have to acquire
594 some familiarity with PO file editor itself.
598 If some common translations have already been saved into a compendium
599 PO file, translators may use PO mode for initializing untranslated
600 entries from the compendium, and also save selected translations into
601 the compendium, updating it (see section <A HREF="gettext_8.html#SEC72">8.4 Using Translation Compendia</A>). Compendium files
602 are meant to be exchanged between members of a given translation team.
606 Programs, or packages of programs, are dynamic in nature: users write
607 bug reports and suggestion for improvements, maintainers react by
608 modifying programs in various ways. The fact that a package has
609 already been internationalized should not make maintainers shy
610 of adding new strings, or modifying strings already translated.
611 They just do their job the best they can. For the Translation
612 Project to work smoothly, it is important that maintainers do not
613 carry translation concerns on their already loaded shoulders, and that
614 translators be kept as free as possible of programming concerns.
618 The only concern maintainers should have is carefully marking new
619 strings as translatable, when they should be, and do not otherwise
620 worry about them being translated, as this will come in proper time.
621 Consequently, when programs and their strings are adjusted in various
622 ways by maintainers, and for matters usually unrelated to translation,
623 <CODE>xgettext</CODE> would construct <TT>‘<VAR>package</VAR>.pot’</TT> files which are
624 evolving over time, so the translations carried by <TT>‘<VAR>lang</VAR>.po’</TT>
625 are slowly fading out of date.
630 It is important for translators (and even maintainers) to understand
631 that package translation is a continuous process in the lifetime of a
632 package, and not something which is done once and for all at the start.
633 After an initial burst of translation activity for a given package,
634 interventions are needed once in a while, because here and there,
635 translated entries become obsolete, and new untranslated entries
636 appear, needing translation.
640 The <CODE>msgmerge</CODE> program has the purpose of refreshing an already
641 existing <TT>‘<VAR>lang</VAR>.po’</TT> file, by comparing it with a newer
642 <TT>‘<VAR>package</VAR>.pot’</TT> template file, extracted by <CODE>xgettext</CODE>
643 out of recent C sources. The refreshing operation adjusts all
644 references to C source locations for strings, since these strings
645 move as programs are modified. Also, <CODE>msgmerge</CODE> comments out as
646 obsolete, in <TT>‘<VAR>lang</VAR>.po’</TT>, those already translated entries
647 which are no longer used in the program sources (see section <A HREF="gettext_8.html#SEC66">8.3.8 Obsolete Entries</A>). It finally discovers new strings and inserts them in
648 the resulting PO file as untranslated entries (see section <A HREF="gettext_8.html#SEC65">8.3.7 Untranslated Entries</A>). See section <A HREF="gettext_7.html#SEC46">7.1 Invoking the <CODE>msgmerge</CODE> Program</A>, for more information about what
649 <CODE>msgmerge</CODE> really does.
653 Whatever route or means taken, the goal is to obtain an updated
654 <TT>‘<VAR>lang</VAR>.po’</TT> file offering translations for all strings.
658 The temporal mobility, or fluidity of PO files, is an integral part of
659 the translation game, and should be well understood, and accepted.
660 People resisting it will have a hard time participating in the
661 Translation Project, or will give a hard time to other participants! In
662 particular, maintainers should relax and include all available official
663 PO files in their distributions, even if these have not recently been
664 updated, without exerting pressure on the translator teams to get the
665 job done. The pressure should rather come
666 from the community of users speaking a particular language, and
667 maintainers should consider themselves fairly relieved of any concern
668 about the adequacy of translation files. On the other hand, translators
669 should reasonably try updating the PO files they are responsible for,
670 while the package is undergoing pretest, prior to an official
675 Once the PO file is complete and dependable, the <CODE>msgfmt</CODE> program
676 is used for turning the PO file into a machine-oriented format, which
677 may yield efficient retrieval of translations by the programs of the
678 package, whenever needed at runtime (see section <A HREF="gettext_10.html#SEC177">10.3 The Format of GNU MO Files</A>). See section <A HREF="gettext_10.html#SEC157">10.1 Invoking the <CODE>msgfmt</CODE> Program</A>, for more information about all modes of execution
679 for the <CODE>msgfmt</CODE> program.
683 Finally, the modified and marked C sources are compiled and linked
684 with the GNU <CODE>gettext</CODE> library, usually through the operation of
685 <CODE>make</CODE>, given a suitable <TT>‘Makefile’</TT> exists for the project,
686 and the resulting executable is installed somewhere users will find it.
687 The MO files themselves should also be properly installed. Given the
688 appropriate environment variables are set (see section <A HREF="gettext_2.html#SEC10">2.3 Setting the Locale through Environment Variables</A>),
689 the program should localize itself automatically, whenever it executes.
693 The remainder of this manual has the purpose of explaining in depth the various
694 steps outlined above.
698 Go to the first, previous, <A HREF="gettext_2.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
projects / platform / upstream / gettext.git / blob