1This is gettext.info, produced by makeinfo version 4.12 from 2gettext.texi. 3 4INFO-DIR-SECTION GNU Gettext Utilities 5START-INFO-DIR-ENTRY 6* gettext: (gettext). GNU gettext utilities. 7* autopoint: (gettext)autopoint Invocation. Copy gettext infrastructure. 8* envsubst: (gettext)envsubst Invocation. Expand environment variables. 9* gettextize: (gettext)gettextize Invocation. Prepare a package for gettext. 10* msgattrib: (gettext)msgattrib Invocation. Select part of a PO file. 11* msgcat: (gettext)msgcat Invocation. Combine several PO files. 12* msgcmp: (gettext)msgcmp Invocation. Compare a PO file and template. 13* msgcomm: (gettext)msgcomm Invocation. Match two PO files. 14* msgconv: (gettext)msgconv Invocation. Convert PO file to encoding. 15* msgen: (gettext)msgen Invocation. Create an English PO file. 16* msgexec: (gettext)msgexec Invocation. Process a PO file. 17* msgfilter: (gettext)msgfilter Invocation. Pipe a PO file through a filter. 18* msgfmt: (gettext)msgfmt Invocation. Make MO files out of PO files. 19* msggrep: (gettext)msggrep Invocation. Select part of a PO file. 20* msginit: (gettext)msginit Invocation. Create a fresh PO file. 21* msgmerge: (gettext)msgmerge Invocation. Update a PO file from template. 22* msgunfmt: (gettext)msgunfmt Invocation. Uncompile MO file into PO file. 23* msguniq: (gettext)msguniq Invocation. Unify duplicates for PO file. 24* ngettext: (gettext)ngettext Invocation. Translate a message with plural. 25* xgettext: (gettext)xgettext Invocation. Extract strings into a PO file. 26* ISO639: (gettext)Language Codes. ISO 639 language codes. 27* ISO3166: (gettext)Country Codes. ISO 3166 country codes. 28END-INFO-DIR-ENTRY 29 30 This file provides documentation for GNU `gettext' utilities. It 31also serves as a reference for the free Translation Project. 32 33 Copyright (C) 1995-1998, 2001-2007 Free Software Foundation, Inc. 34 35 This manual is free documentation. It is dually licensed under the 36GNU FDL and the GNU GPL. This means that you can redistribute this 37manual under either of these two licenses, at your choice. 38 39 This manual is covered by the GNU FDL. Permission is granted to 40copy, distribute and/or modify this document under the terms of the GNU 41Free Documentation License (FDL), either version 1.2 of the License, or 42(at your option) any later version published by the Free Software 43Foundation (FSF); with no Invariant Sections, with no Front-Cover Text, 44and with no Back-Cover Texts. A copy of the license is included in 45*note GNU FDL::. 46 47 This manual is covered by the GNU GPL. You can redistribute it 48and/or modify it under the terms of the GNU General Public License 49(GPL), either version 2 of the License, or (at your option) any later 50version published by the Free Software Foundation (FSF). A copy of the 51license is included in *note GNU GPL::. 52 53 54File: gettext.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) 55 56GNU `gettext' utilities 57*********************** 58 59 This manual documents the GNU gettext tools and the GNU libintl 60library, version 0.17. 61 62* Menu: 63 64* Introduction:: Introduction 65* Users:: The User's View 66* PO Files:: The Format of PO Files 67* Sources:: Preparing Program Sources 68* Template:: Making the PO Template File 69* Creating:: Creating a New PO File 70* Updating:: Updating Existing PO Files 71* Editing:: Editing PO Files 72* Manipulating:: Manipulating PO Files 73* Binaries:: Producing Binary MO Files 74* Programmers:: The Programmer's View 75* Translators:: The Translator's View 76* Maintainers:: The Maintainer's View 77* Installers:: The Installer's and Distributor's View 78* Programming Languages:: Other Programming Languages 79* Conclusion:: Concluding Remarks 80 81* Language Codes:: ISO 639 language codes 82* Country Codes:: ISO 3166 country codes 83* Licenses:: Licenses 84 85* Program Index:: Index of Programs 86* Option Index:: Index of Command-Line Options 87* Variable Index:: Index of Environment Variables 88* PO Mode Index:: Index of Emacs PO Mode Commands 89* Autoconf Macro Index:: Index of Autoconf Macros 90* Index:: General Index 91 92 --- The Detailed Node Listing --- 93 94Introduction 95 96* Why:: The Purpose of GNU `gettext' 97* Concepts:: I18n, L10n, and Such 98* Aspects:: Aspects in Native Language Support 99* Files:: Files Conveying Translations 100* Overview:: Overview of GNU `gettext' 101 102The User's View 103 104* System Installation:: Questions During Operating System Installation 105* Setting the GUI Locale:: How to Specify the Locale Used by GUI Programs 106* Setting the POSIX Locale:: How to Specify the Locale According to POSIX 107* Installing Localizations:: How to Install Additional Translations 108 109Setting the POSIX Locale 110 111* Locale Names:: How a Locale Specification Looks Like 112* Locale Environment Variables:: Which Environment Variable Specfies What 113* The LANGUAGE variable:: How to Specify a Priority List of Languages 114 115Preparing Program Sources 116 117* Importing:: Importing the `gettext' declaration 118* Triggering:: Triggering `gettext' Operations 119* Preparing Strings:: Preparing Translatable Strings 120* Mark Keywords:: How Marks Appear in Sources 121* Marking:: Marking Translatable Strings 122* c-format Flag:: Telling something about the following string 123* Special cases:: Special Cases of Translatable Strings 124* Bug Report Address:: Letting Users Report Translation Bugs 125* Names:: Marking Proper Names for Translation 126* Libraries:: Preparing Library Sources 127 128Making the PO Template File 129 130* xgettext Invocation:: Invoking the `xgettext' Program 131 132Creating a New PO File 133 134* msginit Invocation:: Invoking the `msginit' Program 135* Header Entry:: Filling in the Header Entry 136 137Updating Existing PO Files 138 139* msgmerge Invocation:: Invoking the `msgmerge' Program 140 141Editing PO Files 142 143* KBabel:: KDE's PO File Editor 144* Gtranslator:: GNOME's PO File Editor 145* PO Mode:: Emacs's PO File Editor 146* Compendium:: Using Translation Compendia 147 148Emacs's PO File Editor 149 150* Installation:: Completing GNU `gettext' Installation 151* Main PO Commands:: Main Commands 152* Entry Positioning:: Entry Positioning 153* Normalizing:: Normalizing Strings in Entries 154* Translated Entries:: Translated Entries 155* Fuzzy Entries:: Fuzzy Entries 156* Untranslated Entries:: Untranslated Entries 157* Obsolete Entries:: Obsolete Entries 158* Modifying Translations:: Modifying Translations 159* Modifying Comments:: Modifying Comments 160* Subedit:: Mode for Editing Translations 161* C Sources Context:: C Sources Context 162* Auxiliary:: Consulting Auxiliary PO Files 163 164Using Translation Compendia 165 166* Creating Compendia:: Merging translations for later use 167* Using Compendia:: Using older translations if they fit 168 169Manipulating PO Files 170 171* msgcat Invocation:: Invoking the `msgcat' Program 172* msgconv Invocation:: Invoking the `msgconv' Program 173* msggrep Invocation:: Invoking the `msggrep' Program 174* msgfilter Invocation:: Invoking the `msgfilter' Program 175* msguniq Invocation:: Invoking the `msguniq' Program 176* msgcomm Invocation:: Invoking the `msgcomm' Program 177* msgcmp Invocation:: Invoking the `msgcmp' Program 178* msgattrib Invocation:: Invoking the `msgattrib' Program 179* msgen Invocation:: Invoking the `msgen' Program 180* msgexec Invocation:: Invoking the `msgexec' Program 181* Colorizing:: Highlighting parts of PO files 182* libgettextpo:: Writing your own programs that process PO files 183 184Highlighting parts of PO files 185 186* The --color option:: Triggering colorized output 187* The TERM variable:: The environment variable `TERM' 188* The --style option:: The `--style' option 189* Style rules:: Style rules for PO files 190* Customizing less:: Customizing `less' for viewing PO files 191 192Producing Binary MO Files 193 194* msgfmt Invocation:: Invoking the `msgfmt' Program 195* msgunfmt Invocation:: Invoking the `msgunfmt' Program 196* MO Files:: The Format of GNU MO Files 197 198The Programmer's View 199 200* catgets:: About `catgets' 201* gettext:: About `gettext' 202* Comparison:: Comparing the two interfaces 203* Using libintl.a:: Using libintl.a in own programs 204* gettext grok:: Being a `gettext' grok 205* Temp Programmers:: Temporary Notes for the Programmers Chapter 206 207About `catgets' 208 209* Interface to catgets:: The interface 210* Problems with catgets:: Problems with the `catgets' interface?! 211 212About `gettext' 213 214* Interface to gettext:: The interface 215* Ambiguities:: Solving ambiguities 216* Locating Catalogs:: Locating message catalog files 217* Charset conversion:: How to request conversion to Unicode 218* Contexts:: Solving ambiguities in GUI programs 219* Plural forms:: Additional functions for handling plurals 220* Optimized gettext:: Optimization of the *gettext functions 221 222Temporary Notes for the Programmers Chapter 223 224* Temp Implementations:: Temporary - Two Possible Implementations 225* Temp catgets:: Temporary - About `catgets' 226* Temp WSI:: Temporary - Why a single implementation 227* Temp Notes:: Temporary - Notes 228 229The Translator's View 230 231* Trans Intro 0:: Introduction 0 232* Trans Intro 1:: Introduction 1 233* Discussions:: Discussions 234* Organization:: Organization 235* Information Flow:: Information Flow 236* Prioritizing messages:: How to find which messages to translate first 237 238Organization 239 240* Central Coordination:: Central Coordination 241* National Teams:: National Teams 242* Mailing Lists:: Mailing Lists 243 244National Teams 245 246* Sub-Cultures:: Sub-Cultures 247* Organizational Ideas:: Organizational Ideas 248 249The Maintainer's View 250 251* Flat and Non-Flat:: Flat or Non-Flat Directory Structures 252* Prerequisites:: Prerequisite Works 253* gettextize Invocation:: Invoking the `gettextize' Program 254* Adjusting Files:: Files You Must Create or Alter 255* autoconf macros:: Autoconf macros for use in `configure.ac' 256* CVS Issues:: Integrating with CVS 257* Release Management:: Creating a Distribution Tarball 258 259Files You Must Create or Alter 260 261* po/POTFILES.in:: `POTFILES.in' in `po/' 262* po/LINGUAS:: `LINGUAS' in `po/' 263* po/Makevars:: `Makevars' in `po/' 264* po/Rules-*:: Extending `Makefile' in `po/' 265* configure.ac:: `configure.ac' at top level 266* config.guess:: `config.guess', `config.sub' at top level 267* mkinstalldirs:: `mkinstalldirs' at top level 268* aclocal:: `aclocal.m4' at top level 269* acconfig:: `acconfig.h' at top level 270* config.h.in:: `config.h.in' at top level 271* Makefile:: `Makefile.in' at top level 272* src/Makefile:: `Makefile.in' in `src/' 273* lib/gettext.h:: `gettext.h' in `lib/' 274 275Autoconf macros for use in `configure.ac' 276 277* AM_GNU_GETTEXT:: AM_GNU_GETTEXT in `gettext.m4' 278* AM_GNU_GETTEXT_VERSION:: AM_GNU_GETTEXT_VERSION in `gettext.m4' 279* AM_GNU_GETTEXT_NEED:: AM_GNU_GETTEXT_NEED in `gettext.m4' 280* AM_GNU_GETTEXT_INTL_SUBDIR:: AM_GNU_GETTEXT_INTL_SUBDIR in `intldir.m4' 281* AM_PO_SUBDIRS:: AM_PO_SUBDIRS in `po.m4' 282* AM_ICONV:: AM_ICONV in `iconv.m4' 283 284Integrating with CVS 285 286* Distributed CVS:: Avoiding version mismatch in distributed development 287* Files under CVS:: Files to put under CVS version control 288* autopoint Invocation:: Invoking the `autopoint' Program 289 290Other Programming Languages 291 292* Language Implementors:: The Language Implementor's View 293* Programmers for other Languages:: The Programmer's View 294* Translators for other Languages:: The Translator's View 295* Maintainers for other Languages:: The Maintainer's View 296* List of Programming Languages:: Individual Programming Languages 297* List of Data Formats:: Internationalizable Data 298 299The Translator's View 300 301* c-format:: C Format Strings 302* objc-format:: Objective C Format Strings 303* sh-format:: Shell Format Strings 304* python-format:: Python Format Strings 305* lisp-format:: Lisp Format Strings 306* elisp-format:: Emacs Lisp Format Strings 307* librep-format:: librep Format Strings 308* scheme-format:: Scheme Format Strings 309* smalltalk-format:: Smalltalk Format Strings 310* java-format:: Java Format Strings 311* csharp-format:: C# Format Strings 312* awk-format:: awk Format Strings 313* object-pascal-format:: Object Pascal Format Strings 314* ycp-format:: YCP Format Strings 315* tcl-format:: Tcl Format Strings 316* perl-format:: Perl Format Strings 317* php-format:: PHP Format Strings 318* gcc-internal-format:: GCC internal Format Strings 319* qt-format:: Qt Format Strings 320* kde-format:: KDE Format Strings 321* boost-format:: Boost Format Strings 322 323Individual Programming Languages 324 325* C:: C, C++, Objective C 326* sh:: sh - Shell Script 327* bash:: bash - Bourne-Again Shell Script 328* Python:: Python 329* Common Lisp:: GNU clisp - Common Lisp 330* clisp C:: GNU clisp C sources 331* Emacs Lisp:: Emacs Lisp 332* librep:: librep 333* Scheme:: GNU guile - Scheme 334* Smalltalk:: GNU Smalltalk 335* Java:: Java 336* C#:: C# 337* gawk:: GNU awk 338* Pascal:: Pascal - Free Pascal Compiler 339* wxWidgets:: wxWidgets library 340* YCP:: YCP - YaST2 scripting language 341* Tcl:: Tcl - Tk's scripting language 342* Perl:: Perl 343* PHP:: PHP Hypertext Preprocessor 344* Pike:: Pike 345* GCC-source:: GNU Compiler Collection sources 346 347sh - Shell Script 348 349* Preparing Shell Scripts:: Preparing Shell Scripts for Internationalization 350* gettext.sh:: Contents of `gettext.sh' 351* gettext Invocation:: Invoking the `gettext' program 352* ngettext Invocation:: Invoking the `ngettext' program 353* envsubst Invocation:: Invoking the `envsubst' program 354* eval_gettext Invocation:: Invoking the `eval_gettext' function 355* eval_ngettext Invocation:: Invoking the `eval_ngettext' function 356 357Perl 358 359* General Problems:: General Problems Parsing Perl Code 360* Default Keywords:: Which Keywords Will xgettext Look For? 361* Special Keywords:: How to Extract Hash Keys 362* Quote-like Expressions:: What are Strings And Quote-like Expressions? 363* Interpolation I:: Invalid String Interpolation 364* Interpolation II:: Valid String Interpolation 365* Parentheses:: When To Use Parentheses 366* Long Lines:: How To Grok with Long Lines 367* Perl Pitfalls:: Bugs, Pitfalls, and Things That Do Not Work 368 369Internationalizable Data 370 371* POT:: POT - Portable Object Template 372* RST:: Resource String Table 373* Glade:: Glade - GNOME user interface description 374 375Concluding Remarks 376 377* History:: History of GNU `gettext' 378* References:: Related Readings 379 380Language Codes 381 382* Usual Language Codes:: Two-letter ISO 639 language codes 383* Rare Language Codes:: Three-letter ISO 639 language codes 384 385Licenses 386 387* GNU GPL:: GNU General Public License 388* GNU LGPL:: GNU Lesser General Public License 389* GNU FDL:: GNU Free Documentation License 390 391 392File: gettext.info, Node: Introduction, Next: Users, Prev: Top, Up: Top 393 3941 Introduction 395************** 396 397 This chapter explains the goals sought in the creation of GNU 398`gettext' and the free Translation Project. Then, it explains a few 399broad concepts around Native Language Support, and positions message 400translation with regard to other aspects of national and cultural 401variance, as they apply to programs. It also surveys those files used 402to convey the translations. It explains how the various tools interact 403in the initial generation of these files, and later, how the maintenance 404cycle should usually operate. 405 406 In this manual, we use _he_ when speaking of the programmer or 407maintainer, _she_ when speaking of the translator, and _they_ when 408speaking of the installers or end users of the translated program. 409This is only a convenience for clarifying the documentation. It is 410_absolutely_ not meant to imply that some roles are more appropriate to 411males or females. Besides, as you might guess, GNU `gettext' is meant 412to be useful for people using computers, whatever their sex, race, 413religion or nationality! 414 415 Please send suggestions and corrections to: 416 417 Internet address: 418 bug-gnu-gettext@gnu.org 419 420Please include the manual's edition number and update date in your 421messages. 422 423* Menu: 424 425* Why:: The Purpose of GNU `gettext' 426* Concepts:: I18n, L10n, and Such 427* Aspects:: Aspects in Native Language Support 428* Files:: Files Conveying Translations 429* Overview:: Overview of GNU `gettext' 430 431 432File: gettext.info, Node: Why, Next: Concepts, Prev: Introduction, Up: Introduction 433 4341.1 The Purpose of GNU `gettext' 435================================ 436 437 Usually, programs are written and documented in English, and use 438English at execution time to interact with users. This is true not 439only of GNU software, but also of a great deal of proprietary and free 440software. Using a common language is quite handy for communication 441between developers, maintainers and users from all countries. On the 442other hand, most people are less comfortable with English than with 443their own native language, and would prefer to use their mother tongue 444for day to day's work, as far as possible. Many would simply _love_ to 445see their computer screen showing a lot less of English, and far more 446of their own language. 447 448 However, to many people, this dream might appear so far fetched that 449they may believe it is not even worth spending time thinking about it. 450They have no confidence at all that the dream might ever become true. 451Yet some have not lost hope, and have organized themselves. The 452Translation Project is a formalization of this hope into a workable 453structure, which has a good chance to get all of us nearer the 454achievement of a truly multi-lingual set of programs. 455 456 GNU `gettext' is an important step for the Translation Project, as 457it is an asset on which we may build many other steps. This package 458offers to programmers, translators and even users, a well integrated 459set of tools and documentation. Specifically, the GNU `gettext' 460utilities are a set of tools that provides a framework within which 461other free packages may produce multi-lingual messages. These tools 462include 463 464 * A set of conventions about how programs should be written to 465 support message catalogs. 466 467 * A directory and file naming organization for the message catalogs 468 themselves. 469 470 * A runtime library supporting the retrieval of translated messages. 471 472 * A few stand-alone programs to massage in various ways the sets of 473 translatable strings, or already translated strings. 474 475 * A library supporting the parsing and creation of files containing 476 translated messages. 477 478 * A special mode for Emacs(1) which helps preparing these sets and 479 bringing them up to date. 480 481 GNU `gettext' is designed to minimize the impact of 482internationalization on program sources, keeping this impact as small 483and hardly noticeable as possible. Internationalization has better 484chances of succeeding if it is very light weighted, or at least, appear 485to be so, when looking at program sources. 486 487 The Translation Project also uses the GNU `gettext' distribution as 488a vehicle for documenting its structure and methods. This goes beyond 489the strict technicalities of documenting the GNU `gettext' proper. By 490so doing, translators will find in a single place, as far as possible, 491all they need to know for properly doing their translating work. Also, 492this supplemental documentation might also help programmers, and even 493curious users, in understanding how GNU `gettext' is related to the 494remainder of the Translation Project, and consequently, have a glimpse 495at the _big picture_. 496 497 ---------- Footnotes ---------- 498 499 (1) In this manual, all mentions of Emacs refers to either GNU Emacs 500or to XEmacs, which people sometimes call FSF Emacs and Lucid Emacs, 501respectively. 502 503 504File: gettext.info, Node: Concepts, Next: Aspects, Prev: Why, Up: Introduction 505 5061.2 I18n, L10n, and Such 507======================== 508 509 Two long words appear all the time when we discuss support of native 510language in programs, and these words have a precise meaning, worth 511being explained here, once and for all in this document. The words are 512_internationalization_ and _localization_. Many people, tired of 513writing these long words over and over again, took the habit of writing 514"i18n" and "l10n" instead, quoting the first and last letter of each 515word, and replacing the run of intermediate letters by a number merely 516telling how many such letters there are. But in this manual, in the 517sake of clarity, we will patiently write the names in full, each time... 518 519 By "internationalization", one refers to the operation by which a 520program, or a set of programs turned into a package, is made aware of 521and able to support multiple languages. This is a generalization 522process, by which the programs are untied from calling only English 523strings or other English specific habits, and connected to generic ways 524of doing the same, instead. Program developers may use various 525techniques to internationalize their programs. Some of these have been 526standardized. GNU `gettext' offers one of these standards. *Note 527Programmers::. 528 529 By "localization", one means the operation by which, in a set of 530programs already internationalized, one gives the program all needed 531information so that it can adapt itself to handle its input and output 532in a fashion which is correct for some native language and cultural 533habits. This is a particularisation process, by which generic methods 534already implemented in an internationalized program are used in 535specific ways. The programming environment puts several functions to 536the programmers disposal which allow this runtime configuration. The 537formal description of specific set of cultural habits for some country, 538together with all associated translations targeted to the same native 539language, is called the "locale" for this language or country. Users 540achieve localization of programs by setting proper values to special 541environment variables, prior to executing those programs, identifying 542which locale should be used. 543 544 In fact, locale message support is only one component of the cultural 545data that makes up a particular locale. There are a whole host of 546routines and functions provided to aid programmers in developing 547internationalized software and which allow them to access the data 548stored in a particular locale. When someone presently refers to a 549particular locale, they are obviously referring to the data stored 550within that particular locale. Similarly, if a programmer is referring 551to "accessing the locale routines", they are referring to the complete 552suite of routines that access all of the locale's information. 553 554 One uses the expression "Native Language Support", or merely NLS, 555for speaking of the overall activity or feature encompassing both 556internationalization and localization, allowing for multi-lingual 557interactions in a program. In a nutshell, one could say that 558internationalization is the operation by which further localizations 559are made possible. 560 561 Also, very roughly said, when it comes to multi-lingual messages, 562internationalization is usually taken care of by programmers, and 563localization is usually taken care of by translators. 564 565 566File: gettext.info, Node: Aspects, Next: Files, Prev: Concepts, Up: Introduction 567 5681.3 Aspects in Native Language Support 569====================================== 570 571 For a totally multi-lingual distribution, there are many things to 572translate beyond output messages. 573 574 * As of today, GNU `gettext' offers a complete toolset for 575 translating messages output by C programs. Perl scripts and shell 576 scripts will also need to be translated. Even if there are today 577 some hooks by which this can be done, these hooks are not 578 integrated as well as they should be. 579 580 * Some programs, like `autoconf' or `bison', are able to produce 581 other programs (or scripts). Even if the generating programs 582 themselves are internationalized, the generated programs they 583 produce may need internationalization on their own, and this 584 indirect internationalization could be automated right from the 585 generating program. In fact, quite usually, generating and 586 generated programs could be internationalized independently, as 587 the effort needed is fairly orthogonal. 588 589 * A few programs include textual tables which might need translation 590 themselves, independently of the strings contained in the program 591 itself. For example, RFC 1345 gives an English description for 592 each character which the `recode' program is able to reconstruct 593 at execution. Since these descriptions are extracted from the RFC 594 by mechanical means, translating them properly would require a 595 prior translation of the RFC itself. 596 597 * Almost all programs accept options, which are often worded out so 598 to be descriptive for the English readers; one might want to 599 consider offering translated versions for program options as well. 600 601 * Many programs read, interpret, compile, or are somewhat driven by 602 input files which are texts containing keywords, identifiers, or 603 replies which are inherently translatable. For example, one may 604 want `gcc' to allow diacriticized characters in identifiers or use 605 translated keywords; `rm -i' might accept something else than `y' 606 or `n' for replies, etc. Even if the program will eventually make 607 most of its output in the foreign languages, one has to decide 608 whether the input syntax, option values, etc., are to be localized 609 or not. 610 611 * The manual accompanying a package, as well as all documentation 612 files in the distribution, could surely be translated, too. 613 Translating a manual, with the intent of later keeping up with 614 updates, is a major undertaking in itself, generally. 615 616 617 As we already stressed, translation is only one aspect of locales. 618Other internationalization aspects are system services and are handled 619in GNU `libc'. There are many attributes that are needed to define a 620country's cultural conventions. These attributes include beside the 621country's native language, the formatting of the date and time, the 622representation of numbers, the symbols for currency, etc. These local 623"rules" are termed the country's locale. The locale represents the 624knowledge needed to support the country's native attributes. 625 626 There are a few major areas which may vary between countries and 627hence, define what a locale must describe. The following list helps 628putting multi-lingual messages into the proper context of other tasks 629related to locales. See the GNU `libc' manual for details. 630 631_Characters and Codesets_ 632 The codeset most commonly used through out the USA and most English 633 speaking parts of the world is the ASCII codeset. However, there 634 are many characters needed by various locales that are not found 635 within this codeset. The 8-bit ISO 8859-1 code set has most of 636 the special characters needed to handle the major European 637 languages. However, in many cases, choosing ISO 8859-1 is 638 nevertheless not adequate: it doesn't even handle the major 639 European currency. Hence each locale will need to specify which 640 codeset they need to use and will need to have the appropriate 641 character handling routines to cope with the codeset. 642 643_Currency_ 644 The symbols used vary from country to country as does the position 645 used by the symbol. Software needs to be able to transparently 646 display currency figures in the native mode for each locale. 647 648_Dates_ 649 The format of date varies between locales. For example, Christmas 650 day in 1994 is written as 12/25/94 in the USA and as 25/12/94 in 651 Australia. Other countries might use ISO 8601 dates, etc. 652 653 Time of the day may be noted as HH:MM, HH.MM, or otherwise. Some 654 locales require time to be specified in 24-hour mode rather than 655 as AM or PM. Further, the nature and yearly extent of the 656 Daylight Saving correction vary widely between countries. 657 658_Numbers_ 659 Numbers can be represented differently in different locales. For 660 example, the following numbers are all written correctly for their 661 respective locales: 662 663 12,345.67 English 664 12.345,67 German 665 12345,67 French 666 1,2345.67 Asia 667 668 Some programs could go further and use different unit systems, like 669 English units or Metric units, or even take into account variants 670 about how numbers are spelled in full. 671 672_Messages_ 673 The most obvious area is the language support within a locale. 674 This is where GNU `gettext' provides the means for developers and 675 users to easily change the language that the software uses to 676 communicate to the user. 677 678 679 These areas of cultural conventions are called _locale categories_. 680It is an unfortunate term; _locale aspects_ or _locale feature 681categories_ would be a better term, because each "locale category" 682describes an area or task that requires localization. The concrete data 683that describes the cultural conventions for such an area and for a 684particular culture is also called a _locale category_. In this sense, 685a locale is composed of several locale categories: the locale category 686describing the codeset, the locale category describing the formatting 687of numbers, the locale category containing the translated messages, and 688so on. 689 690 Components of locale outside of message handling are standardized in 691the ISO C standard and the POSIX:2001 standard (also known as the SUSV3 692specification). GNU `libc' fully implements this, and most other 693modern systems provide a more or less reasonable support for at least 694some of the missing components. 695 696 697File: gettext.info, Node: Files, Next: Overview, Prev: Aspects, Up: Introduction 698 6991.4 Files Conveying Translations 700================================ 701 702 The letters PO in `.po' files means Portable Object, to distinguish 703it from `.mo' files, where MO stands for Machine Object. This 704paradigm, as well as the PO file format, is inspired by the NLS 705standard developed by Uniforum, and first implemented by Sun in their 706Solaris system. 707 708 PO files are meant to be read and edited by humans, and associate 709each original, translatable string of a given package with its 710translation in a particular target language. A single PO file is 711dedicated to a single target language. If a package supports many 712languages, there is one such PO file per language supported, and each 713package has its own set of PO files. These PO files are best created by 714the `xgettext' program, and later updated or refreshed through the 715`msgmerge' program. Program `xgettext' extracts all marked messages 716from a set of C files and initializes a PO file with empty 717translations. Program `msgmerge' takes care of adjusting PO files 718between releases of the corresponding sources, commenting obsolete 719entries, initializing new ones, and updating all source line 720references. Files ending with `.pot' are kind of base translation 721files found in distributions, in PO file format. 722 723 MO files are meant to be read by programs, and are binary in nature. 724A few systems already offer tools for creating and handling MO files as 725part of the Native Language Support coming with the system, but the 726format of these MO files is often different from system to system, and 727non-portable. The tools already provided with these systems don't 728support all the features of GNU `gettext'. Therefore GNU `gettext' 729uses its own format for MO files. Files ending with `.gmo' are really 730MO files, when it is known that these files use the GNU format. 731 732 733File: gettext.info, Node: Overview, Prev: Files, Up: Introduction 734 7351.5 Overview of GNU `gettext' 736============================= 737 738 The following diagram summarizes the relation between the files 739handled by GNU `gettext' and the tools acting on these files. It is 740followed by somewhat detailed explanations, which you should read while 741keeping an eye on the diagram. Having a clear understanding of these 742interrelations will surely help programmers, translators and 743maintainers. 744 745 Original C Sources ---> Preparation ---> Marked C Sources ---. 746 | 747 .---------<--- GNU gettext Library | 748 .--- make <---+ | 749 | `---------<--------------------+---------------' 750 | | 751 | .-----<--- PACKAGE.pot <--- xgettext <---' .---<--- PO Compendium 752 | | | ^ 753 | | `---. | 754 | `---. +---> PO editor ---. 755 | +----> msgmerge ------> LANG.po ---->--------' | 756 | .---' | 757 | | | 758 | `-------------<---------------. | 759 | +--- New LANG.po <--------------------' 760 | .--- LANG.gmo <--- msgfmt <---' 761 | | 762 | `---> install ---> /.../LANG/PACKAGE.mo ---. 763 | +---> "Hello world!" 764 `-------> install ---> /.../bin/PROGRAM -------' 765 766 As a programmer, the first step to bringing GNU `gettext' into your 767package is identifying, right in the C sources, those strings which are 768meant to be translatable, and those which are untranslatable. This 769tedious job can be done a little more comfortably using emacs PO mode, 770but you can use any means familiar to you for modifying your C sources. 771Beside this some other simple, standard changes are needed to properly 772initialize the translation library. *Note Sources::, for more 773information about all this. 774 775 For newly written software the strings of course can and should be 776marked while writing it. The `gettext' approach makes this very easy. 777Simply put the following lines at the beginning of each file or in a 778central header file: 779 780 #define _(String) (String) 781 #define N_(String) String 782 #define textdomain(Domain) 783 #define bindtextdomain(Package, Directory) 784 785Doing this allows you to prepare the sources for internationalization. 786Later when you feel ready for the step to use the `gettext' library 787simply replace these definitions by the following: 788 789 #include <libintl.h> 790 #define _(String) gettext (String) 791 #define gettext_noop(String) String 792 #define N_(String) gettext_noop (String) 793 794and link against `libintl.a' or `libintl.so'. Note that on GNU 795systems, you don't need to link with `libintl' because the `gettext' 796library functions are already contained in GNU libc. That is all you 797have to change. 798 799 Once the C sources have been modified, the `xgettext' program is 800used to find and extract all translatable strings, and create a PO 801template file out of all these. This `PACKAGE.pot' file contains all 802original program strings. It has sets of pointers to exactly where in 803C sources each string is used. All translations are set to empty. The 804letter `t' in `.pot' marks this as a Template PO file, not yet oriented 805towards any particular language. *Note xgettext Invocation::, for more 806details about how one calls the `xgettext' program. If you are 807_really_ lazy, you might be interested at working a lot more right 808away, and preparing the whole distribution setup (*note Maintainers::). 809By doing so, you spare yourself typing the `xgettext' command, as `make' 810should now generate the proper things automatically for you! 811 812 The first time through, there is no `LANG.po' yet, so the `msgmerge' 813step may be skipped and replaced by a mere copy of `PACKAGE.pot' to 814`LANG.po', where LANG represents the target language. See *note 815Creating:: for details. 816 817 Then comes the initial translation of messages. Translation in 818itself is a whole matter, still exclusively meant for humans, and whose 819complexity far overwhelms the level of this manual. Nevertheless, a 820few hints are given in some other chapter of this manual (*note 821Translators::). You will also find there indications about how to 822contact translating teams, or becoming part of them, for sharing your 823translating concerns with others who target the same native language. 824 825 While adding the translated messages into the `LANG.po' PO file, if 826you are not using one of the dedicated PO file editors (*note 827Editing::), you are on your own for ensuring that your efforts fully 828respect the PO file format, and quoting conventions (*note PO Files::). 829This is surely not an impossible task, as this is the way many people 830have handled PO files around 1995. On the other hand, by using a PO 831file editor, most details of PO file format are taken care of for you, 832but you have to acquire some familiarity with PO file editor itself. 833 834 If some common translations have already been saved into a compendium 835PO file, translators may use PO mode for initializing untranslated 836entries from the compendium, and also save selected translations into 837the compendium, updating it (*note Compendium::). Compendium files are 838meant to be exchanged between members of a given translation team. 839 840 Programs, or packages of programs, are dynamic in nature: users write 841bug reports and suggestion for improvements, maintainers react by 842modifying programs in various ways. The fact that a package has 843already been internationalized should not make maintainers shy of 844adding new strings, or modifying strings already translated. They just 845do their job the best they can. For the Translation Project to work 846smoothly, it is important that maintainers do not carry translation 847concerns on their already loaded shoulders, and that translators be 848kept as free as possible of programming concerns. 849 850 The only concern maintainers should have is carefully marking new 851strings as translatable, when they should be, and do not otherwise 852worry about them being translated, as this will come in proper time. 853Consequently, when programs and their strings are adjusted in various 854ways by maintainers, and for matters usually unrelated to translation, 855`xgettext' would construct `PACKAGE.pot' files which are evolving over 856time, so the translations carried by `LANG.po' are slowly fading out of 857date. 858 859 It is important for translators (and even maintainers) to understand 860that package translation is a continuous process in the lifetime of a 861package, and not something which is done once and for all at the start. 862After an initial burst of translation activity for a given package, 863interventions are needed once in a while, because here and there, 864translated entries become obsolete, and new untranslated entries 865appear, needing translation. 866 867 The `msgmerge' program has the purpose of refreshing an already 868existing `LANG.po' file, by comparing it with a newer `PACKAGE.pot' 869template file, extracted by `xgettext' out of recent C sources. The 870refreshing operation adjusts all references to C source locations for 871strings, since these strings move as programs are modified. Also, 872`msgmerge' comments out as obsolete, in `LANG.po', those already 873translated entries which are no longer used in the program sources 874(*note Obsolete Entries::). It finally discovers new strings and 875inserts them in the resulting PO file as untranslated entries (*note 876Untranslated Entries::). *Note msgmerge Invocation::, for more 877information about what `msgmerge' really does. 878 879 Whatever route or means taken, the goal is to obtain an updated 880`LANG.po' file offering translations for all strings. 881 882 The temporal mobility, or fluidity of PO files, is an integral part 883of the translation game, and should be well understood, and accepted. 884People resisting it will have a hard time participating in the 885Translation Project, or will give a hard time to other participants! In 886particular, maintainers should relax and include all available official 887PO files in their distributions, even if these have not recently been 888updated, without exerting pressure on the translator teams to get the 889job done. The pressure should rather come from the community of users 890speaking a particular language, and maintainers should consider 891themselves fairly relieved of any concern about the adequacy of 892translation files. On the other hand, translators should reasonably 893try updating the PO files they are responsible for, while the package 894is undergoing pretest, prior to an official distribution. 895 896 Once the PO file is complete and dependable, the `msgfmt' program is 897used for turning the PO file into a machine-oriented format, which may 898yield efficient retrieval of translations by the programs of the 899package, whenever needed at runtime (*note MO Files::). *Note msgfmt 900Invocation::, for more information about all modes of execution for the 901`msgfmt' program. 902 903 Finally, the modified and marked C sources are compiled and linked 904with the GNU `gettext' library, usually through the operation of 905`make', given a suitable `Makefile' exists for the project, and the 906resulting executable is installed somewhere users will find it. The MO 907files themselves should also be properly installed. Given the 908appropriate environment variables are set (*note Setting the POSIX 909Locale::), the program should localize itself automatically, whenever 910it executes. 911 912 The remainder of this manual has the purpose of explaining in depth 913the various steps outlined above. 914 915 916File: gettext.info, Node: Users, Next: PO Files, Prev: Introduction, Up: Top 917 9182 The User's View 919***************** 920 921 Nowadays, when users log into a computer, they usually find that all 922their programs show messages in their native language - at least for 923users of languages with an active free software community, like French 924or German; to a lesser extent for languages with a smaller 925participation in free software and the GNU project, like Hindi and 926Filipino. 927 928 How does this work? How can the user influence the language that is 929used by the programs? This chapter will answer it. 930 931* Menu: 932 933* System Installation:: Questions During Operating System Installation 934* Setting the GUI Locale:: How to Specify the Locale Used by GUI Programs 935* Setting the POSIX Locale:: How to Specify the Locale According to POSIX 936* Installing Localizations:: How to Install Additional Translations 937 938 939File: gettext.info, Node: System Installation, Next: Setting the GUI Locale, Prev: Users, Up: Users 940 9412.1 Operating System Installation 942================================= 943 944 The default language is often already specified during operating 945system installation. When the operating system is installed, the 946installer typically asks for the language used for the installation 947process and, separately, for the language to use in the installed 948system. Some OS installers only ask for the language once. 949 950 This determines the system-wide default language for all users. But 951the installers often give the possibility to install extra 952localizations for additional languages. For example, the localizations 953of KDE (the K Desktop Environment) and OpenOffice.org are often bundled 954separately, as one installable package per language. 955 956 At this point it is good to consider the intended use of the 957machine: If it is a machine designated for personal use, additional 958localizations are probably not necessary. If, however, the machine is 959in use in an organization or company that has international 960relationships, one can consider the needs of guest users. If you have 961a guest from abroad, for a week, what could be his preferred locales? 962It may be worth installing these additional localizations ahead of 963time, since they cost only a bit of disk space at this point. 964 965 The system-wide default language is the locale configuration that is 966used when a new user account is created. But the user can have his own 967locale configuration that is different from the one of the other users 968of the same machine. He can specify it, typically after the first 969login, as described in the next section. 970 971 972File: gettext.info, Node: Setting the GUI Locale, Next: Setting the POSIX Locale, Prev: System Installation, Up: Users 973 9742.2 Setting the Locale Used by GUI Programs 975=========================================== 976 977 The immediately available programs in a user's desktop come from a 978group of programs called a "desktop environment"; it usually includes 979the window manager, a web browser, a text editor, and more. The most 980common free desktop environments are KDE, GNOME, and Xfce. 981 982 The locale used by GUI programs of the desktop environment can be 983specified in a configuration screen called "control center", "language 984settings" or "country settings". 985 986 Individual GUI programs that are not part of the desktop environment 987can have their locale specified either in a settings panel, or through 988environment variables. 989 990 For some programs, it is possible to specify the locale through 991environment variables, possibly even to a different locale than the 992desktop's locale. This means, instead of starting a program through a 993menu or from the file system, you can start it from the command-line, 994after having set some environment variables. The environment variables 995can be those specified in the next section (*note Setting the POSIX 996Locale::); for some versions of KDE, however, the locale is specified 997through a variable `KDE_LANG', rather than `LANG' or `LC_ALL'. 998 999 1000File: gettext.info, Node: Setting the POSIX Locale, Next: Installing Localizations, Prev: Setting the GUI Locale, Up: Users 1001 10022.3 Setting the Locale through Environment Variables 1003==================================================== 1004 1005 As a user, if your language has been installed for this package, in 1006the simplest case, you only have to set the `LANG' environment variable 1007to the appropriate `LL_CC' combination. For example, let's suppose 1008that you speak German and live in Germany. At the shell prompt, merely 1009execute `setenv LANG de_DE' (in `csh'), `export LANG; LANG=de_DE' (in 1010`sh') or `export LANG=de_DE' (in `bash'). This can be done from your 1011`.login' or `.profile' file, once and for all. 1012 1013* Menu: 1014 1015* Locale Names:: How a Locale Specification Looks Like 1016* Locale Environment Variables:: Which Environment Variable Specfies What 1017* The LANGUAGE variable:: How to Specify a Priority List of Languages 1018 1019 1020File: gettext.info, Node: Locale Names, Next: Locale Environment Variables, Prev: Setting the POSIX Locale, Up: Setting the POSIX Locale 1021 10222.3.1 Locale Names 1023------------------ 1024 1025 A locale name usually has the form `LL_CC'. Here `LL' is an ISO 639 1026two-letter language code, and `CC' is an ISO 3166 two-letter country 1027code. For example, for German in Germany, LL is `de', and CC is `DE'. 1028You find a list of the language codes in appendix *note Language 1029Codes:: and a list of the country codes in appendix *note Country 1030Codes::. 1031 1032 You might think that the country code specification is redundant. 1033But in fact, some languages have dialects in different countries. For 1034example, `de_AT' is used for Austria, and `pt_BR' for Brazil. The 1035country code serves to distinguish the dialects. 1036 1037 Many locale names have an extended syntax `LL_CC.ENCODING' that also 1038specifies the character encoding. These are in use because between 10392000 and 2005, most users have switched to locales in UTF-8 encoding. 1040For example, the German locale on glibc systems is nowadays 1041`de_DE.UTF-8'. The older name `de_DE' still refers to the German 1042locale as of 2000 that stores characters in ISO-8859-1 encoding - a 1043text encoding that cannot even accomodate the Euro currency sign. 1044 1045 Some locale names use `LL_CC.@VARIANT' instead of `LL_CC'. The 1046`@VARIANT' can denote any kind of characteristics that is not already 1047implied by the language LL and the country CC. It can denote a 1048particular monetary unit. For example, on glibc systems, `de_DE@euro' 1049denotes the locale that uses the Euro currency, in contrast to the 1050older locale `de_DE' which implies the use of the currency before 2002. 1051It can also denote a dialect of the language, or the script used to 1052write text (for example, `sr_RS@latin' uses the Latin script, whereas 1053`sr_RS' uses the Cyrillic script to write Serbian), or the orthography 1054rules, or similar. 1055 1056 On other systems, some variations of this scheme are used, such as 1057`LL'. You can get the list of locales supported by your system for 1058your language by running the command `locale -a | grep '^LL''. 1059 1060 There is also a special locale, called `C'. When it is used, it 1061disables all localization: in this locale, all programs standardized by 1062POSIX use English messages and an unspecified character encoding (often 1063US-ASCII, but sometimes also ISO-8859-1 or UTF-8, depending on the 1064operating system). 1065 1066 1067File: gettext.info, Node: Locale Environment Variables, Next: The LANGUAGE variable, Prev: Locale Names, Up: Setting the POSIX Locale 1068 10692.3.2 Locale Environment Variables 1070---------------------------------- 1071 1072 A locale is composed of several _locale categories_, see *note 1073Aspects::. When a program looks up locale dependent values, it does 1074this according to the following environment variables, in priority 1075order: 1076 1077 1. `LANGUAGE' 1078 1079 2. `LC_ALL' 1080 1081 3. `LC_xxx', according to selected locale category: `LC_CTYPE', 1082 `LC_NUMERIC', `LC_TIME', `LC_COLLATE', `LC_MONETARY', 1083 `LC_MESSAGES', ... 1084 1085 4. `LANG' 1086 1087 Variables whose value is set but is empty are ignored in this lookup. 1088 1089 `LANG' is the normal environment variable for specifying a locale. 1090As a user, you normally set this variable (unless some of the other 1091variables have already been set by the system, in `/etc/profile' or 1092similar initialization files). 1093 1094 `LC_CTYPE', `LC_NUMERIC', `LC_TIME', `LC_COLLATE', `LC_MONETARY', 1095`LC_MESSAGES', and so on, are the environment variables meant to 1096override `LANG' and affecting a single locale category only. For 1097example, assume you are a Swedish user in Spain, and you want your 1098programs to handle numbers and dates according to Spanish conventions, 1099and only the messages should be in Swedish. Then you could create a 1100locale named `sv_ES' or `sv_ES.UTF-8' by use of the `localedef' 1101program. But it is simpler, and achieves the same effect, to set the 1102`LANG' variable to `es_ES.UTF-8' and the `LC_MESSAGES' variable to 1103`sv_SE.UTF-8'; these two locales come already preinstalled with the 1104operating system. 1105 1106 `LC_ALL' is an environment variable that overrides all of these. It 1107is typically used in scripts that run particular programs. For example, 1108`configure' scripts generated by GNU autoconf use `LC_ALL' to make sure 1109that the configuration tests don't operate in locale dependent ways. 1110 1111 Some systems, unfortunately, set `LC_ALL' in `/etc/profile' or in 1112similar initialization files. As a user, you therefore have to unset 1113this variable if you want to set `LANG' and optionally some of the other 1114`LC_xxx' variables. 1115 1116 The `LANGUAGE' variable is described in the next subsection. 1117 1118 1119File: gettext.info, Node: The LANGUAGE variable, Prev: Locale Environment Variables, Up: Setting the POSIX Locale 1120 11212.3.3 Specifying a Priority List of Languages 1122--------------------------------------------- 1123 1124 Not all programs have translations for all languages. By default, an 1125English message is shown in place of a nonexistent translation. If you 1126understand other languages, you can set up a priority list of languages. 1127This is done through a different environment variable, called 1128`LANGUAGE'. GNU `gettext' gives preference to `LANGUAGE' over `LC_ALL' 1129and `LANG' for the purpose of message handling, but you still need to 1130have `LANG' (or `LC_ALL') set to the primary language; this is required 1131by other parts of the system libraries. For example, some Swedish 1132users who would rather read translations in German than English for 1133when Swedish is not available, set `LANGUAGE' to `sv:de' while leaving 1134`LANG' to `sv_SE'. 1135 1136 Special advice for Norwegian users: The language code for Norwegian 1137bokma*l changed from `no' to `nb' recently (in 2003). During the 1138transition period, while some message catalogs for this language are 1139installed under `nb' and some older ones under `no', it is recommended 1140for Norwegian users to set `LANGUAGE' to `nb:no' so that both newer and 1141older translations are used. 1142 1143 In the `LANGUAGE' environment variable, but not in the other 1144environment variables, `LL_CC' combinations can be abbreviated as `LL' 1145to denote the language's main dialect. For example, `de' is equivalent 1146to `de_DE' (German as spoken in Germany), and `pt' to `pt_PT' 1147(Portuguese as spoken in Portugal) in this context. 1148 1149 Note: The variable `LANGUAGE' is ignored if the locale is set to 1150`C'. In other words, you have to first enable localization, by setting 1151`LANG' (or `LC_ALL') to a value other than `C', before you can use a 1152language priority list through the `LANGUAGE' variable. 1153 1154 1155File: gettext.info, Node: Installing Localizations, Prev: Setting the POSIX Locale, Up: Users 1156 11572.4 Installing Translations for Particular Programs 1158=================================================== 1159 1160 Languages are not equally well supported in all packages using GNU 1161`gettext', and more translations are added over time. Usually, you use 1162the translations that are shipped with the operating system or with 1163particular packages that you install afterwards. But you can also 1164install newer localizations directly. For doing this, you will need an 1165understanding where each localization file is stored on the file system. 1166 1167 For programs that participate in the Translation Project, you can 1168start looking for translations here: 1169`http://translationproject.org/team/index.html'. A snapshot of this 1170information is also found in the `ABOUT-NLS' file that is shipped with 1171GNU gettext. 1172 1173 For programs that are part of the KDE project, the starting point is: 1174`http://i18n.kde.org/'. 1175 1176 For programs that are part of the GNOME project, the starting point 1177is: `http://www.gnome.org/i18n/'. 1178 1179 For other programs, you may check whether the program's source code 1180package contains some `LL.po' files; often they are kept together in a 1181directory called `po/'. Each `LL.po' file contains the message 1182translations for the language whose abbreviation of LL. 1183 1184 1185File: gettext.info, Node: PO Files, Next: Sources, Prev: Users, Up: Top 1186 11873 The Format of PO Files 1188************************ 1189 1190 The GNU `gettext' toolset helps programmers and translators at 1191producing, updating and using translation files, mainly those PO files 1192which are textual, editable files. This chapter explains the format of 1193PO files. 1194 1195 A PO file is made up of many entries, each entry holding the relation 1196between an original untranslated string and its corresponding 1197translation. All entries in a given PO file usually pertain to a 1198single project, and all translations are expressed in a single target 1199language. One PO file "entry" has the following schematic structure: 1200 1201 WHITE-SPACE 1202 # TRANSLATOR-COMMENTS 1203 #. EXTRACTED-COMMENTS 1204 #: REFERENCE... 1205 #, FLAG... 1206 #| msgid PREVIOUS-UNTRANSLATED-STRING 1207 msgid UNTRANSLATED-STRING 1208 msgstr TRANSLATED-STRING 1209 1210 The general structure of a PO file should be well understood by the 1211translator. When using PO mode, very little has to be known about the 1212format details, as PO mode takes care of them for her. 1213 1214 A simple entry can look like this: 1215 1216 #: lib/error.c:116 1217 msgid "Unknown system error" 1218 msgstr "Error desconegut del sistema" 1219 1220 Entries begin with some optional white space. Usually, when 1221generated through GNU `gettext' tools, there is exactly one blank line 1222between entries. Then comments follow, on lines all starting with the 1223character `#'. There are two kinds of comments: those which have some 1224white space immediately following the `#' - the TRANSLATOR COMMENTS -, 1225which comments are created and maintained exclusively by the 1226translator, and those which have some non-white character just after the 1227`#' - the AUTOMATIC COMMENTS -, which comments are created and 1228maintained automatically by GNU `gettext' tools. Comment lines 1229starting with `#.' contain comments given by the programmer, directed 1230at the translator; these comments are called EXTRACTED COMMENTS because 1231the `xgettext' program extracts them from the program's source code. 1232Comment lines starting with `#:' contain references to the program's 1233source code. Comment lines starting with `#,' contain flags; more 1234about these below. Comment lines starting with `#|' contain the 1235previous untranslated string for which the translator gave a 1236translation. 1237 1238 All comments, of either kind, are optional. 1239 1240 After white space and comments, entries show two strings, namely 1241first the untranslated string as it appears in the original program 1242sources, and then, the translation of this string. The original string 1243is introduced by the keyword `msgid', and the translation, by `msgstr'. 1244The two strings, untranslated and translated, are quoted in various 1245ways in the PO file, using `"' delimiters and `\' escapes, but the 1246translator does not really have to pay attention to the precise quoting 1247format, as PO mode fully takes care of quoting for her. 1248 1249 The `msgid' strings, as well as automatic comments, are produced and 1250managed by other GNU `gettext' tools, and PO mode does not provide 1251means for the translator to alter these. The most she can do is merely 1252deleting them, and only by deleting the whole entry. On the other 1253hand, the `msgstr' string, as well as translator comments, are really 1254meant for the translator, and PO mode gives her the full control she 1255needs. 1256 1257 The comment lines beginning with `#,' are special because they are 1258not completely ignored by the programs as comments generally are. The 1259comma separated list of FLAGs is used by the `msgfmt' program to give 1260the user some better diagnostic messages. Currently there are two 1261forms of flags defined: 1262 1263`fuzzy' 1264 This flag can be generated by the `msgmerge' program or it can be 1265 inserted by the translator herself. It shows that the `msgstr' 1266 string might not be a correct translation (anymore). Only the 1267 translator can judge if the translation requires further 1268 modification, or is acceptable as is. Once satisfied with the 1269 translation, she then removes this `fuzzy' attribute. The 1270 `msgmerge' program inserts this when it combined the `msgid' and 1271 `msgstr' entries after fuzzy search only. *Note Fuzzy Entries::. 1272 1273`c-format' 1274`no-c-format' 1275 These flags should not be added by a human. Instead only the 1276 `xgettext' program adds them. In an automated PO file processing 1277 system as proposed here the user changes would be thrown away 1278 again as soon as the `xgettext' program generates a new template 1279 file. 1280 1281 The `c-format' flag tells that the untranslated string and the 1282 translation are supposed to be C format strings. The `no-c-format' 1283 flag tells that they are not C format strings, even though the 1284 untranslated string happens to look like a C format string (with 1285 `%' directives). 1286 1287 In case the `c-format' flag is given for a string the `msgfmt' 1288 does some more tests to check to validity of the translation. 1289 *Note msgfmt Invocation::, *note c-format Flag:: and *note 1290 c-format::. 1291 1292`objc-format' 1293`no-objc-format' 1294 Likewise for Objective C, see *note objc-format::. 1295 1296`sh-format' 1297`no-sh-format' 1298 Likewise for Shell, see *note sh-format::. 1299 1300`python-format' 1301`no-python-format' 1302 Likewise for Python, see *note python-format::. 1303 1304`lisp-format' 1305`no-lisp-format' 1306 Likewise for Lisp, see *note lisp-format::. 1307 1308`elisp-format' 1309`no-elisp-format' 1310 Likewise for Emacs Lisp, see *note elisp-format::. 1311 1312`librep-format' 1313`no-librep-format' 1314 Likewise for librep, see *note librep-format::. 1315 1316`scheme-format' 1317`no-scheme-format' 1318 Likewise for Scheme, see *note scheme-format::. 1319 1320`smalltalk-format' 1321`no-smalltalk-format' 1322 Likewise for Smalltalk, see *note smalltalk-format::. 1323 1324`java-format' 1325`no-java-format' 1326 Likewise for Java, see *note java-format::. 1327 1328`csharp-format' 1329`no-csharp-format' 1330 Likewise for C#, see *note csharp-format::. 1331 1332`awk-format' 1333`no-awk-format' 1334 Likewise for awk, see *note awk-format::. 1335 1336`object-pascal-format' 1337`no-object-pascal-format' 1338 Likewise for Object Pascal, see *note object-pascal-format::. 1339 1340`ycp-format' 1341`no-ycp-format' 1342 Likewise for YCP, see *note ycp-format::. 1343 1344`tcl-format' 1345`no-tcl-format' 1346 Likewise for Tcl, see *note tcl-format::. 1347 1348`perl-format' 1349`no-perl-format' 1350 Likewise for Perl, see *note perl-format::. 1351 1352`perl-brace-format' 1353`no-perl-brace-format' 1354 Likewise for Perl brace, see *note perl-format::. 1355 1356`php-format' 1357`no-php-format' 1358 Likewise for PHP, see *note php-format::. 1359 1360`gcc-internal-format' 1361`no-gcc-internal-format' 1362 Likewise for the GCC sources, see *note gcc-internal-format::. 1363 1364`qt-format' 1365`no-qt-format' 1366 Likewise for Qt, see *note qt-format::. 1367 1368`kde-format' 1369`no-kde-format' 1370 Likewise for KDE, see *note kde-format::. 1371 1372`boost-format' 1373`no-boost-format' 1374 Likewise for Boost, see *note boost-format::. 1375 1376 1377 It is also possible to have entries with a context specifier. They 1378look like this: 1379 1380 WHITE-SPACE 1381 # TRANSLATOR-COMMENTS 1382 #. EXTRACTED-COMMENTS 1383 #: REFERENCE... 1384 #, FLAG... 1385 #| msgctxt PREVIOUS-CONTEXT 1386 #| msgid PREVIOUS-UNTRANSLATED-STRING 1387 msgctxt CONTEXT 1388 msgid UNTRANSLATED-STRING 1389 msgstr TRANSLATED-STRING 1390 1391 The context serves to disambiguate messages with the same 1392UNTRANSLATED-STRING. It is possible to have several entries with the 1393same UNTRANSLATED-STRING in a PO file, provided that they each have a 1394different CONTEXT. Note that an empty CONTEXT string and an absent 1395`msgctxt' line do not mean the same thing. 1396 1397 A different kind of entries is used for translations which involve 1398plural forms. 1399 1400 WHITE-SPACE 1401 # TRANSLATOR-COMMENTS 1402 #. EXTRACTED-COMMENTS 1403 #: REFERENCE... 1404 #, FLAG... 1405 #| msgid PREVIOUS-UNTRANSLATED-STRING-SINGULAR 1406 #| msgid_plural PREVIOUS-UNTRANSLATED-STRING-PLURAL 1407 msgid UNTRANSLATED-STRING-SINGULAR 1408 msgid_plural UNTRANSLATED-STRING-PLURAL 1409 msgstr[0] TRANSLATED-STRING-CASE-0 1410 ... 1411 msgstr[N] TRANSLATED-STRING-CASE-N 1412 1413 Such an entry can look like this: 1414 1415 #: src/msgcmp.c:338 src/po-lex.c:699 1416 #, c-format 1417 msgid "found %d fatal error" 1418 msgid_plural "found %d fatal errors" 1419 msgstr[0] "s'ha trobat %d error fatal" 1420 msgstr[1] "s'han trobat %d errors fatals" 1421 1422 Here also, a `msgctxt' context can be specified before `msgid', like 1423above. 1424 1425 The PREVIOUS-UNTRANSLATED-STRING is optionally inserted by the 1426`msgmerge' program, at the same time when it marks a message fuzzy. It 1427helps the translator to see which changes were done by the developers 1428on the UNTRANSLATED-STRING. 1429 1430 It happens that some lines, usually whitespace or comments, follow 1431the very last entry of a PO file. Such lines are not part of any entry, 1432and will be dropped when the PO file is processed by the tools, or may 1433disturb some PO file editors. 1434 1435 The remainder of this section may be safely skipped by those using a 1436PO file editor, yet it may be interesting for everybody to have a better 1437idea of the precise format of a PO file. On the other hand, those 1438wishing to modify PO files by hand should carefully continue reading on. 1439 1440 Each of UNTRANSLATED-STRING and TRANSLATED-STRING respects the C 1441syntax for a character string, including the surrounding quotes and 1442embedded backslashed escape sequences. When the time comes to write 1443multi-line strings, one should not use escaped newlines. Instead, a 1444closing quote should follow the last character on the line to be 1445continued, and an opening quote should resume the string at the 1446beginning of the following PO file line. For example: 1447 1448 msgid "" 1449 "Here is an example of how one might continue a very long string\n" 1450 "for the common case the string represents multi-line output.\n" 1451 1452In this example, the empty string is used on the first line, to allow 1453better alignment of the `H' from the word `Here' over the `f' from the 1454word `for'. In this example, the `msgid' keyword is followed by three 1455strings, which are meant to be concatenated. Concatenating the empty 1456string does not change the resulting overall string, but it is a way 1457for us to comply with the necessity of `msgid' to be followed by a 1458string on the same line, while keeping the multi-line presentation 1459left-justified, as we find this to be a cleaner disposition. The empty 1460string could have been omitted, but only if the string starting with 1461`Here' was promoted on the first line, right after `msgid'.(1) It was 1462not really necessary either to switch between the two last quoted 1463strings immediately after the newline `\n', the switch could have 1464occurred after _any_ other character, we just did it this way because 1465it is neater. 1466 1467 One should carefully distinguish between end of lines marked as `\n' 1468_inside_ quotes, which are part of the represented string, and end of 1469lines in the PO file itself, outside string quotes, which have no 1470incidence on the represented string. 1471 1472 Outside strings, white lines and comments may be used freely. 1473Comments start at the beginning of a line with `#' and extend until the 1474end of the PO file line. Comments written by translators should have 1475the initial `#' immediately followed by some white space. If the `#' 1476is not immediately followed by white space, this comment is most likely 1477generated and managed by specialized GNU tools, and might disappear or 1478be replaced unexpectedly when the PO file is given to `msgmerge'. 1479 1480 ---------- Footnotes ---------- 1481 1482 (1) This limitation is not imposed by GNU `gettext', but is for 1483compatibility with the `msgfmt' implementation on Solaris. 1484 1485 1486File: gettext.info, Node: Sources, Next: Template, Prev: PO Files, Up: Top 1487 14884 Preparing Program Sources 1489*************************** 1490 1491 For the programmer, changes to the C source code fall into three 1492categories. First, you have to make the localization functions known 1493to all modules needing message translation. Second, you should 1494properly trigger the operation of GNU `gettext' when the program 1495initializes, usually from the `main' function. Last, you should 1496identify, adjust and mark all constant strings in your program needing 1497translation. 1498 1499* Menu: 1500 1501* Importing:: Importing the `gettext' declaration 1502* Triggering:: Triggering `gettext' Operations 1503* Preparing Strings:: Preparing Translatable Strings 1504* Mark Keywords:: How Marks Appear in Sources 1505* Marking:: Marking Translatable Strings 1506* c-format Flag:: Telling something about the following string 1507* Special cases:: Special Cases of Translatable Strings 1508* Bug Report Address:: Letting Users Report Translation Bugs 1509* Names:: Marking Proper Names for Translation 1510* Libraries:: Preparing Library Sources 1511 1512 1513File: gettext.info, Node: Importing, Next: Triggering, Prev: Sources, Up: Sources 1514 15154.1 Importing the `gettext' declaration 1516======================================= 1517 1518 Presuming that your set of programs, or package, has been adjusted 1519so all needed GNU `gettext' files are available, and your `Makefile' 1520files are adjusted (*note Maintainers::), each C module having 1521translated C strings should contain the line: 1522 1523 #include <libintl.h> 1524 1525 Similarly, each C module containing `printf()'/`fprintf()'/... 1526calls with a format string that could be a translated C string (even if 1527the C string comes from a different C module) should contain the line: 1528 1529 #include <libintl.h> 1530 1531 1532File: gettext.info, Node: Triggering, Next: Preparing Strings, Prev: Importing, Up: Sources 1533 15344.2 Triggering `gettext' Operations 1535=================================== 1536 1537 The initialization of locale data should be done with more or less 1538the same code in every program, as demonstrated below: 1539 1540 int 1541 main (int argc, char *argv[]) 1542 { 1543 ... 1544 setlocale (LC_ALL, ""); 1545 bindtextdomain (PACKAGE, LOCALEDIR); 1546 textdomain (PACKAGE); 1547 ... 1548 } 1549 1550 PACKAGE and LOCALEDIR should be provided either by `config.h' or by 1551the Makefile. For now consult the `gettext' or `hello' sources for 1552more information. 1553 1554 The use of `LC_ALL' might not be appropriate for you. `LC_ALL' 1555includes all locale categories and especially `LC_CTYPE'. This latter 1556category is responsible for determining character classes with the 1557`isalnum' etc. functions from `ctype.h' which could especially for 1558programs, which process some kind of input language, be wrong. For 1559example this would mean that a source code using the �� (c-cedilla 1560character) is runnable in France but not in the U.S. 1561 1562 Some systems also have problems with parsing numbers using the 1563`scanf' functions if an other but the `LC_ALL' locale category is used. 1564The standards say that additional formats but the one known in the 1565`"C"' locale might be recognized. But some systems seem to reject 1566numbers in the `"C"' locale format. In some situation, it might also 1567be a problem with the notation itself which makes it impossible to 1568recognize whether the number is in the `"C"' locale or the local 1569format. This can happen if thousands separator characters are used. 1570Some locales define this character according to the national 1571conventions to `'.'' which is the same character used in the `"C"' 1572locale to denote the decimal point. 1573 1574 So it is sometimes necessary to replace the `LC_ALL' line in the 1575code above by a sequence of `setlocale' lines 1576 1577 { 1578 ... 1579 setlocale (LC_CTYPE, ""); 1580 setlocale (LC_MESSAGES, ""); 1581 ... 1582 } 1583 1584On all POSIX conformant systems the locale categories `LC_CTYPE', 1585`LC_MESSAGES', `LC_COLLATE', `LC_MONETARY', `LC_NUMERIC', and `LC_TIME' 1586are available. On some systems which are only ISO C compliant, 1587`LC_MESSAGES' is missing, but a substitute for it is defined in GNU 1588gettext's `<libintl.h>' and in GNU gnulib's `<locale.h>'. 1589 1590 Note that changing the `LC_CTYPE' also affects the functions 1591declared in the `<ctype.h>' standard header and some functions declared 1592in the `<string.h>' and `<stdlib.h>' standard headers. If this is not 1593desirable in your application (for example in a compiler's parser), you 1594can use a set of substitute functions which hardwire the C locale, such 1595as found in the modules `c-ctype', `c-strcase', `c-strcasestr', 1596`c-strtod', `c-strtold' in the GNU gnulib source distribution. 1597 1598 It is also possible to switch the locale forth and back between the 1599environment dependent locale and the C locale, but this approach is 1600normally avoided because a `setlocale' call is expensive, because it is 1601tedious to determine the places where a locale switch is needed in a 1602large program's source, and because switching a locale is not 1603multithread-safe. 1604 1605 1606File: gettext.info, Node: Preparing Strings, Next: Mark Keywords, Prev: Triggering, Up: Sources 1607 16084.3 Preparing Translatable Strings 1609================================== 1610 1611 Before strings can be marked for translations, they sometimes need to 1612be adjusted. Usually preparing a string for translation is done right 1613before marking it, during the marking phase which is described in the 1614next sections. What you have to keep in mind while doing that is the 1615following. 1616 1617 * Decent English style. 1618 1619 * Entire sentences. 1620 1621 * Split at paragraphs. 1622 1623 * Use format strings instead of string concatenation. 1624 1625 * Avoid unusual markup and unusual control characters. 1626 1627Let's look at some examples of these guidelines. 1628 1629 Translatable strings should be in good English style. If slang 1630language with abbreviations and shortcuts is used, often translators 1631will not understand the message and will produce very inappropriate 1632translations. 1633 1634 "%s: is parameter\n" 1635 1636This is nearly untranslatable: Is the displayed item _a_ parameter or 1637_the_ parameter? 1638 1639 "No match" 1640 1641The ambiguity in this message makes it unintelligible: Is the program 1642attempting to set something on fire? Does it mean "The given object does 1643not match the template"? Does it mean "The template does not fit for any 1644of the objects"? 1645 1646 In both cases, adding more words to the message will help both the 1647translator and the English speaking user. 1648 1649 Translatable strings should be entire sentences. It is often not 1650possible to translate single verbs or adjectives in a substitutable way. 1651 1652 printf ("File %s is %s protected", filename, rw ? "write" : "read"); 1653 1654Most translators will not look at the source and will thus only see the 1655string `"File %s is %s protected"', which is unintelligible. Change 1656this to 1657 1658 printf (rw ? "File %s is write protected" : "File %s is read protected", 1659 filename); 1660 1661This way the translator will not only understand the message, she will 1662also be able to find the appropriate grammatical construction. A French 1663translator for example translates "write protected" like "protected 1664against writing". 1665 1666 Entire sentences are also important because in many languages, the 1667declination of some word in a sentence depends on the gender or the 1668number (singular/plural) of another part of the sentence. There are 1669usually more interdependencies between words than in English. The 1670consequence is that asking a translator to translate two half-sentences 1671and then combining these two half-sentences through dumb string 1672concatenation will not work, for many languages, even though it would 1673work for English. That's why translators need to handle entire 1674sentences. 1675 1676 Often sentences don't fit into a single line. If a sentence is 1677output using two subsequent `printf' statements, like this 1678 1679 printf ("Locale charset \"%s\" is different from\n", lcharset); 1680 printf ("input file charset \"%s\".\n", fcharset); 1681 1682the translator would have to translate two half sentences, but nothing 1683in the POT file would tell her that the two half sentences belong 1684together. It is necessary to merge the two `printf' statements so that 1685the translator can handle the entire sentence at once and decide at 1686which place to insert a line break in the translation (if at all): 1687 1688 printf ("Locale charset \"%s\" is different from\n\ 1689 input file charset \"%s\".\n", lcharset, fcharset); 1690 1691 You may now ask: how about two or more adjacent sentences? Like in 1692this case: 1693 1694 puts ("Apollo 13 scenario: Stack overflow handling failed."); 1695 puts ("On the next stack overflow we will crash!!!"); 1696 1697Should these two statements merged into a single one? I would recommend 1698to merge them if the two sentences are related to each other, because 1699then it makes it easier for the translator to understand and translate 1700both. On the other hand, if one of the two messages is a stereotypic 1701one, occurring in other places as well, you will do a favour to the 1702translator by not merging the two. (Identical messages occurring in 1703several places are combined by xgettext, so the translator has to 1704handle them once only.) 1705 1706 Translatable strings should be limited to one paragraph; don't let a 1707single message be longer than ten lines. The reason is that when the 1708translatable string changes, the translator is faced with the task of 1709updating the entire translated string. Maybe only a single word will 1710have changed in the English string, but the translator doesn't see that 1711(with the current translation tools), therefore she has to proofread 1712the entire message. 1713 1714 Many GNU programs have a `--help' output that extends over several 1715screen pages. It is a courtesy towards the translators to split such a 1716message into several ones of five to ten lines each. While doing that, 1717you can also attempt to split the documented options into groups, such 1718as the input options, the output options, and the informative output 1719options. This will help every user to find the option he is looking 1720for. 1721 1722 Hardcoded string concatenation is sometimes used to construct English 1723strings: 1724 1725 strcpy (s, "Replace "); 1726 strcat (s, object1); 1727 strcat (s, " with "); 1728 strcat (s, object2); 1729 strcat (s, "?"); 1730 1731In order to present to the translator only entire sentences, and also 1732because in some languages the translator might want to swap the order 1733of `object1' and `object2', it is necessary to change this to use a 1734format string: 1735 1736 sprintf (s, "Replace %s with %s?", object1, object2); 1737 1738 A similar case is compile time concatenation of strings. The ISO C 173999 include file `<inttypes.h>' contains a macro `PRId64' that can be 1740used as a formatting directive for outputting an `int64_t' integer 1741through `printf'. It expands to a constant string, usually "d" or "ld" 1742or "lld" or something like this, depending on the platform. Assume you 1743have code like 1744 1745 printf ("The amount is %0" PRId64 "\n", number); 1746 1747The `gettext' tools and library have special support for these 1748`<inttypes.h>' macros. You can therefore simply write 1749 1750 printf (gettext ("The amount is %0" PRId64 "\n"), number); 1751 1752The PO file will contain the string "The amount is %0<PRId64>\n". The 1753translators will provide a translation containing "%0<PRId64>" as well, 1754and at runtime the `gettext' function's result will contain the 1755appropriate constant string, "d" or "ld" or "lld". 1756 1757 This works only for the predefined `<inttypes.h>' macros. If you 1758have defined your own similar macros, let's say `MYPRId64', that are 1759not known to `xgettext', the solution for this problem is to change the 1760code like this: 1761 1762 char buf1[100]; 1763 sprintf (buf1, "%0" MYPRId64, number); 1764 printf (gettext ("The amount is %s\n"), buf1); 1765 1766 This means, you put the platform dependent code in one statement, 1767and the internationalization code in a different statement. Note that 1768a buffer length of 100 is safe, because all available hardware integer 1769types are limited to 128 bits, and to print a 128 bit integer one needs 1770at most 54 characters, regardless whether in decimal, octal or 1771hexadecimal. 1772 1773 All this applies to other programming languages as well. For 1774example, in Java and C#, string concatenation is very frequently used, 1775because it is a compiler built-in operator. Like in C, in Java, you 1776would change 1777 1778 System.out.println("Replace "+object1+" with "+object2+"?"); 1779 1780into a statement involving a format string: 1781 1782 System.out.println( 1783 MessageFormat.format("Replace {0} with {1}?", 1784 new Object[] { object1, object2 })); 1785 1786Similarly, in C#, you would change 1787 1788 Console.WriteLine("Replace "+object1+" with "+object2+"?"); 1789 1790into a statement involving a format string: 1791 1792 Console.WriteLine( 1793 String.Format("Replace {0} with {1}?", object1, object2)); 1794 1795 Unusual markup or control characters should not be used in 1796translatable strings. Translators will likely not understand the 1797particular meaning of the markup or control characters. 1798 1799 For example, if you have a convention that `|' delimits the 1800left-hand and right-hand part of some GUI elements, translators will 1801often not understand it without specific comments. It might be better 1802to have the translator translate the left-hand and right-hand part 1803separately. 1804 1805 Another example is the `argp' convention to use a single `\v' 1806(vertical tab) control character to delimit two sections inside a 1807string. This is flawed. Some translators may convert it to a simple 1808newline, some to blank lines. With some PO file editors it may not be 1809easy to even enter a vertical tab control character. So, you cannot be 1810sure that the translation will contain a `\v' character, at the 1811corresponding position. The solution is, again, to let the translator 1812translate two separate strings and combine at run-time the two 1813translated strings with the `\v' required by the convention. 1814 1815 HTML markup, however, is common enough that it's probably ok to use 1816in translatable strings. But please bear in mind that the GNU gettext 1817tools don't verify that the translations are well-formed HTML. 1818 1819 1820File: gettext.info, Node: Mark Keywords, Next: Marking, Prev: Preparing Strings, Up: Sources 1821 18224.4 How Marks Appear in Sources 1823=============================== 1824 1825 All strings requiring translation should be marked in the C sources. 1826Marking is done in such a way that each translatable string appears to 1827be the sole argument of some function or preprocessor macro. There are 1828only a few such possible functions or macros meant for translation, and 1829their names are said to be marking keywords. The marking is attached 1830to strings themselves, rather than to what we do with them. This 1831approach has more uses. A blatant example is an error message produced 1832by formatting. The format string needs translation, as well as some 1833strings inserted through some `%s' specification in the format, while 1834the result from `sprintf' may have so many different instances that it 1835is impractical to list them all in some `error_string_out()' routine, 1836say. 1837 1838 This marking operation has two goals. The first goal of marking is 1839for triggering the retrieval of the translation, at run time. The 1840keyword is possibly resolved into a routine able to dynamically return 1841the proper translation, as far as possible or wanted, for the argument 1842string. Most localizable strings are found in executable positions, 1843that is, attached to variables or given as parameters to functions. 1844But this is not universal usage, and some translatable strings appear 1845in structured initializations. *Note Special cases::. 1846 1847 The second goal of the marking operation is to help `xgettext' at 1848properly extracting all translatable strings when it scans a set of 1849program sources and produces PO file templates. 1850 1851 The canonical keyword for marking translatable strings is `gettext', 1852it gave its name to the whole GNU `gettext' package. For packages 1853making only light use of the `gettext' keyword, macro or function, it 1854is easily used _as is_. However, for packages using the `gettext' 1855interface more heavily, it is usually more convenient to give the main 1856keyword a shorter, less obtrusive name. Indeed, the keyword might 1857appear on a lot of strings all over the package, and programmers 1858usually do not want nor need their program sources to remind them 1859forcefully, all the time, that they are internationalized. Further, a 1860long keyword has the disadvantage of using more horizontal space, 1861forcing more indentation work on sources for those trying to keep them 1862within 79 or 80 columns. 1863 1864 Many packages use `_' (a simple underline) as a keyword, and write 1865`_("Translatable string")' instead of `gettext ("Translatable 1866string")'. Further, the coding rule, from GNU standards, wanting that 1867there is a space between the keyword and the opening parenthesis is 1868relaxed, in practice, for this particular usage. So, the textual 1869overhead per translatable string is reduced to only three characters: 1870the underline and the two parentheses. However, even if GNU `gettext' 1871uses this convention internally, it does not offer it officially. The 1872real, genuine keyword is truly `gettext' indeed. It is fairly easy for 1873those wanting to use `_' instead of `gettext' to declare: 1874 1875 #include <libintl.h> 1876 #define _(String) gettext (String) 1877 1878instead of merely using `#include <libintl.h>'. 1879 1880 The marking keywords `gettext' and `_' take the translatable string 1881as sole argument. It is also possible to define marking functions that 1882take it at another argument position. It is even possible to make the 1883marked argument position depend on the total number of arguments of the 1884function call; this is useful in C++. All this is achieved using 1885`xgettext''s `--keyword' option. 1886 1887 Note also that long strings can be split across lines, into multiple 1888adjacent string tokens. Automatic string concatenation is performed at 1889compile time according to ISO C and ISO C++; `xgettext' also supports 1890this syntax. 1891 1892 Later on, the maintenance is relatively easy. If, as a programmer, 1893you add or modify a string, you will have to ask yourself if the new or 1894altered string requires translation, and include it within `_()' if you 1895think it should be translated. For example, `"%s"' is an example of 1896string _not_ requiring translation. But `"%s: %d"' _does_ require 1897translation, because in French, unlike in English, it's customary to 1898put a space before a colon. 1899 1900 1901File: gettext.info, Node: Marking, Next: c-format Flag, Prev: Mark Keywords, Up: Sources 1902 19034.5 Marking Translatable Strings 1904================================ 1905 1906 In PO mode, one set of features is meant more for the programmer than 1907for the translator, and allows him to interactively mark which strings, 1908in a set of program sources, are translatable, and which are not. Even 1909if it is a fairly easy job for a programmer to find and mark such 1910strings by other means, using any editor of his choice, PO mode makes 1911this work more comfortable. Further, this gives translators who feel a 1912little like programmers, or programmers who feel a little like 1913translators, a tool letting them work at marking translatable strings 1914in the program sources, while simultaneously producing a set of 1915translation in some language, for the package being internationalized. 1916 1917 The set of program sources, targeted by the PO mode commands describe 1918here, should have an Emacs tags table constructed for your project, 1919prior to using these PO file commands. This is easy to do. In any 1920shell window, change the directory to the root of your project, then 1921execute a command resembling: 1922 1923 etags src/*.[hc] lib/*.[hc] 1924 1925presuming here you want to process all `.h' and `.c' files from the 1926`src/' and `lib/' directories. This command will explore all said 1927files and create a `TAGS' file in your root directory, somewhat 1928summarizing the contents using a special file format Emacs can 1929understand. 1930 1931 For packages following the GNU coding standards, there is a make 1932goal `tags' or `TAGS' which constructs the tag files in all directories 1933and for all files containing source code. 1934 1935 Once your `TAGS' file is ready, the following commands assist the 1936programmer at marking translatable strings in his set of sources. But 1937these commands are necessarily driven from within a PO file window, and 1938it is likely that you do not even have such a PO file yet. This is not 1939a problem at all, as you may safely open a new, empty PO file, mainly 1940for using these commands. This empty PO file will slowly fill in while 1941you mark strings as translatable in your program sources. 1942 1943`,' 1944 Search through program sources for a string which looks like a 1945 candidate for translation (`po-tags-search'). 1946 1947`M-,' 1948 Mark the last string found with `_()' (`po-mark-translatable'). 1949 1950`M-.' 1951 Mark the last string found with a keyword taken from a set of 1952 possible keywords. This command with a prefix allows some 1953 management of these keywords (`po-select-mark-and-mark'). 1954 1955 1956 The `,' (`po-tags-search') command searches for the next occurrence 1957of a string which looks like a possible candidate for translation, and 1958displays the program source in another Emacs window, positioned in such 1959a way that the string is near the top of this other window. If the 1960string is too big to fit whole in this window, it is positioned so only 1961its end is shown. In any case, the cursor is left in the PO file 1962window. If the shown string would be better presented differently in 1963different native languages, you may mark it using `M-,' or `M-.'. 1964Otherwise, you might rather ignore it and skip to the next string by 1965merely repeating the `,' command. 1966 1967 A string is a good candidate for translation if it contains a 1968sequence of three or more letters. A string containing at most two 1969letters in a row will be considered as a candidate if it has more 1970letters than non-letters. The command disregards strings containing no 1971letters, or isolated letters only. It also disregards strings within 1972comments, or strings already marked with some keyword PO mode knows 1973(see below). 1974 1975 If you have never told Emacs about some `TAGS' file to use, the 1976command will request that you specify one from the minibuffer, the 1977first time you use the command. You may later change your `TAGS' file 1978by using the regular Emacs command `M-x visit-tags-table', which will 1979ask you to name the precise `TAGS' file you want to use. *Note Tag 1980Tables: (emacs)Tags. 1981 1982 Each time you use the `,' command, the search resumes from where it 1983was left by the previous search, and goes through all program sources, 1984obeying the `TAGS' file, until all sources have been processed. 1985However, by giving a prefix argument to the command (`C-u ,'), you may 1986request that the search be restarted all over again from the first 1987program source; but in this case, strings that you recently marked as 1988translatable will be automatically skipped. 1989 1990 Using this `,' command does not prevent using of other regular Emacs 1991tags commands. For example, regular `tags-search' or 1992`tags-query-replace' commands may be used without disrupting the 1993independent `,' search sequence. However, as implemented, the 1994_initial_ `,' command (or the `,' command is used with a prefix) might 1995also reinitialize the regular Emacs tags searching to the first tags 1996file, this reinitialization might be considered spurious. 1997 1998 The `M-,' (`po-mark-translatable') command will mark the recently 1999found string with the `_' keyword. The `M-.' 2000(`po-select-mark-and-mark') command will request that you type one 2001keyword from the minibuffer and use that keyword for marking the 2002string. Both commands will automatically create a new PO file 2003untranslated entry for the string being marked, and make it the current 2004entry (making it easy for you to immediately proceed to its 2005translation, if you feel like doing it right away). It is possible 2006that the modifications made to the program source by `M-,' or `M-.' 2007render some source line longer than 80 columns, forcing you to break 2008and re-indent this line differently. You may use the `O' command from 2009PO mode, or any other window changing command from Emacs, to break out 2010into the program source window, and do any needed adjustments. You 2011will have to use some regular Emacs command to return the cursor to the 2012PO file window, if you want command `,' for the next string, say. 2013 2014 The `M-.' command has a few built-in speedups, so you do not have to 2015explicitly type all keywords all the time. The first such speedup is 2016that you are presented with a _preferred_ keyword, which you may accept 2017by merely typing `<RET>' at the prompt. The second speedup is that you 2018may type any non-ambiguous prefix of the keyword you really mean, and 2019the command will complete it automatically for you. This also means 2020that PO mode has to _know_ all your possible keywords, and that it will 2021not accept mistyped keywords. 2022 2023 If you reply `?' to the keyword request, the command gives a list of 2024all known keywords, from which you may choose. When the command is 2025prefixed by an argument (`C-u M-.'), it inhibits updating any program 2026source or PO file buffer, and does some simple keyword management 2027instead. In this case, the command asks for a keyword, written in 2028full, which becomes a new allowed keyword for later `M-.' commands. 2029Moreover, this new keyword automatically becomes the _preferred_ 2030keyword for later commands. By typing an already known keyword in 2031response to `C-u M-.', one merely changes the _preferred_ keyword and 2032does nothing more. 2033 2034 All keywords known for `M-.' are recognized by the `,' command when 2035scanning for strings, and strings already marked by any of those known 2036keywords are automatically skipped. If many PO files are opened 2037simultaneously, each one has its own independent set of known keywords. 2038There is no provision in PO mode, currently, for deleting a known 2039keyword, you have to quit the file (maybe using `q') and reopen it 2040afresh. When a PO file is newly brought up in an Emacs window, only 2041`gettext' and `_' are known as keywords, and `gettext' is preferred for 2042the `M-.' command. In fact, this is not useful to prefer `_', as this 2043one is already built in the `M-,' command. 2044 2045 2046File: gettext.info, Node: c-format Flag, Next: Special cases, Prev: Marking, Up: Sources 2047 20484.6 Special Comments preceding Keywords 2049======================================= 2050 2051 In C programs strings are often used within calls of functions from 2052the `printf' family. The special thing about these format strings is 2053that they can contain format specifiers introduced with `%'. Assume we 2054have the code 2055 2056 printf (gettext ("String `%s' has %d characters\n"), s, strlen (s)); 2057 2058A possible German translation for the above string might be: 2059 2060 "%d Zeichen lang ist die Zeichenkette `%s'" 2061 2062 A C programmer, even if he cannot speak German, will recognize that 2063there is something wrong here. The order of the two format specifiers 2064is changed but of course the arguments in the `printf' don't have. 2065This will most probably lead to problems because now the length of the 2066string is regarded as the address. 2067 2068 To prevent errors at runtime caused by translations the `msgfmt' 2069tool can check statically whether the arguments in the original and the 2070translation string match in type and number. If this is not the case 2071and the `-c' option has been passed to `msgfmt', `msgfmt' will give an 2072error and refuse to produce a MO file. Thus consequent use of `msgfmt 2073-c' will catch the error, so that it cannot cause cause problems at 2074runtime. 2075 2076If the word order in the above German translation would be correct one 2077would have to write 2078 2079 "%2$d Zeichen lang ist die Zeichenkette `%1$s'" 2080 2081The routines in `msgfmt' know about this special notation. 2082 2083 Because not all strings in a program must be format strings it is not 2084useful for `msgfmt' to test all the strings in the `.po' file. This 2085might cause problems because the string might contain what looks like a 2086format specifier, but the string is not used in `printf'. 2087 2088 Therefore the `xgettext' adds a special tag to those messages it 2089thinks might be a format string. There is no absolute rule for this, 2090only a heuristic. In the `.po' file the entry is marked using the 2091`c-format' flag in the `#,' comment line (*note PO Files::). 2092 2093 The careful reader now might say that this again can cause problems. 2094The heuristic might guess it wrong. This is true and therefore 2095`xgettext' knows about a special kind of comment which lets the 2096programmer take over the decision. If in the same line as or the 2097immediately preceding line to the `gettext' keyword the `xgettext' 2098program finds a comment containing the words `xgettext:c-format', it 2099will mark the string in any case with the `c-format' flag. This kind 2100of comment should be used when `xgettext' does not recognize the string 2101as a format string but it really is one and it should be tested. 2102Please note that when the comment is in the same line as the `gettext' 2103keyword, it must be before the string to be translated. 2104 2105 This situation happens quite often. The `printf' function is often 2106called with strings which do not contain a format specifier. Of course 2107one would normally use `fputs' but it does happen. In this case 2108`xgettext' does not recognize this as a format string but what happens 2109if the translation introduces a valid format specifier? The `printf' 2110function will try to access one of the parameters but none exists 2111because the original code does not pass any parameters. 2112 2113 `xgettext' of course could make a wrong decision the other way 2114round, i.e. a string marked as a format string actually is not a format 2115string. In this case the `msgfmt' might give too many warnings and 2116would prevent translating the `.po' file. The method to prevent this 2117wrong decision is similar to the one used above, only the comment to 2118use must contain the string `xgettext:no-c-format'. 2119 2120 If a string is marked with `c-format' and this is not correct the 2121user can find out who is responsible for the decision. See *note 2122xgettext Invocation:: to see how the `--debug' option can be used for 2123solving this problem. 2124 2125 2126File: gettext.info, Node: Special cases, Next: Bug Report Address, Prev: c-format Flag, Up: Sources 2127 21284.7 Special Cases of Translatable Strings 2129========================================= 2130 2131 The attentive reader might now point out that it is not always 2132possible to mark translatable string with `gettext' or something like 2133this. Consider the following case: 2134 2135 { 2136 static const char *messages[] = { 2137 "some very meaningful message", 2138 "and another one" 2139 }; 2140 const char *string; 2141 ... 2142 string 2143 = index > 1 ? "a default message" : messages[index]; 2144 2145 fputs (string); 2146 ... 2147 } 2148 2149 While it is no problem to mark the string `"a default message"' it 2150is not possible to mark the string initializers for `messages'. What 2151is to be done? We have to fulfill two tasks. First we have to mark the 2152strings so that the `xgettext' program (*note xgettext Invocation::) 2153can find them, and second we have to translate the string at runtime 2154before printing them. 2155 2156 The first task can be fulfilled by creating a new keyword, which 2157names a no-op. For the second we have to mark all access points to a 2158string from the array. So one solution can look like this: 2159 2160 #define gettext_noop(String) String 2161 2162 { 2163 static const char *messages[] = { 2164 gettext_noop ("some very meaningful message"), 2165 gettext_noop ("and another one") 2166 }; 2167 const char *string; 2168 ... 2169 string 2170 = index > 1 ? gettext ("a default message") : gettext (messages[index]); 2171 2172 fputs (string); 2173 ... 2174 } 2175 2176 Please convince yourself that the string which is written by `fputs' 2177is translated in any case. How to get `xgettext' know the additional 2178keyword `gettext_noop' is explained in *note xgettext Invocation::. 2179 2180 The above is of course not the only solution. You could also come 2181along with the following one: 2182 2183 #define gettext_noop(String) String 2184 2185 { 2186 static const char *messages[] = { 2187 gettext_noop ("some very meaningful message", 2188 gettext_noop ("and another one") 2189 }; 2190 const char *string; 2191 ... 2192 string 2193 = index > 1 ? gettext_noop ("a default message") : messages[index]; 2194 2195 fputs (gettext (string)); 2196 ... 2197 } 2198 2199 But this has a drawback. The programmer has to take care that he 2200uses `gettext_noop' for the string `"a default message"'. A use of 2201`gettext' could have in rare cases unpredictable results. 2202 2203 One advantage is that you need not make control flow analysis to make 2204sure the output is really translated in any case. But this analysis is 2205generally not very difficult. If it should be in any situation you can 2206use this second method in this situation. 2207 2208 2209File: gettext.info, Node: Bug Report Address, Next: Names, Prev: Special cases, Up: Sources 2210 22114.8 Letting Users Report Translation Bugs 2212========================================= 2213 2214 Code sometimes has bugs, but translations sometimes have bugs too. 2215The users need to be able to report them. Reporting translation bugs 2216to the programmer or maintainer of a package is not very useful, since 2217the maintainer must never change a translation, except on behalf of the 2218translator. Hence the translation bugs must be reported to the 2219translators. 2220 2221 Here is a way to organize this so that the maintainer does not need 2222to forward translation bug reports, nor even keep a list of the 2223addresses of the translators or their translation teams. 2224 2225 Every program has a place where is shows the bug report address. For 2226GNU programs, it is the code which handles the "-help" option, 2227typically in a function called "usage". In this place, instruct the 2228translator to add her own bug reporting address. For example, if that 2229code has a statement 2230 2231 printf (_("Report bugs to <%s>.\n"), PACKAGE_BUGREPORT); 2232 2233 you can add some translator instructions like this: 2234 2235 /* TRANSLATORS: The placeholder indicates the bug-reporting address 2236 for this package. Please add _another line_ saying 2237 "Report translation bugs to <...>\n" with the address for translation 2238 bugs (typically your translation team's web or email address). */ 2239 printf (_("Report bugs to <%s>.\n"), PACKAGE_BUGREPORT); 2240 2241 These will be extracted by `xgettext', leading to a .pot file that 2242contains this: 2243 2244 #. TRANSLATORS: The placeholder indicates the bug-reporting address 2245 #. for this package. Please add _another line_ saying 2246 #. "Report translation bugs to <...>\n" with the address for translation 2247 #. bugs (typically your translation team's web or email address). 2248 #: src/hello.c:178 2249 #, c-format 2250 msgid "Report bugs to <%s>.\n" 2251 msgstr "" 2252 2253 2254File: gettext.info, Node: Names, Next: Libraries, Prev: Bug Report Address, Up: Sources 2255 22564.9 Marking Proper Names for Translation 2257======================================== 2258 2259 Should names of persons, cities, locations etc. be marked for 2260translation or not? People who only know languages that can be written 2261with Latin letters (English, Spanish, French, German, etc.) are tempted 2262to say "no", because names usually do not change when transported 2263between these languages. However, in general when translating from one 2264script to another, names are translated too, usually phonetically or by 2265transliteration. For example, Russian or Greek names are converted to 2266the Latin alphabet when being translated to English, and English or 2267French names are converted to the Katakana script when being translated 2268to Japanese. This is necessary because the speakers of the target 2269language in general cannot read the script the name is originally 2270written in. 2271 2272 As a programmer, you should therefore make sure that names are marked 2273for translation, with a special comment telling the translators that it 2274is a proper name and how to pronounce it. Like this: 2275 2276 printf (_("Written by %s.\n"), 2277 /* TRANSLATORS: This is a proper name. See the gettext 2278 manual, section Names. Note this is actually a non-ASCII 2279 name: The first name is (with Unicode escapes) 2280 "Fran\u00e7ois" or (with HTML entities) "François". 2281 Pronunciation is like "fraa-swa pee-nar". */ 2282 _("Francois Pinard")); 2283 2284 As a translator, you should use some care when translating names, 2285because it is frustrating if people see their names mutilated or 2286distorted. If your language uses the Latin script, all you need to do 2287is to reproduce the name as perfectly as you can within the usual 2288character set of your language. In this particular case, this means to 2289provide a translation containing the c-cedilla character. If your 2290language uses a different script and the people speaking it don't 2291usually read Latin words, it means transliteration; but you should 2292still give, in parentheses, the original writing of the name - for the 2293sake of the people that do read the Latin script. Here is an example, 2294using Greek as the target script: 2295 2296 #. This is a proper name. See the gettext 2297 #. manual, section Names. Note this is actually a non-ASCII 2298 #. name: The first name is (with Unicode escapes) 2299 #. "Fran\u00e7ois" or (with HTML entities) "François". 2300 #. Pronunciation is like "fraa-swa pee-nar". 2301 msgid "Francois Pinard" 2302 msgstr "\phi\rho\alpha\sigma\omicron\alpha \pi\iota\nu\alpha\rho" 2303 " (Francois Pinard)" 2304 2305 Because translation of names is such a sensitive domain, it is a good 2306idea to test your translation before submitting it. 2307 2308 The translation project `http://sourceforge.net/projects/translation' 2309has set up a POT file and translation domain consisting of program 2310author names, with better facilities for the translator than those 2311presented here. Namely, there the original name is written directly in 2312Unicode (rather than with Unicode escapes or HTML entities), and the 2313pronunciation is denoted using the International Phonetic Alphabet (see 2314`http://www.wikipedia.org/wiki/International_Phonetic_Alphabet'). 2315 2316 However, we don't recommend this approach for all POT files in all 2317packages, because this would force translators to use PO files in UTF-8 2318encoding, which is - in the current state of software (as of 2003) - a 2319major hassle for translators using GNU Emacs or XEmacs with po-mode. 2320 2321 2322File: gettext.info, Node: Libraries, Prev: Names, Up: Sources 2323 23244.10 Preparing Library Sources 2325============================== 2326 2327 When you are preparing a library, not a program, for the use of 2328`gettext', only a few details are different. Here we assume that the 2329library has a translation domain and a POT file of its own. (If it 2330uses the translation domain and POT file of the main program, then the 2331previous sections apply without changes.) 2332 2333 1. The library code doesn't call `setlocale (LC_ALL, "")'. It's the 2334 responsibility of the main program to set the locale. The 2335 library's documentation should mention this fact, so that 2336 developers of programs using the library are aware of it. 2337 2338 2. The library code doesn't call `textdomain (PACKAGE)', because it 2339 would interfere with the text domain set by the main program. 2340 2341 3. The initialization code for a program was 2342 2343 setlocale (LC_ALL, ""); 2344 bindtextdomain (PACKAGE, LOCALEDIR); 2345 textdomain (PACKAGE); 2346 2347 For a library it is reduced to 2348 2349 bindtextdomain (PACKAGE, LOCALEDIR); 2350 2351 If your library's API doesn't already have an initialization 2352 function, you need to create one, containing at least the 2353 `bindtextdomain' invocation. However, you usually don't need to 2354 export and document this initialization function: It is sufficient 2355 that all entry points of the library call the initialization 2356 function if it hasn't been called before. The typical idiom used 2357 to achieve this is a static boolean variable that indicates 2358 whether the initialization function has been called. Like this: 2359 2360 static bool libfoo_initialized; 2361 2362 static void 2363 libfoo_initialize (void) 2364 { 2365 bindtextdomain (PACKAGE, LOCALEDIR); 2366 libfoo_initialized = true; 2367 } 2368 2369 /* This function is part of the exported API. */ 2370 struct foo * 2371 create_foo (...) 2372 { 2373 /* Must ensure the initialization is performed. */ 2374 if (!libfoo_initialized) 2375 libfoo_initialize (); 2376 ... 2377 } 2378 2379 /* This function is part of the exported API. The argument must be 2380 non-NULL and have been created through create_foo(). */ 2381 int 2382 foo_refcount (struct foo *argument) 2383 { 2384 /* No need to invoke the initialization function here, because 2385 create_foo() must already have been called before. */ 2386 ... 2387 } 2388 2389 4. The usual declaration of the `_' macro in each source file was 2390 2391 #include <libintl.h> 2392 #define _(String) gettext (String) 2393 2394 for a program. For a library, which has its own translation 2395 domain, it reads like this: 2396 2397 #include <libintl.h> 2398 #define _(String) dgettext (PACKAGE, String) 2399 2400 In other words, `dgettext' is used instead of `gettext'. 2401 Similarly, the `dngettext' function should be used in place of the 2402 `ngettext' function. 2403 2404 2405File: gettext.info, Node: Template, Next: Creating, Prev: Sources, Up: Top 2406 24075 Making the PO Template File 2408***************************** 2409 2410 After preparing the sources, the programmer creates a PO template 2411file. This section explains how to use `xgettext' for this purpose. 2412 2413 `xgettext' creates a file named `DOMAINNAME.po'. You should then 2414rename it to `DOMAINNAME.pot'. (Why doesn't `xgettext' create it under 2415the name `DOMAINNAME.pot' right away? The answer is: for historical 2416reasons. When `xgettext' was specified, the distinction between a PO 2417file and PO file template was fuzzy, and the suffix `.pot' wasn't in 2418use at that time.) 2419 2420* Menu: 2421 2422* xgettext Invocation:: Invoking the `xgettext' Program 2423 2424 2425File: gettext.info, Node: xgettext Invocation, Prev: Template, Up: Template 2426 24275.1 Invoking the `xgettext' Program 2428=================================== 2429 2430 xgettext [OPTION] [INPUTFILE] ... 2431 2432 The `xgettext' program extracts translatable strings from given 2433input files. 2434 24355.1.1 Input file location 2436------------------------- 2437 2438`INPUTFILE ...' 2439 Input files. 2440 2441`-f FILE' 2442`--files-from=FILE' 2443 Read the names of the input files from FILE instead of getting 2444 them from the command line. 2445 2446`-D DIRECTORY' 2447`--directory=DIRECTORY' 2448 Add DIRECTORY to the list of directories. Source files are 2449 searched relative to this list of directories. The resulting `.po' 2450 file will be written relative to the current directory, though. 2451 2452 2453 If INPUTFILE is `-', standard input is read. 2454 24555.1.2 Output file location 2456-------------------------- 2457 2458`-d NAME' 2459`--default-domain=NAME' 2460 Use `NAME.po' for output (instead of `messages.po'). 2461 2462`-o FILE' 2463`--output=FILE' 2464 Write output to specified file (instead of `NAME.po' or 2465 `messages.po'). 2466 2467`-p DIR' 2468`--output-dir=DIR' 2469 Output files will be placed in directory DIR. 2470 2471 2472 If the output FILE is `-' or `/dev/stdout', the output is written to 2473standard output. 2474 24755.1.3 Choice of input file language 2476----------------------------------- 2477 2478`-L NAME' 2479`--language=NAME' 2480 Specifies the language of the input files. The supported languages 2481 are `C', `C++', `ObjectiveC', `PO', `Python', `Lisp', `EmacsLisp', 2482 `librep', `Scheme', `Smalltalk', `Java', `JavaProperties', `C#', 2483 `awk', `YCP', `Tcl', `Perl', `PHP', `GCC-source', `NXStringTable', 2484 `RST', `Glade'. 2485 2486`-C' 2487`--c++' 2488 This is a shorthand for `--language=C++'. 2489 2490 2491 By default the language is guessed depending on the input file name 2492extension. 2493 24945.1.4 Input file interpretation 2495------------------------------- 2496 2497`--from-code=NAME' 2498 Specifies the encoding of the input files. This option is needed 2499 only if some untranslated message strings or their corresponding 2500 comments contain non-ASCII characters. Note that Tcl and Glade 2501 input files are always assumed to be in UTF-8, regardless of this 2502 option. 2503 2504 2505 By default the input files are assumed to be in ASCII. 2506 25075.1.5 Operation mode 2508-------------------- 2509 2510`-j' 2511`--join-existing' 2512 Join messages with existing file. 2513 2514`-x FILE' 2515`--exclude-file=FILE' 2516 Entries from FILE are not extracted. FILE should be a PO or POT 2517 file. 2518 2519`-c [TAG]' 2520`--add-comments[=TAG]' 2521 Place comment block with TAG (or those preceding keyword lines) in 2522 output file. 2523 2524 25255.1.6 Language specific options 2526------------------------------- 2527 2528`-a' 2529`--extract-all' 2530 Extract all strings. 2531 2532 This option has an effect with most languages, namely C, C++, 2533 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, 2534 Tcl, Perl, PHP, GCC-source, Glade. 2535 2536`-k KEYWORDSPEC' 2537`--keyword[=KEYWORDSPEC]' 2538 Additional keyword to be looked for (without KEYWORDSPEC means not 2539 to use default keywords). 2540 2541 If KEYWORDSPEC is a C identifier ID, `xgettext' looks for strings 2542 in the first argument of each call to the function or macro ID. 2543 If KEYWORDSPEC is of the form `ID:ARGNUM', `xgettext' looks for 2544 strings in the ARGNUMth argument of the call. If KEYWORDSPEC is 2545 of the form `ID:ARGNUM1,ARGNUM2', `xgettext' looks for strings in 2546 the ARGNUM1st argument and in the ARGNUM2nd argument of the call, 2547 and treats them as singular/plural variants for a message with 2548 plural handling. Also, if KEYWORDSPEC is of the form 2549 `ID:CONTEXTARGNUMc,ARGNUM' or `ID:ARGNUM,CONTEXTARGNUMc', 2550 `xgettext' treats strings in the CONTEXTARGNUMth argument as a 2551 context specifier. And, as a special-purpose support for GNOME, 2552 if KEYWORDSPEC is of the form `ID:ARGNUMg', `xgettext' recognizes 2553 the ARGNUMth argument as a string with context, using the GNOME 2554 `glib' syntax `"msgctxt|msgid"'. 2555 Furthermore, if KEYWORDSPEC is of the form `ID:...,TOTALNUMARGSt', 2556 `xgettext' recognizes this argument specification only if the 2557 number of actual arguments is equal to TOTALNUMARGS. This is 2558 useful for disambiguating overloaded function calls in C++. 2559 Finally, if KEYWORDSPEC is of the form `ID:ARGNUM...,"XCOMMENT"', 2560 `xgettext', when extracting a message from the specified argument 2561 strings, adds an extracted comment XCOMMENT to the message. Note 2562 that when used through a normal shell command line, the 2563 double-quotes around the XCOMMENT need to be escaped. 2564 2565 This option has an effect with most languages, namely C, C++, 2566 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, 2567 Tcl, Perl, PHP, GCC-source, Glade. 2568 2569 The default keyword specifications, which are always looked for if 2570 not explicitly disabled, are language dependent. They are: 2571 2572 * For C, C++, and GCC-source: `gettext', `dgettext:2', 2573 `dcgettext:2', `ngettext:1,2', `dngettext:2,3', 2574 `dcngettext:2,3', `gettext_noop', and `pgettext:1c,2', 2575 `dpgettext:2c,3', `dcpgettext:2c,3', `npgettext:1c,2,3', 2576 `dnpgettext:2c,3,4', `dcnpgettext:2c,3,4'. 2577 2578 * For Objective C: Like for C, and also `NSLocalizedString', 2579 `_', `NSLocalizedStaticString', `__'. 2580 2581 * For Shell scripts: `gettext', `ngettext:1,2', `eval_gettext', 2582 `eval_ngettext:1,2'. 2583 2584 * For Python: `gettext', `ugettext', `dgettext:2', 2585 `ngettext:1,2', `ungettext:1,2', `dngettext:2,3', `_'. 2586 2587 * For Lisp: `gettext', `ngettext:1,2', `gettext-noop'. 2588 2589 * For EmacsLisp: `_'. 2590 2591 * For librep: `_'. 2592 2593 * For Scheme: `gettext', `ngettext:1,2', `gettext-noop'. 2594 2595 * For Java: `GettextResource.gettext:2', 2596 `GettextResource.ngettext:2,3', 2597 `GettextResource.pgettext:2c,3', 2598 `GettextResource.npgettext:2c,3,4', `gettext', `ngettext:1,2', 2599 `pgettext:1c,2', `npgettext:1c,2,3', `getString'. 2600 2601 * For C#: `GetString', `GetPluralString:1,2', 2602 `GetParticularString:1c,2', 2603 `GetParticularPluralString:1c,2,3'. 2604 2605 * For awk: `dcgettext', `dcngettext:1,2'. 2606 2607 * For Tcl: `::msgcat::mc'. 2608 2609 * For Perl: `gettext', `%gettext', `$gettext', `dgettext:2', 2610 `dcgettext:2', `ngettext:1,2', `dngettext:2,3', 2611 `dcngettext:2,3', `gettext_noop'. 2612 2613 * For PHP: `_', `gettext', `dgettext:2', `dcgettext:2', 2614 `ngettext:1,2', `dngettext:2,3', `dcngettext:2,3'. 2615 2616 * For Glade 1: `label', `title', `text', `format', `copyright', 2617 `comments', `preview_text', `tooltip'. 2618 2619 To disable the default keyword specifications, the option `-k' or 2620 `--keyword' or `--keyword=', without a KEYWORDSPEC, can be used. 2621 2622`--flag=WORD:ARG:FLAG' 2623 Specifies additional flags for strings occurring as part of the 2624 ARGth argument of the function WORD. The possible flags are the 2625 possible format string indicators, such as `c-format', and their 2626 negations, such as `no-c-format', possibly prefixed with `pass-'. 2627 The meaning of `--flag=FUNCTION:ARG:LANG-format' is that in 2628 language LANG, the specified FUNCTION expects as ARGth argument a 2629 format string. (For those of you familiar with GCC function 2630 attributes, `--flag=FUNCTION:ARG:c-format' is roughly equivalent 2631 to the declaration `__attribute__ ((__format__ (__printf__, ARG, 2632 ...)))' attached to FUNCTION in a C source file.) For example, if 2633 you use the `error' function from GNU libc, you can specify its 2634 behaviour through `--flag=error:3:c-format'. The effect of this 2635 specification is that `xgettext' will mark as format strings all 2636 `gettext' invocations that occur as ARGth argument of FUNCTION. 2637 This is useful when such strings contain no format string 2638 directives: together with the checks done by `msgfmt -c' it will 2639 ensure that translators cannot accidentally use format string 2640 directives that would lead to a crash at runtime. 2641 The meaning of `--flag=FUNCTION:ARG:pass-LANG-format' is that in 2642 language LANG, if the FUNCTION call occurs in a position that must 2643 yield a format string, then its ARGth argument must yield a format 2644 string of the same type as well. (If you know GCC function 2645 attributes, the `--flag=FUNCTION:ARG:pass-c-format' option is 2646 roughly equivalent to the declaration `__attribute__ 2647 ((__format_arg__ (ARG)))' attached to FUNCTION in a C source file.) 2648 For example, if you use the `_' shortcut for the `gettext' 2649 function, you should use `--flag=_:1:pass-c-format'. The effect 2650 of this specification is that `xgettext' will propagate a format 2651 string requirement for a `_("string")' call to its first argument, 2652 the literal `"string"', and thus mark it as a format string. This 2653 is useful when such strings contain no format string directives: 2654 together with the checks done by `msgfmt -c' it will ensure that 2655 translators cannot accidentally use format string directives that 2656 would lead to a crash at runtime. 2657 This option has an effect with most languages, namely C, C++, 2658 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java, 2659 C#, awk, YCP, Tcl, Perl, PHP, GCC-source. 2660 2661`-T' 2662`--trigraphs' 2663 Understand ANSI C trigraphs for input. 2664 This option has an effect only with the languages C, C++, 2665 ObjectiveC. 2666 2667`--qt' 2668 Recognize Qt format strings. 2669 This option has an effect only with the language C++. 2670 2671`--kde' 2672 Recognize KDE 4 format strings. 2673 This option has an effect only with the language C++. 2674 2675`--boost' 2676 Recognize Boost format strings. 2677 This option has an effect only with the language C++. 2678 2679`--debug' 2680 Use the flags `c-format' and `possible-c-format' to show who was 2681 responsible for marking a message as a format string. The latter 2682 form is used if the `xgettext' program decided, the format form is 2683 used if the programmer prescribed it. 2684 2685 By default only the `c-format' form is used. The translator should 2686 not have to care about these details. 2687 2688 2689 This implementation of `xgettext' is able to process a few awkward 2690cases, like strings in preprocessor macros, ANSI concatenation of 2691adjacent strings, and escaped end of lines for continued strings. 2692 26935.1.7 Output details 2694-------------------- 2695 2696`--force-po' 2697 Always write an output file even if no message is defined. 2698 2699`-i' 2700`--indent' 2701 Write the .po file using indented style. 2702 2703`--no-location' 2704 Do not write `#: FILENAME:LINE' lines. Note that using this 2705 option makes it harder for technically skilled translators to 2706 understand each message's context. 2707 2708`-n' 2709`--add-location' 2710 Generate `#: FILENAME:LINE' lines (default). 2711 2712`--strict' 2713 Write out a strict Uniforum conforming PO file. Note that this 2714 Uniforum format should be avoided because it doesn't support the 2715 GNU extensions. 2716 2717`--properties-output' 2718 Write out a Java ResourceBundle in Java `.properties' syntax. Note 2719 that this file format doesn't support plural forms and silently 2720 drops obsolete messages. 2721 2722`--stringtable-output' 2723 Write out a NeXTstep/GNUstep localized resource file in `.strings' 2724 syntax. Note that this file format doesn't support plural forms. 2725 2726`-w NUMBER' 2727`--width=NUMBER' 2728 Set the output page width. Long strings in the output files will 2729 be split across multiple lines in order to ensure that each line's 2730 width (= number of screen columns) is less or equal to the given 2731 NUMBER. 2732 2733`--no-wrap' 2734 Do not break long message lines. Message lines whose width 2735 exceeds the output page width will not be split into several 2736 lines. Only file reference lines which are wider than the output 2737 page width will be split. 2738 2739`-s' 2740`--sort-output' 2741 Generate sorted output. Note that using this option makes it much 2742 harder for the translator to understand each message's context. 2743 2744`-F' 2745`--sort-by-file' 2746 Sort output by file location. 2747 2748`--omit-header' 2749 Don't write header with `msgid ""' entry. 2750 2751 This is useful for testing purposes because it eliminates a source 2752 of variance for generated `.gmo' files. With `--omit-header', two 2753 invocations of `xgettext' on the same files with the same options 2754 at different times are guaranteed to produce the same results. 2755 2756 Note that using this option will lead to an error if the resulting 2757 file would not entirely be in ASCII. 2758 2759`--copyright-holder=STRING' 2760 Set the copyright holder in the output. STRING should be the 2761 copyright holder of the surrounding package. (Note that the msgstr 2762 strings, extracted from the package's sources, belong to the 2763 copyright holder of the package.) Translators are expected to 2764 transfer or disclaim the copyright for their translations, so that 2765 package maintainers can distribute them without legal risk. If 2766 STRING is empty, the output files are marked as being in the 2767 public domain; in this case, the translators are expected to 2768 disclaim their copyright, again so that package maintainers can 2769 distribute them without legal risk. 2770 2771 The default value for STRING is the Free Software Foundation, Inc., 2772 simply because `xgettext' was first used in the GNU project. 2773 2774`--foreign-user' 2775 Omit FSF copyright in output. This option is equivalent to 2776 `--copyright-holder='''. It can be useful for packages outside 2777 the GNU project that want their translations to be in the public 2778 domain. 2779 2780`--package-name=PACKAGE' 2781 Set the package name in the header of the output. 2782 2783`--package-version=VERSION' 2784 Set the package version in the header of the output. This option 2785 has an effect only if the `--package-name' option is also used. 2786 2787`--msgid-bugs-address=EMAIL@ADDRESS' 2788 Set the reporting address for msgid bugs. This is the email 2789 address or URL to which the translators shall report bugs in the 2790 untranslated strings: 2791 2792 - Strings which are not entire sentences, see the maintainer 2793 guidelines in *note Preparing Strings::. 2794 2795 - Strings which use unclear terms or require additional context 2796 to be understood. 2797 2798 - Strings which make invalid assumptions about notation of 2799 date, time or money. 2800 2801 - Pluralisation problems. 2802 2803 - Incorrect English spelling. 2804 2805 - Incorrect formatting. 2806 2807 It can be your email address, or a mailing list address where 2808 translators can write to without being subscribed, or the URL of a 2809 web page through which the translators can contact you. 2810 2811 The default value is empty, which means that translators will be 2812 clueless! Don't forget to specify this option. 2813 2814`-m [STRING]' 2815`--msgstr-prefix[=STRING]' 2816 Use STRING (or "" if not specified) as prefix for msgstr entries. 2817 2818`-M [STRING]' 2819`--msgstr-suffix[=STRING]' 2820 Use STRING (or "" if not specified) as suffix for msgstr entries. 2821 2822 28235.1.8 Informative output 2824------------------------ 2825 2826`-h' 2827`--help' 2828 Display this help and exit. 2829 2830`-V' 2831`--version' 2832 Output version information and exit. 2833 2834 2835 2836File: gettext.info, Node: Creating, Next: Updating, Prev: Template, Up: Top 2837 28386 Creating a New PO File 2839************************ 2840 2841 When starting a new translation, the translator creates a file called 2842`LANG.po', as a copy of the `PACKAGE.pot' template file with 2843modifications in the initial comments (at the beginning of the file) 2844and in the header entry (the first entry, near the beginning of the 2845file). 2846 2847 The easiest way to do so is by use of the `msginit' program. For 2848example: 2849 2850 $ cd PACKAGE-VERSION 2851 $ cd po 2852 $ msginit 2853 2854 The alternative way is to do the copy and modifications by hand. To 2855do so, the translator copies `PACKAGE.pot' to `LANG.po'. Then she 2856modifies the initial comments and the header entry of this file. 2857 2858* Menu: 2859 2860* msginit Invocation:: Invoking the `msginit' Program 2861* Header Entry:: Filling in the Header Entry 2862 2863 2864File: gettext.info, Node: msginit Invocation, Next: Header Entry, Prev: Creating, Up: Creating 2865 28666.1 Invoking the `msginit' Program 2867================================== 2868 2869 msginit [OPTION] 2870 2871 The `msginit' program creates a new PO file, initializing the meta 2872information with values from the user's environment. 2873 28746.1.1 Input file location 2875------------------------- 2876 2877`-i INPUTFILE' 2878`--input=INPUTFILE' 2879 Input POT file. 2880 2881 2882 If no INPUTFILE is given, the current directory is searched for the 2883POT file. If it is `-', standard input is read. 2884 28856.1.2 Output file location 2886-------------------------- 2887 2888`-o FILE' 2889`--output-file=FILE' 2890 Write output to specified PO file. 2891 2892 2893 If no output file is given, it depends on the `--locale' option or 2894the user's locale setting. If it is `-', the results are written to 2895standard output. 2896 28976.1.3 Input file syntax 2898----------------------- 2899 2900`-P' 2901`--properties-input' 2902 Assume the input file is a Java ResourceBundle in Java 2903 `.properties' syntax, not in PO file syntax. 2904 2905`--stringtable-input' 2906 Assume the input file is a NeXTstep/GNUstep localized resource 2907 file in `.strings' syntax, not in PO file syntax. 2908 2909 29106.1.4 Output details 2911-------------------- 2912 2913`-l LL_CC' 2914`--locale=LL_CC' 2915 Set target locale. LL should be a language code, and CC should be 2916 a country code. The command `locale -a' can be used to output a 2917 list of all installed locales. The default is the user's locale 2918 setting. 2919 2920`--no-translator' 2921 Declares that the PO file will not have a human translator and is 2922 instead automatically generated. 2923 2924`-p' 2925`--properties-output' 2926 Write out a Java ResourceBundle in Java `.properties' syntax. Note 2927 that this file format doesn't support plural forms and silently 2928 drops obsolete messages. 2929 2930`--stringtable-output' 2931 Write out a NeXTstep/GNUstep localized resource file in `.strings' 2932 syntax. Note that this file format doesn't support plural forms. 2933 2934`-w NUMBER' 2935`--width=NUMBER' 2936 Set the output page width. Long strings in the output files will 2937 be split across multiple lines in order to ensure that each line's 2938 width (= number of screen columns) is less or equal to the given 2939 NUMBER. 2940 2941`--no-wrap' 2942 Do not break long message lines. Message lines whose width 2943 exceeds the output page width will not be split into several 2944 lines. Only file reference lines which are wider than the output 2945 page width will be split. 2946 2947 29486.1.5 Informative output 2949------------------------ 2950 2951`-h' 2952`--help' 2953 Display this help and exit. 2954 2955`-V' 2956`--version' 2957 Output version information and exit. 2958 2959 2960 2961File: gettext.info, Node: Header Entry, Prev: msginit Invocation, Up: Creating 2962 29636.2 Filling in the Header Entry 2964=============================== 2965 2966 The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and "FIRST 2967AUTHOR <EMAIL@ADDRESS>, YEAR" ought to be replaced by sensible 2968information. This can be done in any text editor; if Emacs is used and 2969it switched to PO mode automatically (because it has recognized the 2970file's suffix), you can disable it by typing `M-x fundamental-mode'. 2971 2972 Modifying the header entry can already be done using PO mode: in 2973Emacs, type `M-x po-mode RET' and then `RET' again to start editing the 2974entry. You should fill in the following fields. 2975 2976Project-Id-Version 2977 This is the name and version of the package. Fill it in if it has 2978 not already been filled in by `xgettext'. 2979 2980Report-Msgid-Bugs-To 2981 This has already been filled in by `xgettext'. It contains an 2982 email address or URL where you can report bugs in the untranslated 2983 strings: 2984 2985 - Strings which are not entire sentences, see the maintainer 2986 guidelines in *note Preparing Strings::. 2987 2988 - Strings which use unclear terms or require additional context 2989 to be understood. 2990 2991 - Strings which make invalid assumptions about notation of 2992 date, time or money. 2993 2994 - Pluralisation problems. 2995 2996 - Incorrect English spelling. 2997 2998 - Incorrect formatting. 2999 3000POT-Creation-Date 3001 This has already been filled in by `xgettext'. 3002 3003PO-Revision-Date 3004 You don't need to fill this in. It will be filled by the PO file 3005 editor when you save the file. 3006 3007Last-Translator 3008 Fill in your name and email address (without double quotes). 3009 3010Language-Team 3011 Fill in the English name of the language, and the email address or 3012 homepage URL of the language team you are part of. 3013 3014 Before starting a translation, it is a good idea to get in touch 3015 with your translation team, not only to make sure you don't do 3016 duplicated work, but also to coordinate difficult linguistic 3017 issues. 3018 3019 In the Free Translation Project, each translation team has its own 3020 mailing list. The up-to-date list of teams can be found at the 3021 Free Translation Project's homepage, 3022 `http://translationproject.org/', in the "Teams" area. 3023 3024Content-Type 3025 Replace `CHARSET' with the character encoding used for your 3026 language, in your locale, or UTF-8. This field is needed for 3027 correct operation of the `msgmerge' and `msgfmt' programs, as well 3028 as for users whose locale's character encoding differs from yours 3029 (see *note Charset conversion::). 3030 3031 You get the character encoding of your locale by running the shell 3032 command `locale charmap'. If the result is `C' or 3033 `ANSI_X3.4-1968', which is equivalent to `ASCII' (= `US-ASCII'), 3034 it means that your locale is not correctly configured. In this 3035 case, ask your translation team which charset to use. `ASCII' is 3036 not usable for any language except Latin. 3037 3038 Because the PO files must be portable to operating systems with 3039 less advanced internationalization facilities, the character 3040 encodings that can be used are limited to those supported by both 3041 GNU `libc' and GNU `libiconv'. These are: `ASCII', `ISO-8859-1', 3042 `ISO-8859-2', `ISO-8859-3', `ISO-8859-4', `ISO-8859-5', 3043 `ISO-8859-6', `ISO-8859-7', `ISO-8859-8', `ISO-8859-9', 3044 `ISO-8859-13', `ISO-8859-14', `ISO-8859-15', `KOI8-R', `KOI8-U', 3045 `KOI8-T', `CP850', `CP866', `CP874', `CP932', `CP949', `CP950', 3046 `CP1250', `CP1251', `CP1252', `CP1253', `CP1254', `CP1255', 3047 `CP1256', `CP1257', `GB2312', `EUC-JP', `EUC-KR', `EUC-TW', 3048 `BIG5', `BIG5-HKSCS', `GBK', `GB18030', `SHIFT_JIS', `JOHAB', 3049 `TIS-620', `VISCII', `GEORGIAN-PS', `UTF-8'. 3050 3051 In the GNU system, the following encodings are frequently used for 3052 the corresponding languages. 3053 3054 * `ISO-8859-1' for Afrikaans, Albanian, Basque, Breton, 3055 Catalan, Cornish, Danish, Dutch, English, Estonian, Faroese, 3056 Finnish, French, Galician, German, Greenlandic, Icelandic, 3057 Indonesian, Irish, Italian, Malay, Manx, Norwegian, Occitan, 3058 Portuguese, Spanish, Swedish, Tagalog, Uzbek, Walloon, 3059 3060 * `ISO-8859-2' for Bosnian, Croatian, Czech, Hungarian, Polish, 3061 Romanian, Serbian, Slovak, Slovenian, 3062 3063 * `ISO-8859-3' for Maltese, 3064 3065 * `ISO-8859-5' for Macedonian, Serbian, 3066 3067 * `ISO-8859-6' for Arabic, 3068 3069 * `ISO-8859-7' for Greek, 3070 3071 * `ISO-8859-8' for Hebrew, 3072 3073 * `ISO-8859-9' for Turkish, 3074 3075 * `ISO-8859-13' for Latvian, Lithuanian, Maori, 3076 3077 * `ISO-8859-14' for Welsh, 3078 3079 * `ISO-8859-15' for Basque, Catalan, Dutch, English, Finnish, 3080 French, Galician, German, Irish, Italian, Portuguese, 3081 Spanish, Swedish, Walloon, 3082 3083 * `KOI8-R' for Russian, 3084 3085 * `KOI8-U' for Ukrainian, 3086 3087 * `KOI8-T' for Tajik, 3088 3089 * `CP1251' for Bulgarian, Byelorussian, 3090 3091 * `GB2312', `GBK', `GB18030' for simplified writing of Chinese, 3092 3093 * `BIG5', `BIG5-HKSCS' for traditional writing of Chinese, 3094 3095 * `EUC-JP' for Japanese, 3096 3097 * `EUC-KR' for Korean, 3098 3099 * `TIS-620' for Thai, 3100 3101 * `GEORGIAN-PS' for Georgian, 3102 3103 * `UTF-8' for any language, including those listed above. 3104 3105 When single quote characters or double quote characters are used in 3106 translations for your language, and your locale's encoding is one 3107 of the ISO-8859-* charsets, it is best if you create your PO files 3108 in UTF-8 encoding, instead of your locale's encoding. This is 3109 because in UTF-8 the real quote characters can be represented 3110 (single quote characters: U+2018, U+2019, double quote characters: 3111 U+201C, U+201D), whereas none of ISO-8859-* charsets has them all. 3112 Users in UTF-8 locales will see the real quote characters, whereas 3113 users in ISO-8859-* locales will see the vertical apostrophe and 3114 the vertical double quote instead (because that's what the 3115 character set conversion will transliterate them to). 3116 3117 To enter such quote characters under X11, you can change your 3118 keyboard mapping using the `xmodmap' program. The X11 names of 3119 the quote characters are "leftsinglequotemark", 3120 "rightsinglequotemark", "leftdoublequotemark", 3121 "rightdoublequotemark", "singlelowquotemark", "doublelowquotemark". 3122 3123 Note that only recent versions of GNU Emacs support the UTF-8 3124 encoding: Emacs 20 with Mule-UCS, and Emacs 21. As of January 3125 2001, XEmacs doesn't support the UTF-8 encoding. 3126 3127 The character encoding name can be written in either upper or 3128 lower case. Usually upper case is preferred. 3129 3130Content-Transfer-Encoding 3131 Set this to `8bit'. 3132 3133Plural-Forms 3134 This field is optional. It is only needed if the PO file has 3135 plural forms. You can find them by searching for the 3136 `msgid_plural' keyword. The format of the plural forms field is 3137 described in *note Plural forms::. 3138 3139 3140File: gettext.info, Node: Updating, Next: Editing, Prev: Creating, Up: Top 3141 31427 Updating Existing PO Files 3143**************************** 3144 3145* Menu: 3146 3147* msgmerge Invocation:: Invoking the `msgmerge' Program 3148 3149 3150File: gettext.info, Node: msgmerge Invocation, Prev: Updating, Up: Updating 3151 31527.1 Invoking the `msgmerge' Program 3153=================================== 3154 3155 msgmerge [OPTION] DEF.po REF.pot 3156 3157 The `msgmerge' program merges two Uniforum style .po files together. 3158The DEF.po file is an existing PO file with translations which will be 3159taken over to the newly created file as long as they still match; 3160comments will be preserved, but extracted comments and file positions 3161will be discarded. The REF.pot file is the last created PO file with 3162up-to-date source references but old translations, or a PO Template file 3163(generally created by `xgettext'); any translations or comments in the 3164file will be discarded, however dot comments and file positions will be 3165preserved. Where an exact match cannot be found, fuzzy matching is 3166used to produce better results. 3167 31687.1.1 Input file location 3169------------------------- 3170 3171`DEF.po' 3172 Translations referring to old sources. 3173 3174`REF.pot' 3175 References to the new sources. 3176 3177`-D DIRECTORY' 3178`--directory=DIRECTORY' 3179 Add DIRECTORY to the list of directories. Source files are 3180 searched relative to this list of directories. The resulting `.po' 3181 file will be written relative to the current directory, though. 3182 3183`-C FILE' 3184`--compendium=FILE' 3185 Specify an additional library of message translations. *Note 3186 Compendium::. This option may be specified more than once. 3187 3188 31897.1.2 Operation mode 3190-------------------- 3191 3192`-U' 3193`--update' 3194 Update DEF.po. Do nothing if DEF.po is already up to date. 3195 3196 31977.1.3 Output file location 3198-------------------------- 3199 3200`-o FILE' 3201`--output-file=FILE' 3202 Write output to specified file. 3203 3204 3205 The results are written to standard output if no output file is 3206specified or if it is `-'. 3207 32087.1.4 Output file location in update mode 3209----------------------------------------- 3210 3211 The result is written back to DEF.po. 3212 3213`--backup=CONTROL' 3214 Make a backup of DEF.po 3215 3216`--suffix=SUFFIX' 3217 Override the usual backup suffix. 3218 3219 3220 The version control method may be selected via the `--backup' option 3221or through the `VERSION_CONTROL' environment variable. Here are the 3222values: 3223 3224`none' 3225`off' 3226 Never make backups (even if `--backup' is given). 3227 3228`numbered' 3229`t' 3230 Make numbered backups. 3231 3232`existing' 3233`nil' 3234 Make numbered backups if numbered backups for this file already 3235 exist, otherwise make simple backups. 3236 3237`simple' 3238`never' 3239 Always make simple backups. 3240 3241 3242 The backup suffix is `~', unless set with `--suffix' or the 3243`SIMPLE_BACKUP_SUFFIX' environment variable. 3244 32457.1.5 Operation modifiers 3246------------------------- 3247 3248`-m' 3249`--multi-domain' 3250 Apply REF.pot to each of the domains in DEF.po. 3251 3252`-N' 3253`--no-fuzzy-matching' 3254 Do not use fuzzy matching when an exact match is not found. This 3255 may speed up the operation considerably. 3256 3257`--previous' 3258 Keep the previous msgids of translated messages, marked with `#|', 3259 when adding the fuzzy marker to such messages. 3260 32617.1.6 Input file syntax 3262----------------------- 3263 3264`-P' 3265`--properties-input' 3266 Assume the input files are Java ResourceBundles in Java 3267 `.properties' syntax, not in PO file syntax. 3268 3269`--stringtable-input' 3270 Assume the input files are NeXTstep/GNUstep localized resource 3271 files in `.strings' syntax, not in PO file syntax. 3272 3273 32747.1.7 Output details 3275-------------------- 3276 3277`--force-po' 3278 Always write an output file even if it contains no message. 3279 3280`-i' 3281`--indent' 3282 Write the .po file using indented style. 3283 3284`--no-location' 3285 Do not write `#: FILENAME:LINE' lines. 3286 3287`--add-location' 3288 Generate `#: FILENAME:LINE' lines (default). 3289 3290`--strict' 3291 Write out a strict Uniforum conforming PO file. Note that this 3292 Uniforum format should be avoided because it doesn't support the 3293 GNU extensions. 3294 3295`-p' 3296`--properties-output' 3297 Write out a Java ResourceBundle in Java `.properties' syntax. Note 3298 that this file format doesn't support plural forms and silently 3299 drops obsolete messages. 3300 3301`--stringtable-output' 3302 Write out a NeXTstep/GNUstep localized resource file in `.strings' 3303 syntax. Note that this file format doesn't support plural forms. 3304 3305`-w NUMBER' 3306`--width=NUMBER' 3307 Set the output page width. Long strings in the output files will 3308 be split across multiple lines in order to ensure that each line's 3309 width (= number of screen columns) is less or equal to the given 3310 NUMBER. 3311 3312`--no-wrap' 3313 Do not break long message lines. Message lines whose width 3314 exceeds the output page width will not be split into several 3315 lines. Only file reference lines which are wider than the output 3316 page width will be split. 3317 3318`-s' 3319`--sort-output' 3320 Generate sorted output. Note that using this option makes it much 3321 harder for the translator to understand each message's context. 3322 3323`-F' 3324`--sort-by-file' 3325 Sort output by file location. 3326 3327 33287.1.8 Informative output 3329------------------------ 3330 3331`-h' 3332`--help' 3333 Display this help and exit. 3334 3335`-V' 3336`--version' 3337 Output version information and exit. 3338 3339`-v' 3340`--verbose' 3341 Increase verbosity level. 3342 3343`-q' 3344`--quiet' 3345`--silent' 3346 Suppress progress indicators. 3347 3348 3349 3350File: gettext.info, Node: Editing, Next: Manipulating, Prev: Updating, Up: Top 3351 33528 Editing PO Files 3353****************** 3354 3355* Menu: 3356 3357* KBabel:: KDE's PO File Editor 3358* Gtranslator:: GNOME's PO File Editor 3359* PO Mode:: Emacs's PO File Editor 3360* Compendium:: Using Translation Compendia 3361 3362 3363File: gettext.info, Node: KBabel, Next: Gtranslator, Prev: Editing, Up: Editing 3364 33658.1 KDE's PO File Editor 3366======================== 3367 3368 3369File: gettext.info, Node: Gtranslator, Next: PO Mode, Prev: KBabel, Up: Editing 3370 33718.2 GNOME's PO File Editor 3372========================== 3373 3374 3375File: gettext.info, Node: PO Mode, Next: Compendium, Prev: Gtranslator, Up: Editing 3376 33778.3 Emacs's PO File Editor 3378========================== 3379 3380 For those of you being the lucky users of Emacs, PO mode has been 3381specifically created for providing a cozy environment for editing or 3382modifying PO files. While editing a PO file, PO mode allows for the 3383easy browsing of auxiliary and compendium PO files, as well as for 3384following references into the set of C program sources from which PO 3385files have been derived. It has a few special features, among which 3386are the interactive marking of program strings as translatable, and the 3387validation of PO files with easy repositioning to PO file lines showing 3388errors. 3389 3390 For the beginning, besides main PO mode commands (*note Main PO 3391Commands::), you should know how to move between entries (*note Entry 3392Positioning::), and how to handle untranslated entries (*note 3393Untranslated Entries::). 3394 3395* Menu: 3396 3397* Installation:: Completing GNU `gettext' Installation 3398* Main PO Commands:: Main Commands 3399* Entry Positioning:: Entry Positioning 3400* Normalizing:: Normalizing Strings in Entries 3401* Translated Entries:: Translated Entries 3402* Fuzzy Entries:: Fuzzy Entries 3403* Untranslated Entries:: Untranslated Entries 3404* Obsolete Entries:: Obsolete Entries 3405* Modifying Translations:: Modifying Translations 3406* Modifying Comments:: Modifying Comments 3407* Subedit:: Mode for Editing Translations 3408* C Sources Context:: C Sources Context 3409* Auxiliary:: Consulting Auxiliary PO Files 3410 3411 3412File: gettext.info, Node: Installation, Next: Main PO Commands, Prev: PO Mode, Up: PO Mode 3413 34148.3.1 Completing GNU `gettext' Installation 3415------------------------------------------- 3416 3417 Once you have received, unpacked, configured and compiled the GNU 3418`gettext' distribution, the `make install' command puts in place the 3419programs `xgettext', `msgfmt', `gettext', and `msgmerge', as well as 3420their available message catalogs. To top off a comfortable 3421installation, you might also want to make the PO mode available to your 3422Emacs users. 3423 3424 During the installation of the PO mode, you might want to modify your 3425file `.emacs', once and for all, so it contains a few lines looking 3426like: 3427 3428 (setq auto-mode-alist 3429 (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist)) 3430 (autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t) 3431 3432 Later, whenever you edit some `.po' file, or any file having the 3433string `.po.' within its name, Emacs loads `po-mode.elc' (or 3434`po-mode.el') as needed, and automatically activates PO mode commands 3435for the associated buffer. The string _PO_ appears in the mode line 3436for any buffer for which PO mode is active. Many PO files may be 3437active at once in a single Emacs session. 3438 3439 If you are using Emacs version 20 or newer, and have already 3440installed the appropriate international fonts on your system, you may 3441also tell Emacs how to determine automatically the coding system of 3442every PO file. This will often (but not always) cause the necessary 3443fonts to be loaded and used for displaying the translations on your 3444Emacs screen. For this to happen, add the lines: 3445 3446 (modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\." 3447 'po-find-file-coding-system) 3448 (autoload 'po-find-file-coding-system "po-mode") 3449 3450to your `.emacs' file. If, with this, you still see boxes instead of 3451international characters, try a different font set (via Shift Mouse 3452button 1). 3453 3454 3455File: gettext.info, Node: Main PO Commands, Next: Entry Positioning, Prev: Installation, Up: PO Mode 3456 34578.3.2 Main PO mode Commands 3458--------------------------- 3459 3460 After setting up Emacs with something similar to the lines in *note 3461Installation::, PO mode is activated for a window when Emacs finds a PO 3462file in that window. This puts the window read-only and establishes a 3463po-mode-map, which is a genuine Emacs mode, in a way that is not derived 3464from text mode in any way. Functions found on `po-mode-hook', if any, 3465will be executed. 3466 3467 When PO mode is active in a window, the letters `PO' appear in the 3468mode line for that window. The mode line also displays how many 3469entries of each kind are held in the PO file. For example, the string 3470`132t+3f+10u+2o' would tell the translator that the PO mode contains 3471132 translated entries (*note Translated Entries::, 3 fuzzy entries 3472(*note Fuzzy Entries::), 10 untranslated entries (*note Untranslated 3473Entries::) and 2 obsolete entries (*note Obsolete Entries::). 3474Zero-coefficients items are not shown. So, in this example, if the 3475fuzzy entries were unfuzzied, the untranslated entries were translated 3476and the obsolete entries were deleted, the mode line would merely 3477display `145t' for the counters. 3478 3479 The main PO commands are those which do not fit into the other 3480categories of subsequent sections. These allow for quitting PO mode or 3481for managing windows in special ways. 3482 3483`_' 3484 Undo last modification to the PO file (`po-undo'). 3485 3486`Q' 3487 Quit processing and save the PO file (`po-quit'). 3488 3489`q' 3490 Quit processing, possibly after confirmation 3491 (`po-confirm-and-quit'). 3492 3493`0' 3494 Temporary leave the PO file window (`po-other-window'). 3495 3496`?' 3497`h' 3498 Show help about PO mode (`po-help'). 3499 3500`=' 3501 Give some PO file statistics (`po-statistics'). 3502 3503`V' 3504 Batch validate the format of the whole PO file (`po-validate'). 3505 3506 3507 The command `_' (`po-undo') interfaces to the Emacs _undo_ facility. 3508*Note Undoing Changes: (emacs)Undo. Each time `U' is typed, 3509modifications which the translator did to the PO file are undone a 3510little more. For the purpose of undoing, each PO mode command is 3511atomic. This is especially true for the `<RET>' command: the whole 3512edition made by using a single use of this command is undone at once, 3513even if the edition itself implied several actions. However, while in 3514the editing window, one can undo the edition work quite parsimoniously. 3515 3516 The commands `Q' (`po-quit') and `q' (`po-confirm-and-quit') are 3517used when the translator is done with the PO file. The former is a bit 3518less verbose than the latter. If the file has been modified, it is 3519saved to disk first. In both cases, and prior to all this, the 3520commands check if any untranslated messages remain in the PO file and, 3521if so, the translator is asked if she really wants to leave off working 3522with this PO file. This is the preferred way of getting rid of an 3523Emacs PO file buffer. Merely killing it through the usual command 3524`C-x k' (`kill-buffer') is not the tidiest way to proceed. 3525 3526 The command `0' (`po-other-window') is another, softer way, to leave 3527PO mode, temporarily. It just moves the cursor to some other Emacs 3528window, and pops one if necessary. For example, if the translator just 3529got PO mode to show some source context in some other, she might 3530discover some apparent bug in the program source that needs correction. 3531This command allows the translator to change sex, become a programmer, 3532and have the cursor right into the window containing the program she 3533(or rather _he_) wants to modify. By later getting the cursor back in 3534the PO file window, or by asking Emacs to edit this file once again, PO 3535mode is then recovered. 3536 3537 The command `h' (`po-help') displays a summary of all available PO 3538mode commands. The translator should then type any character to resume 3539normal PO mode operations. The command `?' has the same effect as `h'. 3540 3541 The command `=' (`po-statistics') computes the total number of 3542entries in the PO file, the ordinal of the current entry (counted from 35431), the number of untranslated entries, the number of obsolete entries, 3544and displays all these numbers. 3545 3546 The command `V' (`po-validate') launches `msgfmt' in checking and 3547verbose mode over the current PO file. This command first offers to 3548save the current PO file on disk. The `msgfmt' tool, from GNU 3549`gettext', has the purpose of creating a MO file out of a PO file, and 3550PO mode uses the features of this program for checking the overall 3551format of a PO file, as well as all individual entries. 3552 3553 The program `msgfmt' runs asynchronously with Emacs, so the 3554translator regains control immediately while her PO file is being 3555studied. Error output is collected in the Emacs `*compilation*' buffer, 3556displayed in another window. The regular Emacs command `C-x`' 3557(`next-error'), as well as other usual compile commands, allow the 3558translator to reposition quickly to the offending parts of the PO file. 3559Once the cursor is on the line in error, the translator may decide on 3560any PO mode action which would help correcting the error. 3561 3562 3563File: gettext.info, Node: Entry Positioning, Next: Normalizing, Prev: Main PO Commands, Up: PO Mode 3564 35658.3.3 Entry Positioning 3566----------------------- 3567 3568 The cursor in a PO file window is almost always part of an entry. 3569The only exceptions are the special case when the cursor is after the 3570last entry in the file, or when the PO file is empty. The entry where 3571the cursor is found to be is said to be the current entry. Many PO 3572mode commands operate on the current entry, so moving the cursor does 3573more than allowing the translator to browse the PO file, this also 3574selects on which entry commands operate. 3575 3576 Some PO mode commands alter the position of the cursor in a 3577specialized way. A few of those special purpose positioning are 3578described here, the others are described in following sections (for a 3579complete list try `C-h m'): 3580 3581`.' 3582 Redisplay the current entry (`po-current-entry'). 3583 3584`n' 3585 Select the entry after the current one (`po-next-entry'). 3586 3587`p' 3588 Select the entry before the current one (`po-previous-entry'). 3589 3590`<' 3591 Select the first entry in the PO file (`po-first-entry'). 3592 3593`>' 3594 Select the last entry in the PO file (`po-last-entry'). 3595 3596`m' 3597 Record the location of the current entry for later use 3598 (`po-push-location'). 3599 3600`r' 3601 Return to a previously saved entry location (`po-pop-location'). 3602 3603`x' 3604 Exchange the current entry location with the previously saved one 3605 (`po-exchange-location'). 3606 3607 3608 Any Emacs command able to reposition the cursor may be used to 3609select the current entry in PO mode, including commands which move by 3610characters, lines, paragraphs, screens or pages, and search commands. 3611However, there is a kind of standard way to display the current entry 3612in PO mode, which usual Emacs commands moving the cursor do not 3613especially try to enforce. The command `.' (`po-current-entry') has 3614the sole purpose of redisplaying the current entry properly, after the 3615current entry has been changed by means external to PO mode, or the 3616Emacs screen otherwise altered. 3617 3618 It is yet to be decided if PO mode helps the translator, or otherwise 3619irritates her, by forcing a rigid window disposition while she is doing 3620her work. We originally had quite precise ideas about how windows 3621should behave, but on the other hand, anyone used to Emacs is often 3622happy to keep full control. Maybe a fixed window disposition might be 3623offered as a PO mode option that the translator might activate or 3624deactivate at will, so it could be offered on an experimental basis. 3625If nobody feels a real need for using it, or a compulsion for writing 3626it, we should drop this whole idea. The incentive for doing it should 3627come from translators rather than programmers, as opinions from an 3628experienced translator are surely more worth to me than opinions from 3629programmers _thinking_ about how _others_ should do translation. 3630 3631 The commands `n' (`po-next-entry') and `p' (`po-previous-entry') 3632move the cursor the entry following, or preceding, the current one. If 3633`n' is given while the cursor is on the last entry of the PO file, or 3634if `p' is given while the cursor is on the first entry, no move is done. 3635 3636 The commands `<' (`po-first-entry') and `>' (`po-last-entry') move 3637the cursor to the first entry, or last entry, of the PO file. When the 3638cursor is located past the last entry in a PO file, most PO mode 3639commands will return an error saying `After last entry'. Moreover, the 3640commands `<' and `>' have the special property of being able to work 3641even when the cursor is not into some PO file entry, and one may use 3642them for nicely correcting this situation. But even these commands 3643will fail on a truly empty PO file. There are development plans for 3644the PO mode for it to interactively fill an empty PO file from sources. 3645*Note Marking::. 3646 3647 The translator may decide, before working at the translation of a 3648particular entry, that she needs to browse the remainder of the PO 3649file, maybe for finding the terminology or phraseology used in related 3650entries. She can of course use the standard Emacs idioms for saving 3651the current cursor location in some register, and use that register for 3652getting back, or else, use the location ring. 3653 3654 PO mode offers another approach, by which cursor locations may be 3655saved onto a special stack. The command `m' (`po-push-location') 3656merely adds the location of current entry to the stack, pushing the 3657already saved locations under the new one. The command `r' 3658(`po-pop-location') consumes the top stack element and repositions the 3659cursor to the entry associated with that top element. This position is 3660then lost, for the next `r' will move the cursor to the previously 3661saved location, and so on until no locations remain on the stack. 3662 3663 If the translator wants the position to be kept on the location 3664stack, maybe for taking a look at the entry associated with the top 3665element, then go elsewhere with the intent of getting back later, she 3666ought to use `m' immediately after `r'. 3667 3668 The command `x' (`po-exchange-location') simultaneously repositions 3669the cursor to the entry associated with the top element of the stack of 3670saved locations, and replaces that top element with the location of the 3671current entry before the move. Consequently, repeating the `x' command 3672toggles alternatively between two entries. For achieving this, the 3673translator will position the cursor on the first entry, use `m', then 3674position to the second entry, and merely use `x' for making the switch. 3675 3676 3677File: gettext.info, Node: Normalizing, Next: Translated Entries, Prev: Entry Positioning, Up: PO Mode 3678 36798.3.4 Normalizing Strings in Entries 3680------------------------------------ 3681 3682 There are many different ways for encoding a particular string into a 3683PO file entry, because there are so many different ways to split and 3684quote multi-line strings, and even, to represent special characters by 3685backslashed escaped sequences. Some features of PO mode rely on the 3686ability for PO mode to scan an already existing PO file for a 3687particular string encoded into the `msgid' field of some entry. Even 3688if PO mode has internally all the built-in machinery for implementing 3689this recognition easily, doing it fast is technically difficult. To 3690facilitate a solution to this efficiency problem, we decided on a 3691canonical representation for strings. 3692 3693 A conventional representation of strings in a PO file is currently 3694under discussion, and PO mode experiments with a canonical 3695representation. Having both `xgettext' and PO mode converging towards 3696a uniform way of representing equivalent strings would be useful, as 3697the internal normalization needed by PO mode could be automatically 3698satisfied when using `xgettext' from GNU `gettext'. An explicit PO 3699mode normalization should then be only necessary for PO files imported 3700from elsewhere, or for when the convention itself evolves. 3701 3702 So, for achieving normalization of at least the strings of a given 3703PO file needing a canonical representation, the following PO mode 3704command is available: 3705 3706`M-x po-normalize' 3707 Tidy the whole PO file by making entries more uniform. 3708 3709 3710 The special command `M-x po-normalize', which has no associated 3711keys, revises all entries, ensuring that strings of both original and 3712translated entries use uniform internal quoting in the PO file. It 3713also removes any crumb after the last entry. This command may be 3714useful for PO files freshly imported from elsewhere, or if we ever 3715improve on the canonical quoting format we use. This canonical format 3716is not only meant for getting cleaner PO files, but also for greatly 3717speeding up `msgid' string lookup for some other PO mode commands. 3718 3719 `M-x po-normalize' presently makes three passes over the entries. 3720The first implements heuristics for converting PO files for GNU 3721`gettext' 0.6 and earlier, in which `msgid' and `msgstr' fields were 3722using K&R style C string syntax for multi-line strings. These 3723heuristics may fail for comments not related to obsolete entries and 3724ending with a backslash; they also depend on subsequent passes for 3725finalizing the proper commenting of continued lines for obsolete 3726entries. This first pass might disappear once all oldish PO files 3727would have been adjusted. The second and third pass normalize all 3728`msgid' and `msgstr' strings respectively. They also clean out those 3729trailing backslashes used by XView's `msgfmt' for continued lines. 3730 3731 Having such an explicit normalizing command allows for importing PO 3732files from other sources, but also eases the evolution of the current 3733convention, evolution driven mostly by aesthetic concerns, as of now. 3734It is easy to make suggested adjustments at a later time, as the 3735normalizing command and eventually, other GNU `gettext' tools should 3736greatly automate conformance. A description of the canonical string 3737format is given below, for the particular benefit of those not having 3738Emacs handy, and who would nevertheless want to handcraft their PO 3739files in nice ways. 3740 3741 Right now, in PO mode, strings are single line or multi-line. A 3742string goes multi-line if and only if it has _embedded_ newlines, that 3743is, if it matches `[^\n]\n+[^\n]'. So, we would have: 3744 3745 msgstr "\n\nHello, world!\n\n\n" 3746 3747 but, replacing the space by a newline, this becomes: 3748 3749 msgstr "" 3750 "\n" 3751 "\n" 3752 "Hello,\n" 3753 "world!\n" 3754 "\n" 3755 "\n" 3756 3757 We are deliberately using a caricatural example, here, to make the 3758point clearer. Usually, multi-lines are not that bad looking. It is 3759probable that we will implement the following suggestion. We might 3760lump together all initial newlines into the empty string, and also all 3761newlines introducing empty lines (that is, for N > 1, the N-1'th last 3762newlines would go together on a separate string), so making the 3763previous example appear: 3764 3765 msgstr "\n\n" 3766 "Hello,\n" 3767 "world!\n" 3768 "\n\n" 3769 3770 There are a few yet undecided little points about string 3771normalization, to be documented in this manual, once these questions 3772settle. 3773 3774 3775File: gettext.info, Node: Translated Entries, Next: Fuzzy Entries, Prev: Normalizing, Up: PO Mode 3776 37778.3.5 Translated Entries 3778------------------------ 3779 3780 Each PO file entry for which the `msgstr' field has been filled with 3781a translation, and which is not marked as fuzzy (*note Fuzzy Entries::), 3782is said to be a "translated" entry. Only translated entries will later 3783be compiled by GNU `msgfmt' and become usable in programs. Other entry 3784types will be excluded; translation will not occur for them. 3785 3786 Some commands are more specifically related to translated entry 3787processing. 3788 3789`t' 3790 Find the next translated entry (`po-next-translated-entry'). 3791 3792`T' 3793 Find the previous translated entry 3794 (`po-previous-translated-entry'). 3795 3796 3797 The commands `t' (`po-next-translated-entry') and `T' 3798(`po-previous-translated-entry') move forwards or backwards, chasing 3799for an translated entry. If none is found, the search is extended and 3800wraps around in the PO file buffer. 3801 3802 Translated entries usually result from the translator having edited 3803in a translation for them, *note Modifying Translations::. However, if 3804the variable `po-auto-fuzzy-on-edit' is not `nil', the entry having 3805received a new translation first becomes a fuzzy entry, which ought to 3806be later unfuzzied before becoming an official, genuine translated 3807entry. *Note Fuzzy Entries::. 3808 3809 3810File: gettext.info, Node: Fuzzy Entries, Next: Untranslated Entries, Prev: Translated Entries, Up: PO Mode 3811 38128.3.6 Fuzzy Entries 3813------------------- 3814 3815 Each PO file entry may have a set of "attributes", which are 3816qualities given a name and explicitly associated with the translation, 3817using a special system comment. One of these attributes has the name 3818`fuzzy', and entries having this attribute are said to have a fuzzy 3819translation. They are called fuzzy entries, for short. 3820 3821 Fuzzy entries, even if they account for translated entries for most 3822other purposes, usually call for revision by the translator. Those may 3823be produced by applying the program `msgmerge' to update an older 3824translated PO files according to a new PO template file, when this tool 3825hypothesises that some new `msgid' has been modified only slightly out 3826of an older one, and chooses to pair what it thinks to be the old 3827translation for the new modified entry. The slight alteration in the 3828original string (the `msgid' string) should often be reflected in the 3829translated string, and this requires the intervention of the 3830translator. For this reason, `msgmerge' might mark some entries as 3831being fuzzy. 3832 3833 Also, the translator may decide herself to mark an entry as fuzzy 3834for her own convenience, when she wants to remember that the entry has 3835to be later revisited. So, some commands are more specifically related 3836to fuzzy entry processing. 3837 3838`z' 3839 Find the next fuzzy entry (`po-next-fuzzy-entry'). 3840 3841`Z' 3842 Find the previous fuzzy entry (`po-previous-fuzzy-entry'). 3843 3844`<TAB>' 3845 Remove the fuzzy attribute of the current entry (`po-unfuzzy'). 3846 3847 3848 The commands `z' (`po-next-fuzzy-entry') and `Z' 3849(`po-previous-fuzzy-entry') move forwards or backwards, chasing for a 3850fuzzy entry. If none is found, the search is extended and wraps around 3851in the PO file buffer. 3852 3853 The command `<TAB>' (`po-unfuzzy') removes the fuzzy attribute 3854associated with an entry, usually leaving it translated. Further, if 3855the variable `po-auto-select-on-unfuzzy' has not the `nil' value, the 3856`<TAB>' command will automatically chase for another interesting entry 3857to work on. The initial value of `po-auto-select-on-unfuzzy' is `nil'. 3858 3859 The initial value of `po-auto-fuzzy-on-edit' is `nil'. However, if 3860the variable `po-auto-fuzzy-on-edit' is set to `t', any entry edited 3861through the `<RET>' command is marked fuzzy, as a way to ensure some 3862kind of double check, later. In this case, the usual paradigm is that 3863an entry becomes fuzzy (if not already) whenever the translator 3864modifies it. If she is satisfied with the translation, she then uses 3865`<TAB>' to pick another entry to work on, clearing the fuzzy attribute 3866on the same blow. If she is not satisfied yet, she merely uses `<SPC>' 3867to chase another entry, leaving the entry fuzzy. 3868 3869 The translator may also use the `<DEL>' command 3870(`po-fade-out-entry') over any translated entry to mark it as being 3871fuzzy, when she wants to easily leave a trace she wants to later return 3872working at this entry. 3873 3874 Also, when time comes to quit working on a PO file buffer with the 3875`q' command, the translator is asked for confirmation, if fuzzy string 3876still exists. 3877 3878 3879File: gettext.info, Node: Untranslated Entries, Next: Obsolete Entries, Prev: Fuzzy Entries, Up: PO Mode 3880 38818.3.7 Untranslated Entries 3882-------------------------- 3883 3884 When `xgettext' originally creates a PO file, unless told otherwise, 3885it initializes the `msgid' field with the untranslated string, and 3886leaves the `msgstr' string to be empty. Such entries, having an empty 3887translation, are said to be "untranslated" entries. Later, when the 3888programmer slightly modifies some string right in the program, this 3889change is later reflected in the PO file by the appearance of a new 3890untranslated entry for the modified string. 3891 3892 The usual commands moving from entry to entry consider untranslated 3893entries on the same level as active entries. Untranslated entries are 3894easily recognizable by the fact they end with `msgstr ""'. 3895 3896 The work of the translator might be (quite naively) seen as the 3897process of seeking for an untranslated entry, editing a translation for 3898it, and repeating these actions until no untranslated entries remain. 3899Some commands are more specifically related to untranslated entry 3900processing. 3901 3902`u' 3903 Find the next untranslated entry (`po-next-untranslated-entry'). 3904 3905`U' 3906 Find the previous untranslated entry 3907 (`po-previous-untransted-entry'). 3908 3909`k' 3910 Turn the current entry into an untranslated one (`po-kill-msgstr'). 3911 3912 3913 The commands `u' (`po-next-untranslated-entry') and `U' 3914(`po-previous-untransted-entry') move forwards or backwards, chasing 3915for an untranslated entry. If none is found, the search is extended 3916and wraps around in the PO file buffer. 3917 3918 An entry can be turned back into an untranslated entry by merely 3919emptying its translation, using the command `k' (`po-kill-msgstr'). 3920*Note Modifying Translations::. 3921 3922 Also, when time comes to quit working on a PO file buffer with the 3923`q' command, the translator is asked for confirmation, if some 3924untranslated string still exists. 3925 3926 3927File: gettext.info, Node: Obsolete Entries, Next: Modifying Translations, Prev: Untranslated Entries, Up: PO Mode 3928 39298.3.8 Obsolete Entries 3930---------------------- 3931 3932 By "obsolete" PO file entries, we mean those entries which are 3933commented out, usually by `msgmerge' when it found that the translation 3934is not needed anymore by the package being localized. 3935 3936 The usual commands moving from entry to entry consider obsolete 3937entries on the same level as active entries. Obsolete entries are 3938easily recognizable by the fact that all their lines start with `#', 3939even those lines containing `msgid' or `msgstr'. 3940 3941 Commands exist for emptying the translation or reinitializing it to 3942the original untranslated string. Commands interfacing with the kill 3943ring may force some previously saved text into the translation. The 3944user may interactively edit the translation. All these commands may 3945apply to obsolete entries, carefully leaving the entry obsolete after 3946the fact. 3947 3948 Moreover, some commands are more specifically related to obsolete 3949entry processing. 3950 3951`o' 3952 Find the next obsolete entry (`po-next-obsolete-entry'). 3953 3954`O' 3955 Find the previous obsolete entry (`po-previous-obsolete-entry'). 3956 3957`<DEL>' 3958 Make an active entry obsolete, or zap out an obsolete entry 3959 (`po-fade-out-entry'). 3960 3961 3962 The commands `o' (`po-next-obsolete-entry') and `O' 3963(`po-previous-obsolete-entry') move forwards or backwards, chasing for 3964an obsolete entry. If none is found, the search is extended and wraps 3965around in the PO file buffer. 3966 3967 PO mode does not provide ways for un-commenting an obsolete entry 3968and making it active, because this would reintroduce an original 3969untranslated string which does not correspond to any marked string in 3970the program sources. This goes with the philosophy of never 3971introducing useless `msgid' values. 3972 3973 However, it is possible to comment out an active entry, so making it 3974obsolete. GNU `gettext' utilities will later react to the 3975disappearance of a translation by using the untranslated string. The 3976command `<DEL>' (`po-fade-out-entry') pushes the current entry a little 3977further towards annihilation. If the entry is active (it is a 3978translated entry), then it is first made fuzzy. If it is already fuzzy, 3979then the entry is merely commented out, with confirmation. If the entry 3980is already obsolete, then it is completely deleted from the PO file. 3981It is easy to recycle the translation so deleted into some other PO file 3982entry, usually one which is untranslated. *Note Modifying 3983Translations::. 3984 3985 Here is a quite interesting problem to solve for later development of 3986PO mode, for those nights you are not sleepy. The idea would be that 3987PO mode might become bright enough, one of these days, to make good 3988guesses at retrieving the most probable candidate, among all obsolete 3989entries, for initializing the translation of a newly appeared string. 3990I think it might be a quite hard problem to do this algorithmically, as 3991we have to develop good and efficient measures of string similarity. 3992Right now, PO mode completely lets the decision to the translator, when 3993the time comes to find the adequate obsolete translation, it merely 3994tries to provide handy tools for helping her to do so. 3995 3996 3997File: gettext.info, Node: Modifying Translations, Next: Modifying Comments, Prev: Obsolete Entries, Up: PO Mode 3998 39998.3.9 Modifying Translations 4000---------------------------- 4001 4002 PO mode prevents direct modification of the PO file, by the usual 4003means Emacs gives for altering a buffer's contents. By doing so, it 4004pretends helping the translator to avoid little clerical errors about 4005the overall file format, or the proper quoting of strings, as those 4006errors would be easily made. Other kinds of errors are still possible, 4007but some may be caught and diagnosed by the batch validation process, 4008which the translator may always trigger by the `V' command. For all 4009other errors, the translator has to rely on her own judgment, and also 4010on the linguistic reports submitted to her by the users of the 4011translated package, having the same mother tongue. 4012 4013 When the time comes to create a translation, correct an error 4014diagnosed mechanically or reported by a user, the translators have to 4015resort to using the following commands for modifying the translations. 4016 4017`<RET>' 4018 Interactively edit the translation (`po-edit-msgstr'). 4019 4020`<LFD>' 4021`C-j' 4022 Reinitialize the translation with the original, untranslated string 4023 (`po-msgid-to-msgstr'). 4024 4025`k' 4026 Save the translation on the kill ring, and delete it 4027 (`po-kill-msgstr'). 4028 4029`w' 4030 Save the translation on the kill ring, without deleting it 4031 (`po-kill-ring-save-msgstr'). 4032 4033`y' 4034 Replace the translation, taking the new from the kill ring 4035 (`po-yank-msgstr'). 4036 4037 4038 The command `<RET>' (`po-edit-msgstr') opens a new Emacs window 4039meant to edit in a new translation, or to modify an already existing 4040translation. The new window contains a copy of the translation taken 4041from the current PO file entry, all ready for edition, expunged of all 4042quoting marks, fully modifiable and with the complete extent of Emacs 4043modifying commands. When the translator is done with her 4044modifications, she may use `C-c C-c' to close the subedit window with 4045the automatically requoted results, or `C-c C-k' to abort her 4046modifications. *Note Subedit::, for more information. 4047 4048 The command `<LFD>' (`po-msgid-to-msgstr') initializes, or 4049reinitializes the translation with the original string. This command is 4050normally used when the translator wants to redo a fresh translation of 4051the original string, disregarding any previous work. 4052 4053 It is possible to arrange so, whenever editing an untranslated 4054entry, the `<LFD>' command be automatically executed. If you set 4055`po-auto-edit-with-msgid' to `t', the translation gets initialised with 4056the original string, in case none exists already. The default value 4057for `po-auto-edit-with-msgid' is `nil'. 4058 4059 In fact, whether it is best to start a translation with an empty 4060string, or rather with a copy of the original string, is a matter of 4061taste or habit. Sometimes, the source language and the target language 4062are so different that is simply best to start writing on an empty page. 4063At other times, the source and target languages are so close that it 4064would be a waste to retype a number of words already being written in 4065the original string. A translator may also like having the original 4066string right under her eyes, as she will progressively overwrite the 4067original text with the translation, even if this requires some extra 4068editing work to get rid of the original. 4069 4070 The command `k' (`po-kill-msgstr') merely empties the translation 4071string, so turning the entry into an untranslated one. But while doing 4072so, its previous contents is put apart in a special place, known as the 4073kill ring. The command `w' (`po-kill-ring-save-msgstr') has also the 4074effect of taking a copy of the translation onto the kill ring, but it 4075otherwise leaves the entry alone, and does _not_ remove the translation 4076from the entry. Both commands use exactly the Emacs kill ring, which 4077is shared between buffers, and which is well known already to Emacs 4078lovers. 4079 4080 The translator may use `k' or `w' many times in the course of her 4081work, as the kill ring may hold several saved translations. From the 4082kill ring, strings may later be reinserted in various Emacs buffers. 4083In particular, the kill ring may be used for moving translation strings 4084between different entries of a single PO file buffer, or if the 4085translator is handling many such buffers at once, even between PO files. 4086 4087 To facilitate exchanges with buffers which are not in PO mode, the 4088translation string put on the kill ring by the `k' command is fully 4089unquoted before being saved: external quotes are removed, multi-line 4090strings are concatenated, and backslash escaped sequences are turned 4091into their corresponding characters. In the special case of obsolete 4092entries, the translation is also uncommented prior to saving. 4093 4094 The command `y' (`po-yank-msgstr') completely replaces the 4095translation of the current entry by a string taken from the kill ring. 4096Following Emacs terminology, we then say that the replacement string is 4097"yanked" into the PO file buffer. *Note Yanking: (emacs)Yanking. The 4098first time `y' is used, the translation receives the value of the most 4099recent addition to the kill ring. If `y' is typed once again, 4100immediately, without intervening keystrokes, the translation just 4101inserted is taken away and replaced by the second most recent addition 4102to the kill ring. By repeating `y' many times in a row, the translator 4103may travel along the kill ring for saved strings, until she finds the 4104string she really wanted. 4105 4106 When a string is yanked into a PO file entry, it is fully and 4107automatically requoted for complying with the format PO files should 4108have. Further, if the entry is obsolete, PO mode then appropriately 4109push the inserted string inside comments. Once again, translators 4110should not burden themselves with quoting considerations besides, of 4111course, the necessity of the translated string itself respective to the 4112program using it. 4113 4114 Note that `k' or `w' are not the only commands pushing strings on 4115the kill ring, as almost any PO mode command replacing translation 4116strings (or the translator comments) automatically saves the old string 4117on the kill ring. The main exceptions to this general rule are the 4118yanking commands themselves. 4119 4120 To better illustrate the operation of killing and yanking, let's use 4121an actual example, taken from a common situation. When the programmer 4122slightly modifies some string right in the program, his change is later 4123reflected in the PO file by the appearance of a new untranslated entry 4124for the modified string, and the fact that the entry translating the 4125original or unmodified string becomes obsolete. In many cases, the 4126translator might spare herself some work by retrieving the unmodified 4127translation from the obsolete entry, then initializing the untranslated 4128entry `msgstr' field with this retrieved translation. Once this done, 4129the obsolete entry is not wanted anymore, and may be safely deleted. 4130 4131 When the translator finds an untranslated entry and suspects that a 4132slight variant of the translation exists, she immediately uses `m' to 4133mark the current entry location, then starts chasing obsolete entries 4134with `o', hoping to find some translation corresponding to the 4135unmodified string. Once found, she uses the `<DEL>' command for 4136deleting the obsolete entry, knowing that `<DEL>' also _kills_ the 4137translation, that is, pushes the translation on the kill ring. Then, 4138`r' returns to the initial untranslated entry, and `y' then _yanks_ the 4139saved translation right into the `msgstr' field. The translator is 4140then free to use `<RET>' for fine tuning the translation contents, and 4141maybe to later use `u', then `m' again, for going on with the next 4142untranslated string. 4143 4144 When some sequence of keys has to be typed over and over again, the 4145translator may find it useful to become better acquainted with the Emacs 4146capability of learning these sequences and playing them back under 4147request. *Note Keyboard Macros: (emacs)Keyboard Macros. 4148 4149 4150File: gettext.info, Node: Modifying Comments, Next: Subedit, Prev: Modifying Translations, Up: PO Mode 4151 41528.3.10 Modifying Comments 4153------------------------- 4154 4155 Any translation work done seriously will raise many linguistic 4156difficulties, for which decisions have to be made, and the choices 4157further documented. These documents may be saved within the PO file in 4158form of translator comments, which the translator is free to create, 4159delete, or modify at will. These comments may be useful to herself 4160when she returns to this PO file after a while. 4161 4162 Comments not having whitespace after the initial `#', for example, 4163those beginning with `#.' or `#:', are _not_ translator comments, they 4164are exclusively created by other `gettext' tools. So, the commands 4165below will never alter such system added comments, they are not meant 4166for the translator to modify. *Note PO Files::. 4167 4168 The following commands are somewhat similar to those modifying 4169translations, so the general indications given for those apply here. 4170*Note Modifying Translations::. 4171 4172`#' 4173 Interactively edit the translator comments (`po-edit-comment'). 4174 4175`K' 4176 Save the translator comments on the kill ring, and delete it 4177 (`po-kill-comment'). 4178 4179`W' 4180 Save the translator comments on the kill ring, without deleting it 4181 (`po-kill-ring-save-comment'). 4182 4183`Y' 4184 Replace the translator comments, taking the new from the kill ring 4185 (`po-yank-comment'). 4186 4187 4188 These commands parallel PO mode commands for modifying the 4189translation strings, and behave much the same way as they do, except 4190that they handle this part of PO file comments meant for translator 4191usage, rather than the translation strings. So, if the descriptions 4192given below are slightly succinct, it is because the full details have 4193already been given. *Note Modifying Translations::. 4194 4195 The command `#' (`po-edit-comment') opens a new Emacs window 4196containing a copy of the translator comments on the current PO file 4197entry. If there are no such comments, PO mode understands that the 4198translator wants to add a comment to the entry, and she is presented 4199with an empty screen. Comment marks (`#') and the space following them 4200are automatically removed before edition, and reinstated after. For 4201translator comments pertaining to obsolete entries, the uncommenting 4202and recommenting operations are done twice. Once in the editing 4203window, the keys `C-c C-c' allow the translator to tell she is finished 4204with editing the comment. *Note Subedit::, for further details. 4205 4206 Functions found on `po-subedit-mode-hook', if any, are executed after 4207the string has been inserted in the edit buffer. 4208 4209 The command `K' (`po-kill-comment') gets rid of all translator 4210comments, while saving those comments on the kill ring. The command 4211`W' (`po-kill-ring-save-comment') takes a copy of the translator 4212comments on the kill ring, but leaves them undisturbed in the current 4213entry. The command `Y' (`po-yank-comment') completely replaces the 4214translator comments by a string taken at the front of the kill ring. 4215When this command is immediately repeated, the comments just inserted 4216are withdrawn, and replaced by other strings taken along the kill ring. 4217 4218 On the kill ring, all strings have the same nature. There is no 4219distinction between _translation_ strings and _translator comments_ 4220strings. So, for example, let's presume the translator has just 4221finished editing a translation, and wants to create a new translator 4222comment to document why the previous translation was not good, just to 4223remember what was the problem. Foreseeing that she will do that in her 4224documentation, the translator may want to quote the previous 4225translation in her translator comments. To do so, she may initialize 4226the translator comments with the previous translation, still at the 4227head of the kill ring. Because editing already pushed the previous 4228translation on the kill ring, she merely has to type `M-w' prior to 4229`#', and the previous translation will be right there, all ready for 4230being introduced by some explanatory text. 4231 4232 On the other hand, presume there are some translator comments already 4233and that the translator wants to add to those comments, instead of 4234wholly replacing them. Then, she should edit the comment right away 4235with `#'. Once inside the editing window, she can use the regular 4236Emacs commands `C-y' (`yank') and `M-y' (`yank-pop') to get the 4237previous translation where she likes. 4238 4239 4240File: gettext.info, Node: Subedit, Next: C Sources Context, Prev: Modifying Comments, Up: PO Mode 4241 42428.3.11 Details of Sub Edition 4243----------------------------- 4244 4245 The PO subedit minor mode has a few peculiarities worth being 4246described in fuller detail. It installs a few commands over the usual 4247editing set of Emacs, which are described below. 4248 4249`C-c C-c' 4250 Complete edition (`po-subedit-exit'). 4251 4252`C-c C-k' 4253 Abort edition (`po-subedit-abort'). 4254 4255`C-c C-a' 4256 Consult auxiliary PO files (`po-subedit-cycle-auxiliary'). 4257 4258 4259 The window's contents represents a translation for a given message, 4260or a translator comment. The translator may modify this window to her 4261heart's content. Once this is done, the command `C-c C-c' 4262(`po-subedit-exit') may be used to return the edited translation into 4263the PO file, replacing the original translation, even if it moved out of 4264sight or if buffers were switched. 4265 4266 If the translator becomes unsatisfied with her translation or 4267comment, to the extent she prefers keeping what was existent prior to 4268the `<RET>' or `#' command, she may use the command `C-c C-k' 4269(`po-subedit-abort') to merely get rid of edition, while preserving the 4270original translation or comment. Another way would be for her to exit 4271normally with `C-c C-c', then type `U' once for undoing the whole 4272effect of last edition. 4273 4274 The command `C-c C-a' (`po-subedit-cycle-auxiliary') allows for 4275glancing through translations already achieved in other languages, 4276directly while editing the current translation. This may be quite 4277convenient when the translator is fluent at many languages, but of 4278course, only makes sense when such completed auxiliary PO files are 4279already available to her (*note Auxiliary::). 4280 4281 Functions found on `po-subedit-mode-hook', if any, are executed after 4282the string has been inserted in the edit buffer. 4283 4284 While editing her translation, the translator should pay attention 4285to not inserting unwanted `<RET>' (newline) characters at the end of 4286the translated string if those are not meant to be there, or to removing 4287such characters when they are required. Since these characters are not 4288visible in the editing buffer, they are easily introduced by mistake. 4289To help her, `<RET>' automatically puts the character `<' at the end of 4290the string being edited, but this `<' is not really part of the string. 4291On exiting the editing window with `C-c C-c', PO mode automatically 4292removes such `<' and all whitespace added after it. If the translator 4293adds characters after the terminating `<', it looses its delimiting 4294property and integrally becomes part of the string. If she removes the 4295delimiting `<', then the edited string is taken _as is_, with all 4296trailing newlines, even if invisible. Also, if the translated string 4297ought to end itself with a genuine `<', then the delimiting `<' may not 4298be removed; so the string should appear, in the editing window, as 4299ending with two `<' in a row. 4300 4301 When a translation (or a comment) is being edited, the translator 4302may move the cursor back into the PO file buffer and freely move to 4303other entries, browsing at will. If, with an edition pending, the 4304translator wanders in the PO file buffer, she may decide to start 4305modifying another entry. Each entry being edited has its own subedit 4306buffer. It is possible to simultaneously edit the translation _and_ 4307the comment of a single entry, or to edit entries in different PO 4308files, all at once. Typing `<RET>' on a field already being edited 4309merely resumes that particular edit. Yet, the translator should better 4310be comfortable at handling many Emacs windows! 4311 4312 Pending subedits may be completed or aborted in any order, regardless 4313of how or when they were started. When many subedits are pending and 4314the translator asks for quitting the PO file (with the `q' command), 4315subedits are automatically resumed one at a time, so she may decide for 4316each of them. 4317 4318 4319File: gettext.info, Node: C Sources Context, Next: Auxiliary, Prev: Subedit, Up: PO Mode 4320 43218.3.12 C Sources Context 4322------------------------ 4323 4324 PO mode is particularly powerful when used with PO files created 4325through GNU `gettext' utilities, as those utilities insert special 4326comments in the PO files they generate. Some of these special comments 4327relate the PO file entry to exactly where the untranslated string 4328appears in the program sources. 4329 4330 When the translator gets to an untranslated entry, she is fairly 4331often faced with an original string which is not as informative as it 4332normally should be, being succinct, cryptic, or otherwise ambiguous. 4333Before choosing how to translate the string, she needs to understand 4334better what the string really means and how tight the translation has 4335to be. Most of the time, when problems arise, the only way left to make 4336her judgment is looking at the true program sources from where this 4337string originated, searching for surrounding comments the programmer 4338might have put in there, and looking around for helping clues of _any_ 4339kind. 4340 4341 Surely, when looking at program sources, the translator will receive 4342more help if she is a fluent programmer. However, even if she is not 4343versed in programming and feels a little lost in C code, the translator 4344should not be shy at taking a look, once in a while. It is most 4345probable that she will still be able to find some of the hints she 4346needs. She will learn quickly to not feel uncomfortable in program 4347code, paying more attention to programmer's comments, variable and 4348function names (if he dared choosing them well), and overall 4349organization, than to the program code itself. 4350 4351 The following commands are meant to help the translator at getting 4352program source context for a PO file entry. 4353 4354`s' 4355 Resume the display of a program source context, or cycle through 4356 them (`po-cycle-source-reference'). 4357 4358`M-s' 4359 Display of a program source context selected by menu 4360 (`po-select-source-reference'). 4361 4362`S' 4363 Add a directory to the search path for source files 4364 (`po-consider-source-path'). 4365 4366`M-S' 4367 Delete a directory from the search path for source files 4368 (`po-ignore-source-path'). 4369 4370 4371 The commands `s' (`po-cycle-source-reference') and `M-s' 4372(`po-select-source-reference') both open another window displaying some 4373source program file, and already positioned in such a way that it shows 4374an actual use of the string to be translated. By doing so, the command 4375gives source program context for the string. But if the entry has no 4376source context references, or if all references are unresolved along 4377the search path for program sources, then the command diagnoses this as 4378an error. 4379 4380 Even if `s' (or `M-s') opens a new window, the cursor stays in the 4381PO file window. If the translator really wants to get into the program 4382source window, she ought to do it explicitly, maybe by using command 4383`O'. 4384 4385 When `s' is typed for the first time, or for a PO file entry which 4386is different of the last one used for getting source context, then the 4387command reacts by giving the first context available for this entry, if 4388any. If some context has already been recently displayed for the 4389current PO file entry, and the translator wandered off to do other 4390things, typing `s' again will merely resume, in another window, the 4391context last displayed. In particular, if the translator moved the 4392cursor away from the context in the source file, the command will bring 4393the cursor back to the context. By using `s' many times in a row, with 4394no other commands intervening, PO mode will cycle to the next available 4395contexts for this particular entry, getting back to the first context 4396once the last has been shown. 4397 4398 The command `M-s' behaves differently. Instead of cycling through 4399references, it lets the translator choose a particular reference among 4400many, and displays that reference. It is best used with completion, if 4401the translator types `<TAB>' immediately after `M-s', in response to 4402the question, she will be offered a menu of all possible references, as 4403a reminder of which are the acceptable answers. This command is useful 4404only where there are really many contexts available for a single string 4405to translate. 4406 4407 Program source files are usually found relative to where the PO file 4408stands. As a special provision, when this fails, the file is also 4409looked for, but relative to the directory immediately above it. Those 4410two cases take proper care of most PO files. However, it might happen 4411that a PO file has been moved, or is edited in a different place than 4412its normal location. When this happens, the translator should tell PO 4413mode in which directory normally sits the genuine PO file. Many such 4414directories may be specified, and all together, they constitute what is 4415called the "search path" for program sources. The command `S' 4416(`po-consider-source-path') is used to interactively enter a new 4417directory at the front of the search path, and the command `M-S' 4418(`po-ignore-source-path') is used to select, with completion, one of 4419the directories she does not want anymore on the search path. 4420 4421 4422File: gettext.info, Node: Auxiliary, Prev: C Sources Context, Up: PO Mode 4423 44248.3.13 Consulting Auxiliary PO Files 4425------------------------------------ 4426 4427 PO mode is able to help the knowledgeable translator, being fluent in 4428many languages, at taking advantage of translations already achieved in 4429other languages she just happens to know. It provides these other 4430language translations as additional context for her own work. Moreover, 4431it has features to ease the production of translations for many 4432languages at once, for translators preferring to work in this way. 4433 4434 An "auxiliary" PO file is an existing PO file meant for the same 4435package the translator is working on, but targeted to a different mother 4436tongue language. Commands exist for declaring and handling auxiliary 4437PO files, and also for showing contexts for the entry under work. 4438 4439 Here are the auxiliary file commands available in PO mode. 4440 4441`a' 4442 Seek auxiliary files for another translation for the same entry 4443 (`po-cycle-auxiliary'). 4444 4445`C-c C-a' 4446 Switch to a particular auxiliary file (`po-select-auxiliary'). 4447 4448`A' 4449 Declare this PO file as an auxiliary file 4450 (`po-consider-as-auxiliary'). 4451 4452`M-A' 4453 Remove this PO file from the list of auxiliary files 4454 (`po-ignore-as-auxiliary'). 4455 4456 4457 Command `A' (`po-consider-as-auxiliary') adds the current PO file to 4458the list of auxiliary files, while command `M-A' 4459(`po-ignore-as-auxiliary' just removes it. 4460 4461 The command `a' (`po-cycle-auxiliary') seeks all auxiliary PO files, 4462round-robin, searching for a translated entry in some other language 4463having an `msgid' field identical as the one for the current entry. 4464The found PO file, if any, takes the place of the current PO file in 4465the display (its window gets on top). Before doing so, the current PO 4466file is also made into an auxiliary file, if not already. So, `a' in 4467this newly displayed PO file will seek another PO file, and so on, so 4468repeating `a' will eventually yield back the original PO file. 4469 4470 The command `C-c C-a' (`po-select-auxiliary') asks the translator 4471for her choice of a particular auxiliary file, with completion, and 4472then switches to that selected PO file. The command also checks if the 4473selected file has an `msgid' field identical as the one for the current 4474entry, and if yes, this entry becomes current. Otherwise, the cursor 4475of the selected file is left undisturbed. 4476 4477 For all this to work fully, auxiliary PO files will have to be 4478normalized, in that way that `msgid' fields should be written _exactly_ 4479the same way. It is possible to write `msgid' fields in various ways 4480for representing the same string, different writing would break the 4481proper behaviour of the auxiliary file commands of PO mode. This is not 4482expected to be much a problem in practice, as most existing PO files 4483have their `msgid' entries written by the same GNU `gettext' tools. 4484 4485 However, PO files initially created by PO mode itself, while marking 4486strings in source files, are normalised differently. So are PO files 4487resulting of the `M-x normalize' command. Until these discrepancies 4488between PO mode and other GNU `gettext' tools get fully resolved, the 4489translator should stay aware of normalisation issues. 4490 4491 4492File: gettext.info, Node: Compendium, Prev: PO Mode, Up: Editing 4493 44948.4 Using Translation Compendia 4495=============================== 4496 4497 A "compendium" is a special PO file containing a set of translations 4498recurring in many different packages. The translator can use gettext 4499tools to build a new compendium, to add entries to her compendium, and 4500to initialize untranslated entries, or to update already translated 4501entries, from translations kept in the compendium. 4502 4503* Menu: 4504 4505* Creating Compendia:: Merging translations for later use 4506* Using Compendia:: Using older translations if they fit 4507 4508 4509File: gettext.info, Node: Creating Compendia, Next: Using Compendia, Prev: Compendium, Up: Compendium 4510 45118.4.1 Creating Compendia 4512------------------------ 4513 4514 Basically every PO file consisting of translated entries only can be 4515declared as a valid compendium. Often the translator wants to have 4516special compendia; let's consider two cases: `concatenating PO files' 4517and `extracting a message subset from a PO file'. 4518 45198.4.1.1 Concatenate PO Files 4520............................ 4521 4522 To concatenate several valid PO files into one compendium file you 4523can use `msgcomm' or `msgcat' (the latter preferred): 4524 4525 msgcat -o compendium.po file1.po file2.po 4526 4527 By default, `msgcat' will accumulate divergent translations for the 4528same string. Those occurrences will be marked as `fuzzy' and highly 4529visible decorated; calling `msgcat' on `file1.po': 4530 4531 #: src/hello.c:200 4532 #, c-format 4533 msgid "Report bugs to <%s>.\n" 4534 msgstr "Comunicar `bugs' a <%s>.\n" 4535 4536and `file2.po': 4537 4538 #: src/bye.c:100 4539 #, c-format 4540 msgid "Report bugs to <%s>.\n" 4541 msgstr "Comunicar \"bugs\" a <%s>.\n" 4542 4543will result in: 4544 4545 #: src/hello.c:200 src/bye.c:100 4546 #, fuzzy, c-format 4547 msgid "Report bugs to <%s>.\n" 4548 msgstr "" 4549 "#-#-#-#-# file1.po #-#-#-#-#\n" 4550 "Comunicar `bugs' a <%s>.\n" 4551 "#-#-#-#-# file2.po #-#-#-#-#\n" 4552 "Comunicar \"bugs\" a <%s>.\n" 4553 4554The translator will have to resolve this "conflict" manually; she has 4555to decide whether the first or the second version is appropriate (or 4556provide a new translation), to delete the "marker lines", and finally 4557to remove the `fuzzy' mark. 4558 4559 If the translator knows in advance the first found translation of a 4560message is always the best translation she can make use to the 4561`--use-first' switch: 4562 4563 msgcat --use-first -o compendium.po file1.po file2.po 4564 4565 A good compendium file must not contain `fuzzy' or untranslated 4566entries. If input files are "dirty" you must preprocess the input 4567files or postprocess the result using `msgattrib --translated 4568--no-fuzzy'. 4569 45708.4.1.2 Extract a Message Subset from a PO File 4571............................................... 4572 4573 Nobody wants to translate the same messages again and again; thus you 4574may wish to have a compendium file containing `getopt.c' messages. 4575 4576 To extract a message subset (e.g., all `getopt.c' messages) from an 4577existing PO file into one compendium file you can use `msggrep': 4578 4579 msggrep --location src/getopt.c -o compendium.po file.po 4580 4581 4582File: gettext.info, Node: Using Compendia, Prev: Creating Compendia, Up: Compendium 4583 45848.4.2 Using Compendia 4585--------------------- 4586 4587 You can use a compendium file to initialize a translation from 4588scratch or to update an already existing translation. 4589 45908.4.2.1 Initialize a New Translation File 4591......................................... 4592 4593 Since a PO file with translations does not exist the translator can 4594merely use `/dev/null' to fake the "old" translation file. 4595 4596 msgmerge --compendium compendium.po -o file.po /dev/null file.pot 4597 45988.4.2.2 Update an Existing Translation File 4599........................................... 4600 4601 Concatenate the compendium file(s) and the existing PO, merge the 4602result with the POT file and remove the obsolete entries (optional, 4603here done using `sed'): 4604 4605 msgcat --use-first -o update.po compendium1.po compendium2.po file.po 4606 msgmerge update.po file.pot | msgattrib --no-obsolete > file.po 4607 4608 4609File: gettext.info, Node: Manipulating, Next: Binaries, Prev: Editing, Up: Top 4610 46119 Manipulating PO Files 4612*********************** 4613 4614 Sometimes it is necessary to manipulate PO files in a way that is 4615better performed automatically than by hand. GNU `gettext' includes a 4616complete set of tools for this purpose. 4617 4618 When merging two packages into a single package, the resulting POT 4619file will be the concatenation of the two packages' POT files. Thus the 4620maintainer must concatenate the two existing package translations into 4621a single translation catalog, for each language. This is best performed 4622using `msgcat'. It is then the translators' duty to deal with any 4623possible conflicts that arose during the merge. 4624 4625 When a translator takes over the translation job from another 4626translator, but she uses a different character encoding in her locale, 4627she will convert the catalog to her character encoding. This is best 4628done through the `msgconv' program. 4629 4630 When a maintainer takes a source file with tagged messages from 4631another package, he should also take the existing translations for this 4632source file (and not let the translators do the same job twice). One 4633way to do this is through `msggrep', another is to create a POT file for 4634that source file and use `msgmerge'. 4635 4636 When a translator wants to adjust some translation catalog for a 4637special dialect or orthography -- for example, German as written in 4638Switzerland versus German as written in Germany -- she needs to apply 4639some text processing to every message in the catalog. The tool for 4640doing this is `msgfilter'. 4641 4642 Another use of `msgfilter' is to produce approximately the POT file 4643for which a given PO file was made. This can be done through a filter 4644command like `msgfilter sed -e d | sed -e '/^# /d''. Note that the 4645original POT file may have had different comments and different plural 4646message counts, that's why it's better to use the original POT file if 4647available. 4648 4649 When a translator wants to check her translations, for example 4650according to orthography rules or using a non-interactive spell 4651checker, she can do so using the `msgexec' program. 4652 4653 When third party tools create PO or POT files, sometimes duplicates 4654cannot be avoided. But the GNU `gettext' tools give an error when they 4655encounter duplicate msgids in the same file and in the same domain. To 4656merge duplicates, the `msguniq' program can be used. 4657 4658 `msgcomm' is a more general tool for keeping or throwing away 4659duplicates, occurring in different files. 4660 4661 `msgcmp' can be used to check whether a translation catalog is 4662completely translated. 4663 4664 `msgattrib' can be used to select and extract only the fuzzy or 4665untranslated messages of a translation catalog. 4666 4667 `msgen' is useful as a first step for preparing English translation 4668catalogs. It copies each message's msgid to its msgstr. 4669 4670 Finally, for those applications where all these various programs are 4671not sufficient, a library `libgettextpo' is provided that can be used to 4672write other specialized programs that process PO files. 4673 4674* Menu: 4675 4676* msgcat Invocation:: Invoking the `msgcat' Program 4677* msgconv Invocation:: Invoking the `msgconv' Program 4678* msggrep Invocation:: Invoking the `msggrep' Program 4679* msgfilter Invocation:: Invoking the `msgfilter' Program 4680* msguniq Invocation:: Invoking the `msguniq' Program 4681* msgcomm Invocation:: Invoking the `msgcomm' Program 4682* msgcmp Invocation:: Invoking the `msgcmp' Program 4683* msgattrib Invocation:: Invoking the `msgattrib' Program 4684* msgen Invocation:: Invoking the `msgen' Program 4685* msgexec Invocation:: Invoking the `msgexec' Program 4686* Colorizing:: Highlighting parts of PO files 4687* libgettextpo:: Writing your own programs that process PO files 4688 4689 4690File: gettext.info, Node: msgcat Invocation, Next: msgconv Invocation, Prev: Manipulating, Up: Manipulating 4691 46929.1 Invoking the `msgcat' Program 4693================================= 4694 4695 msgcat [OPTION] [INPUTFILE]... 4696 4697 The `msgcat' program concatenates and merges the specified PO files. 4698It finds messages which are common to two or more of the specified PO 4699files. By using the `--more-than' option, greater commonality may be 4700requested before messages are printed. Conversely, the `--less-than' 4701option may be used to specify less commonality before messages are 4702printed (i.e. `--less-than=2' will only print the unique messages). 4703Translations, comments and extract comments will be cumulated, except 4704that if `--use-first' is specified, they will be taken from the first 4705PO file to define them. File positions from all PO files will be 4706cumulated. 4707 47089.1.1 Input file location 4709------------------------- 4710 4711`INPUTFILE ...' 4712 Input files. 4713 4714`-f FILE' 4715`--files-from=FILE' 4716 Read the names of the input files from FILE instead of getting 4717 them from the command line. 4718 4719`-D DIRECTORY' 4720`--directory=DIRECTORY' 4721 Add DIRECTORY to the list of directories. Source files are 4722 searched relative to this list of directories. The resulting `.po' 4723 file will be written relative to the current directory, though. 4724 4725 4726 If INPUTFILE is `-', standard input is read. 4727 47289.1.2 Output file location 4729-------------------------- 4730 4731`-o FILE' 4732`--output-file=FILE' 4733 Write output to specified file. 4734 4735 4736 The results are written to standard output if no output file is 4737specified or if it is `-'. 4738 47399.1.3 Message selection 4740----------------------- 4741 4742`-< NUMBER' 4743`--less-than=NUMBER' 4744 Print messages with less than NUMBER definitions, defaults to 4745 infinite if not set. 4746 4747`-> NUMBER' 4748`--more-than=NUMBER' 4749 Print messages with more than NUMBER definitions, defaults to 0 if 4750 not set. 4751 4752`-u' 4753`--unique' 4754 Shorthand for `--less-than=2'. Requests that only unique messages 4755 be printed. 4756 4757 47589.1.4 Input file syntax 4759----------------------- 4760 4761`-P' 4762`--properties-input' 4763 Assume the input files are Java ResourceBundles in Java 4764 `.properties' syntax, not in PO file syntax. 4765 4766`--stringtable-input' 4767 Assume the input files are NeXTstep/GNUstep localized resource 4768 files in `.strings' syntax, not in PO file syntax. 4769 4770 47719.1.5 Output details 4772-------------------- 4773 4774`-t' 4775`--to-code=NAME' 4776 Specify encoding for output. 4777 4778`--use-first' 4779 Use first available translation for each message. Don't merge 4780 several translations into one. 4781 4782`--color' 4783`--color=WHEN' 4784 Specify whether or when to use colors and other text attributes. 4785 See *note The --color option:: for details. 4786 4787`--style=STYLE_FILE' 4788 Specify the CSS style rule file to use for `--color'. See *note 4789 The --style option:: for details. 4790 4791`--force-po' 4792 Always write an output file even if it contains no message. 4793 4794`-i' 4795`--indent' 4796 Write the .po file using indented style. 4797 4798`--no-location' 4799 Do not write `#: FILENAME:LINE' lines. 4800 4801`-n' 4802`--add-location' 4803 Generate `#: FILENAME:LINE' lines (default). 4804 4805`--strict' 4806 Write out a strict Uniforum conforming PO file. Note that this 4807 Uniforum format should be avoided because it doesn't support the 4808 GNU extensions. 4809 4810`-p' 4811`--properties-output' 4812 Write out a Java ResourceBundle in Java `.properties' syntax. Note 4813 that this file format doesn't support plural forms and silently 4814 drops obsolete messages. 4815 4816`--stringtable-output' 4817 Write out a NeXTstep/GNUstep localized resource file in `.strings' 4818 syntax. Note that this file format doesn't support plural forms. 4819 4820`-w NUMBER' 4821`--width=NUMBER' 4822 Set the output page width. Long strings in the output files will 4823 be split across multiple lines in order to ensure that each line's 4824 width (= number of screen columns) is less or equal to the given 4825 NUMBER. 4826 4827`--no-wrap' 4828 Do not break long message lines. Message lines whose width 4829 exceeds the output page width will not be split into several 4830 lines. Only file reference lines which are wider than the output 4831 page width will be split. 4832 4833`-s' 4834`--sort-output' 4835 Generate sorted output. Note that using this option makes it much 4836 harder for the translator to understand each message's context. 4837 4838`-F' 4839`--sort-by-file' 4840 Sort output by file location. 4841 4842 48439.1.6 Informative output 4844------------------------ 4845 4846`-h' 4847`--help' 4848 Display this help and exit. 4849 4850`-V' 4851`--version' 4852 Output version information and exit. 4853 4854 4855 4856File: gettext.info, Node: msgconv Invocation, Next: msggrep Invocation, Prev: msgcat Invocation, Up: Manipulating 4857 48589.2 Invoking the `msgconv' Program 4859================================== 4860 4861 msgconv [OPTION] [INPUTFILE] 4862 4863 The `msgconv' program converts a translation catalog to a different 4864character encoding. 4865 48669.2.1 Input file location 4867------------------------- 4868 4869`INPUTFILE' 4870 Input PO file. 4871 4872`-D DIRECTORY' 4873`--directory=DIRECTORY' 4874 Add DIRECTORY to the list of directories. Source files are 4875 searched relative to this list of directories. The resulting `.po' 4876 file will be written relative to the current directory, though. 4877 4878 4879 If no INPUTFILE is given or if it is `-', standard input is read. 4880 48819.2.2 Output file location 4882-------------------------- 4883 4884`-o FILE' 4885`--output-file=FILE' 4886 Write output to specified file. 4887 4888 4889 The results are written to standard output if no output file is 4890specified or if it is `-'. 4891 48929.2.3 Conversion target 4893----------------------- 4894 4895`-t' 4896`--to-code=NAME' 4897 Specify encoding for output. 4898 4899 4900 The default encoding is the current locale's encoding. 4901 49029.2.4 Input file syntax 4903----------------------- 4904 4905`-P' 4906`--properties-input' 4907 Assume the input file is a Java ResourceBundle in Java 4908 `.properties' syntax, not in PO file syntax. 4909 4910`--stringtable-input' 4911 Assume the input file is a NeXTstep/GNUstep localized resource 4912 file in `.strings' syntax, not in PO file syntax. 4913 4914 49159.2.5 Output details 4916-------------------- 4917 4918`--force-po' 4919 Always write an output file even if it contains no message. 4920 4921`-i' 4922`--indent' 4923 Write the .po file using indented style. 4924 4925`--no-location' 4926 Do not write `#: FILENAME:LINE' lines. 4927 4928`--add-location' 4929 Generate `#: FILENAME:LINE' lines (default). 4930 4931`--strict' 4932 Write out a strict Uniforum conforming PO file. Note that this 4933 Uniforum format should be avoided because it doesn't support the 4934 GNU extensions. 4935 4936`-p' 4937`--properties-output' 4938 Write out a Java ResourceBundle in Java `.properties' syntax. Note 4939 that this file format doesn't support plural forms and silently 4940 drops obsolete messages. 4941 4942`--stringtable-output' 4943 Write out a NeXTstep/GNUstep localized resource file in `.strings' 4944 syntax. Note that this file format doesn't support plural forms. 4945 4946`-w NUMBER' 4947`--width=NUMBER' 4948 Set the output page width. Long strings in the output files will 4949 be split across multiple lines in order to ensure that each line's 4950 width (= number of screen columns) is less or equal to the given 4951 NUMBER. 4952 4953`--no-wrap' 4954 Do not break long message lines. Message lines whose width 4955 exceeds the output page width will not be split into several 4956 lines. Only file reference lines which are wider than the output 4957 page width will be split. 4958 4959`-s' 4960`--sort-output' 4961 Generate sorted output. Note that using this option makes it much 4962 harder for the translator to understand each message's context. 4963 4964`-F' 4965`--sort-by-file' 4966 Sort output by file location. 4967 4968 49699.2.6 Informative output 4970------------------------ 4971 4972`-h' 4973`--help' 4974 Display this help and exit. 4975 4976`-V' 4977`--version' 4978 Output version information and exit. 4979 4980 4981 4982File: gettext.info, Node: msggrep Invocation, Next: msgfilter Invocation, Prev: msgconv Invocation, Up: Manipulating 4983 49849.3 Invoking the `msggrep' Program 4985================================== 4986 4987 msggrep [OPTION] [INPUTFILE] 4988 4989 The `msggrep' program extracts all messages of a translation catalog 4990that match a given pattern or belong to some given source files. 4991 49929.3.1 Input file location 4993------------------------- 4994 4995`INPUTFILE' 4996 Input PO file. 4997 4998`-D DIRECTORY' 4999`--directory=DIRECTORY' 5000 Add DIRECTORY to the list of directories. Source files are 5001 searched relative to this list of directories. The resulting `.po' 5002 file will be written relative to the current directory, though. 5003 5004 5005 If no INPUTFILE is given or if it is `-', standard input is read. 5006 50079.3.2 Output file location 5008-------------------------- 5009 5010`-o FILE' 5011`--output-file=FILE' 5012 Write output to specified file. 5013 5014 5015 The results are written to standard output if no output file is 5016specified or if it is `-'. 5017 50189.3.3 Message selection 5019----------------------- 5020 5021 [-N SOURCEFILE]... [-M DOMAINNAME]... 5022 [-J MSGCTXT-PATTERN] [-K MSGID-PATTERN] [-T MSGSTR-PATTERN] 5023 [-C COMMENT-PATTERN] 5024 5025 A message is selected if 5026 * it comes from one of the specified source files, 5027 5028 * or if it comes from one of the specified domains, 5029 5030 * or if `-J' is given and its context (msgctxt) matches 5031 MSGCTXT-PATTERN, 5032 5033 * or if `-K' is given and its key (msgid or msgid_plural) matches 5034 MSGID-PATTERN, 5035 5036 * or if `-T' is given and its translation (msgstr) matches 5037 MSGSTR-PATTERN, 5038 5039 * or if `-C' is given and the translator's comment matches 5040 COMMENT-PATTERN. 5041 5042 When more than one selection criterion is specified, the set of 5043selected messages is the union of the selected messages of each 5044criterion. 5045 5046 MSGCTXT-PATTERN or MSGID-PATTERN or MSGSTR-PATTERN syntax: 5047 [-E | -F] [-e PATTERN | -f FILE]... 5048 PATTERNs are basic regular expressions by default, or extended 5049regular expressions if -E is given, or fixed strings if -F is given. 5050 5051`-N SOURCEFILE' 5052`--location=SOURCEFILE' 5053 Select messages extracted from SOURCEFILE. SOURCEFILE can be 5054 either a literal file name or a wildcard pattern. 5055 5056`-M DOMAINNAME' 5057`--domain=DOMAINNAME' 5058 Select messages belonging to domain DOMAINNAME. 5059 5060`-J' 5061`--msgctxt' 5062 Start of patterns for the msgctxt. 5063 5064`-K' 5065`--msgid' 5066 Start of patterns for the msgid. 5067 5068`-T' 5069`--msgstr' 5070 Start of patterns for the msgstr. 5071 5072`-C' 5073`--comment' 5074 Start of patterns for the translator's comment. 5075 5076`-X' 5077`--extracted-comment' 5078 Start of patterns for the extracted comments. 5079 5080`-E' 5081`--extended-regexp' 5082 Specify that PATTERN is an extended regular expression. 5083 5084`-F' 5085`--fixed-strings' 5086 Specify that PATTERN is a set of newline-separated strings. 5087 5088`-e PATTERN' 5089`--regexp=PATTERN' 5090 Use PATTERN as a regular expression. 5091 5092`-f FILE' 5093`--file=FILE' 5094 Obtain PATTERN from FILE. 5095 5096`-i' 5097`--ignore-case' 5098 Ignore case distinctions. 5099 5100`-v' 5101`--invert-match' 5102 Output only the messages that do not match any selection 5103 criterion, instead of the messages that match a selection 5104 criterion. 5105 5106 51079.3.4 Input file syntax 5108----------------------- 5109 5110`-P' 5111`--properties-input' 5112 Assume the input file is a Java ResourceBundle in Java 5113 `.properties' syntax, not in PO file syntax. 5114 5115`--stringtable-input' 5116 Assume the input file is a NeXTstep/GNUstep localized resource 5117 file in `.strings' syntax, not in PO file syntax. 5118 5119 51209.3.5 Output details 5121-------------------- 5122 5123`--force-po' 5124 Always write an output file even if it contains no message. 5125 5126`--indent' 5127 Write the .po file using indented style. 5128 5129`--no-location' 5130 Do not write `#: FILENAME:LINE' lines. 5131 5132`--add-location' 5133 Generate `#: FILENAME:LINE' lines (default). 5134 5135`--strict' 5136 Write out a strict Uniforum conforming PO file. Note that this 5137 Uniforum format should be avoided because it doesn't support the 5138 GNU extensions. 5139 5140`-p' 5141`--properties-output' 5142 Write out a Java ResourceBundle in Java `.properties' syntax. Note 5143 that this file format doesn't support plural forms and silently 5144 drops obsolete messages. 5145 5146`--stringtable-output' 5147 Write out a NeXTstep/GNUstep localized resource file in `.strings' 5148 syntax. Note that this file format doesn't support plural forms. 5149 5150`-w NUMBER' 5151`--width=NUMBER' 5152 Set the output page width. Long strings in the output files will 5153 be split across multiple lines in order to ensure that each line's 5154 width (= number of screen columns) is less or equal to the given 5155 NUMBER. 5156 5157`--no-wrap' 5158 Do not break long message lines. Message lines whose width 5159 exceeds the output page width will not be split into several 5160 lines. Only file reference lines which are wider than the output 5161 page width will be split. 5162 5163`--sort-output' 5164 Generate sorted output. Note that using this option makes it much 5165 harder for the translator to understand each message's context. 5166 5167`--sort-by-file' 5168 Sort output by file location. 5169 5170 51719.3.6 Informative output 5172------------------------ 5173 5174`-h' 5175`--help' 5176 Display this help and exit. 5177 5178`-V' 5179`--version' 5180 Output version information and exit. 5181 5182 51839.3.7 Examples 5184-------------- 5185 5186 To extract the messages that come from the source files 5187`gnulib-lib/error.c' and `gnulib-lib/getopt.c': 5188 5189 msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po 5190 5191 To extract the messages that contain the string "Please specify" in 5192the original string: 5193 5194 msggrep --msgid -F -e 'Please specify' input.po 5195 5196 To extract the messages that have a context specifier of either 5197"Menu>File" or "Menu>Edit" or a submenu of them: 5198 5199 msggrep --msgctxt -E -e '^Menu>(File|Edit)' input.po 5200 5201 To extract the messages whose translation contains one of the 5202strings in the file `wordlist.txt': 5203 5204 msggrep --msgstr -F -f wordlist.txt input.po 5205 5206 5207File: gettext.info, Node: msgfilter Invocation, Next: msguniq Invocation, Prev: msggrep Invocation, Up: Manipulating 5208 52099.4 Invoking the `msgfilter' Program 5210==================================== 5211 5212 msgfilter [OPTION] FILTER [FILTER-OPTION] 5213 5214 The `msgfilter' program applies a filter to all translations of a 5215translation catalog. 5216 52179.4.1 Input file location 5218------------------------- 5219 5220`-i INPUTFILE' 5221`--input=INPUTFILE' 5222 Input PO file. 5223 5224`-D DIRECTORY' 5225`--directory=DIRECTORY' 5226 Add DIRECTORY to the list of directories. Source files are 5227 searched relative to this list of directories. The resulting `.po' 5228 file will be written relative to the current directory, though. 5229 5230 5231 If no INPUTFILE is given or if it is `-', standard input is read. 5232 52339.4.2 Output file location 5234-------------------------- 5235 5236`-o FILE' 5237`--output-file=FILE' 5238 Write output to specified file. 5239 5240 5241 The results are written to standard output if no output file is 5242specified or if it is `-'. 5243 52449.4.3 The filter 5245---------------- 5246 5247 The FILTER can be any program that reads a translation from standard 5248input and writes a modified translation to standard output. A 5249frequently used filter is `sed'. A few particular built-in filters are 5250also recognized. 5251 5252 Note: If the filter is not a built-in filter, you have to care about 5253encodings: It is your responsibility to ensure that the FILTER can cope 5254with input encoded in the translation catalog's encoding. If the 5255FILTER wants input in a particular encoding, you can in a first step 5256convert the translation catalog to that encoding using the `msgconv' 5257program, before invoking `msgfilter'. If the FILTER wants input in the 5258locale's encoding, but you want to avoid the locale's encoding, then 5259you can first convert the translation catalog to UTF-8 using the 5260`msgconv' program and then make `msgfilter' work in an UTF-8 locale, by 5261using the `LC_ALL' environment variable. 5262 5263 Note: Most translations in a translation catalog don't end with a 5264newline character. For this reason, it is important that the FILTER 5265recognizes its last input line even if it ends without a newline, and 5266that it doesn't add an undesired trailing newline at the end. The `sed' 5267program on some platforms is known to ignore the last line of input if 5268it is not terminated with a newline. You can use GNU `sed' instead; it 5269does not have this limitation. 5270 52719.4.4 Useful FILTER-OPTIONs when the FILTER is `sed' 5272---------------------------------------------------- 5273 5274`-e SCRIPT' 5275`--expression=SCRIPT' 5276 Add SCRIPT to the commands to be executed. 5277 5278`-f SCRIPTFILE' 5279`--file=SCRIPTFILE' 5280 Add the contents of SCRIPTFILE to the commands to be executed. 5281 5282`-n' 5283`--quiet' 5284`--silent' 5285 Suppress automatic printing of pattern space. 5286 5287 52889.4.5 Built-in FILTERs 5289---------------------- 5290 5291 The filter `recode-sr-latin' is recognized as a built-in filter. 5292The command `recode-sr-latin' converts Serbian text, written in the 5293Cyrillic script, to the Latin script. The command `msgfilter 5294recode-sr-latin' applies this conversion to the translations of a PO 5295file. Thus, it can be used to convert an `sr.po' file to an 5296`sr@latin.po' file. 5297 5298 The use of built-in filters is not sensitive to the current locale's 5299encoding. Moreover, when used with a built-in filter, `msgfilter' can 5300automatically convert the message catalog to the UTF-8 encoding when 5301needed. 5302 53039.4.6 Input file syntax 5304----------------------- 5305 5306`-P' 5307`--properties-input' 5308 Assume the input file is a Java ResourceBundle in Java 5309 `.properties' syntax, not in PO file syntax. 5310 5311`--stringtable-input' 5312 Assume the input file is a NeXTstep/GNUstep localized resource 5313 file in `.strings' syntax, not in PO file syntax. 5314 5315 53169.4.7 Output details 5317-------------------- 5318 5319`--force-po' 5320 Always write an output file even if it contains no message. 5321 5322`--indent' 5323 Write the .po file using indented style. 5324 5325`--keep-header' 5326 Keep the header entry, i.e. the message with `msgid ""', 5327 unmodified, instead of filtering it. By default, the header entry 5328 is subject to filtering like any other message. 5329 5330`--no-location' 5331 Do not write `#: FILENAME:LINE' lines. 5332 5333`--add-location' 5334 Generate `#: FILENAME:LINE' lines (default). 5335 5336`--strict' 5337 Write out a strict Uniforum conforming PO file. Note that this 5338 Uniforum format should be avoided because it doesn't support the 5339 GNU extensions. 5340 5341`-p' 5342`--properties-output' 5343 Write out a Java ResourceBundle in Java `.properties' syntax. Note 5344 that this file format doesn't support plural forms and silently 5345 drops obsolete messages. 5346 5347`--stringtable-output' 5348 Write out a NeXTstep/GNUstep localized resource file in `.strings' 5349 syntax. Note that this file format doesn't support plural forms. 5350 5351`-w NUMBER' 5352`--width=NUMBER' 5353 Set the output page width. Long strings in the output files will 5354 be split across multiple lines in order to ensure that each line's 5355 width (= number of screen columns) is less or equal to the given 5356 NUMBER. 5357 5358`--no-wrap' 5359 Do not break long message lines. Message lines whose width 5360 exceeds the output page width will not be split into several 5361 lines. Only file reference lines which are wider than the output 5362 page width will be split. 5363 5364`-s' 5365`--sort-output' 5366 Generate sorted output. Note that using this option makes it much 5367 harder for the translator to understand each message's context. 5368 5369`-F' 5370`--sort-by-file' 5371 Sort output by file location. 5372 5373 53749.4.8 Informative output 5375------------------------ 5376 5377`-h' 5378`--help' 5379 Display this help and exit. 5380 5381`-V' 5382`--version' 5383 Output version information and exit. 5384 5385 53869.4.9 Examples 5387-------------- 5388 5389 To convert German translations to Swiss orthography (in an UTF-8 5390locale): 5391 5392 msgconv -t UTF-8 de.po | msgfilter sed -e 's/��/ss/g' 5393 5394 To convert Serbian translations in Cyrillic script to Latin script: 5395 5396 msgfilter recode-sr-latin sr.po 5397 5398 5399File: gettext.info, Node: msguniq Invocation, Next: msgcomm Invocation, Prev: msgfilter Invocation, Up: Manipulating 5400 54019.5 Invoking the `msguniq' Program 5402================================== 5403 5404 msguniq [OPTION] [INPUTFILE] 5405 5406 The `msguniq' program unifies duplicate translations in a translation 5407catalog. It finds duplicate translations of the same message ID. Such 5408duplicates are invalid input for other programs like `msgfmt', 5409`msgmerge' or `msgcat'. By default, duplicates are merged together. 5410When using the `--repeated' option, only duplicates are output, and all 5411other messages are discarded. Comments and extracted comments will be 5412cumulated, except that if `--use-first' is specified, they will be 5413taken from the first translation. File positions will be cumulated. 5414When using the `--unique' option, duplicates are discarded. 5415 54169.5.1 Input file location 5417------------------------- 5418 5419`INPUTFILE' 5420 Input PO file. 5421 5422`-D DIRECTORY' 5423`--directory=DIRECTORY' 5424 Add DIRECTORY to the list of directories. Source files are 5425 searched relative to this list of directories. The resulting `.po' 5426 file will be written relative to the current directory, though. 5427 5428 5429 If no INPUTFILE is given or if it is `-', standard input is read. 5430 54319.5.2 Output file location 5432-------------------------- 5433 5434`-o FILE' 5435`--output-file=FILE' 5436 Write output to specified file. 5437 5438 5439 The results are written to standard output if no output file is 5440specified or if it is `-'. 5441 54429.5.3 Message selection 5443----------------------- 5444 5445`-d' 5446`--repeated' 5447 Print only duplicates. 5448 5449`-u' 5450`--unique' 5451 Print only unique messages, discard duplicates. 5452 5453 54549.5.4 Input file syntax 5455----------------------- 5456 5457`-P' 5458`--properties-input' 5459 Assume the input file is a Java ResourceBundle in Java 5460 `.properties' syntax, not in PO file syntax. 5461 5462`--stringtable-input' 5463 Assume the input file is a NeXTstep/GNUstep localized resource 5464 file in `.strings' syntax, not in PO file syntax. 5465 5466 54679.5.5 Output details 5468-------------------- 5469 5470`-t' 5471`--to-code=NAME' 5472 Specify encoding for output. 5473 5474`--use-first' 5475 Use first available translation for each message. Don't merge 5476 several translations into one. 5477 5478`--force-po' 5479 Always write an output file even if it contains no message. 5480 5481`-i' 5482`--indent' 5483 Write the .po file using indented style. 5484 5485`--no-location' 5486 Do not write `#: FILENAME:LINE' lines. 5487 5488`-n' 5489`--add-location' 5490 Generate `#: FILENAME:LINE' lines (default). 5491 5492`--strict' 5493 Write out a strict Uniforum conforming PO file. Note that this 5494 Uniforum format should be avoided because it doesn't support the 5495 GNU extensions. 5496 5497`-p' 5498`--properties-output' 5499 Write out a Java ResourceBundle in Java `.properties' syntax. Note 5500 that this file format doesn't support plural forms and silently 5501 drops obsolete messages. 5502 5503`--stringtable-output' 5504 Write out a NeXTstep/GNUstep localized resource file in `.strings' 5505 syntax. Note that this file format doesn't support plural forms. 5506 5507`-w NUMBER' 5508`--width=NUMBER' 5509 Set the output page width. Long strings in the output files will 5510 be split across multiple lines in order to ensure that each line's 5511 width (= number of screen columns) is less or equal to the given 5512 NUMBER. 5513 5514`--no-wrap' 5515 Do not break long message lines. Message lines whose width 5516 exceeds the output page width will not be split into several 5517 lines. Only file reference lines which are wider than the output 5518 page width will be split. 5519 5520`-s' 5521`--sort-output' 5522 Generate sorted output. Note that using this option makes it much 5523 harder for the translator to understand each message's context. 5524 5525`-F' 5526`--sort-by-file' 5527 Sort output by file location. 5528 5529 55309.5.6 Informative output 5531------------------------ 5532 5533`-h' 5534`--help' 5535 Display this help and exit. 5536 5537`-V' 5538`--version' 5539 Output version information and exit. 5540 5541 5542 5543File: gettext.info, Node: msgcomm Invocation, Next: msgcmp Invocation, Prev: msguniq Invocation, Up: Manipulating 5544 55459.6 Invoking the `msgcomm' Program 5546================================== 5547 5548 msgcomm [OPTION] [INPUTFILE]... 5549 5550 The `msgcomm' program finds messages which are common to two or more 5551of the specified PO files. By using the `--more-than' option, greater 5552commonality may be requested before messages are printed. Conversely, 5553the `--less-than' option may be used to specify less commonality before 5554messages are printed (i.e. `--less-than=2' will only print the unique 5555messages). Translations, comments and extract comments will be 5556preserved, but only from the first PO file to define them. File 5557positions from all PO files will be cumulated. 5558 55599.6.1 Input file location 5560------------------------- 5561 5562`INPUTFILE ...' 5563 Input files. 5564 5565`-f FILE' 5566`--files-from=FILE' 5567 Read the names of the input files from FILE instead of getting 5568 them from the command line. 5569 5570`-D DIRECTORY' 5571`--directory=DIRECTORY' 5572 Add DIRECTORY to the list of directories. Source files are 5573 searched relative to this list of directories. The resulting `.po' 5574 file will be written relative to the current directory, though. 5575 5576 5577 If INPUTFILE is `-', standard input is read. 5578 55799.6.2 Output file location 5580-------------------------- 5581 5582`-o FILE' 5583`--output-file=FILE' 5584 Write output to specified file. 5585 5586 5587 The results are written to standard output if no output file is 5588specified or if it is `-'. 5589 55909.6.3 Message selection 5591----------------------- 5592 5593`-< NUMBER' 5594`--less-than=NUMBER' 5595 Print messages with less than NUMBER definitions, defaults to 5596 infinite if not set. 5597 5598`-> NUMBER' 5599`--more-than=NUMBER' 5600 Print messages with more than NUMBER definitions, defaults to 1 if 5601 not set. 5602 5603`-u' 5604`--unique' 5605 Shorthand for `--less-than=2'. Requests that only unique messages 5606 be printed. 5607 5608 56099.6.4 Input file syntax 5610----------------------- 5611 5612`-P' 5613`--properties-input' 5614 Assume the input files are Java ResourceBundles in Java 5615 `.properties' syntax, not in PO file syntax. 5616 5617`--stringtable-input' 5618 Assume the input files are NeXTstep/GNUstep localized resource 5619 files in `.strings' syntax, not in PO file syntax. 5620 5621 56229.6.5 Output details 5623-------------------- 5624 5625`--force-po' 5626 Always write an output file even if it contains no message. 5627 5628`-i' 5629`--indent' 5630 Write the .po file using indented style. 5631 5632`--no-location' 5633 Do not write `#: FILENAME:LINE' lines. 5634 5635`-n' 5636`--add-location' 5637 Generate `#: FILENAME:LINE' lines (default). 5638 5639`--strict' 5640 Write out a strict Uniforum conforming PO file. Note that this 5641 Uniforum format should be avoided because it doesn't support the 5642 GNU extensions. 5643 5644`-p' 5645`--properties-output' 5646 Write out a Java ResourceBundle in Java `.properties' syntax. Note 5647 that this file format doesn't support plural forms and silently 5648 drops obsolete messages. 5649 5650`--stringtable-output' 5651 Write out a NeXTstep/GNUstep localized resource file in `.strings' 5652 syntax. Note that this file format doesn't support plural forms. 5653 5654`-w NUMBER' 5655`--width=NUMBER' 5656 Set the output page width. Long strings in the output files will 5657 be split across multiple lines in order to ensure that each line's 5658 width (= number of screen columns) is less or equal to the given 5659 NUMBER. 5660 5661`--no-wrap' 5662 Do not break long message lines. Message lines whose width 5663 exceeds the output page width will not be split into several 5664 lines. Only file reference lines which are wider than the output 5665 page width will be split. 5666 5667`-s' 5668`--sort-output' 5669 Generate sorted output. Note that using this option makes it much 5670 harder for the translator to understand each message's context. 5671 5672`-F' 5673`--sort-by-file' 5674 Sort output by file location. 5675 5676`--omit-header' 5677 Don't write header with `msgid ""' entry. 5678 5679 56809.6.6 Informative output 5681------------------------ 5682 5683`-h' 5684`--help' 5685 Display this help and exit. 5686 5687`-V' 5688`--version' 5689 Output version information and exit. 5690 5691 5692 5693File: gettext.info, Node: msgcmp Invocation, Next: msgattrib Invocation, Prev: msgcomm Invocation, Up: Manipulating 5694 56959.7 Invoking the `msgcmp' Program 5696================================= 5697 5698 msgcmp [OPTION] DEF.po REF.pot 5699 5700 The `msgcmp' program compares two Uniforum style .po files to check 5701that both contain the same set of msgid strings. The DEF.po file is an 5702existing PO file with the translations. The REF.pot file is the last 5703created PO file, or a PO Template file (generally created by 5704`xgettext'). This is useful for checking that you have translated each 5705and every message in your program. Where an exact match cannot be 5706found, fuzzy matching is used to produce better diagnostics. 5707 57089.7.1 Input file location 5709------------------------- 5710 5711`DEF.po' 5712 Translations. 5713 5714`REF.pot' 5715 References to the sources. 5716 5717`-D DIRECTORY' 5718`--directory=DIRECTORY' 5719 Add DIRECTORY to the list of directories. Source files are 5720 searched relative to this list of directories. 5721 5722 57239.7.2 Operation modifiers 5724------------------------- 5725 5726`-m' 5727`--multi-domain' 5728 Apply REF.pot to each of the domains in DEF.po. 5729 5730`--use-fuzzy' 5731 Consider fuzzy messages in the DEF.po file like translated 5732 messages. Note that using this option is usually wrong, because 5733 fuzzy messages are exactly those which have not been validated by 5734 a human translator. 5735 5736`--use-untranslated' 5737 Consider untranslated messages in the DEF.po file like translated 5738 messages. Note that using this option is usually wrong. 5739 5740 57419.7.3 Input file syntax 5742----------------------- 5743 5744`-P' 5745`--properties-input' 5746 Assume the input files are Java ResourceBundles in Java 5747 `.properties' syntax, not in PO file syntax. 5748 5749`--stringtable-input' 5750 Assume the input files are NeXTstep/GNUstep localized resource 5751 files in `.strings' syntax, not in PO file syntax. 5752 5753 57549.7.4 Informative output 5755------------------------ 5756 5757`-h' 5758`--help' 5759 Display this help and exit. 5760 5761`-V' 5762`--version' 5763 Output version information and exit. 5764 5765 5766 5767File: gettext.info, Node: msgattrib Invocation, Next: msgen Invocation, Prev: msgcmp Invocation, Up: Manipulating 5768 57699.8 Invoking the `msgattrib' Program 5770==================================== 5771 5772 msgattrib [OPTION] [INPUTFILE] 5773 5774 The `msgattrib' program filters the messages of a translation catalog 5775according to their attributes, and manipulates the attributes. 5776 57779.8.1 Input file location 5778------------------------- 5779 5780`INPUTFILE' 5781 Input PO file. 5782 5783`-D DIRECTORY' 5784`--directory=DIRECTORY' 5785 Add DIRECTORY to the list of directories. Source files are 5786 searched relative to this list of directories. The resulting `.po' 5787 file will be written relative to the current directory, though. 5788 5789 5790 If no INPUTFILE is given or if it is `-', standard input is read. 5791 57929.8.2 Output file location 5793-------------------------- 5794 5795`-o FILE' 5796`--output-file=FILE' 5797 Write output to specified file. 5798 5799 5800 The results are written to standard output if no output file is 5801specified or if it is `-'. 5802 58039.8.3 Message selection 5804----------------------- 5805 5806`--translated' 5807 Keep translated messages, remove untranslated messages. 5808 5809`--untranslated' 5810 Keep untranslated messages, remove translated messages. 5811 5812`--no-fuzzy' 5813 Remove `fuzzy' marked messages. 5814 5815`--only-fuzzy' 5816 Keep `fuzzy' marked messages, remove all other messages. 5817 5818`--no-obsolete' 5819 Remove obsolete #~ messages. 5820 5821`--only-obsolete' 5822 Keep obsolete #~ messages, remove all other messages. 5823 5824 58259.8.4 Attribute manipulation 5826---------------------------- 5827 5828 Attributes are modified after the message selection/removal has been 5829performed. If the `--only-file' or `--ignore-file' option is 5830specified, the attribute modification is applied only to those messages 5831that are listed in the ONLY-FILE and not listed in the IGNORE-FILE. 5832 5833`--set-fuzzy' 5834 Set all messages `fuzzy'. 5835 5836`--clear-fuzzy' 5837 Set all messages non-`fuzzy'. 5838 5839`--set-obsolete' 5840 Set all messages obsolete. 5841 5842`--clear-obsolete' 5843 Set all messages non-obsolete. 5844 5845`--clear-previous' 5846 Remove the "previous msgid" (`#|') comments from all messages. 5847 5848`--only-file=FILE' 5849 Limit the attribute changes to entries that are listed in FILE. 5850 FILE should be a PO or POT file. 5851 5852`--ignore-file=FILE' 5853 Limit the attribute changes to entries that are not listed in FILE. 5854 FILE should be a PO or POT file. 5855 5856`--fuzzy' 5857 Synonym for `--only-fuzzy --clear-fuzzy': It keeps only the fuzzy 5858 messages and removes their `fuzzy' mark. 5859 5860`--obsolete' 5861 Synonym for `--only-obsolete --clear-obsolete': It keeps only the 5862 obsolete messages and makes them non-obsolete. 5863 5864 58659.8.5 Input file syntax 5866----------------------- 5867 5868`-P' 5869`--properties-input' 5870 Assume the input file is a Java ResourceBundle in Java 5871 `.properties' syntax, not in PO file syntax. 5872 5873`--stringtable-input' 5874 Assume the input file is a NeXTstep/GNUstep localized resource 5875 file in `.strings' syntax, not in PO file syntax. 5876 5877 58789.8.6 Output details 5879-------------------- 5880 5881`--force-po' 5882 Always write an output file even if it contains no message. 5883 5884`-i' 5885`--indent' 5886 Write the .po file using indented style. 5887 5888`--no-location' 5889 Do not write `#: FILENAME:LINE' lines. 5890 5891`-n' 5892`--add-location' 5893 Generate `#: FILENAME:LINE' lines (default). 5894 5895`--strict' 5896 Write out a strict Uniforum conforming PO file. Note that this 5897 Uniforum format should be avoided because it doesn't support the 5898 GNU extensions. 5899 5900`-p' 5901`--properties-output' 5902 Write out a Java ResourceBundle in Java `.properties' syntax. Note 5903 that this file format doesn't support plural forms and silently 5904 drops obsolete messages. 5905 5906`--stringtable-output' 5907 Write out a NeXTstep/GNUstep localized resource file in `.strings' 5908 syntax. Note that this file format doesn't support plural forms. 5909 5910`-w NUMBER' 5911`--width=NUMBER' 5912 Set the output page width. Long strings in the output files will 5913 be split across multiple lines in order to ensure that each line's 5914 width (= number of screen columns) is less or equal to the given 5915 NUMBER. 5916 5917`--no-wrap' 5918 Do not break long message lines. Message lines whose width 5919 exceeds the output page width will not be split into several 5920 lines. Only file reference lines which are wider than the output 5921 page width will be split. 5922 5923`-s' 5924`--sort-output' 5925 Generate sorted output. Note that using this option makes it much 5926 harder for the translator to understand each message's context. 5927 5928`-F' 5929`--sort-by-file' 5930 Sort output by file location. 5931 5932 59339.8.7 Informative output 5934------------------------ 5935 5936`-h' 5937`--help' 5938 Display this help and exit. 5939 5940`-V' 5941`--version' 5942 Output version information and exit. 5943 5944 5945 5946File: gettext.info, Node: msgen Invocation, Next: msgexec Invocation, Prev: msgattrib Invocation, Up: Manipulating 5947 59489.9 Invoking the `msgen' Program 5949================================ 5950 5951 msgen [OPTION] INPUTFILE 5952 5953 The `msgen' program creates an English translation catalog. The 5954input file is the last created English PO file, or a PO Template file 5955(generally created by xgettext). Untranslated entries are assigned a 5956translation that is identical to the msgid. 5957 5958 Note: `msginit --no-translator --locale=en' performs a very similar 5959task. The main difference is that `msginit' cares specially about the 5960header entry, whereas `msgen' doesn't. 5961 59629.9.1 Input file location 5963------------------------- 5964 5965`INPUTFILE' 5966 Input PO or POT file. 5967 5968`-D DIRECTORY' 5969`--directory=DIRECTORY' 5970 Add DIRECTORY to the list of directories. Source files are 5971 searched relative to this list of directories. The resulting `.po' 5972 file will be written relative to the current directory, though. 5973 5974 5975 If INPUTFILE is `-', standard input is read. 5976 59779.9.2 Output file location 5978-------------------------- 5979 5980`-o FILE' 5981`--output-file=FILE' 5982 Write output to specified file. 5983 5984 5985 The results are written to standard output if no output file is 5986specified or if it is `-'. 5987 59889.9.3 Input file syntax 5989----------------------- 5990 5991`-P' 5992`--properties-input' 5993 Assume the input file is a Java ResourceBundle in Java 5994 `.properties' syntax, not in PO file syntax. 5995 5996`--stringtable-input' 5997 Assume the input file is a NeXTstep/GNUstep localized resource 5998 file in `.strings' syntax, not in PO file syntax. 5999 6000 60019.9.4 Output details 6002-------------------- 6003 6004`--force-po' 6005 Always write an output file even if it contains no message. 6006 6007`-i' 6008`--indent' 6009 Write the .po file using indented style. 6010 6011`--no-location' 6012 Do not write `#: FILENAME:LINE' lines. 6013 6014`--add-location' 6015 Generate `#: FILENAME:LINE' lines (default). 6016 6017`--strict' 6018 Write out a strict Uniforum conforming PO file. Note that this 6019 Uniforum format should be avoided because it doesn't support the 6020 GNU extensions. 6021 6022`-p' 6023`--properties-output' 6024 Write out a Java ResourceBundle in Java `.properties' syntax. Note 6025 that this file format doesn't support plural forms and silently 6026 drops obsolete messages. 6027 6028`--stringtable-output' 6029 Write out a NeXTstep/GNUstep localized resource file in `.strings' 6030 syntax. Note that this file format doesn't support plural forms. 6031 6032`-w NUMBER' 6033`--width=NUMBER' 6034 Set the output page width. Long strings in the output files will 6035 be split across multiple lines in order to ensure that each line's 6036 width (= number of screen columns) is less or equal to the given 6037 NUMBER. 6038 6039`--no-wrap' 6040 Do not break long message lines. Message lines whose width 6041 exceeds the output page width will not be split into several 6042 lines. Only file reference lines which are wider than the output 6043 page width will be split. 6044 6045`-s' 6046`--sort-output' 6047 Generate sorted output. Note that using this option makes it much 6048 harder for the translator to understand each message's context. 6049 6050`-F' 6051`--sort-by-file' 6052 Sort output by file location. 6053 6054 60559.9.5 Informative output 6056------------------------ 6057 6058`-h' 6059`--help' 6060 Display this help and exit. 6061 6062`-V' 6063`--version' 6064 Output version information and exit. 6065 6066 6067 6068File: gettext.info, Node: msgexec Invocation, Next: Colorizing, Prev: msgen Invocation, Up: Manipulating 6069 60709.10 Invoking the `msgexec' Program 6071=================================== 6072 6073 msgexec [OPTION] COMMAND [COMMAND-OPTION] 6074 6075 The `msgexec' program applies a command to all translations of a 6076translation catalog. The COMMAND can be any program that reads a 6077translation from standard input. It is invoked once for each 6078translation. Its output becomes msgexec's output. `msgexec''s return 6079code is the maximum return code across all invocations. 6080 6081 A special builtin command called `0' outputs the translation, 6082followed by a null byte. The output of `msgexec 0' is suitable as 6083input for `xargs -0'. 6084 6085 During each COMMAND invocation, the environment variable 6086`MSGEXEC_MSGID' is bound to the message's msgid, and the environment 6087variable `MSGEXEC_LOCATION' is bound to the location in the PO file of 6088the message. If the message has a context, the environment variable 6089`MSGEXEC_MSGCTXT' is bound to the message's msgctxt, otherwise it is 6090unbound. 6091 6092 Note: It is your responsibility to ensure that the COMMAND can cope 6093with input encoded in the translation catalog's encoding. If the 6094COMMAND wants input in a particular encoding, you can in a first step 6095convert the translation catalog to that encoding using the `msgconv' 6096program, before invoking `msgexec'. If the COMMAND wants input in the 6097locale's encoding, but you want to avoid the locale's encoding, then 6098you can first convert the translation catalog to UTF-8 using the 6099`msgconv' program and then make `msgexec' work in an UTF-8 locale, by 6100using the `LC_ALL' environment variable. 6101 61029.10.1 Input file location 6103-------------------------- 6104 6105`-i INPUTFILE' 6106`--input=INPUTFILE' 6107 Input PO file. 6108 6109`-D DIRECTORY' 6110`--directory=DIRECTORY' 6111 Add DIRECTORY to the list of directories. Source files are 6112 searched relative to this list of directories. The resulting `.po' 6113 file will be written relative to the current directory, though. 6114 6115 6116 If no INPUTFILE is given or if it is `-', standard input is read. 6117 61189.10.2 Input file syntax 6119------------------------ 6120 6121`-P' 6122`--properties-input' 6123 Assume the input file is a Java ResourceBundle in Java 6124 `.properties' syntax, not in PO file syntax. 6125 6126`--stringtable-input' 6127 Assume the input file is a NeXTstep/GNUstep localized resource 6128 file in `.strings' syntax, not in PO file syntax. 6129 6130 61319.10.3 Informative output 6132------------------------- 6133 6134`-h' 6135`--help' 6136 Display this help and exit. 6137 6138`-V' 6139`--version' 6140 Output version information and exit. 6141 6142 6143 6144File: gettext.info, Node: Colorizing, Next: libgettextpo, Prev: msgexec Invocation, Up: Manipulating 6145 61469.11 Highlighting parts of PO files 6147=================================== 6148 6149 Translators are usually only interested in seeing the untranslated 6150and fuzzy messages of a PO file. Also, when a message is set fuzzy 6151because the msgid changed, they want to see the differences between the 6152previous msgid and the current one (especially if the msgid is long and 6153only few words in it have changed). Finally, it's always welcome to 6154highlight the different sections of a message in a PO file (comments, 6155msgid, msgstr, etc.). 6156 6157 Such highlighting is possible through the `msgcat' options `--color' 6158and `--style'. 6159 6160* Menu: 6161 6162* The --color option:: Triggering colorized output 6163* The TERM variable:: The environment variable `TERM' 6164* The --style option:: The `--style' option 6165* Style rules:: Style rules for PO files 6166* Customizing less:: Customizing `less' for viewing PO files 6167 6168 6169File: gettext.info, Node: The --color option, Next: The TERM variable, Up: Colorizing 6170 61719.11.1 The `--color' option 6172--------------------------- 6173 6174 The `--color=WHEN' option specifies under which conditions colorized 6175output should be generated. The WHEN part can be one of the following: 6176 6177`always' 6178`yes' 6179 The output will be colorized. 6180 6181`never' 6182`no' 6183 The output will not be colorized. 6184 6185`auto' 6186`tty' 6187 The output will be colorized if the output device is a tty, i.e. 6188 when the output goes directly to a text screen or terminal 6189 emulator window. 6190 6191`html' 6192 The output will be colorized and be in HTML format. 6193 6194`--color' is equivalent to `--color=yes'. The default is 6195`--color=auto'. 6196 6197 Thus, a command like `msgcat vi.po' will produce colorized output 6198when called by itself in a command window. Whereas in a pipe, such as 6199`msgcat vi.po | less -R', it will not produce colorized output. To get 6200colorized output in this situation nevertheless, use the command 6201`msgcat --color vi.po | less -R'. 6202 6203 The `--color=html' option will produce output that can be viewed in 6204a browser. This can be useful, for example, for Indic languages, 6205because the renderic of Indic scripts in browser is usually better than 6206in terminal emulators. 6207 6208 Note that the output produced with the `--color' option is _not_ a 6209valid PO file in itself. It contains additional terminal-specific 6210escape sequences or HTML tags. A PO file reader will give a syntax 6211error when confronted with such content. Except for the `--color=html' 6212case, you therefore normally don't need to save output produced with the 6213`--color' option in a file. 6214 6215 6216File: gettext.info, Node: The TERM variable, Next: The --style option, Prev: The --color option, Up: Colorizing 6217 62189.11.2 The environment variable `TERM' 6219-------------------------------------- 6220 6221 The environment variable `TERM' contains a identifier for the text 6222window's capabilities. You can get a detailed list of these 6223cababilities by using the `infocmp' command, using `man 5 terminfo' as a 6224reference. 6225 6226 When producing text with embedded color directives, `msgcat' looks 6227at the `TERM' variable. Text windows today typically support at least 62288 colors. Often, however, the text window supports 16 or more colors, 6229even though the `TERM' variable is set to a identifier denoting only 8 6230supported colors. It can be worth setting the `TERM' variable to a 6231different value in these cases: 6232 6233`xterm' 6234 `xterm' is in most cases built with support for 16 colors. It can 6235 also be built with support for 88 or 256 colors (but not both). 6236 You can try to set `TERM' to either `xterm-16color', 6237 `xterm-88color', or `xterm-256color'. 6238 6239`rxvt' 6240 `rxvt' is often built with support for 16 colors. You can try to 6241 set `TERM' to `rxvt-16color'. 6242 6243`konsole' 6244 `konsole' too is often built with support for 16 colors. You can 6245 try to set `TERM' to `konsole-16color' or `xterm-16color'. 6246 6247 After setting `TERM', you can verify it by invoking `msgcat 6248--color=test' and seeing whether the output looks like a reasonable 6249color map. 6250 6251 6252File: gettext.info, Node: The --style option, Next: Style rules, Prev: The TERM variable, Up: Colorizing 6253 62549.11.3 The `--style' option 6255--------------------------- 6256 6257 The `--style=STYLE_FILE' option specifies the style file to use when 6258colorizing. It has an effect only when the `--color' option is 6259effective. 6260 6261 If the `--style' option is not specified, the environment variable 6262`PO_STYLE' is considered. It is meant to point to the user's preferred 6263style for PO files. 6264 6265 The default style file is 6266`$prefix/share/gettext/styles/po-default.css', where `$prefix' is the 6267installation location. 6268 6269 A few style files are predefined: 6270`po-vim.css' 6271 This style imitates the look used by vim 7. 6272 6273`po-emacs-x.css' 6274 This style imitates the look used by GNU Emacs 21 and 22 in an X11 6275 window. 6276 6277`po-emacs-xterm.css' 6278`po-emacs-xterm16.css' 6279`po-emacs-xterm256.css' 6280 This style imitates the look used by GNU Emacs 22 in a terminal of 6281 type `xterm' (8 colors) or `xterm-16color' (16 colors) or 6282 `xterm-256color' (256 colors), respectively. 6283 6284You can use these styles without specifying a directory. They are 6285actually located in `$prefix/share/gettext/styles/', where `$prefix' is 6286the installation location. 6287 6288 You can also design your own styles. This is described in the next 6289section. 6290 6291 6292File: gettext.info, Node: Style rules, Next: Customizing less, Prev: The --style option, Up: Colorizing 6293 62949.11.4 Style rules for PO files 6295------------------------------- 6296 6297 The same style file can be used for styling of a PO file, for 6298terminal output and for HTML output. It is written in CSS (Cascading 6299Style Sheet) syntax. See `http://www.w3.org/TR/css2/cover.html' for a 6300formal definition of CSS. Many HTML authoring tutorials also contain 6301explanations of CSS. 6302 6303 In the case of HTML output, the style file is embedded in the HTML 6304output. In the case of text output, the style file is interpreted by 6305the `msgcat' program. This means, in particular, that when `@import' 6306is used with relative file names, the file names are 6307 6308 - relative to the resulting HTML file, in the case of HTML output, 6309 6310 - relative to the style sheet containing the `@import', in the case 6311 of text output. (Actually, `@import's are not yet supported in 6312 this case, due to a limitation in `libcroco'.) 6313 6314 CSS rules are built up from selectors and declarations. The 6315declarations specify graphical properties; the selectors specify 6316specify when they apply. 6317 6318 In PO files, the following simple selectors (based on "CSS classes", 6319see the CSS2 spec, section 5.8.3) are supported. 6320 6321 * Selectors that apply to entire messages: 6322 6323 `.header' 6324 This matches the header entry of a PO file. 6325 6326 `.translated' 6327 This matches a translated message. 6328 6329 `.untranslated' 6330 This matches an untranslated message (i.e. a message with 6331 empty translation). 6332 6333 `.fuzzy' 6334 This matches a fuzzy message (i.e. a message which has a 6335 translation that needs review by the translator). 6336 6337 `.obsolete' 6338 This matches an obsolete message (i.e. a message that was 6339 translated but is not needed by the current POT file any 6340 more). 6341 6342 * Selectors that apply to parts of a message in PO syntax. Recall 6343 the general structure of a message in PO syntax: 6344 6345 WHITE-SPACE 6346 # TRANSLATOR-COMMENTS 6347 #. EXTRACTED-COMMENTS 6348 #: REFERENCE... 6349 #, FLAG... 6350 #| msgid PREVIOUS-UNTRANSLATED-STRING 6351 msgid UNTRANSLATED-STRING 6352 msgstr TRANSLATED-STRING 6353 6354 `.comment' 6355 This matches all comments (translator comments, extracted 6356 comments, source file reference comments, flag comments, 6357 previous message comments, as well as the entire obsolete 6358 messages). 6359 6360 `.translator-comment' 6361 This matches the translator comments. 6362 6363 `.extracted-comment' 6364 This matches the extracted comments, i.e. the comments placed 6365 by the programmer at the attention of the translator. 6366 6367 `.reference-comment' 6368 This matches the source file reference comments (entire 6369 lines). 6370 6371 `.reference' 6372 This matches the individual source file references inside the 6373 source file reference comment lines. 6374 6375 `.flag-comment' 6376 This matches the flag comment lines (entire lines). 6377 6378 `.flag' 6379 This matches the individual flags inside flag comment lines. 6380 6381 `.fuzzy-flag' 6382 This matches the `fuzzy' flag inside flag comment lines. 6383 6384 `.previous-comment' 6385 This matches the comments containing the previous 6386 untranslated string (entire lines). 6387 6388 `.previous' 6389 This matches the previous untranslated string including the 6390 string delimiters, the associated keywords (`msgid' etc.) and 6391 the spaces between them. 6392 6393 `.msgid' 6394 This matches the untranslated string including the string 6395 delimiters, the associated keywords (`msgid' etc.) and the 6396 spaces between them. 6397 6398 `.msgstr' 6399 This matches the translated string including the string 6400 delimiters, the associated keywords (`msgstr' etc.) and the 6401 spaces between them. 6402 6403 `.keyword' 6404 This matches the keywords (`msgid', `msgstr', etc.). 6405 6406 `.string' 6407 This matches strings, including the string delimiters (double 6408 quotes). 6409 6410 * Selectors that apply to parts of strings: 6411 6412 `.text' 6413 This matches the entire contents of a string (excluding the 6414 string delimiters, i.e. the double quotes). 6415 6416 `.escape-sequence' 6417 This matches an escape sequence (starting with a backslash). 6418 6419 `.format-directive' 6420 This matches a format string directive (starting with a `%' 6421 sign in the case of most programming languages, with a `{' in 6422 the case of `java-format' and `csharp-format', with a `~' in 6423 the case of `lisp-format' and `scheme-format', or with `$' in 6424 the case of `sh-format'). 6425 6426 `.invalid-format-directive' 6427 This matches an invalid format string directive. 6428 6429 `.added' 6430 In an untranslated string, this matches a part of the string 6431 that was not present in the previous untranslated string. 6432 (Not yet implemented in this release.) 6433 6434 `.changed' 6435 In an untranslated string or in a previous untranslated 6436 string, this matches a part of the string that is changed or 6437 replaced. (Not yet implemented in this release.) 6438 6439 `.removed' 6440 In a previous untranslated string, this matches a part of the 6441 string that is not present in the current untranslated 6442 string. (Not yet implemented in this release.) 6443 6444 These selectors can be combined to hierarchical selectors. For 6445example, 6446 6447 .msgstr .invalid-format-directive { color: red; } 6448 6449will highlight the invalid format directives in the translated strings. 6450 6451 In text mode, pseudo-classes (CSS2 spec, section 5.11) and 6452pseudo-elements (CSS2 spec, section 5.12) are not supported. 6453 6454 The declarations in HTML mode are not limited; any graphical 6455attribute supported by the browsers can be used. 6456 6457 The declarations in text mode are limited to the following 6458properties. Other properties will be silently ignored. 6459 6460`color' (CSS2 spec, section 14.1) 6461`background-color' (CSS2 spec, section 14.2.1) 6462 These properties is supported. Colors will be adjusted to match 6463 the terminal's capabilities. Note that many terminals support 6464 only 8 colors. 6465 6466`font-weight' (CSS2 spec, section 15.2.3) 6467 This property is supported, but most terminals can only render two 6468 different weights: `normal' and `bold'. Values >= 600 are 6469 rendered as `bold'. 6470 6471`font-style' (CSS2 spec, section 15.2.3) 6472 This property is supported. The values `italic' and `oblique' are 6473 rendered the same way. 6474 6475`text-decoration' (CSS2 spec, section 16.3.1) 6476 This property is supported, limited to the values `none' and 6477 `underline'. 6478 6479 6480File: gettext.info, Node: Customizing less, Prev: Style rules, Up: Colorizing 6481 64829.11.5 Customizing `less' for viewing PO files 6483---------------------------------------------- 6484 6485 The `less' program is a popular text file browser for use in a text 6486screen or terminal emulator. It also supports text with embedded escape 6487sequences for colors and text decorations. 6488 6489 You can use `less' to view a PO file like this (assuming an UTF-8 6490environment): 6491 6492 msgcat --to-code=UTF-8 --color xyz.po | less -R 6493 6494 You can simplify this to this simple command: 6495 6496 less xyz.po 6497 6498after these three preparations: 6499 6500 1. Add the options `-R' and `-f' to the `LESS' environment variable. 6501 In sh shells: 6502 $ LESS="$LESS -R -f" 6503 $ export LESS 6504 6505 2. If your system does not already have the `lessopen.sh' and 6506 `lessclose.sh' scripts, create them and set the `LESSOPEN' and 6507 `LESSCLOSE' environment variables, as indicated in the manual page 6508 (`man less'). 6509 6510 3. Add to `lessopen.sh' a piece of script that recognizes PO files 6511 through their file extension and invokes `msgcat' on them, 6512 producing a temporary file. Like this: 6513 6514 case "$1" in 6515 *.po) 6516 tmpfile=`mktemp "${TMPDIR-/tmp}/less.XXXXXX"` 6517 msgcat --to-code=UTF-8 --color "$1" > "$tmpfile" 6518 echo "$tmpfile" 6519 exit 0 6520 ;; 6521 esac 6522 6523 6524File: gettext.info, Node: libgettextpo, Prev: Colorizing, Up: Manipulating 6525 65269.12 Writing your own programs that process PO files 6527==================================================== 6528 6529 For the tasks for which a combination of `msgattrib', `msgcat' etc. 6530is not sufficient, a set of C functions is provided in a library, to 6531make it possible to process PO files in your own programs. When you 6532use this library, you don't need to write routines to parse the PO 6533file; instead, you retrieve a pointer in memory to each of messages 6534contained in the PO file. Functions for writing PO files are not 6535provided at this time. 6536 6537 The functions are declared in the header file `<gettext-po.h>', and 6538are defined in a library called `libgettextpo'. 6539 6540 -- Data Type: po_file_t 6541 This is a pointer type that refers to the contents of a PO file, 6542 after it has been read into memory. 6543 6544 -- Data Type: po_message_iterator_t 6545 This is a pointer type that refers to an iterator that produces a 6546 sequence of messages. 6547 6548 -- Data Type: po_message_t 6549 This is a pointer type that refers to a message of a PO file, 6550 including its translation. 6551 6552 -- Function: po_file_t po_file_read (const char *FILENAME) 6553 The `po_file_read' function reads a PO file into memory. The file 6554 name is given as argument. The return value is a handle to the PO 6555 file's contents, valid until `po_file_free' is called on it. In 6556 case of error, the return value is `NULL', and `errno' is set. 6557 6558 -- Function: void po_file_free (po_file_t FILE) 6559 The `po_file_free' function frees a PO file's contents from memory, 6560 including all messages that are only implicitly accessible through 6561 iterators. 6562 6563 -- Function: const char * const * po_file_domains (po_file_t FILE) 6564 The `po_file_domains' function returns the domains for which the 6565 given PO file has messages. The return value is a `NULL' 6566 terminated array which is valid as long as the FILE handle is 6567 valid. For PO files which contain no `domain' directive, the 6568 return value contains only one domain, namely the default domain 6569 `"messages"'. 6570 6571 -- Function: po_message_iterator_t po_message_iterator (po_file_t 6572 FILE, const char *DOMAIN) 6573 The `po_message_iterator' returns an iterator that will produce the 6574 messages of FILE that belong to the given DOMAIN. If DOMAIN is 6575 `NULL', the default domain is used instead. To list the messages, 6576 use the function `po_next_message' repeatedly. 6577 6578 -- Function: void po_message_iterator_free (po_message_iterator_t 6579 ITERATOR) 6580 The `po_message_iterator_free' function frees an iterator 6581 previously allocated through the `po_message_iterator' function. 6582 6583 -- Function: po_message_t po_next_message (po_message_iterator_t 6584 ITERATOR) 6585 The `po_next_message' function returns the next message from 6586 ITERATOR and advances the iterator. It returns `NULL' when the 6587 iterator has reached the end of its message list. 6588 6589 The following functions returns details of a `po_message_t'. Recall 6590that the results are valid as long as the FILE handle is valid. 6591 6592 -- Function: const char * po_message_msgid (po_message_t MESSAGE) 6593 The `po_message_msgid' function returns the `msgid' (untranslated 6594 English string) of a message. This is guaranteed to be non-`NULL'. 6595 6596 -- Function: const char * po_message_msgid_plural (po_message_t 6597 MESSAGE) 6598 The `po_message_msgid_plural' function returns the `msgid_plural' 6599 (untranslated English plural string) of a message with plurals, or 6600 `NULL' for a message without plural. 6601 6602 -- Function: const char * po_message_msgstr (po_message_t MESSAGE) 6603 The `po_message_msgstr' function returns the `msgstr' (translation) 6604 of a message. For an untranslated message, the return value is an 6605 empty string. 6606 6607 -- Function: const char * po_message_msgstr_plural (po_message_t 6608 MESSAGE, int INDEX) 6609 The `po_message_msgstr_plural' function returns the 6610 `msgstr[INDEX]' of a message with plurals, or `NULL' when the 6611 INDEX is out of range or for a message without plural. 6612 6613 Here is an example code how these functions can be used. 6614 6615 const char *filename = ...; 6616 po_file_t file = po_file_read (filename); 6617 6618 if (file == NULL) 6619 error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename); 6620 { 6621 const char * const *domains = po_file_domains (file); 6622 const char * const *domainp; 6623 6624 for (domainp = domains; *domainp; domainp++) 6625 { 6626 const char *domain = *domainp; 6627 po_message_iterator_t iterator = po_message_iterator (file, domain); 6628 6629 for (;;) 6630 { 6631 po_message_t *message = po_next_message (iterator); 6632 6633 if (message == NULL) 6634 break; 6635 { 6636 const char *msgid = po_message_msgid (message); 6637 const char *msgstr = po_message_msgstr (message); 6638 6639 ... 6640 } 6641 } 6642 po_message_iterator_free (iterator); 6643 } 6644 } 6645 po_file_free (file); 6646 6647 6648File: gettext.info, Node: Binaries, Next: Programmers, Prev: Manipulating, Up: Top 6649 665010 Producing Binary MO Files 6651**************************** 6652 6653* Menu: 6654 6655* msgfmt Invocation:: Invoking the `msgfmt' Program 6656* msgunfmt Invocation:: Invoking the `msgunfmt' Program 6657* MO Files:: The Format of GNU MO Files 6658 6659 6660File: gettext.info, Node: msgfmt Invocation, Next: msgunfmt Invocation, Prev: Binaries, Up: Binaries 6661 666210.1 Invoking the `msgfmt' Program 6663================================== 6664 6665 msgfmt [OPTION] FILENAME.po ... 6666 6667 The `msgfmt' programs generates a binary message catalog from a 6668textual translation description. 6669 667010.1.1 Input file location 6671-------------------------- 6672 6673`FILENAME.po ...' 6674 6675`-D DIRECTORY' 6676`--directory=DIRECTORY' 6677 Add DIRECTORY to the list of directories. Source files are 6678 searched relative to this list of directories. The resulting `.po' 6679 file will be written relative to the current directory, though. 6680 6681 6682 If an input file is `-', standard input is read. 6683 668410.1.2 Operation mode 6685--------------------- 6686 6687`-j' 6688`--java' 6689 Java mode: generate a Java `ResourceBundle' class. 6690 6691`--java2' 6692 Like -java, and assume Java2 (JDK 1.2 or higher). 6693 6694`--csharp' 6695 C# mode: generate a .NET .dll file containing a subclass of 6696 `GettextResourceSet'. 6697 6698`--csharp-resources' 6699 C# resources mode: generate a .NET `.resources' file. 6700 6701`--tcl' 6702 Tcl mode: generate a tcl/msgcat `.msg' file. 6703 6704`--qt' 6705 Qt mode: generate a Qt `.qm' file. 6706 6707 670810.1.3 Output file location 6709--------------------------- 6710 6711`-o FILE' 6712`--output-file=FILE' 6713 Write output to specified file. 6714 6715`--strict' 6716 Direct the program to work strictly following the Uniforum/Sun 6717 implementation. Currently this only affects the naming of the 6718 output file. If this option is not given the name of the output 6719 file is the same as the domain name. If the strict Uniforum mode 6720 is enabled the suffix `.mo' is added to the file name if it is not 6721 already present. 6722 6723 We find this behaviour of Sun's implementation rather silly and so 6724 by default this mode is _not_ selected. 6725 6726 6727 If the output FILE is `-', output is written to standard output. 6728 672910.1.4 Output file location in Java mode 6730---------------------------------------- 6731 6732`-r RESOURCE' 6733`--resource=RESOURCE' 6734 Specify the resource name. 6735 6736`-l LOCALE' 6737`--locale=LOCALE' 6738 Specify the locale name, either a language specification of the 6739 form LL or a combined language and country specification of the 6740 form LL_CC. 6741 6742`-d DIRECTORY' 6743 Specify the base directory of classes directory hierarchy. 6744 6745 6746 The class name is determined by appending the locale name to the 6747resource name, separated with an underscore. The `-d' option is 6748mandatory. The class is written under the specified directory. 6749 675010.1.5 Output file location in C# mode 6751-------------------------------------- 6752 6753`-r RESOURCE' 6754`--resource=RESOURCE' 6755 Specify the resource name. 6756 6757`-l LOCALE' 6758`--locale=LOCALE' 6759 Specify the locale name, either a language specification of the 6760 form LL or a combined language and country specification of the 6761 form LL_CC. 6762 6763`-d DIRECTORY' 6764 Specify the base directory for locale dependent `.dll' files. 6765 6766 6767 The `-l' and `-d' options are mandatory. The `.dll' file is written 6768in a subdirectory of the specified directory whose name depends on the 6769locale. 6770 677110.1.6 Output file location in Tcl mode 6772--------------------------------------- 6773 6774`-l LOCALE' 6775`--locale=LOCALE' 6776 Specify the locale name, either a language specification of the 6777 form LL or a combined language and country specification of the 6778 form LL_CC. 6779 6780`-d DIRECTORY' 6781 Specify the base directory of `.msg' message catalogs. 6782 6783 6784 The `-l' and `-d' options are mandatory. The `.msg' file is written 6785in the specified directory. 6786 678710.1.7 Input file syntax 6788------------------------ 6789 6790`-P' 6791`--properties-input' 6792 Assume the input files are Java ResourceBundles in Java 6793 `.properties' syntax, not in PO file syntax. 6794 6795`--stringtable-input' 6796 Assume the input files are NeXTstep/GNUstep localized resource 6797 files in `.strings' syntax, not in PO file syntax. 6798 6799 680010.1.8 Input file interpretation 6801-------------------------------- 6802 6803`-c' 6804`--check' 6805 Perform all the checks implied by `--check-format', 6806 `--check-header', `--check-domain'. 6807 6808`--check-format' 6809 Check language dependent format strings. 6810 6811 If the string represents a format string used in a `printf'-like 6812 function both strings should have the same number of `%' format 6813 specifiers, with matching types. If the flag `c-format' or 6814 `possible-c-format' appears in the special comment <#,> for this 6815 entry a check is performed. For example, the check will diagnose 6816 using `%.*s' against `%s', or `%d' against `%s', or `%d' against 6817 `%x'. It can even handle positional parameters. 6818 6819 Normally the `xgettext' program automatically decides whether a 6820 string is a format string or not. This algorithm is not perfect, 6821 though. It might regard a string as a format string though it is 6822 not used in a `printf'-like function and so `msgfmt' might report 6823 errors where there are none. 6824 6825 To solve this problem the programmer can dictate the decision to 6826 the `xgettext' program (*note c-format::). The translator should 6827 not consider removing the flag from the <#,> line. This "fix" 6828 would be reversed again as soon as `msgmerge' is called the next 6829 time. 6830 6831`--check-header' 6832 Verify presence and contents of the header entry. *Note Header 6833 Entry::, for a description of the various fields in the header 6834 entry. 6835 6836`--check-domain' 6837 Check for conflicts between domain directives and the 6838 `--output-file' option 6839 6840`-C' 6841`--check-compatibility' 6842 Check that GNU msgfmt behaves like X/Open msgfmt. This will give 6843 an error when attempting to use the GNU extensions. 6844 6845`--check-accelerators[=CHAR]' 6846 Check presence of keyboard accelerators for menu items. This is 6847 based on the convention used in some GUIs that a keyboard 6848 accelerator in a menu item string is designated by an immediately 6849 preceding `&' character. Sometimes a keyboard accelerator is also 6850 called "keyboard mnemonic". This check verifies that if the 6851 untranslated string has exactly one `&' character, the translated 6852 string has exactly one `&' as well. If this option is given with 6853 a CHAR argument, this CHAR should be a non-alphanumeric character 6854 and is used as keyboard accelerator mark instead of `&'. 6855 6856`-f' 6857`--use-fuzzy' 6858 Use fuzzy entries in output. Note that using this option is 6859 usually wrong, because fuzzy messages are exactly those which have 6860 not been validated by a human translator. 6861 6862 686310.1.9 Output details 6864--------------------- 6865 6866`-a NUMBER' 6867`--alignment=NUMBER' 6868 Align strings to NUMBER bytes (default: 1). 6869 6870`--no-hash' 6871 Don't include a hash table in the binary file. Lookup will be 6872 more expensive at run time (binary search instead of hash table 6873 lookup). 6874 6875 687610.1.10 Informative output 6877-------------------------- 6878 6879`-h' 6880`--help' 6881 Display this help and exit. 6882 6883`-V' 6884`--version' 6885 Output version information and exit. 6886 6887`--statistics' 6888 Print statistics about translations. 6889 6890`-v' 6891`--verbose' 6892 Increase verbosity level. 6893 6894 6895 6896File: gettext.info, Node: msgunfmt Invocation, Next: MO Files, Prev: msgfmt Invocation, Up: Binaries 6897 689810.2 Invoking the `msgunfmt' Program 6899==================================== 6900 6901 msgunfmt [OPTION] [FILE]... 6902 6903 The `msgunfmt' program converts a binary message catalog to a 6904Uniforum style .po file. 6905 690610.2.1 Operation mode 6907--------------------- 6908 6909`-j' 6910`--java' 6911 Java mode: input is a Java `ResourceBundle' class. 6912 6913`--csharp' 6914 C# mode: input is a .NET .dll file containing a subclass of 6915 `GettextResourceSet'. 6916 6917`--csharp-resources' 6918 C# resources mode: input is a .NET `.resources' file. 6919 6920`--tcl' 6921 Tcl mode: input is a tcl/msgcat `.msg' file. 6922 6923 692410.2.2 Input file location 6925-------------------------- 6926 6927`FILE ...' 6928 Input .mo files. 6929 6930 6931 If no input FILE is given or if it is `-', standard input is read. 6932 693310.2.3 Input file location in Java mode 6934--------------------------------------- 6935 6936`-r RESOURCE' 6937`--resource=RESOURCE' 6938 Specify the resource name. 6939 6940`-l LOCALE' 6941`--locale=LOCALE' 6942 Specify the locale name, either a language specification of the 6943 form LL or a combined language and country specification of the 6944 form LL_CC. 6945 6946 6947 The class name is determined by appending the locale name to the 6948resource name, separated with an underscore. The class is located 6949using the `CLASSPATH'. 6950 695110.2.4 Input file location in C# mode 6952------------------------------------- 6953 6954`-r RESOURCE' 6955`--resource=RESOURCE' 6956 Specify the resource name. 6957 6958`-l LOCALE' 6959`--locale=LOCALE' 6960 Specify the locale name, either a language specification of the 6961 form LL or a combined language and country specification of the 6962 form LL_CC. 6963 6964`-d DIRECTORY' 6965 Specify the base directory for locale dependent `.dll' files. 6966 6967 6968 The `-l' and `-d' options are mandatory. The `.msg' file is located 6969in a subdirectory of the specified directory whose name depends on the 6970locale. 6971 697210.2.5 Input file location in Tcl mode 6973-------------------------------------- 6974 6975`-l LOCALE' 6976`--locale=LOCALE' 6977 Specify the locale name, either a language specification of the 6978 form LL or a combined language and country specification of the 6979 form LL_CC. 6980 6981`-d DIRECTORY' 6982 Specify the base directory of `.msg' message catalogs. 6983 6984 6985 The `-l' and `-d' options are mandatory. The `.msg' file is located 6986in the specified directory. 6987 698810.2.6 Output file location 6989--------------------------- 6990 6991`-o FILE' 6992`--output-file=FILE' 6993 Write output to specified file. 6994 6995 6996 The results are written to standard output if no output file is 6997specified or if it is `-'. 6998 699910.2.7 Output details 7000--------------------- 7001 7002`--force-po' 7003 Always write an output file even if it contains no message. 7004 7005`-i' 7006`--indent' 7007 Write the .po file using indented style. 7008 7009`--strict' 7010 Write out a strict Uniforum conforming PO file. Note that this 7011 Uniforum format should be avoided because it doesn't support the 7012 GNU extensions. 7013 7014`-p' 7015`--properties-output' 7016 Write out a Java ResourceBundle in Java `.properties' syntax. Note 7017 that this file format doesn't support plural forms and silently 7018 drops obsolete messages. 7019 7020`--stringtable-output' 7021 Write out a NeXTstep/GNUstep localized resource file in `.strings' 7022 syntax. Note that this file format doesn't support plural forms. 7023 7024`-w NUMBER' 7025`--width=NUMBER' 7026 Set the output page width. Long strings in the output files will 7027 be split across multiple lines in order to ensure that each line's 7028 width (= number of screen columns) is less or equal to the given 7029 NUMBER. 7030 7031`--no-wrap' 7032 Do not break long message lines. Message lines whose width 7033 exceeds the output page width will not be split into several 7034 lines. Only file reference lines which are wider than the output 7035 page width will be split. 7036 7037`-s' 7038`--sort-output' 7039 Generate sorted output. Note that using this option makes it much 7040 harder for the translator to understand each message's context. 7041 7042 704310.2.8 Informative output 7044------------------------- 7045 7046`-h' 7047`--help' 7048 Display this help and exit. 7049 7050`-V' 7051`--version' 7052 Output version information and exit. 7053 7054`-v' 7055`--verbose' 7056 Increase verbosity level. 7057 7058 7059 7060File: gettext.info, Node: MO Files, Prev: msgunfmt Invocation, Up: Binaries 7061 706210.3 The Format of GNU MO Files 7063=============================== 7064 7065 The format of the generated MO files is best described by a picture, 7066which appears below. 7067 7068 The first two words serve the identification of the file. The magic 7069number will always signal GNU MO files. The number is stored in the 7070byte order of the generating machine, so the magic number really is two 7071numbers: `0x950412de' and `0xde120495'. The second word describes the 7072current revision of the file format. For now the revision is 0. This 7073might change in future versions, and ensures that the readers of MO 7074files can distinguish new formats from old ones, so that both can be 7075handled correctly. The version is kept separate from the magic number, 7076instead of using different magic numbers for different formats, mainly 7077because `/etc/magic' is not updated often. It might be better to have 7078magic separated from internal format version identification. 7079 7080 Follow a number of pointers to later tables in the file, allowing 7081for the extension of the prefix part of MO files without having to 7082recompile programs reading them. This might become useful for later 7083inserting a few flag bits, indication about the charset used, new 7084tables, or other things. 7085 7086 Then, at offset O and offset T in the picture, two tables of string 7087descriptors can be found. In both tables, each string descriptor uses 7088two 32 bits integers, one for the string length, another for the offset 7089of the string in the MO file, counting in bytes from the start of the 7090file. The first table contains descriptors for the original strings, 7091and is sorted so the original strings are in increasing lexicographical 7092order. The second table contains descriptors for the translated 7093strings, and is parallel to the first table: to find the corresponding 7094translation one has to access the array slot in the second array with 7095the same index. 7096 7097 Having the original strings sorted enables the use of simple binary 7098search, for when the MO file does not contain an hashing table, or for 7099when it is not practical to use the hashing table provided in the MO 7100file. This also has another advantage, as the empty string in a PO 7101file GNU `gettext' is usually _translated_ into some system information 7102attached to that particular MO file, and the empty string necessarily 7103becomes the first in both the original and translated tables, making 7104the system information very easy to find. 7105 7106 The size S of the hash table can be zero. In this case, the hash 7107table itself is not contained in the MO file. Some people might prefer 7108this because a precomputed hashing table takes disk space, and does not 7109win _that_ much speed. The hash table contains indices to the sorted 7110array of strings in the MO file. Conflict resolution is done by double 7111hashing. The precise hashing algorithm used is fairly dependent on GNU 7112`gettext' code, and is not documented here. 7113 7114 As for the strings themselves, they follow the hash file, and each 7115is terminated with a <NUL>, and this <NUL> is not counted in the length 7116which appears in the string descriptor. The `msgfmt' program has an 7117option selecting the alignment for MO file strings. With this option, 7118each string is separately aligned so it starts at an offset which is a 7119multiple of the alignment value. On some RISC machines, a correct 7120alignment will speed things up. 7121 7122 Contexts are stored by storing the concatenation of the context, a 7123<EOT> byte, and the original string, instead of the original string. 7124 7125 Plural forms are stored by letting the plural of the original string 7126follow the singular of the original string, separated through a <NUL> 7127byte. The length which appears in the string descriptor includes both. 7128However, only the singular of the original string takes part in the 7129hash table lookup. The plural variants of the translation are all 7130stored consecutively, separated through a <NUL> byte. Here also, the 7131length in the string descriptor includes all of them. 7132 7133 Nothing prevents a MO file from having embedded <NUL>s in strings. 7134However, the program interface currently used already presumes that 7135strings are <NUL> terminated, so embedded <NUL>s are somewhat useless. 7136But the MO file format is general enough so other interfaces would be 7137later possible, if for example, we ever want to implement wide 7138characters right in MO files, where <NUL> bytes may accidentally 7139appear. (No, we don't want to have wide characters in MO files. They 7140would make the file unnecessarily large, and the `wchar_t' type being 7141platform dependent, MO files would be platform dependent as well.) 7142 7143 This particular issue has been strongly debated in the GNU `gettext' 7144development forum, and it is expectable that MO file format will evolve 7145or change over time. It is even possible that many formats may later 7146be supported concurrently. But surely, we have to start somewhere, and 7147the MO file format described here is a good start. Nothing is cast in 7148concrete, and the format may later evolve fairly easily, so we should 7149feel comfortable with the current approach. 7150 7151 byte 7152 +------------------------------------------+ 7153 0 | magic number = 0x950412de | 7154 | | 7155 4 | file format revision = 0 | 7156 | | 7157 8 | number of strings | == N 7158 | | 7159 12 | offset of table with original strings | == O 7160 | | 7161 16 | offset of table with translation strings | == T 7162 | | 7163 20 | size of hashing table | == S 7164 | | 7165 24 | offset of hashing table | == H 7166 | | 7167 . . 7168 . (possibly more entries later) . 7169 . . 7170 | | 7171 O | length & offset 0th string ----------------. 7172 O + 8 | length & offset 1st string ------------------. 7173 ... ... | | 7174 O + ((N-1)*8)| length & offset (N-1)th string | | | 7175 | | | | 7176 T | length & offset 0th translation ---------------. 7177 T + 8 | length & offset 1st translation -----------------. 7178 ... ... | | | | 7179 T + ((N-1)*8)| length & offset (N-1)th translation | | | | | 7180 | | | | | | 7181 H | start hash table | | | | | 7182 ... ... | | | | 7183 H + S * 4 | end hash table | | | | | 7184 | | | | | | 7185 | NUL terminated 0th string <----------------' | | | 7186 | | | | | 7187 | NUL terminated 1st string <------------------' | | 7188 | | | | 7189 ... ... | | 7190 | | | | 7191 | NUL terminated 0th translation <---------------' | 7192 | | | 7193 | NUL terminated 1st translation <-----------------' 7194 | | 7195 ... ... 7196 | | 7197 +------------------------------------------+ 7198 7199 7200File: gettext.info, Node: Programmers, Next: Translators, Prev: Binaries, Up: Top 7201 720211 The Programmer's View 7203************************ 7204 7205 One aim of the current message catalog implementation provided by 7206GNU `gettext' was to use the system's message catalog handling, if the 7207installer wishes to do so. So we perhaps should first take a look at 7208the solutions we know about. The people in the POSIX committee did not 7209manage to agree on one of the semi-official standards which we'll 7210describe below. In fact they couldn't agree on anything, so they 7211decided only to include an example of an interface. The major Unix 7212vendors are split in the usage of the two most important 7213specifications: X/Open's catgets vs. Uniforum's gettext interface. 7214We'll describe them both and later explain our solution of this dilemma. 7215 7216* Menu: 7217 7218* catgets:: About `catgets' 7219* gettext:: About `gettext' 7220* Comparison:: Comparing the two interfaces 7221* Using libintl.a:: Using libintl.a in own programs 7222* gettext grok:: Being a `gettext' grok 7223* Temp Programmers:: Temporary Notes for the Programmers Chapter 7224 7225 7226File: gettext.info, Node: catgets, Next: gettext, Prev: Programmers, Up: Programmers 7227 722811.1 About `catgets' 7229==================== 7230 7231 The `catgets' implementation is defined in the X/Open Portability 7232Guide, Volume 3, XSI Supplementary Definitions, Chapter 5. But the 7233process of creating this standard seemed to be too slow for some of the 7234Unix vendors so they created their implementations on preliminary 7235versions of the standard. Of course this leads again to problems while 7236writing platform independent programs: even the usage of `catgets' does 7237not guarantee a unique interface. 7238 7239 Another, personal comment on this that only a bunch of committee 7240members could have made this interface. They never really tried to 7241program using this interface. It is a fast, memory-saving 7242implementation, an user can happily live with it. But programmers hate 7243it (at least I and some others do...) 7244 7245 But we must not forget one point: after all the trouble with 7246transferring the rights on Unix(tm) they at last came to X/Open, the 7247very same who published this specification. This leads me to making 7248the prediction that this interface will be in future Unix standards 7249(e.g. Spec1170) and therefore part of all Unix implementation 7250(implementations, which are _allowed_ to wear this name). 7251 7252* Menu: 7253 7254* Interface to catgets:: The interface 7255* Problems with catgets:: Problems with the `catgets' interface?! 7256 7257 7258File: gettext.info, Node: Interface to catgets, Next: Problems with catgets, Prev: catgets, Up: catgets 7259 726011.1.1 The Interface 7261-------------------- 7262 7263 The interface to the `catgets' implementation consists of three 7264functions which correspond to those used in file access: `catopen' to 7265open the catalog for using, `catgets' for accessing the message tables, 7266and `catclose' for closing after work is done. Prototypes for the 7267functions and the needed definitions are in the `<nl_types.h>' header 7268file. 7269 7270 `catopen' is used like in this: 7271 7272 nl_catd catd = catopen ("catalog_name", 0); 7273 7274 The function takes as the argument the name of the catalog. This 7275usual refers to the name of the program or the package. The second 7276parameter is not further specified in the standard. I don't even know 7277whether it is implemented consistently among various systems. So the 7278common advice is to use `0' as the value. The return value is a handle 7279to the message catalog, equivalent to handles to file returned by 7280`open'. 7281 7282 This handle is of course used in the `catgets' function which can be 7283used like this: 7284 7285 char *translation = catgets (catd, set_no, msg_id, "original string"); 7286 7287 The first parameter is this catalog descriptor. The second parameter 7288specifies the set of messages in this catalog, in which the message 7289described by `msg_id' is obtained. `catgets' therefore uses a 7290three-stage addressing: 7291 7292 catalog name => set number => message ID => translation 7293 7294 The fourth argument is not used to address the translation. It is 7295given as a default value in case when one of the addressing stages 7296fail. One important thing to remember is that although the return type 7297of catgets is `char *' the resulting string _must not_ be changed. It 7298should better be `const char *', but the standard is published in 1988, 7299one year before ANSI C. 7300 7301The last of these functions is used and behaves as expected: 7302 7303 catclose (catd); 7304 7305 After this no `catgets' call using the descriptor is legal anymore. 7306 7307 7308File: gettext.info, Node: Problems with catgets, Prev: Interface to catgets, Up: catgets 7309 731011.1.2 Problems with the `catgets' Interface?! 7311---------------------------------------------- 7312 7313 Now that this description seemed to be really easy -- where are the 7314problems we speak of? In fact the interface could be used in a 7315reasonable way, but constructing the message catalogs is a pain. The 7316reason for this lies in the third argument of `catgets': the unique 7317message ID. This has to be a numeric value for all messages in a single 7318set. Perhaps you could imagine the problems keeping such a list while 7319changing the source code. Add a new message here, remove one there. Of 7320course there have been developed a lot of tools helping to organize this 7321chaos but one as the other fails in one aspect or the other. We don't 7322want to say that the other approach has no problems but they are far 7323more easy to manage. 7324 7325 7326File: gettext.info, Node: gettext, Next: Comparison, Prev: catgets, Up: Programmers 7327 732811.2 About `gettext' 7329==================== 7330 7331 The definition of the `gettext' interface comes from a Uniforum 7332proposal. It was submitted there by Sun, who had implemented the 7333`gettext' function in SunOS 4, around 1990. Nowadays, the `gettext' 7334interface is specified by the OpenI18N standard. 7335 7336 The main point about this solution is that it does not follow the 7337method of normal file handling (open-use-close) and that it does not 7338burden the programmer with so many tasks, especially the unique key 7339handling. Of course here also a unique key is needed, but this key is 7340the message itself (how long or short it is). See *note Comparison:: 7341for a more detailed comparison of the two methods. 7342 7343 The following section contains a rather detailed description of the 7344interface. We make it that detailed because this is the interface we 7345chose for the GNU `gettext' Library. Programmers interested in using 7346this library will be interested in this description. 7347 7348* Menu: 7349 7350* Interface to gettext:: The interface 7351* Ambiguities:: Solving ambiguities 7352* Locating Catalogs:: Locating message catalog files 7353* Charset conversion:: How to request conversion to Unicode 7354* Contexts:: Solving ambiguities in GUI programs 7355* Plural forms:: Additional functions for handling plurals 7356* Optimized gettext:: Optimization of the *gettext functions 7357 7358 7359File: gettext.info, Node: Interface to gettext, Next: Ambiguities, Prev: gettext, Up: gettext 7360 736111.2.1 The Interface 7362-------------------- 7363 7364 The minimal functionality an interface must have is a) to select a 7365domain the strings are coming from (a single domain for all programs is 7366not reasonable because its construction and maintenance is difficult, 7367perhaps impossible) and b) to access a string in a selected domain. 7368 7369 This is principally the description of the `gettext' interface. It 7370has a global domain which unqualified usages reference. Of course this 7371domain is selectable by the user. 7372 7373 char *textdomain (const char *domain_name); 7374 7375 This provides the possibility to change or query the current status 7376of the current global domain of the `LC_MESSAGE' category. The 7377argument is a null-terminated string, whose characters must be legal in 7378the use in filenames. If the DOMAIN_NAME argument is `NULL', the 7379function returns the current value. If no value has been set before, 7380the name of the default domain is returned: _messages_. Please note 7381that although the return value of `textdomain' is of type `char *' no 7382changing is allowed. It is also important to know that no checks of 7383the availability are made. If the name is not available you will see 7384this by the fact that no translations are provided. 7385 7386To use a domain set by `textdomain' the function 7387 7388 char *gettext (const char *msgid); 7389 7390is to be used. This is the simplest reasonable form one can imagine. 7391The translation of the string MSGID is returned if it is available in 7392the current domain. If it is not available, the argument itself is 7393returned. If the argument is `NULL' the result is undefined. 7394 7395 One thing which should come into mind is that no explicit dependency 7396to the used domain is given. The current value of the domain is used. 7397If this changes between two executions of the same `gettext' call in 7398the program, both calls reference a different message catalog. 7399 7400 For the easiest case, which is normally used in internationalized 7401packages, once at the beginning of execution a call to `textdomain' is 7402issued, setting the domain to a unique name, normally the package name. 7403In the following code all strings which have to be translated are 7404filtered through the gettext function. That's all, the package speaks 7405your language. 7406 7407 7408File: gettext.info, Node: Ambiguities, Next: Locating Catalogs, Prev: Interface to gettext, Up: gettext 7409 741011.2.2 Solving Ambiguities 7411-------------------------- 7412 7413 While this single name domain works well for most applications there 7414might be the need to get translations from more than one domain. Of 7415course one could switch between different domains with calls to 7416`textdomain', but this is really not convenient nor is it fast. A 7417possible situation could be one case subject to discussion during this 7418writing: all error messages of functions in the set of common used 7419functions should go into a separate domain `error'. By this mean we 7420would only need to translate them once. Another case are messages from 7421a library, as these _have_ to be independent of the current domain set 7422by the application. 7423 7424For this reasons there are two more functions to retrieve strings: 7425 7426 char *dgettext (const char *domain_name, const char *msgid); 7427 char *dcgettext (const char *domain_name, const char *msgid, 7428 int category); 7429 7430 Both take an additional argument at the first place, which 7431corresponds to the argument of `textdomain'. The third argument of 7432`dcgettext' allows to use another locale category but `LC_MESSAGES'. 7433But I really don't know where this can be useful. If the DOMAIN_NAME 7434is `NULL' or CATEGORY has an value beside the known ones, the result is 7435undefined. It should also be noted that this function is not part of 7436the second known implementation of this function family, the one found 7437in Solaris. 7438 7439 A second ambiguity can arise by the fact, that perhaps more than one 7440domain has the same name. This can be solved by specifying where the 7441needed message catalog files can be found. 7442 7443 char *bindtextdomain (const char *domain_name, 7444 const char *dir_name); 7445 7446 Calling this function binds the given domain to a file in the 7447specified directory (how this file is determined follows below). 7448Especially a file in the systems default place is not favored against 7449the specified file anymore (as it would be by solely using 7450`textdomain'). A `NULL' pointer for the DIR_NAME parameter returns the 7451binding associated with DOMAIN_NAME. If DOMAIN_NAME itself is `NULL' 7452nothing happens and a `NULL' pointer is returned. Here again as for 7453all the other functions is true that none of the return value must be 7454changed! 7455 7456 It is important to remember that relative path names for the 7457DIR_NAME parameter can be trouble. Since the path is always computed 7458relative to the current directory different results will be achieved 7459when the program executes a `chdir' command. Relative paths should 7460always be avoided to avoid dependencies and unreliabilities. 7461 7462 7463File: gettext.info, Node: Locating Catalogs, Next: Charset conversion, Prev: Ambiguities, Up: gettext 7464 746511.2.3 Locating Message Catalog Files 7466------------------------------------- 7467 7468 Because many different languages for many different packages have to 7469be stored we need some way to add these information to file message 7470catalog files. The way usually used in Unix environments is have this 7471encoding in the file name. This is also done here. The directory name 7472given in `bindtextdomain's second argument (or the default directory), 7473followed by the name of the locale, the locale category, and the domain 7474name are concatenated: 7475 7476 DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo 7477 7478 The default value for DIR_NAME is system specific. For the GNU 7479library, and for packages adhering to its conventions, it's: 7480 /usr/local/share/locale 7481 7482LOCALE is the name of the locale category which is designated by 7483`LC_CATEGORY'. For `gettext' and `dgettext' this `LC_CATEGORY' is 7484always `LC_MESSAGES'.(1) The name of the locale category is determined 7485through `setlocale (LC_CATEGORY, NULL)'. (2) When using the function 7486`dcgettext', you can specify the locale category through the third 7487argument. 7488 7489 ---------- Footnotes ---------- 7490 7491 (1) Some system, e.g. mingw, don't have `LC_MESSAGES'. Here we use 7492a more or less arbitrary value for it, namely 1729, the smallest 7493positive integer which can be represented in two different ways as the 7494sum of two cubes. 7495 7496 (2) When the system does not support `setlocale' its behavior in 7497setting the locale values is simulated by looking at the environment 7498variables. 7499 7500 7501File: gettext.info, Node: Charset conversion, Next: Contexts, Prev: Locating Catalogs, Up: gettext 7502 750311.2.4 How to specify the output character set `gettext' uses 7504------------------------------------------------------------- 7505 7506 `gettext' not only looks up a translation in a message catalog. It 7507also converts the translation on the fly to the desired output character 7508set. This is useful if the user is working in a different character set 7509than the translator who created the message catalog, because it avoids 7510distributing variants of message catalogs which differ only in the 7511character set. 7512 7513 The output character set is, by default, the value of `nl_langinfo 7514(CODESET)', which depends on the `LC_CTYPE' part of the current locale. 7515But programs which store strings in a locale independent way (e.g. 7516UTF-8) can request that `gettext' and related functions return the 7517translations in that encoding, by use of the `bind_textdomain_codeset' 7518function. 7519 7520 Note that the MSGID argument to `gettext' is not subject to 7521character set conversion. Also, when `gettext' does not find a 7522translation for MSGID, it returns MSGID unchanged - independently of 7523the current output character set. It is therefore recommended that all 7524MSGIDs be US-ASCII strings. 7525 7526 -- Function: char * bind_textdomain_codeset (const char *DOMAINNAME, 7527 const char *CODESET) 7528 The `bind_textdomain_codeset' function can be used to specify the 7529 output character set for message catalogs for domain DOMAINNAME. 7530 The CODESET argument must be a valid codeset name which can be used 7531 for the `iconv_open' function, or a null pointer. 7532 7533 If the CODESET parameter is the null pointer, 7534 `bind_textdomain_codeset' returns the currently selected codeset 7535 for the domain with the name DOMAINNAME. It returns `NULL' if no 7536 codeset has yet been selected. 7537 7538 The `bind_textdomain_codeset' function can be used several times. 7539 If used multiple times with the same DOMAINNAME argument, the 7540 later call overrides the settings made by the earlier one. 7541 7542 The `bind_textdomain_codeset' function returns a pointer to a 7543 string containing the name of the selected codeset. The string is 7544 allocated internally in the function and must not be changed by the 7545 user. If the system went out of core during the execution of 7546 `bind_textdomain_codeset', the return value is `NULL' and the 7547 global variable ERRNO is set accordingly. 7548 7549 7550File: gettext.info, Node: Contexts, Next: Plural forms, Prev: Charset conversion, Up: gettext 7551 755211.2.5 Using contexts for solving ambiguities 7553--------------------------------------------- 7554 7555 One place where the `gettext' functions, if used normally, have big 7556problems is within programs with graphical user interfaces (GUIs). The 7557problem is that many of the strings which have to be translated are very 7558short. They have to appear in pull-down menus which restricts the 7559length. But strings which are not containing entire sentences or at 7560least large fragments of a sentence may appear in more than one 7561situation in the program but might have different translations. This is 7562especially true for the one-word strings which are frequently used in 7563GUI programs. 7564 7565 As a consequence many people say that the `gettext' approach is 7566wrong and instead `catgets' should be used which indeed does not have 7567this problem. But there is a very simple and powerful method to handle 7568this kind of problems with the `gettext' functions. 7569 7570 Contexts can be added to strings to be translated. A context 7571dependent translation lookup is when a translation for a given string 7572is searched, that is limited to a given context. The translation for 7573the same string in a different context can be different. The different 7574translations of the same string in different contexts can be stored in 7575the in the same MO file, and can be edited by the translator in the 7576same PO file. 7577 7578 The `gettext.h' include file contains the lookup macros for strings 7579with contexts. They are implemented as thin macros and inline functions 7580over the functions from `<libintl.h>'. 7581 7582 const char *pgettext (const char *msgctxt, const char *msgid); 7583 7584 In a call of this macro, MSGCTXT and MSGID must be string literals. 7585The macro returns the translation of MSGID, restricted to the context 7586given by MSGCTXT. 7587 7588 The MSGCTXT string is visible in the PO file to the translator. You 7589should try to make it somehow canonical and never changing. Because 7590every time you change an MSGCTXT, the translator will have to review 7591the translation of MSGID. 7592 7593 Finding a canonical MSGCTXT string that doesn't change over time can 7594be hard. But you shouldn't use the file name or class name containing 7595the `pgettext' call - because it is a common development task to rename 7596a file or a class, and it shouldn't cause translator work. Also you 7597shouldn't use a comment in the form of a complete English sentence as 7598MSGCTXT - because orthography or grammar changes are often applied to 7599such sentences, and again, it shouldn't force the translator to do a 7600review. 7601 7602 The `p' in `pgettext' stands for "particular": `pgettext' fetches a 7603particular translation of the MSGID. 7604 7605 const char *dpgettext (const char *domain_name, 7606 const char *msgctxt, const char *msgid); 7607 const char *dcpgettext (const char *domain_name, 7608 const char *msgctxt, const char *msgid, 7609 int category); 7610 7611 These are generalizations of `pgettext'. They behave similarly to 7612`dgettext' and `dcgettext', respectively. The DOMAIN_NAME argument 7613defines the translation domain. The CATEGORY argument allows to use 7614another locale category than `LC_MESSAGES'. 7615 7616 As as example consider the following fictional situation. A GUI 7617program has a menu bar with the following entries: 7618 7619 +------------+------------+--------------------------------------+ 7620 | File | Printer | | 7621 +------------+------------+--------------------------------------+ 7622 | Open | | Select | 7623 | New | | Open | 7624 +----------+ | Connect | 7625 +----------+ 7626 7627 To have the strings `File', `Printer', `Open', `New', `Select', and 7628`Connect' translated there has to be at some point in the code a call 7629to a function of the `gettext' family. But in two places the string 7630passed into the function would be `Open'. The translations might not 7631be the same and therefore we are in the dilemma described above. 7632 7633 What distinguishes the two places is the menu path from the menu 7634root to the particular menu entries: 7635 7636 Menu|File 7637 Menu|Printer 7638 Menu|File|Open 7639 Menu|File|New 7640 Menu|Printer|Select 7641 Menu|Printer|Open 7642 Menu|Printer|Connect 7643 7644 The context is thus the menu path without its last part. So, the 7645calls look like this: 7646 7647 pgettext ("Menu|", "File") 7648 pgettext ("Menu|", "Printer") 7649 pgettext ("Menu|File|", "Open") 7650 pgettext ("Menu|File|", "New") 7651 pgettext ("Menu|Printer|", "Select") 7652 pgettext ("Menu|Printer|", "Open") 7653 pgettext ("Menu|Printer|", "Connect") 7654 7655 Whether or not to use the `|' character at the end of the context is 7656a matter of style. 7657 7658 For more complex cases, where the MSGCTXT or MSGID are not string 7659literals, more general macros are available: 7660 7661 const char *pgettext_expr (const char *msgctxt, const char *msgid); 7662 const char *dpgettext_expr (const char *domain_name, 7663 const char *msgctxt, const char *msgid); 7664 const char *dcpgettext_expr (const char *domain_name, 7665 const char *msgctxt, const char *msgid, 7666 int category); 7667 7668 Here MSGCTXT and MSGID can be arbitrary string-valued expressions. 7669These macros are more general. But in the case that both argument 7670expressions are string literals, the macros without the `_expr' suffix 7671are more efficient. 7672 7673 7674File: gettext.info, Node: Plural forms, Next: Optimized gettext, Prev: Contexts, Up: gettext 7675 767611.2.6 Additional functions for plural forms 7677-------------------------------------------- 7678 7679 The functions of the `gettext' family described so far (and all the 7680`catgets' functions as well) have one problem in the real world which 7681have been neglected completely in all existing approaches. What is 7682meant here is the handling of plural forms. 7683 7684 Looking through Unix source code before the time anybody thought 7685about internationalization (and, sadly, even afterwards) one can often 7686find code similar to the following: 7687 7688 printf ("%d file%s deleted", n, n == 1 ? "" : "s"); 7689 7690After the first complaints from people internationalizing the code 7691people either completely avoided formulations like this or used strings 7692like `"file(s)"'. Both look unnatural and should be avoided. First 7693tries to solve the problem correctly looked like this: 7694 7695 if (n == 1) 7696 printf ("%d file deleted", n); 7697 else 7698 printf ("%d files deleted", n); 7699 7700 But this does not solve the problem. It helps languages where the 7701plural form of a noun is not simply constructed by adding an `s' but 7702that is all. Once again people fell into the trap of believing the 7703rules their language is using are universal. But the handling of plural 7704forms differs widely between the language families. For example, Rafal 7705Maszkowski `<rzm@mat.uni.torun.pl>' reports: 7706 7707 In Polish we use e.g. plik (file) this way: 7708 1 plik 7709 2,3,4 pliki 7710 5-21 pliko'w 7711 22-24 pliki 7712 25-31 pliko'w 7713 and so on (o' means 8859-2 oacute which should be rather okreska, 7714 similar to aogonek). 7715 7716 There are two things which can differ between languages (and even 7717inside language families); 7718 7719 * The form how plural forms are built differs. This is a problem 7720 with languages which have many irregularities. German, for 7721 instance, is a drastic case. Though English and German are part 7722 of the same language family (Germanic), the almost regular forming 7723 of plural noun forms (appending an `s') is hardly found in German. 7724 7725 * The number of plural forms differ. This is somewhat surprising for 7726 those who only have experiences with Romanic and Germanic languages 7727 since here the number is the same (there are two). 7728 7729 But other language families have only one form or many forms. More 7730 information on this in an extra section. 7731 7732 The consequence of this is that application writers should not try to 7733solve the problem in their code. This would be localization since it is 7734only usable for certain, hardcoded language environments. Instead the 7735extended `gettext' interface should be used. 7736 7737 These extra functions are taking instead of the one key string two 7738strings and a numerical argument. The idea behind this is that using 7739the numerical argument and the first string as a key, the implementation 7740can select using rules specified by the translator the right plural 7741form. The two string arguments then will be used to provide a return 7742value in case no message catalog is found (similar to the normal 7743`gettext' behavior). In this case the rules for Germanic language is 7744used and it is assumed that the first string argument is the singular 7745form, the second the plural form. 7746 7747 This has the consequence that programs without language catalogs can 7748display the correct strings only if the program itself is written using 7749a Germanic language. This is a limitation but since the GNU C library 7750(as well as the GNU `gettext' package) are written as part of the GNU 7751package and the coding standards for the GNU project require program 7752being written in English, this solution nevertheless fulfills its 7753purpose. 7754 7755 -- Function: char * ngettext (const char *MSGID1, const char *MSGID2, 7756 unsigned long int N) 7757 The `ngettext' function is similar to the `gettext' function as it 7758 finds the message catalogs in the same way. But it takes two 7759 extra arguments. The MSGID1 parameter must contain the singular 7760 form of the string to be converted. It is also used as the key 7761 for the search in the catalog. The MSGID2 parameter is the plural 7762 form. The parameter N is used to determine the plural form. If no 7763 message catalog is found MSGID1 is returned if `n == 1', otherwise 7764 `msgid2'. 7765 7766 An example for the use of this function is: 7767 7768 printf (ngettext ("%d file removed", "%d files removed", n), n); 7769 7770 Please note that the numeric value N has to be passed to the 7771 `printf' function as well. It is not sufficient to pass it only to 7772 `ngettext'. 7773 7774 In the English singular case, the number - always 1 - can be 7775 replaced with "one": 7776 7777 printf (ngettext ("One file removed", "%d files removed", n), n); 7778 7779 This works because the `printf' function discards excess arguments 7780 that are not consumed by the format string. 7781 7782 It is also possible to use this function when the strings don't 7783 contain a cardinal number: 7784 7785 puts (ngettext ("Delete the selected file?", 7786 "Delete the selected files?", 7787 n)); 7788 7789 In this case the number N is only used to choose the plural form. 7790 7791 -- Function: char * dngettext (const char *DOMAIN, const char *MSGID1, 7792 const char *MSGID2, unsigned long int N) 7793 The `dngettext' is similar to the `dgettext' function in the way 7794 the message catalog is selected. The difference is that it takes 7795 two extra parameter to provide the correct plural form. These two 7796 parameters are handled in the same way `ngettext' handles them. 7797 7798 -- Function: char * dcngettext (const char *DOMAIN, const char 7799 *MSGID1, const char *MSGID2, unsigned long int N, int 7800 CATEGORY) 7801 The `dcngettext' is similar to the `dcgettext' function in the way 7802 the message catalog is selected. The difference is that it takes 7803 two extra parameter to provide the correct plural form. These two 7804 parameters are handled in the same way `ngettext' handles them. 7805 7806 Now, how do these functions solve the problem of the plural forms? 7807Without the input of linguists (which was not available) it was not 7808possible to determine whether there are only a few different forms in 7809which plural forms are formed or whether the number can increase with 7810every new supported language. 7811 7812 Therefore the solution implemented is to allow the translator to 7813specify the rules of how to select the plural form. Since the formula 7814varies with every language this is the only viable solution except for 7815hardcoding the information in the code (which still would require the 7816possibility of extensions to not prevent the use of new languages). 7817 7818 The information about the plural form selection has to be stored in 7819the header entry of the PO file (the one with the empty `msgid' string). 7820The plural form information looks like this: 7821 7822 Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1; 7823 7824 The `nplurals' value must be a decimal number which specifies how 7825many different plural forms exist for this language. The string 7826following `plural' is an expression which is using the C language 7827syntax. Exceptions are that no negative numbers are allowed, numbers 7828must be decimal, and the only variable allowed is `n'. Spaces are 7829allowed in the expression, but backslash-newlines are not; in the 7830examples below the backslash-newlines are present for formatting 7831purposes only. This expression will be evaluated whenever one of the 7832functions `ngettext', `dngettext', or `dcngettext' is called. The 7833numeric value passed to these functions is then substituted for all uses 7834of the variable `n' in the expression. The resulting value then must 7835be greater or equal to zero and smaller than the value given as the 7836value of `nplurals'. 7837 7838The following rules are known at this point. The language with families 7839are listed. But this does not necessarily mean the information can be 7840generalized for the whole family (as can be easily seen in the table 7841below).(1) 7842 7843Only one form: 7844 Some languages only require one single form. There is no 7845 distinction between the singular and plural form. An appropriate 7846 header entry would look like this: 7847 7848 Plural-Forms: nplurals=1; plural=0; 7849 7850 Languages with this property include: 7851 7852 Asian family 7853 Japanese, Korean, Vietnamese 7854 7855 Turkic/Altaic family 7856 Turkish 7857 7858Two forms, singular used for one only 7859 This is the form used in most existing programs since it is what 7860 English is using. A header entry would look like this: 7861 7862 Plural-Forms: nplurals=2; plural=n != 1; 7863 7864 (Note: this uses the feature of C expressions that boolean 7865 expressions have to value zero or one.) 7866 7867 Languages with this property include: 7868 7869 Germanic family 7870 Danish, Dutch, English, Faroese, German, Norwegian, Swedish 7871 7872 Finno-Ugric family 7873 Estonian, Finnish 7874 7875 Latin/Greek family 7876 Greek 7877 7878 Semitic family 7879 Hebrew 7880 7881 Romanic family 7882 Italian, Portuguese, Spanish 7883 7884 Artificial 7885 Esperanto 7886 7887 Another language using the same header entry is: 7888 7889 Finno-Ugric family 7890 Hungarian 7891 7892 Hungarian does not appear to have a plural if you look at 7893 sentences involving cardinal numbers. For example, "1 apple" is 7894 "1 alma", and "123 apples" is "123 alma". But when the number is 7895 not explicit, the distinction between singular and plural exists: 7896 "the apple" is "az alma", and "the apples" is "az alm��k". Since 7897 `ngettext' has to support both types of sentences, it is 7898 classified here, under "two forms". 7899 7900Two forms, singular used for zero and one 7901 Exceptional case in the language family. The header entry would 7902 be: 7903 7904 Plural-Forms: nplurals=2; plural=n>1; 7905 7906 Languages with this property include: 7907 7908 Romanic family 7909 French, Brazilian Portuguese 7910 7911Three forms, special case for zero 7912 The header entry would be: 7913 7914 Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2; 7915 7916 Languages with this property include: 7917 7918 Baltic family 7919 Latvian 7920 7921Three forms, special cases for one and two 7922 The header entry would be: 7923 7924 Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2; 7925 7926 Languages with this property include: 7927 7928 Celtic 7929 Gaeilge (Irish) 7930 7931Three forms, special case for numbers ending in 00 or [2-9][0-9] 7932 The header entry would be: 7933 7934 Plural-Forms: nplurals=3; \ 7935 plural=n==1 ? 0 : (n==0 || (n%100 > 0 && n%100 < 20)) ? 1 : 2; 7936 7937 Languages with this property include: 7938 7939 Romanic family 7940 Romanian 7941 7942Three forms, special case for numbers ending in 1[2-9] 7943 The header entry would look like this: 7944 7945 Plural-Forms: nplurals=3; \ 7946 plural=n%10==1 && n%100!=11 ? 0 : \ 7947 n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2; 7948 7949 Languages with this property include: 7950 7951 Baltic family 7952 Lithuanian 7953 7954Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4] 7955 The header entry would look like this: 7956 7957 Plural-Forms: nplurals=3; \ 7958 plural=n%10==1 && n%100!=11 ? 0 : \ 7959 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2; 7960 7961 Languages with this property include: 7962 7963 Slavic family 7964 Croatian, Serbian, Russian, Ukrainian 7965 7966Three forms, special cases for 1 and 2, 3, 4 7967 The header entry would look like this: 7968 7969 Plural-Forms: nplurals=3; \ 7970 plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2; 7971 7972 Languages with this property include: 7973 7974 Slavic family 7975 Slovak, Czech 7976 7977Three forms, special case for one and some numbers ending in 2, 3, or 4 7978 The header entry would look like this: 7979 7980 Plural-Forms: nplurals=3; \ 7981 plural=n==1 ? 0 : \ 7982 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2; 7983 7984 Languages with this property include: 7985 7986 Slavic family 7987 Polish 7988 7989Four forms, special case for one and all numbers ending in 02, 03, or 04 7990 The header entry would look like this: 7991 7992 Plural-Forms: nplurals=4; \ 7993 plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3; 7994 7995 Languages with this property include: 7996 7997 Slavic family 7998 Slovenian 7999 8000 You might now ask, `ngettext' handles only numbers N of type 8001`unsigned long'. What about larger integer types? What about negative 8002numbers? What about floating-point numbers? 8003 8004 About larger integer types, such as `uintmax_t' or `unsigned long 8005long': they can be handled by reducing the value to a range that fits 8006in an `unsigned long'. Simply casting the value to `unsigned long' 8007would not do the right thing, since it would treat `ULONG_MAX + 1' like 8008zero, `ULONG_MAX + 2' like singular, and the like. Here you can 8009exploit the fact that all mentioned plural form formulas eventually 8010become periodic, with a period that is a divisor of 100 (or 1000 or 80111000000). So, when you reduce a large value to another one in the 8012range [1000000, 1999999] that ends in the same 6 decimal digits, you 8013can assume that it will lead to the same plural form selection. This 8014code does this: 8015 8016 #include <inttypes.h> 8017 uintmax_t nbytes = ...; 8018 printf (ngettext ("The file has %"PRIuMAX" byte.", 8019 "The file has %"PRIuMAX" bytes.", 8020 (nbytes > ULONG_MAX 8021 ? (nbytes % 1000000) + 1000000 8022 : nbytes)), 8023 nbytes); 8024 8025 Negative and floating-point values usually represent physical 8026entities for which singular and plural don't clearly apply. In such 8027cases, there is no need to use `ngettext'; a simple `gettext' call with 8028a form suitable for all values will do. For example: 8029 8030 printf (gettext ("Time elapsed: %.3f seconds"), 8031 num_milliseconds * 0.001); 8032 8033Even if NUM_MILLISECONDS happens to be a multiple of 1000, the output 8034 Time elapsed: 1.000 seconds 8035 is acceptable in English, and similarly for other languages. 8036 8037 ---------- Footnotes ---------- 8038 8039 (1) Additions are welcome. Send appropriate information to 8040<bug-gnu-gettext@gnu.org> and <bug-glibc-manual@gnu.org>. 8041 8042 8043File: gettext.info, Node: Optimized gettext, Prev: Plural forms, Up: gettext 8044 804511.2.7 Optimization of the *gettext functions 8046--------------------------------------------- 8047 8048 At this point of the discussion we should talk about an advantage of 8049the GNU `gettext' implementation. Some readers might have pointed out 8050that an internationalized program might have a poor performance if some 8051string has to be translated in an inner loop. While this is unavoidable 8052when the string varies from one run of the loop to the other it is 8053simply a waste of time when the string is always the same. Take the 8054following example: 8055 8056 { 8057 while (...) 8058 { 8059 puts (gettext ("Hello world")); 8060 } 8061 } 8062 8063When the locale selection does not change between two runs the resulting 8064string is always the same. One way to use this is: 8065 8066 { 8067 str = gettext ("Hello world"); 8068 while (...) 8069 { 8070 puts (str); 8071 } 8072 } 8073 8074But this solution is not usable in all situation (e.g. when the locale 8075selection changes) nor does it lead to legible code. 8076 8077 For this reason, GNU `gettext' caches previous translation results. 8078When the same translation is requested twice, with no new message 8079catalogs being loaded in between, `gettext' will, the second time, find 8080the result through a single cache lookup. 8081 8082 8083File: gettext.info, Node: Comparison, Next: Using libintl.a, Prev: gettext, Up: Programmers 8084 808511.3 Comparing the Two Interfaces 8086================================= 8087 8088 The following discussion is perhaps a little bit colored. As said 8089above we implemented GNU `gettext' following the Uniforum proposal and 8090this surely has its reasons. But it should show how we came to this 8091decision. 8092 8093 First we take a look at the developing process. When we write an 8094application using NLS provided by `gettext' we proceed as always. Only 8095when we come to a string which might be seen by the users and thus has 8096to be translated we use `gettext("...")' instead of `"..."'. At the 8097beginning of each source file (or in a central header file) we define 8098 8099 #define gettext(String) (String) 8100 8101 Even this definition can be avoided when the system supports the 8102`gettext' function in its C library. When we compile this code the 8103result is the same as if no NLS code is used. When you take a look at 8104the GNU `gettext' code you will see that we use `_("...")' instead of 8105`gettext("...")'. This reduces the number of additional characters per 8106translatable string to _3_ (in words: three). 8107 8108 When now a production version of the program is needed we simply 8109replace the definition 8110 8111 #define _(String) (String) 8112 8113by 8114 8115 #include <libintl.h> 8116 #define _(String) gettext (String) 8117 8118Additionally we run the program `xgettext' on all source code file 8119which contain translatable strings and that's it: we have a running 8120program which does not depend on translations to be available, but which 8121can use any that becomes available. 8122 8123 The same procedure can be done for the `gettext_noop' invocations 8124(*note Special cases::). One usually defines `gettext_noop' as a no-op 8125macro. So you should consider the following code for your project: 8126 8127 #define gettext_noop(String) String 8128 #define N_(String) gettext_noop (String) 8129 8130 `N_' is a short form similar to `_'. The `Makefile' in the `po/' 8131directory of GNU `gettext' knows by default both of the mentioned short 8132forms so you are invited to follow this proposal for your own ease. 8133 8134 Now to `catgets'. The main problem is the work for the programmer. 8135Every time he comes to a translatable string he has to define a number 8136(or a symbolic constant) which has also be defined in the message 8137catalog file. He also has to take care for duplicate entries, 8138duplicate message IDs etc. If he wants to have the same quality in the 8139message catalog as the GNU `gettext' program provides he also has to 8140put the descriptive comments for the strings and the location in all 8141source code files in the message catalog. This is nearly a Mission: 8142Impossible. 8143 8144 But there are also some points people might call advantages speaking 8145for `catgets'. If you have a single word in a string and this string 8146is used in different contexts it is likely that in one or the other 8147language the word has different translations. Example: 8148 8149 printf ("%s: %d", gettext ("number"), number_of_errors) 8150 8151 printf ("you should see %d %s", number_count, 8152 number_count == 1 ? gettext ("number") : gettext ("numbers")) 8153 8154 Here we have to translate two times the string `"number"'. Even if 8155you do not speak a language beside English it might be possible to 8156recognize that the two words have a different meaning. In German the 8157first appearance has to be translated to `"Anzahl"' and the second to 8158`"Zahl"'. 8159 8160 Now you can say that this example is really esoteric. And you are 8161right! This is exactly how we felt about this problem and decide that 8162it does not weight that much. The solution for the above problem could 8163be very easy: 8164 8165 printf ("%s %d", gettext ("number:"), number_of_errors) 8166 8167 printf (number_count == 1 ? gettext ("you should see %d number") 8168 : gettext ("you should see %d numbers"), 8169 number_count) 8170 8171 We believe that we can solve all conflicts with this method. If it 8172is difficult one can also consider changing one of the conflicting 8173string a little bit. But it is not impossible to overcome. 8174 8175 `catgets' allows same original entry to have different translations, 8176but `gettext' has another, scalable approach for solving ambiguities of 8177this kind: *Note Ambiguities::. 8178 8179 8180File: gettext.info, Node: Using libintl.a, Next: gettext grok, Prev: Comparison, Up: Programmers 8181 818211.4 Using libintl.a in own programs 8183==================================== 8184 8185 Starting with version 0.9.4 the library `libintl.h' should be 8186self-contained. I.e., you can use it in your own programs without 8187providing additional functions. The `Makefile' will put the header and 8188the library in directories selected using the `$(prefix)'. 8189 8190 8191File: gettext.info, Node: gettext grok, Next: Temp Programmers, Prev: Using libintl.a, Up: Programmers 8192 819311.5 Being a `gettext' grok 8194=========================== 8195 8196 * NOTE: * This documentation section is outdated and needs to be 8197revised. 8198 8199 To fully exploit the functionality of the GNU `gettext' library it 8200is surely helpful to read the source code. But for those who don't want 8201to spend that much time in reading the (sometimes complicated) code here 8202is a list comments: 8203 8204 * Changing the language at runtime 8205 8206 For interactive programs it might be useful to offer a selection 8207 of the used language at runtime. To understand how to do this one 8208 need to know how the used language is determined while executing 8209 the `gettext' function. The method which is presented here only 8210 works correctly with the GNU implementation of the `gettext' 8211 functions. 8212 8213 In the function `dcgettext' at every call the current setting of 8214 the highest priority environment variable is determined and used. 8215 Highest priority means here the following list with decreasing 8216 priority: 8217 8218 1. `LANGUAGE' 8219 8220 2. `LC_ALL' 8221 8222 3. `LC_xxx', according to selected locale category 8223 8224 4. `LANG' 8225 8226 Afterwards the path is constructed using the found value and the 8227 translation file is loaded if available. 8228 8229 What happens now when the value for, say, `LANGUAGE' changes? 8230 According to the process explained above the new value of this 8231 variable is found as soon as the `dcgettext' function is called. 8232 But this also means the (perhaps) different message catalog file 8233 is loaded. In other words: the used language is changed. 8234 8235 But there is one little hook. The code for gcc-2.7.0 and up 8236 provides some optimization. This optimization normally prevents 8237 the calling of the `dcgettext' function as long as no new catalog 8238 is loaded. But if `dcgettext' is not called the program also 8239 cannot find the `LANGUAGE' variable be changed (*note Optimized 8240 gettext::). A solution for this is very easy. Include the 8241 following code in the language switching function. 8242 8243 /* Change language. */ 8244 setenv ("LANGUAGE", "fr", 1); 8245 8246 /* Make change known. */ 8247 { 8248 extern int _nl_msg_cat_cntr; 8249 ++_nl_msg_cat_cntr; 8250 } 8251 8252 The variable `_nl_msg_cat_cntr' is defined in `loadmsgcat.c'. You 8253 don't need to know what this is for. But it can be used to detect 8254 whether a `gettext' implementation is GNU gettext and not non-GNU 8255 system's native gettext implementation. 8256 8257 8258 8259File: gettext.info, Node: Temp Programmers, Prev: gettext grok, Up: Programmers 8260 826111.6 Temporary Notes for the Programmers Chapter 8262================================================ 8263 8264 * NOTE: * This documentation section is outdated and needs to be 8265revised. 8266 8267* Menu: 8268 8269* Temp Implementations:: Temporary - Two Possible Implementations 8270* Temp catgets:: Temporary - About `catgets' 8271* Temp WSI:: Temporary - Why a single implementation 8272* Temp Notes:: Temporary - Notes 8273 8274 8275File: gettext.info, Node: Temp Implementations, Next: Temp catgets, Prev: Temp Programmers, Up: Temp Programmers 8276 827711.6.1 Temporary - Two Possible Implementations 8278----------------------------------------------- 8279 8280 There are two competing methods for language independent messages: 8281the X/Open `catgets' method, and the Uniforum `gettext' method. The 8282`catgets' method indexes messages by integers; the `gettext' method 8283indexes them by their English translations. The `catgets' method has 8284been around longer and is supported by more vendors. The `gettext' 8285method is supported by Sun, and it has been heard that the COSE 8286multi-vendor initiative is supporting it. Neither method is a POSIX 8287standard; the POSIX.1 committee had a lot of disagreement in this area. 8288 8289 Neither one is in the POSIX standard. There was much disagreement 8290in the POSIX.1 committee about using the `gettext' routines vs. 8291`catgets' (XPG). In the end the committee couldn't agree on anything, 8292so no messaging system was included as part of the standard. I believe 8293the informative annex of the standard includes the XPG3 messaging 8294interfaces, "...as an example of a messaging system that has been 8295implemented..." 8296 8297 They were very careful not to say anywhere that you should use one 8298set of interfaces over the other. For more on this topic please see 8299the Programming for Internationalization FAQ. 8300 8301 8302File: gettext.info, Node: Temp catgets, Next: Temp WSI, Prev: Temp Implementations, Up: Temp Programmers 8303 830411.6.2 Temporary - About `catgets' 8305---------------------------------- 8306 8307 There have been a few discussions of late on the use of `catgets' as 8308a base. I think it important to present both sides of the argument and 8309hence am opting to play devil's advocate for a little bit. 8310 8311 I'll not deny the fact that `catgets' could have been designed a lot 8312better. It currently has quite a number of limitations and these have 8313already been pointed out. 8314 8315 However there is a great deal to be said for consistency and 8316standardization. A common recurring problem when writing Unix software 8317is the myriad portability problems across Unix platforms. It seems as 8318if every Unix vendor had a look at the operating system and found parts 8319they could improve upon. Undoubtedly, these modifications are probably 8320innovative and solve real problems. However, software developers have 8321a hard time keeping up with all these changes across so many platforms. 8322 8323 And this has prompted the Unix vendors to begin to standardize their 8324systems. Hence the impetus for Spec1170. Every major Unix vendor has 8325committed to supporting this standard and every Unix software developer 8326waits with glee the day they can write software to this standard and 8327simply recompile (without having to use autoconf) across different 8328platforms. 8329 8330 As I understand it, Spec1170 is roughly based upon version 4 of the 8331X/Open Portability Guidelines (XPG4). Because `catgets' and friends 8332are defined in XPG4, I'm led to believe that `catgets' is a part of 8333Spec1170 and hence will become a standardized component of all Unix 8334systems. 8335 8336 8337File: gettext.info, Node: Temp WSI, Next: Temp Notes, Prev: Temp catgets, Up: Temp Programmers 8338 833911.6.3 Temporary - Why a single implementation 8340---------------------------------------------- 8341 8342 Now it seems kind of wasteful to me to have two different systems 8343installed for accessing message catalogs. If we do want to remedy 8344`catgets' deficiencies why don't we try to expand `catgets' (in a 8345compatible manner) rather than implement an entirely new system. 8346Otherwise, we'll end up with two message catalog access systems 8347installed with an operating system - one set of routines for packages 8348using GNU `gettext' for their internationalization, and another set of 8349routines (catgets) for all other software. Bloated? 8350 8351 Supposing another catalog access system is implemented. Which do we 8352recommend? At least for Linux, we need to attract as many software 8353developers as possible. Hence we need to make it as easy for them to 8354port their software as possible. Which means supporting `catgets'. We 8355will be implementing the `libintl' code within our `libc', but does 8356this mean we also have to incorporate another message catalog access 8357scheme within our `libc' as well? And what about people who are going 8358to be using the `libintl' + non-`catgets' routines. When they port 8359their software to other platforms, they're now going to have to include 8360the front-end (`libintl') code plus the back-end code (the non-`catgets' 8361access routines) with their software instead of just including the 8362`libintl' code with their software. 8363 8364 Message catalog support is however only the tip of the iceberg. 8365What about the data for the other locale categories? They also have a 8366number of deficiencies. Are we going to abandon them as well and 8367develop another duplicate set of routines (should `libintl' expand 8368beyond message catalog support)? 8369 8370 Like many parts of Unix that can be improved upon, we're stuck with 8371balancing compatibility with the past with useful improvements and 8372innovations for the future. 8373 8374 8375File: gettext.info, Node: Temp Notes, Prev: Temp WSI, Up: Temp Programmers 8376 837711.6.4 Temporary - Notes 8378------------------------ 8379 8380 X/Open agreed very late on the standard form so that many 8381implementations differ from the final form. Both of my system (old 8382Linux catgets and Ultrix-4) have a strange variation. 8383 8384 OK. After incorporating the last changes I have to spend some time 8385on making the GNU/Linux `libc' `gettext' functions. So in future 8386Solaris is not the only system having `gettext'. 8387 8388 8389File: gettext.info, Node: Translators, Next: Maintainers, Prev: Programmers, Up: Top 8390 839112 The Translator's View 8392************************ 8393 8394* Menu: 8395 8396* Trans Intro 0:: Introduction 0 8397* Trans Intro 1:: Introduction 1 8398* Discussions:: Discussions 8399* Organization:: Organization 8400* Information Flow:: Information Flow 8401* Prioritizing messages:: How to find which messages to translate first 8402 8403 8404File: gettext.info, Node: Trans Intro 0, Next: Trans Intro 1, Prev: Translators, Up: Translators 8405 840612.1 Introduction 0 8407=================== 8408 8409 * NOTE: * This documentation section is outdated and needs to be 8410revised. 8411 8412 Free software is going international! The Translation Project is a 8413way to get maintainers, translators and users all together, so free 8414software will gradually become able to speak many native languages. 8415 8416 The GNU `gettext' tool set contains _everything_ maintainers need 8417for internationalizing their packages for messages. It also contains 8418quite useful tools for helping translators at localizing messages to 8419their native language, once a package has already been 8420internationalized. 8421 8422 To achieve the Translation Project, we need many interested people 8423who like their own language and write it well, and who are also able to 8424synergize with other translators speaking the same language. If you'd 8425like to volunteer to _work_ at translating messages, please send mail 8426to your translating team. 8427 8428 Each team has its own mailing list, courtesy of Linux International. 8429You may reach your translating team at the address `LL@li.org', 8430replacing LL by the two-letter ISO 639 code for your language. 8431Language codes are _not_ the same as country codes given in ISO 3166. 8432The following translating teams exist: 8433 8434 Chinese `zh', Czech `cs', Danish `da', Dutch `nl', Esperanto `eo', 8435 Finnish `fi', French `fr', Irish `ga', German `de', Greek `el', 8436 Italian `it', Japanese `ja', Indonesian `in', Norwegian `no', 8437 Polish `pl', Portuguese `pt', Russian `ru', Spanish `es', Swedish 8438 `sv' and Turkish `tr'. 8439 8440For example, you may reach the Chinese translating team by writing to 8441`zh@li.org'. When you become a member of the translating team for your 8442own language, you may subscribe to its list. For example, Swedish 8443people can send a message to `sv-request@li.org', having this message 8444body: 8445 8446 subscribe 8447 8448 Keep in mind that team members should be interested in _working_ at 8449translations, or at solving translational difficulties, rather than 8450merely lurking around. If your team does not exist yet and you want to 8451start one, please write to `coordinator@translationproject.org'; you 8452will then reach the coordinator for all translator teams. 8453 8454 A handful of GNU packages have already been adapted and provided 8455with message translations for several languages. Translation teams 8456have begun to organize, using these packages as a starting point. But 8457there are many more packages and many languages for which we have no 8458volunteer translators. If you would like to volunteer to work at 8459translating messages, please send mail to 8460`coordinator@translationproject.org' indicating what language(s) you 8461can work on. 8462 8463 8464File: gettext.info, Node: Trans Intro 1, Next: Discussions, Prev: Trans Intro 0, Up: Translators 8465 846612.2 Introduction 1 8467=================== 8468 8469 * NOTE: * This documentation section is outdated and needs to be 8470revised. 8471 8472 This is now official, GNU is going international! Here is the 8473announcement submitted for the January 1995 GNU Bulletin: 8474 8475 A handful of GNU packages have already been adapted and provided 8476 with message translations for several languages. Translation 8477 teams have begun to organize, using these packages as a starting 8478 point. But there are many more packages and many languages for 8479 which we have no volunteer translators. If you'd like to 8480 volunteer to work at translating messages, please send mail to 8481 `coordinator@translationproject.org' indicating what language(s) 8482 you can work on. 8483 8484 This document should answer many questions for those who are curious 8485about the process or would like to contribute. Please at least skim 8486over it, hoping to cut down a little of the high volume of e-mail 8487generated by this collective effort towards internationalization of 8488free software. 8489 8490 Most free programming which is widely shared is done in English, and 8491currently, English is used as the main communicating language between 8492national communities collaborating to free software. This very document 8493is written in English. This will not change in the foreseeable future. 8494 8495 However, there is a strong appetite from national communities for 8496having more software able to write using national language and habits, 8497and there is an on-going effort to modify free software in such a way 8498that it becomes able to do so. The experiments driven so far raised an 8499enthusiastic response from pretesters, so we believe that 8500internationalization of free software is dedicated to succeed. 8501 8502 For suggestion clarifications, additions or corrections to this 8503document, please e-mail to `coordinator@translationproject.org'. 8504 8505 8506File: gettext.info, Node: Discussions, Next: Organization, Prev: Trans Intro 1, Up: Translators 8507 850812.3 Discussions 8509================ 8510 8511 * NOTE: * This documentation section is outdated and needs to be 8512revised. 8513 8514 Facing this internationalization effort, a few users expressed their 8515concerns. Some of these doubts are presented and discussed, here. 8516 8517 * Smaller groups 8518 8519 Some languages are not spoken by a very large number of people, so 8520 people speaking them sometimes consider that there may not be all 8521 that much demand such versions of free software packages. 8522 Moreover, many people being _into computers_, in some countries, 8523 generally seem to prefer English versions of their software. 8524 8525 On the other end, people might enjoy their own language a lot, and 8526 be very motivated at providing to themselves the pleasure of 8527 having their beloved free software speaking their mother tongue. 8528 They do themselves a personal favor, and do not pay that much 8529 attention to the number of people benefiting of their work. 8530 8531 * Misinterpretation 8532 8533 Other users are shy to push forward their own language, seeing in 8534 this some kind of misplaced propaganda. Someone thought there 8535 must be some users of the language over the networks pestering 8536 other people with it. 8537 8538 But any spoken language is worth localization, because there are 8539 people behind the language for whom the language is important and 8540 dear to their hearts. 8541 8542 * Odd translations 8543 8544 The biggest problem is to find the right translations so that 8545 everybody can understand the messages. Translations are usually a 8546 little odd. Some people get used to English, to the extent they 8547 may find translations into their own language "rather pushy, 8548 obnoxious and sometimes even hilarious." As a French speaking 8549 man, I have the experience of those instruction manuals for goods, 8550 so poorly translated in French in Korea or Taiwan... 8551 8552 The fact is that we sometimes have to create a kind of national 8553 computer culture, and this is not easy without the collaboration of 8554 many people liking their mother tongue. This is why translations 8555 are better achieved by people knowing and loving their own 8556 language, and ready to work together at improving the results they 8557 obtain. 8558 8559 * Dependencies over the GPL or LGPL 8560 8561 Some people wonder if using GNU `gettext' necessarily brings their 8562 package under the protective wing of the GNU General Public 8563 License or the GNU Library General Public License, when they do 8564 not want to make their program free, or want other kinds of 8565 freedom. The simplest answer is "normally not". 8566 8567 The `gettext-runtime' part of GNU `gettext', i.e. the contents of 8568 `libintl', is covered by the GNU Library General Public License. 8569 The `gettext-tools' part of GNU `gettext', i.e. the rest of the 8570 GNU `gettext' package, is covered by the GNU General Public 8571 License. 8572 8573 The mere marking of localizable strings in a package, or 8574 conditional inclusion of a few lines for initialization, is not 8575 really including GPL'ed or LGPL'ed code. However, since the 8576 localization routines in `libintl' are under the LGPL, the LGPL 8577 needs to be considered. It gives the right to distribute the 8578 complete unmodified source of `libintl' even with non-free 8579 programs. It also gives the right to use `libintl' as a shared 8580 library, even for non-free programs. But it gives the right to 8581 use `libintl' as a static library or to incorporate `libintl' into 8582 another library only to free software. 8583 8584 8585 8586File: gettext.info, Node: Organization, Next: Information Flow, Prev: Discussions, Up: Translators 8587 858812.4 Organization 8589================= 8590 8591 * NOTE: * This documentation section is outdated and needs to be 8592revised. 8593 8594 On a larger scale, the true solution would be to organize some kind 8595of fairly precise set up in which volunteers could participate. I gave 8596some thought to this idea lately, and realize there will be some touchy 8597points. I thought of writing to Richard Stallman to launch such a 8598project, but feel it might be good to shake out the ideas between 8599ourselves first. Most probably that Linux International has some 8600experience in the field already, or would like to orchestrate the 8601volunteer work, maybe. Food for thought, in any case! 8602 8603 I guess we have to setup something early, somehow, that will help 8604many possible contributors of the same language to interlock and avoid 8605work duplication, and further be put in contact for solving together 8606problems particular to their tongue (in most languages, there are many 8607difficulties peculiar to translating technical English). My Swedish 8608contributor acknowledged these difficulties, and I'm well aware of them 8609for French. 8610 8611 This is surely not a technical issue, but we should manage so the 8612effort of locale contributors be maximally useful, despite the national 8613team layer interface between contributors and maintainers. 8614 8615 The Translation Project needs some setup for coordinating language 8616coordinators. Localizing evolving programs will surely become a 8617permanent and continuous activity in the free software community, once 8618well started. The setup should be minimally completed and tested 8619before GNU `gettext' becomes an official reality. The e-mail address 8620`coordinator@translationproject.org' has been set up for receiving 8621offers from volunteers and general e-mail on these topics. This address 8622reaches the Translation Project coordinator. 8623 8624* Menu: 8625 8626* Central Coordination:: Central Coordination 8627* National Teams:: National Teams 8628* Mailing Lists:: Mailing Lists 8629 8630 8631File: gettext.info, Node: Central Coordination, Next: National Teams, Prev: Organization, Up: Organization 8632 863312.4.1 Central Coordination 8634--------------------------- 8635 8636 I also think GNU will need sooner than it thinks, that someone set up 8637a way to organize and coordinate these groups. Some kind of group of 8638groups. My opinion is that it would be good that GNU delegates this 8639task to a small group of collaborating volunteers, shortly. Perhaps in 8640`gnu.announce' a list of this national committee's can be published. 8641 8642 My role as coordinator would simply be to refer to Ulrich any German 8643speaking volunteer interested to localization of free software 8644packages, and maybe helping national groups to initially organize, 8645while maintaining national registries for until national groups are 8646ready to take over. In fact, the coordinator should ease volunteers to 8647get in contact with one another for creating national teams, which 8648should then select one coordinator per language, or country 8649(regionalized language). If well done, the coordination should be 8650useful without being an overwhelming task, the time to put delegations 8651in place. 8652 8653 8654File: gettext.info, Node: National Teams, Next: Mailing Lists, Prev: Central Coordination, Up: Organization 8655 865612.4.2 National Teams 8657--------------------- 8658 8659 I suggest we look for volunteer coordinators/editors for individual 8660languages. These people will scan contributions of translation files 8661for various programs, for their own languages, and will ensure high and 8662uniform standards of diction. 8663 8664 From my current experience with other people in these days, those who 8665provide localizations are very enthusiastic about the process, and are 8666more interested in the localization process than in the program they 8667localize, and want to do many programs, not just one. This seems to 8668confirm that having a coordinator/editor for each language is a good 8669idea. 8670 8671 We need to choose someone who is good at writing clear and concise 8672prose in the language in question. That is hard--we can't check it 8673ourselves. So we need to ask a few people to judge each others' 8674writing and select the one who is best. 8675 8676 I announce my prerelease to a few dozen people, and you would not 8677believe all the discussions it generated already. I shudder to think 8678what will happen when this will be launched, for true, officially, 8679world wide. Who am I to arbitrate between two Czekolsovak users 8680contradicting each other, for example? 8681 8682 I assume that your German is not much better than my French so that 8683I would not be able to judge about these formulations. What I would 8684suggest is that for each language there is a group for people who 8685maintain the PO files and judge about changes. I suspect there will be 8686cultural differences between how such groups of people will behave. 8687Some will have relaxed ways, reach consensus easily, and have anyone of 8688the group relate to the maintainers, while others will fight to death, 8689organize heavy administrations up to national standards, and use strict 8690channels. 8691 8692 The German team is putting out a good example. Right now, they are 8693maybe half a dozen people revising translations of each other and 8694discussing the linguistic issues. I do not even have all the names. 8695Ulrich Drepper is taking care of coordinating the German team. He 8696subscribed to all my pretest lists, so I do not even have to warn him 8697specifically of incoming releases. 8698 8699 I'm sure, that is a good idea to get teams for each language working 8700on translations. That will make the translations better and more 8701consistent. 8702 8703* Menu: 8704 8705* Sub-Cultures:: Sub-Cultures 8706* Organizational Ideas:: Organizational Ideas 8707 8708 8709File: gettext.info, Node: Sub-Cultures, Next: Organizational Ideas, Prev: National Teams, Up: National Teams 8710 871112.4.2.1 Sub-Cultures 8712..................... 8713 8714 Taking French for example, there are a few sub-cultures around 8715computers which developed diverging vocabularies. Picking volunteers 8716here and there without addressing this problem in an organized way, 8717soon in the project, might produce a distasteful mix of 8718internationalized programs, and possibly trigger endless quarrels among 8719those who really care. 8720 8721 Keeping some kind of unity in the way French localization of 8722internationalized programs is achieved is a difficult (and delicate) 8723job. Knowing the latin character of French people (:-), if we take this 8724the wrong way, we could end up nowhere, or spoil a lot of energies. 8725Maybe we should begin to address this problem seriously _before_ GNU 8726`gettext' become officially published. And I suspect that this means 8727soon! 8728 8729 8730File: gettext.info, Node: Organizational Ideas, Prev: Sub-Cultures, Up: National Teams 8731 873212.4.2.2 Organizational Ideas 8733............................. 8734 8735 I expect the next big changes after the official release. Please 8736note that I use the German translation of the short GPL message. We 8737need to set a few good examples before the localization goes out for 8738true in the free software community. Here are a few points to discuss: 8739 8740 * Each group should have one FTP server (at least one master). 8741 8742 * The files on the server should reflect the latest version (of 8743 course!) and it should also contain a RCS directory with the 8744 corresponding archives (I don't have this now). 8745 8746 * There should also be a ChangeLog file (this is more useful than the 8747 RCS archive but can be generated automatically from the later by 8748 Emacs). 8749 8750 * A "core group" should judge about questionable changes (for now 8751 this group consists solely by me but I ask some others 8752 occasionally; this also seems to work). 8753 8754 8755 8756File: gettext.info, Node: Mailing Lists, Prev: National Teams, Up: Organization 8757 875812.4.3 Mailing Lists 8759-------------------- 8760 8761 If we get any inquiries about GNU `gettext', send them on to: 8762 8763 `coordinator@translationproject.org' 8764 8765 The `*-pretest' lists are quite useful to me, maybe the idea could 8766be generalized to many GNU, and non-GNU packages. But each maintainer 8767his/her way! 8768 8769 Fran��ois, we have a mechanism in place here at `gnu.ai.mit.edu' to 8770track teams, support mailing lists for them and log members. We have a 8771slight preference that you use it. If this is OK with you, I can get 8772you clued in. 8773 8774 Things are changing! A few years ago, when Daniel Fekete and I 8775asked for a mailing list for GNU localization, nested at the FSF, we 8776were politely invited to organize it anywhere else, and so did we. For 8777communicating with my pretesters, I later made a handful of mailing 8778lists located at iro.umontreal.ca and administrated by `majordomo'. 8779These lists have been _very_ dependable so far... 8780 8781 I suspect that the German team will organize itself a mailing list 8782located in Germany, and so forth for other countries. But before they 8783organize for true, it could surely be useful to offer mailing lists 8784located at the FSF to each national team. So yes, please explain me 8785how I should proceed to create and handle them. 8786 8787 We should create temporary mailing lists, one per country, to help 8788people organize. Temporary, because once regrouped and structured, it 8789would be fair the volunteers from country bring back _their_ list in 8790there and manage it as they want. My feeling is that, in the long run, 8791each team should run its own list, from within their country. There 8792also should be some central list to which all teams could subscribe as 8793they see fit, as long as each team is represented in it. 8794 8795 8796File: gettext.info, Node: Information Flow, Next: Prioritizing messages, Prev: Organization, Up: Translators 8797 879812.5 Information Flow 8799===================== 8800 8801 * NOTE: * This documentation section is outdated and needs to be 8802revised. 8803 8804 There will surely be some discussion about this messages after the 8805packages are finally released. If people now send you some proposals 8806for better messages, how do you proceed? Jim, please note that right 8807now, as I put forward nearly a dozen of localizable programs, I receive 8808both the translations and the coordination concerns about them. 8809 8810 If I put one of my things to pretest, Ulrich receives the 8811announcement and passes it on to the German team, who make last minute 8812revisions. Then he submits the translation files to me _as the 8813maintainer_. For free packages I do not maintain, I would not even 8814hear about it. This scheme could be made to work for the whole 8815Translation Project, I think. For security reasons, maybe Ulrich 8816(national coordinators, in fact) should update central registry kept at 8817the Translation Project (Jim, me, or Len's recruits) once in a while. 8818 8819 In December/January, I was aggressively ready to internationalize 8820all of GNU, giving myself the duty of one small GNU package per week or 8821so, taking many weeks or months for bigger packages. But it does not 8822work this way. I first did all the things I'm responsible for. I've 8823nothing against some missionary work on other maintainers, but I'm also 8824loosing a lot of energy over it--same debates over again. 8825 8826 And when the first localized packages are released we'll get a lot of 8827responses about ugly translations :-). Surely, and we need to have 8828beforehand a fairly good idea about how to handle the information flow 8829between the national teams and the package maintainers. 8830 8831 Please start saving somewhere a quick history of each PO file. I 8832know for sure that the file format will change, allowing for comments. 8833It would be nice that each file has a kind of log, and references for 8834those who want to submit comments or gripes, or otherwise contribute. 8835I sent a proposal for a fast and flexible format, but it is not 8836receiving acceptance yet by the GNU deciders. I'll tell you when I 8837have more information about this. 8838 8839 8840File: gettext.info, Node: Prioritizing messages, Prev: Information Flow, Up: Translators 8841 884212.6 Prioritizing messages: How to determine which messages to translate first 8843============================================================================== 8844 8845 A translator sometimes has only a limited amount of time per week to 8846spend on a package, and some packages have quite large message catalogs 8847(over 1000 messages). Therefore she wishes to translate the messages 8848first that are the most visible to the user, or that occur most 8849frequently. This section describes how to determine these "most 8850urgent" messages. It also applies to determine the "next most urgent" 8851messages after the message catalog has already been partially 8852translated. 8853 8854 In a first step, she uses the programs like a user would do. While 8855she does this, the GNU `gettext' library logs into a file the not yet 8856translated messages for which a translation was requested from the 8857program. 8858 8859 In a second step, she uses the PO mode to translate precisely this 8860set of messages. 8861 8862 Here a more details. The GNU `libintl' library (but not the 8863corresponding functions in GNU `libc') supports an environment variable 8864`GETTEXT_LOG_UNTRANSLATED'. The GNU `libintl' library will log into 8865this file the messages for which `gettext()' and related functions 8866couldn't find the translation. If the file doesn't exist, it will be 8867created as needed. On systems with GNU `libc' a shared library 8868`preloadable_libintl.so' is provided that can be used with the ELF 8869`LD_PRELOAD' mechanism. 8870 8871 So, in the first step, the translator uses these commands on systems 8872with GNU `libc': 8873 8874 $ LD_PRELOAD=/usr/local/lib/preloadable_libintl.so 8875 $ export LD_PRELOAD 8876 $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused 8877 $ export GETTEXT_LOG_UNTRANSLATED 8878 8879and these commands on other systems: 8880 8881 $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused 8882 $ export GETTEXT_LOG_UNTRANSLATED 8883 8884 Then she uses and peruses the programs. (It is a good and 8885recommended practice to use the programs for which you provide 8886translations: it gives you the needed context.) When done, she removes 8887the environment variables: 8888 8889 $ unset LD_PRELOAD 8890 $ unset GETTEXT_LOG_UNTRANSLATED 8891 8892 The second step starts with removing duplicates: 8893 8894 $ msguniq $HOME/gettextlogused > missing.po 8895 8896 The result is a PO file, but needs some preprocessing before a PO 8897file editor can be used with it. First, it is a multi-domain PO file, 8898containing messages from many translation domains. Second, it lacks 8899all translator comments and source references. Here is how to get a 8900list of the affected translation domains: 8901 8902 $ sed -n -e 's,^domain "\(.*\)"$,\1,p' < missing.po | sort | uniq 8903 8904 Then the translator can handle the domains one by one. For 8905simplicity, let's use environment variables to denote the language, 8906domain and source package. 8907 8908 $ lang=nl # your language 8909 $ domain=coreutils # the name of the domain to be handled 8910 $ package=/usr/src/gnu/coreutils-4.5.4 # the package where it comes from 8911 8912 She takes the latest copy of `$lang.po' from the Translation Project, 8913or from the package (in most cases, `$package/po/$lang.po'), or creates 8914a fresh one if she's the first translator (see *note Creating::). She 8915then uses the following commands to mark the not urgent messages as 8916"obsolete". (This doesn't mean that these messages - translated and 8917untranslated ones - will go away. It simply means that the PO file 8918editor will ignore them in the following editing session.) 8919 8920 $ msggrep --domain=$domain missing.po | grep -v '^domain' \ 8921 > $domain-missing.po 8922 $ msgattrib --set-obsolete --ignore-file $domain-missing.po $domain.$lang.po \ 8923 > $domain.$lang-urgent.po 8924 8925 The she translates `$domain.$lang-urgent.po' by use of a PO file 8926editor (*note Editing::). (FIXME: I don't know whether `KBabel' and 8927`gtranslator' also preserve obsolete messages, as they should.) 8928Finally she restores the not urgent messages (with their earlier 8929translations, for those which were already translated) through this 8930command: 8931 8932 $ msgmerge --no-fuzzy-matching $domain.$lang-urgent.po $package/po/$domain.pot \ 8933 > $domain.$lang.po 8934 8935 Then she can submit `$domain.$lang.po' and proceed to the next 8936domain. 8937 8938 8939File: gettext.info, Node: Maintainers, Next: Installers, Prev: Translators, Up: Top 8940 894113 The Maintainer's View 8942************************ 8943 8944 The maintainer of a package has many responsibilities. One of them 8945is ensuring that the package will install easily on many platforms, and 8946that the magic we described earlier (*note Users::) will work for 8947installers and end users. 8948 8949 Of course, there are many possible ways by which GNU `gettext' might 8950be integrated in a distribution, and this chapter does not cover them 8951in all generality. Instead, it details one possible approach which is 8952especially adequate for many free software distributions following GNU 8953standards, or even better, Gnits standards, because GNU `gettext' is 8954purposely for helping the internationalization of the whole GNU 8955project, and as many other good free packages as possible. So, the 8956maintainer's view presented here presumes that the package already has 8957a `configure.ac' file and uses GNU Autoconf. 8958 8959 Nevertheless, GNU `gettext' may surely be useful for free packages 8960not following GNU standards and conventions, but the maintainers of such 8961packages might have to show imagination and initiative in organizing 8962their distributions so `gettext' work for them in all situations. 8963There are surely many, out there. 8964 8965 Even if `gettext' methods are now stabilizing, slight adjustments 8966might be needed between successive `gettext' versions, so you should 8967ideally revise this chapter in subsequent releases, looking for changes. 8968 8969* Menu: 8970 8971* Flat and Non-Flat:: Flat or Non-Flat Directory Structures 8972* Prerequisites:: Prerequisite Works 8973* gettextize Invocation:: Invoking the `gettextize' Program 8974* Adjusting Files:: Files You Must Create or Alter 8975* autoconf macros:: Autoconf macros for use in `configure.ac' 8976* CVS Issues:: Integrating with CVS 8977* Release Management:: Creating a Distribution Tarball 8978 8979 8980File: gettext.info, Node: Flat and Non-Flat, Next: Prerequisites, Prev: Maintainers, Up: Maintainers 8981 898213.1 Flat or Non-Flat Directory Structures 8983========================================== 8984 8985 Some free software packages are distributed as `tar' files which 8986unpack in a single directory, these are said to be "flat" distributions. 8987Other free software packages have a one level hierarchy of 8988subdirectories, using for example a subdirectory named `doc/' for the 8989Texinfo manual and man pages, another called `lib/' for holding 8990functions meant to replace or complement C libraries, and a 8991subdirectory `src/' for holding the proper sources for the package. 8992These other distributions are said to be "non-flat". 8993 8994 We cannot say much about flat distributions. A flat directory 8995structure has the disadvantage of increasing the difficulty of updating 8996to a new version of GNU `gettext'. Also, if you have many PO files, 8997this could somewhat pollute your single directory. Also, GNU 8998`gettext''s libintl sources consist of C sources, shell scripts, `sed' 8999scripts and complicated Makefile rules, which don't fit well into an 9000existing flat structure. For these reasons, we recommend to use 9001non-flat approach in this case as well. 9002 9003 Maybe because GNU `gettext' itself has a non-flat structure, we have 9004more experience with this approach, and this is what will be described 9005in the remaining of this chapter. Some maintainers might use this as 9006an opportunity to unflatten their package structure. 9007 9008 9009File: gettext.info, Node: Prerequisites, Next: gettextize Invocation, Prev: Flat and Non-Flat, Up: Maintainers 9010 901113.2 Prerequisite Works 9012======================= 9013 9014 There are some works which are required for using GNU `gettext' in 9015one of your package. These works have some kind of generality that 9016escape the point by point descriptions used in the remainder of this 9017chapter. So, we describe them here. 9018 9019 * Before attempting to use `gettextize' you should install some 9020 other packages first. Ensure that recent versions of GNU `m4', 9021 GNU Autoconf and GNU `gettext' are already installed at your site, 9022 and if not, proceed to do this first. If you get to install these 9023 things, beware that GNU `m4' must be fully installed before GNU 9024 Autoconf is even _configured_. 9025 9026 To further ease the task of a package maintainer the `automake' 9027 package was designed and implemented. GNU `gettext' now uses this 9028 tool and the `Makefile's in the `intl/' and `po/' therefore know 9029 about all the goals necessary for using `automake' and `libintl' 9030 in one project. 9031 9032 Those four packages are only needed by you, as a maintainer; the 9033 installers of your own package and end users do not really need 9034 any of GNU `m4', GNU Autoconf, GNU `gettext', or GNU `automake' 9035 for successfully installing and running your package, with messages 9036 properly translated. But this is not completely true if you 9037 provide internationalized shell scripts within your own package: 9038 GNU `gettext' shall then be installed at the user site if the end 9039 users want to see the translation of shell script messages. 9040 9041 * Your package should use Autoconf and have a `configure.ac' or 9042 `configure.in' file. If it does not, you have to learn how. The 9043 Autoconf documentation is quite well written, it is a good idea 9044 that you print it and get familiar with it. 9045 9046 * Your C sources should have already been modified according to 9047 instructions given earlier in this manual. *Note Sources::. 9048 9049 * Your `po/' directory should receive all PO files submitted to you 9050 by the translator teams, each having `LL.po' as a name. This is 9051 not usually easy to get translation work done before your package 9052 gets internationalized and available! Since the cycle has to 9053 start somewhere, the easiest for the maintainer is to start with 9054 absolutely no PO files, and wait until various translator teams 9055 get interested in your package, and submit PO files. 9056 9057 9058 It is worth adding here a few words about how the maintainer should 9059ideally behave with PO files submissions. As a maintainer, your role is 9060to authenticate the origin of the submission as being the representative 9061of the appropriate translating teams of the Translation Project (forward 9062the submission to `coordinator@translationproject.org' in case of 9063doubt), to ensure that the PO file format is not severely broken and 9064does not prevent successful installation, and for the rest, to merely 9065put these PO files in `po/' for distribution. 9066 9067 As a maintainer, you do not have to take on your shoulders the 9068responsibility of checking if the translations are adequate or 9069complete, and should avoid diving into linguistic matters. Translation 9070teams drive themselves and are fully responsible of their linguistic 9071choices for the Translation Project. Keep in mind that translator 9072teams are _not_ driven by maintainers. You can help by carefully 9073redirecting all communications and reports from users about linguistic 9074matters to the appropriate translation team, or explain users how to 9075reach or join their team. The simplest might be to send them the 9076`ABOUT-NLS' file. 9077 9078 Maintainers should _never ever_ apply PO file bug reports 9079themselves, short-cutting translation teams. If some translator has 9080difficulty to get some of her points through her team, it should not be 9081an option for her to directly negotiate translations with maintainers. 9082Teams ought to settle their problems themselves, if any. If you, as a 9083maintainer, ever think there is a real problem with a team, please 9084never try to _solve_ a team's problem on your own. 9085 9086 9087File: gettext.info, Node: gettextize Invocation, Next: Adjusting Files, Prev: Prerequisites, Up: Maintainers 9088 908913.3 Invoking the `gettextize' Program 9090====================================== 9091 9092 The `gettextize' program is an interactive tool that helps the 9093maintainer of a package internationalized through GNU `gettext'. It is 9094used for two purposes: 9095 9096 * As a wizard, when a package is modified to use GNU `gettext' for 9097 the first time. 9098 9099 * As a migration tool, for upgrading the GNU `gettext' support in a 9100 package from a previous to a newer version of GNU `gettext'. 9101 9102 This program performs the following tasks: 9103 9104 * It copies into the package some files that are consistently and 9105 identically needed in every package internationalized through GNU 9106 `gettext'. 9107 9108 * It performs as many of the tasks mentioned in the next section 9109 *note Adjusting Files:: as can be performed automatically. 9110 9111 * It removes obsolete files and idioms used for previous GNU 9112 `gettext' versions to the form recommended for the current GNU 9113 `gettext' version. 9114 9115 * It prints a summary of the tasks that ought to be done manually 9116 and could not be done automatically by `gettextize'. 9117 9118 It can be invoked as follows: 9119 9120 gettextize [ OPTION... ] [ DIRECTORY ] 9121 9122and accepts the following options: 9123 9124`-f' 9125`--force' 9126 Force replacement of files which already exist. 9127 9128`--intl' 9129 Install the libintl sources in a subdirectory named `intl/'. This 9130 libintl will be used to provide internationalization on systems 9131 that don't have GNU libintl installed. If this option is omitted, 9132 the call to `AM_GNU_GETTEXT' in `configure.ac' should read: 9133 `AM_GNU_GETTEXT([external])', and internationalization will not be 9134 enabled on systems lacking GNU gettext. 9135 9136`--po-dir=DIR' 9137 Specify a directory containing PO files. Such a directory 9138 contains the translations into various languages of a particular 9139 POT file. This option can be specified multiple times, once for 9140 each translation domain. If it is not specified, the directory 9141 named `po/' is updated. 9142 9143`--no-changelog' 9144 Don't update or create ChangeLog files. By default, `gettextize' 9145 logs all changes (file additions, modifications and removals) in a 9146 file called `ChangeLog' in each affected directory. 9147 9148`--symlink' 9149 Make symbolic links instead of copying the needed files. This can 9150 be useful to save a few kilobytes of disk space, but it requires 9151 extra effort to create self-contained tarballs, it may disturb 9152 some mechanism the maintainer applies to the sources, and it is 9153 likely to introduce bugs when a newer version of `gettext' is 9154 installed on the system. 9155 9156`-n' 9157`--dry-run' 9158 Print modifications but don't perform them. All actions that 9159 `gettextize' would normally execute are inhibited and instead only 9160 listed on standard output. 9161 9162`--help' 9163 Display this help and exit. 9164 9165`--version' 9166 Output version information and exit. 9167 9168 9169 If DIRECTORY is given, this is the top level directory of a package 9170to prepare for using GNU `gettext'. If not given, it is assumed that 9171the current directory is the top level directory of such a package. 9172 9173 The program `gettextize' provides the following files. However, no 9174existing file will be replaced unless the option `--force' (`-f') is 9175specified. 9176 9177 1. The `ABOUT-NLS' file is copied in the main directory of your 9178 package, the one being at the top level. This file gives the main 9179 indications about how to install and use the Native Language 9180 Support features of your program. You might elect to use a more 9181 recent copy of this `ABOUT-NLS' file than the one provided through 9182 `gettextize', if you have one handy. You may also fetch a more 9183 recent copy of file `ABOUT-NLS' from Translation Project sites, 9184 and from most GNU archive sites. 9185 9186 2. A `po/' directory is created for eventually holding all 9187 translation files, but initially only containing the file 9188 `po/Makefile.in.in' from the GNU `gettext' distribution (beware 9189 the double `.in' in the file name) and a few auxiliary files. If 9190 the `po/' directory already exists, it will be preserved along 9191 with the files it contains, and only `Makefile.in.in' and the 9192 auxiliary files will be overwritten. 9193 9194 If `--po-dir' has been specified, this holds for every directory 9195 specified through `--po-dir', instead of `po/'. 9196 9197 3. Only if `--intl' has been specified: A `intl/' directory is 9198 created and filled with most of the files originally in the 9199 `intl/' directory of the GNU `gettext' distribution. Also, if 9200 option `--force' (`-f') is given, the `intl/' directory is emptied 9201 first. 9202 9203 4. The file `config.rpath' is copied into the directory containing 9204 configuration support files. It is needed by the `AM_GNU_GETTEXT' 9205 autoconf macro. 9206 9207 5. Only if the project is using GNU `automake': A set of `autoconf' 9208 macro files is copied into the package's `autoconf' macro 9209 repository, usually in a directory called `m4/'. 9210 9211 If your site support symbolic links, `gettextize' will not actually 9212copy the files into your package, but establish symbolic links instead. 9213This avoids duplicating the disk space needed in all packages. Merely 9214using the `-h' option while creating the `tar' archive of your 9215distribution will resolve each link by an actual copy in the 9216distribution archive. So, to insist, you really should use `-h' option 9217with `tar' within your `dist' goal of your main `Makefile.in'. 9218 9219 Furthermore, `gettextize' will update all `Makefile.am' files in 9220each affected directory, as well as the top level `configure.ac' or 9221`configure.in' file. 9222 9223 It is interesting to understand that most new files for supporting 9224GNU `gettext' facilities in one package go in `intl/', `po/' and `m4/' 9225subdirectories. One distinction between `intl/' and the two other 9226directories is that `intl/' is meant to be completely identical in all 9227packages using GNU `gettext', while the other directories will mostly 9228contain package dependent files. 9229 9230 The `gettextize' program makes backup files for all files it 9231replaces or changes, and also write ChangeLog entries about these 9232changes. This way, the careful maintainer can check after running 9233`gettextize' whether its changes are acceptable to him, and possibly 9234adjust them. An exception to this rule is the `intl/' directory, which 9235is added or replaced or removed as a whole. 9236 9237 It is important to understand that `gettextize' can not do the 9238entire job of adapting a package for using GNU `gettext'. The amount 9239of remaining work depends on whether the package uses GNU `automake' or 9240not. But in any case, the maintainer should still read the section 9241*note Adjusting Files:: after invoking `gettextize'. 9242 9243 In particular, if after using `gettexize', you get an error 9244`AC_COMPILE_IFELSE was called before AC_GNU_SOURCE' or `AC_RUN_IFELSE 9245was called before AC_GNU_SOURCE', you can fix it by modifying 9246`configure.ac', as described in *note configure.ac::. 9247 9248 It is also important to understand that `gettextize' is not part of 9249the GNU build system, in the sense that it should not be invoked 9250automatically, and not be invoked by someone who doesn't assume the 9251responsibilities of a package maintainer. For the latter purpose, a 9252separate tool is provided, see *note autopoint Invocation::. 9253 9254 9255File: gettext.info, Node: Adjusting Files, Next: autoconf macros, Prev: gettextize Invocation, Up: Maintainers 9256 925713.4 Files You Must Create or Alter 9258=================================== 9259 9260 Besides files which are automatically added through `gettextize', 9261there are many files needing revision for properly interacting with GNU 9262`gettext'. If you are closely following GNU standards for Makefile 9263engineering and auto-configuration, the adaptations should be easier to 9264achieve. Here is a point by point description of the changes needed in 9265each. 9266 9267 So, here comes a list of files, each one followed by a description of 9268all alterations it needs. Many examples are taken out from the GNU 9269`gettext' 0.17 distribution itself, or from the GNU `hello' 9270distribution (`http://www.franken.de/users/gnu/ke/hello' or 9271`http://www.gnu.franken.de/ke/hello/') You may indeed refer to the 9272source code of the GNU `gettext' and GNU `hello' packages, as they are 9273intended to be good examples for using GNU gettext functionality. 9274 9275* Menu: 9276 9277* po/POTFILES.in:: `POTFILES.in' in `po/' 9278* po/LINGUAS:: `LINGUAS' in `po/' 9279* po/Makevars:: `Makevars' in `po/' 9280* po/Rules-*:: Extending `Makefile' in `po/' 9281* configure.ac:: `configure.ac' at top level 9282* config.guess:: `config.guess', `config.sub' at top level 9283* mkinstalldirs:: `mkinstalldirs' at top level 9284* aclocal:: `aclocal.m4' at top level 9285* acconfig:: `acconfig.h' at top level 9286* config.h.in:: `config.h.in' at top level 9287* Makefile:: `Makefile.in' at top level 9288* src/Makefile:: `Makefile.in' in `src/' 9289* lib/gettext.h:: `gettext.h' in `lib/' 9290 9291 9292File: gettext.info, Node: po/POTFILES.in, Next: po/LINGUAS, Prev: Adjusting Files, Up: Adjusting Files 9293 929413.4.1 `POTFILES.in' in `po/' 9295----------------------------- 9296 9297 The `po/' directory should receive a file named `POTFILES.in'. This 9298file tells which files, among all program sources, have marked strings 9299needing translation. Here is an example of such a file: 9300 9301 # List of source files containing translatable strings. 9302 # Copyright (C) 1995 Free Software Foundation, Inc. 9303 9304 # Common library files 9305 lib/error.c 9306 lib/getopt.c 9307 lib/xmalloc.c 9308 9309 # Package source files 9310 src/gettext.c 9311 src/msgfmt.c 9312 src/xgettext.c 9313 9314Hash-marked comments and white lines are ignored. All other lines list 9315those source files containing strings marked for translation (*note 9316Mark Keywords::), in a notation relative to the top level of your whole 9317distribution, rather than the location of the `POTFILES.in' file itself. 9318 9319 When a C file is automatically generated by a tool, like `flex' or 9320`bison', that doesn't introduce translatable strings by itself, it is 9321recommended to list in `po/POTFILES.in' the real source file (ending in 9322`.l' in the case of `flex', or in `.y' in the case of `bison'), not the 9323generated C file. 9324 9325 9326File: gettext.info, Node: po/LINGUAS, Next: po/Makevars, Prev: po/POTFILES.in, Up: Adjusting Files 9327 932813.4.2 `LINGUAS' in `po/' 9329------------------------- 9330 9331 The `po/' directory should also receive a file named `LINGUAS'. 9332This file contains the list of available translations. It is a 9333whitespace separated list. Hash-marked comments and white lines are 9334ignored. Here is an example file: 9335 9336 # Set of available languages. 9337 de fr 9338 9339This example means that German and French PO files are available, so 9340that these languages are currently supported by your package. If you 9341want to further restrict, at installation time, the set of installed 9342languages, this should not be done by modifying the `LINGUAS' file, but 9343rather by using the `LINGUAS' environment variable (*note Installers::). 9344 9345 It is recommended that you add the "languages" `en@quot' and 9346`en@boldquot' to the `LINGUAS' file. `en@quot' is a variant of English 9347message catalogs (`en') which uses real quotation marks instead of the 9348ugly looking asymmetric ASCII substitutes ``' and `''. `en@boldquot' 9349is a variant of `en@quot' that additionally outputs quoted pieces of 9350text in a bold font, when used in a terminal emulator which supports 9351the VT100 escape sequences (such as `xterm' or the Linux console, but 9352not Emacs in `M-x shell' mode). 9353 9354 These extra message catalogs `en@quot' and `en@boldquot' are 9355constructed automatically, not by translators; to support them, you 9356need the files `Rules-quot', `quot.sed', `boldquot.sed', 9357`en@quot.header', `en@boldquot.header', `insert-header.sin' in the 9358`po/' directory. You can copy them from GNU gettext's `po/' directory; 9359they are also installed by running `gettextize'. 9360 9361 9362File: gettext.info, Node: po/Makevars, Next: po/Rules-*, Prev: po/LINGUAS, Up: Adjusting Files 9363 936413.4.3 `Makevars' in `po/' 9365-------------------------- 9366 9367 The `po/' directory also has a file named `Makevars'. It contains 9368variables that are specific to your project. `po/Makevars' gets 9369inserted into the `po/Makefile' when the latter is created. The 9370variables thus take effect when the POT file is created or updated, and 9371when the message catalogs get installed. 9372 9373 The first three variables can be left unmodified if your package has 9374a single message domain and, accordingly, a single `po/' directory. 9375Only packages which have multiple `po/' directories at different 9376locations need to adjust the three first variables defined in 9377`Makevars'. 9378 9379 As an alternative to the `XGETTEXT_OPTIONS' variables, it is also 9380possible to specify `xgettext' options through the `AM_XGETTEXT_OPTION' 9381autoconf macro. See *note AM_XGETTEXT_OPTION::. 9382 9383 9384File: gettext.info, Node: po/Rules-*, Next: configure.ac, Prev: po/Makevars, Up: Adjusting Files 9385 938613.4.4 Extending `Makefile' in `po/' 9387------------------------------------ 9388 9389 All files called `Rules-*' in the `po/' directory get appended to 9390the `po/Makefile' when it is created. They present an opportunity to 9391add rules for special PO files to the Makefile, without needing to mess 9392with `po/Makefile.in.in'. 9393 9394 GNU gettext comes with a `Rules-quot' file, containing rules for 9395building catalogs `en@quot.po' and `en@boldquot.po'. The effect of 9396`en@quot.po' is that people who set their `LANGUAGE' environment 9397variable to `en@quot' will get messages with proper looking symmetric 9398Unicode quotation marks instead of abusing the ASCII grave accent and 9399the ASCII apostrophe for indicating quotations. To enable this 9400catalog, simply add `en@quot' to the `po/LINGUAS' file. The effect of 9401`en@boldquot.po' is that people who set `LANGUAGE' to `en@boldquot' 9402will get not only proper quotation marks, but also the quoted text will 9403be shown in a bold font on terminals and consoles. This catalog is 9404useful only for command-line programs, not GUI programs. To enable it, 9405similarly add `en@boldquot' to the `po/LINGUAS' file. 9406 9407 Similarly, you can create rules for building message catalogs for the 9408`sr@latin' locale - Serbian written with the Latin alphabet - from 9409those for the `sr' locale - Serbian written with Cyrillic letters. See 9410*note msgfilter Invocation::. 9411 9412 9413File: gettext.info, Node: configure.ac, Next: config.guess, Prev: po/Rules-*, Up: Adjusting Files 9414 941513.4.5 `configure.ac' at top level 9416---------------------------------- 9417 9418 `configure.ac' or `configure.in' - this is the source from which 9419`autoconf' generates the `configure' script. 9420 9421 1. Declare the package and version. 9422 9423 This is done by a set of lines like these: 9424 9425 PACKAGE=gettext 9426 VERSION=0.17 9427 AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE") 9428 AC_DEFINE_UNQUOTED(VERSION, "$VERSION") 9429 AC_SUBST(PACKAGE) 9430 AC_SUBST(VERSION) 9431 9432 or, if you are using GNU `automake', by a line like this: 9433 9434 AM_INIT_AUTOMAKE(gettext, 0.17) 9435 9436 Of course, you replace `gettext' with the name of your package, 9437 and `0.17' by its version numbers, exactly as they should appear 9438 in the packaged `tar' file name of your distribution 9439 (`gettext-0.17.tar.gz', here). 9440 9441 2. Check for internationalization support. 9442 9443 Here is the main `m4' macro for triggering internationalization 9444 support. Just add this line to `configure.ac': 9445 9446 AM_GNU_GETTEXT 9447 9448 This call is purposely simple, even if it generates a lot of 9449 configure time checking and actions. 9450 9451 If you have suppressed the `intl/' subdirectory by calling 9452 `gettextize' without `--intl' option, this call should read 9453 9454 AM_GNU_GETTEXT([external]) 9455 9456 3. Have output files created. 9457 9458 The `AC_OUTPUT' directive, at the end of your `configure.ac' file, 9459 needs to be modified in two ways: 9460 9461 AC_OUTPUT([EXISTING CONFIGURATION FILES intl/Makefile po/Makefile.in], 9462 [EXISTING ADDITIONAL ACTIONS]) 9463 9464 The modification to the first argument to `AC_OUTPUT' asks for 9465 substitution in the `intl/' and `po/' directories. Note the `.in' 9466 suffix used for `po/' only. This is because the distributed file 9467 is really `po/Makefile.in.in'. 9468 9469 If you have suppressed the `intl/' subdirectory by calling 9470 `gettextize' without `--intl' option, then you don't need to add 9471 `intl/Makefile' to the `AC_OUTPUT' line. 9472 9473 9474 If, after doing the recommended modifications, a command like 9475`aclocal -I m4' or `autoconf' or `autoreconf' fails with a trace 9476similar to this: 9477 9478 configure.ac:44: warning: AC_COMPILE_IFELSE was called before AC_GNU_SOURCE 9479 ../../lib/autoconf/specific.m4:335: AC_GNU_SOURCE is expanded from... 9480 m4/lock.m4:224: gl_LOCK is expanded from... 9481 m4/gettext.m4:571: gt_INTL_SUBDIR_CORE is expanded from... 9482 m4/gettext.m4:472: AM_INTL_SUBDIR is expanded from... 9483 m4/gettext.m4:347: AM_GNU_GETTEXT is expanded from... 9484 configure.ac:44: the top level 9485 configure.ac:44: warning: AC_RUN_IFELSE was called before AC_GNU_SOURCE 9486 9487you need to add an explicit invocation of `AC_GNU_SOURCE' in the 9488`configure.ac' file - after `AC_PROG_CC' but before `AM_GNU_GETTEXT', 9489most likely very close to the `AC_PROG_CC' invocation. This is 9490necessary because of ordering restrictions imposed by GNU autoconf. 9491 9492 9493File: gettext.info, Node: config.guess, Next: mkinstalldirs, Prev: configure.ac, Up: Adjusting Files 9494 949513.4.6 `config.guess', `config.sub' at top level 9496------------------------------------------------ 9497 9498 If you haven't suppressed the `intl/' subdirectory, you need to add 9499the GNU `config.guess' and `config.sub' files to your distribution. 9500They are needed because the `intl/' directory has platform dependent 9501support for determining the locale's character encoding and therefore 9502needs to identify the platform. 9503 9504 You can obtain the newest version of `config.guess' and `config.sub' 9505from the CVS of the `config' project at `http://savannah.gnu.org/'. The 9506commands to fetch them are 9507 $ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.guess' 9508 $ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.sub' 9509 Less recent versions are also contained in the GNU `automake' and 9510GNU `libtool' packages. 9511 9512 Normally, `config.guess' and `config.sub' are put at the top level 9513of a distribution. But it is also possible to put them in a 9514subdirectory, altogether with other configuration support files like 9515`install-sh', `ltconfig', `ltmain.sh' or `missing'. All you need to 9516do, other than moving the files, is to add the following line to your 9517`configure.ac'. 9518 9519 AC_CONFIG_AUX_DIR([SUBDIR]) 9520 9521 9522File: gettext.info, Node: mkinstalldirs, Next: aclocal, Prev: config.guess, Up: Adjusting Files 9523 952413.4.7 `mkinstalldirs' at top level 9525----------------------------------- 9526 9527 With earlier versions of GNU gettext, you needed to add the GNU 9528`mkinstalldirs' script to your distribution. This is not needed any 9529more. You can remove it if you not also using an automake version 9530older than automake 1.9. 9531 9532 9533File: gettext.info, Node: aclocal, Next: acconfig, Prev: mkinstalldirs, Up: Adjusting Files 9534 953513.4.8 `aclocal.m4' at top level 9536-------------------------------- 9537 9538 If you do not have an `aclocal.m4' file in your distribution, the 9539simplest is to concatenate the files `codeset.m4', `gettext.m4', 9540`glibc2.m4', `glibc21.m4', `iconv.m4', `intdiv0.m4', `intl.m4', 9541`intldir.m4', `intlmacosx.m4', `intmax.m4', `inttypes_h.m4', 9542`inttypes-pri.m4', `lcmessage.m4', `lib-ld.m4', `lib-link.m4', 9543`lib-prefix.m4', `lock.m4', `longlong.m4', `nls.m4', `po.m4', 9544`printf-posix.m4', `progtest.m4', `size_max.m4', `stdint_h.m4', 9545`uintmax_t.m4', `visibility.m4', `wchar_t.m4', `wint_t.m4', `xsize.m4' 9546from GNU `gettext''s `m4/' directory into a single file. If you have 9547suppressed the `intl/' directory, only `gettext.m4', `iconv.m4', 9548`lib-ld.m4', `lib-link.m4', `lib-prefix.m4', `nls.m4', `po.m4', 9549`progtest.m4' need to be concatenated. 9550 9551 If you are not using GNU `automake' 1.8 or newer, you will need to 9552add a file `mkdirp.m4' from a newer automake distribution to the list 9553of files above. 9554 9555 If you already have an `aclocal.m4' file, then you will have to 9556merge the said macro files into your `aclocal.m4'. Note that if you 9557are upgrading from a previous release of GNU `gettext', you should most 9558probably _replace_ the macros (`AM_GNU_GETTEXT', etc.), as they usually 9559change a little from one release of GNU `gettext' to the next. Their 9560contents may vary as we get more experience with strange systems out 9561there. 9562 9563 If you are using GNU `automake' 1.5 or newer, it is enough to put 9564these macro files into a subdirectory named `m4/' and add the line 9565 9566 ACLOCAL_AMFLAGS = -I m4 9567 9568to your top level `Makefile.am'. 9569 9570 These macros check for the internationalization support functions 9571and related informations. Hopefully, once stabilized, these macros 9572might be integrated in the standard Autoconf set, because this piece of 9573`m4' code will be the same for all projects using GNU `gettext'. 9574 9575 9576File: gettext.info, Node: acconfig, Next: config.h.in, Prev: aclocal, Up: Adjusting Files 9577 957813.4.9 `acconfig.h' at top level 9579-------------------------------- 9580 9581 Earlier GNU `gettext' releases required to put definitions for 9582`ENABLE_NLS', `HAVE_GETTEXT' and `HAVE_LC_MESSAGES', `HAVE_STPCPY', 9583`PACKAGE' and `VERSION' into an `acconfig.h' file. This is not needed 9584any more; you can remove them from your `acconfig.h' file unless your 9585package uses them independently from the `intl/' directory. 9586 9587 9588File: gettext.info, Node: config.h.in, Next: Makefile, Prev: acconfig, Up: Adjusting Files 9589 959013.4.10 `config.h.in' at top level 9591---------------------------------- 9592 9593 The include file template that holds the C macros to be defined by 9594`configure' is usually called `config.h.in' and may be maintained 9595either manually or automatically. 9596 9597 If `gettextize' has created an `intl/' directory, this file must be 9598called `config.h.in' and must be at the top level. If, however, you 9599have suppressed the `intl/' directory by calling `gettextize' without 9600`--intl' option, then you can choose the name of this file and its 9601location freely. 9602 9603 If it is maintained automatically, by use of the `autoheader' 9604program, you need to do nothing about it. This is the case in 9605particular if you are using GNU `automake'. 9606 9607 If it is maintained manually, and if `gettextize' has created an 9608`intl/' directory, you should switch to using `autoheader'. The list 9609of C macros to be added for the sake of the `intl/' directory is just 9610too long to be maintained manually; it also changes between different 9611versions of GNU `gettext'. 9612 9613 If it is maintained manually, and if on the other hand you have 9614suppressed the `intl/' directory by calling `gettextize' without 9615`--intl' option, then you can get away by adding the following lines to 9616`config.h.in': 9617 9618 /* Define to 1 if translation of program messages to the user's 9619 native language is requested. */ 9620 #undef ENABLE_NLS 9621 9622 9623File: gettext.info, Node: Makefile, Next: src/Makefile, Prev: config.h.in, Up: Adjusting Files 9624 962513.4.11 `Makefile.in' at top level 9626---------------------------------- 9627 9628 Here are a few modifications you need to make to your main, top-level 9629`Makefile.in' file. 9630 9631 1. Add the following lines near the beginning of your `Makefile.in', 9632 so the `dist:' goal will work properly (as explained further down): 9633 9634 PACKAGE = @PACKAGE@ 9635 VERSION = @VERSION@ 9636 9637 2. Add file `ABOUT-NLS' to the `DISTFILES' definition, so the file 9638 gets distributed. 9639 9640 3. Wherever you process subdirectories in your `Makefile.in', be sure 9641 you also process the subdirectories `intl' and `po'. Special 9642 rules in the `Makefiles' take care for the case where no 9643 internationalization is wanted. 9644 9645 If you are using Makefiles, either generated by automake, or 9646 hand-written so they carefully follow the GNU coding standards, 9647 the effected goals for which the new subdirectories must be 9648 handled include `installdirs', `install', `uninstall', `clean', 9649 `distclean'. 9650 9651 Here is an example of a canonical order of processing. In this 9652 example, we also define `SUBDIRS' in `Makefile.in' for it to be 9653 further used in the `dist:' goal. 9654 9655 SUBDIRS = doc intl lib src po 9656 9657 Note that you must arrange for `make' to descend into the `intl' 9658 directory before descending into other directories containing code 9659 which make use of the `libintl.h' header file. For this reason, 9660 here we mention `intl' before `lib' and `src'. 9661 9662 4. A delicate point is the `dist:' goal, as both `intl/Makefile' and 9663 `po/Makefile' will later assume that the proper directory has been 9664 set up from the main `Makefile'. Here is an example at what the 9665 `dist:' goal might look like: 9666 9667 distdir = $(PACKAGE)-$(VERSION) 9668 dist: Makefile 9669 rm -fr $(distdir) 9670 mkdir $(distdir) 9671 chmod 777 $(distdir) 9672 for file in $(DISTFILES); do \ 9673 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \ 9674 done 9675 for subdir in $(SUBDIRS); do \ 9676 mkdir $(distdir)/$$subdir || exit 1; \ 9677 chmod 777 $(distdir)/$$subdir; \ 9678 (cd $$subdir && $(MAKE) $@) || exit 1; \ 9679 done 9680 tar chozf $(distdir).tar.gz $(distdir) 9681 rm -fr $(distdir) 9682 9683 9684 Note that if you are using GNU `automake', `Makefile.in' is 9685automatically generated from `Makefile.am', and all needed changes to 9686`Makefile.am' are already made by running `gettextize'. 9687 9688 9689File: gettext.info, Node: src/Makefile, Next: lib/gettext.h, Prev: Makefile, Up: Adjusting Files 9690 969113.4.12 `Makefile.in' in `src/' 9692------------------------------- 9693 9694 Some of the modifications made in the main `Makefile.in' will also 9695be needed in the `Makefile.in' from your package sources, which we 9696assume here to be in the `src/' subdirectory. Here are all the 9697modifications needed in `src/Makefile.in': 9698 9699 1. In view of the `dist:' goal, you should have these lines near the 9700 beginning of `src/Makefile.in': 9701 9702 PACKAGE = @PACKAGE@ 9703 VERSION = @VERSION@ 9704 9705 2. If not done already, you should guarantee that `top_srcdir' gets 9706 defined. This will serve for `cpp' include files. Just add the 9707 line: 9708 9709 top_srcdir = @top_srcdir@ 9710 9711 3. You might also want to define `subdir' as `src', later allowing 9712 for almost uniform `dist:' goals in all your `Makefile.in'. At 9713 list, the `dist:' goal below assume that you used: 9714 9715 subdir = src 9716 9717 4. The `main' function of your program will normally call 9718 `bindtextdomain' (see *note Triggering::), like this: 9719 9720 bindtextdomain (PACKAGE, LOCALEDIR); 9721 textdomain (PACKAGE); 9722 9723 To make LOCALEDIR known to the program, add the following lines to 9724 `Makefile.in': 9725 9726 datadir = @datadir@ 9727 localedir = $(datadir)/locale 9728 DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@ 9729 9730 Note that `@datadir@' defaults to `$(prefix)/share', thus 9731 `$(localedir)' defaults to `$(prefix)/share/locale'. 9732 9733 5. You should ensure that the final linking will use `@LIBINTL@' or 9734 `@LTLIBINTL@' as a library. `@LIBINTL@' is for use without 9735 `libtool', `@LTLIBINTL@' is for use with `libtool'. An easy way 9736 to achieve this is to manage that it gets into `LIBS', like this: 9737 9738 LIBS = @LIBINTL@ @LIBS@ 9739 9740 In most packages internationalized with GNU `gettext', one will 9741 find a directory `lib/' in which a library containing some helper 9742 functions will be build. (You need at least the few functions 9743 which the GNU `gettext' Library itself needs.) However some of 9744 the functions in the `lib/' also give messages to the user which 9745 of course should be translated, too. Taking care of this, the 9746 support library (say `libsupport.a') should be placed before 9747 `@LIBINTL@' and `@LIBS@' in the above example. So one has to 9748 write this: 9749 9750 LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@ 9751 9752 6. You should also ensure that directory `intl/' will be searched for 9753 C preprocessor include files in all circumstances. So, you have to 9754 manage so both `-I../intl' and `-I$(top_srcdir)/intl' will be 9755 given to the C compiler. 9756 9757 7. Your `dist:' goal has to conform with others. Here is a 9758 reasonable definition for it: 9759 9760 distdir = ../$(PACKAGE)-$(VERSION)/$(subdir) 9761 dist: Makefile $(DISTFILES) 9762 for file in $(DISTFILES); do \ 9763 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir) || exit 1; \ 9764 done 9765 9766 9767 Note that if you are using GNU `automake', `Makefile.in' is 9768automatically generated from `Makefile.am', and the first three changes 9769and the last change are not necessary. The remaining needed 9770`Makefile.am' modifications are the following: 9771 9772 1. To make LOCALEDIR known to the program, add the following to 9773 `Makefile.am': 9774 9775 <module>_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\" 9776 9777 for each specific module or compilation unit, or 9778 9779 AM_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\" 9780 9781 for all modules and compilation units together. Furthermore, add 9782 this line to define `localedir': 9783 9784 localedir = $(datadir)/locale 9785 9786 2. To ensure that the final linking will use `@LIBINTL@' or 9787 `@LTLIBINTL@' as a library, add the following to `Makefile.am': 9788 9789 <program>_LDADD = @LIBINTL@ 9790 9791 for each specific program, or 9792 9793 LDADD = @LIBINTL@ 9794 9795 for all programs together. Remember that when you use `libtool' 9796 to link a program, you need to use @LTLIBINTL@ instead of @LIBINTL@ 9797 for that program. 9798 9799 3. If you have an `intl/' directory, whose contents is created by 9800 `gettextize', then to ensure that it will be searched for C 9801 preprocessor include files in all circumstances, add something like 9802 this to `Makefile.am': 9803 9804 AM_CPPFLAGS = -I../intl -I$(top_srcdir)/intl 9805 9806 9807 9808File: gettext.info, Node: lib/gettext.h, Prev: src/Makefile, Up: Adjusting Files 9809 981013.4.13 `gettext.h' in `lib/' 9811----------------------------- 9812 9813 Internationalization of packages, as provided by GNU `gettext', is 9814optional. It can be turned off in two situations: 9815 9816 * When the installer has specified `./configure --disable-nls'. This 9817 can be useful when small binaries are more important than 9818 features, for example when building utilities for boot diskettes. 9819 It can also be useful in order to get some specific C compiler 9820 warnings about code quality with some older versions of GCC (older 9821 than 3.0). 9822 9823 * When the package does not include the `intl/' subdirectory, and the 9824 libintl.h header (with its associated libintl library, if any) is 9825 not already installed on the system, it is preferable that the 9826 package builds without internationalization support, rather than 9827 to give a compilation error. 9828 9829 A C preprocessor macro can be used to detect these two cases. 9830Usually, when `libintl.h' was found and not explicitly disabled, the 9831`ENABLE_NLS' macro will be defined to 1 in the autoconf generated 9832configuration file (usually called `config.h'). In the two negative 9833situations, however, this macro will not be defined, thus it will 9834evaluate to 0 in C preprocessor expressions. 9835 9836 `gettext.h' is a convenience header file for conditional use of 9837`<libintl.h>', depending on the `ENABLE_NLS' macro. If `ENABLE_NLS' is 9838set, it includes `<libintl.h>'; otherwise it defines no-op substitutes 9839for the libintl.h functions. We recommend the use of `"gettext.h"' 9840over direct use of `<libintl.h>', so that portability to older systems 9841is guaranteed and installers can turn off internationalization if they 9842want to. In the C code, you will then write 9843 9844 #include "gettext.h" 9845 9846instead of 9847 9848 #include <libintl.h> 9849 9850 The location of `gettext.h' is usually in a directory containing 9851auxiliary include files. In many GNU packages, there is a directory 9852`lib/' containing helper functions; `gettext.h' fits there. In other 9853packages, it can go into the `src' directory. 9854 9855 Do not install the `gettext.h' file in public locations. Every 9856package that needs it should contain a copy of it on its own. 9857 9858 9859File: gettext.info, Node: autoconf macros, Next: CVS Issues, Prev: Adjusting Files, Up: Maintainers 9860 986113.5 Autoconf macros for use in `configure.ac' 9862============================================== 9863 9864 GNU `gettext' installs macros for use in a package's `configure.ac' 9865or `configure.in'. *Note Introduction: (autoconf)Top. The primary 9866macro is, of course, `AM_GNU_GETTEXT'. 9867 9868* Menu: 9869 9870* AM_GNU_GETTEXT:: AM_GNU_GETTEXT in `gettext.m4' 9871* AM_GNU_GETTEXT_VERSION:: AM_GNU_GETTEXT_VERSION in `gettext.m4' 9872* AM_GNU_GETTEXT_NEED:: AM_GNU_GETTEXT_NEED in `gettext.m4' 9873* AM_GNU_GETTEXT_INTL_SUBDIR:: AM_GNU_GETTEXT_INTL_SUBDIR in `intldir.m4' 9874* AM_PO_SUBDIRS:: AM_PO_SUBDIRS in `po.m4' 9875* AM_XGETTEXT_OPTION:: AM_XGETTEXT_OPTION in `po.m4' 9876* AM_ICONV:: AM_ICONV in `iconv.m4' 9877 9878 9879File: gettext.info, Node: AM_GNU_GETTEXT, Next: AM_GNU_GETTEXT_VERSION, Prev: autoconf macros, Up: autoconf macros 9880 988113.5.1 AM_GNU_GETTEXT in `gettext.m4' 9882------------------------------------- 9883 9884 The `AM_GNU_GETTEXT' macro tests for the presence of the GNU gettext 9885function family in either the C library or a separate `libintl' library 9886(shared or static libraries are both supported) or in the package's 9887`intl/' directory. It also invokes `AM_PO_SUBDIRS', thus preparing the 9888`po/' directories of the package for building. 9889 9890 `AM_GNU_GETTEXT' accepts up to three optional arguments. The general 9891syntax is 9892 9893 AM_GNU_GETTEXT([INTLSYMBOL], [NEEDSYMBOL], [INTLDIR]) 9894 9895 INTLSYMBOL can be `external' or `no-libtool'. The default (if it is 9896not specified or empty) is `no-libtool'. INTLSYMBOL should be 9897`external' for packages with no `intl/' directory. For packages with 9898an `intl/' directory, you can either use an INTLSYMBOL equal to 9899`no-libtool', or you can use `external' and override by using the macro 9900`AM_GNU_GETTEXT_INTL_SUBDIR' elsewhere. The two ways to specify the 9901existence of an `intl/' directory are equivalent. At build time, a 9902static library `$(top_builddir)/intl/libintl.a' will then be created. 9903 9904 If NEEDSYMBOL is specified and is `need-ngettext', then GNU gettext 9905implementations (in libc or libintl) without the `ngettext()' function 9906will be ignored. If NEEDSYMBOL is specified and is 9907`need-formatstring-macros', then GNU gettext implementations that don't 9908support the ISO C 99 `<inttypes.h>' formatstring macros will be ignored. 9909Only one NEEDSYMBOL can be specified. These requirements can also be 9910specified by using the macro `AM_GNU_GETTEXT_NEED' elsewhere. To 9911specify more than one requirement, just specify the strongest one among 9912them, or invoke the `AM_GNU_GETTEXT_NEED' macro several times. The 9913hierarchy among the various alternatives is as follows: 9914`need-formatstring-macros' implies `need-ngettext'. 9915 9916 INTLDIR is used to find the intl libraries. If empty, the value 9917`$(top_builddir)/intl/' is used. 9918 9919 The `AM_GNU_GETTEXT' macro determines whether GNU gettext is 9920available and should be used. If so, it sets the `USE_NLS' variable to 9921`yes'; it defines `ENABLE_NLS' to 1 in the autoconf generated 9922configuration file (usually called `config.h'); it sets the variables 9923`LIBINTL' and `LTLIBINTL' to the linker options for use in a Makefile 9924(`LIBINTL' for use without libtool, `LTLIBINTL' for use with libtool); 9925it adds an `-I' option to `CPPFLAGS' if necessary. In the negative 9926case, it sets `USE_NLS' to `no'; it sets `LIBINTL' and `LTLIBINTL' to 9927empty and doesn't change `CPPFLAGS'. 9928 9929 The complexities that `AM_GNU_GETTEXT' deals with are the following: 9930 9931 * Some operating systems have `gettext' in the C library, for example 9932 glibc. Some have it in a separate library `libintl'. GNU 9933 `libintl' might have been installed as part of the GNU `gettext' 9934 package. 9935 9936 * GNU `libintl', if installed, is not necessarily already in the 9937 search path (`CPPFLAGS' for the include file search path, 9938 `LDFLAGS' for the library search path). 9939 9940 * Except for glibc, the operating system's native `gettext' cannot 9941 exploit the GNU mo files, doesn't have the necessary locale 9942 dependency features, and cannot convert messages from the 9943 catalog's text encoding to the user's locale encoding. 9944 9945 * GNU `libintl', if installed, is not necessarily already in the run 9946 time library search path. To avoid the need for setting an 9947 environment variable like `LD_LIBRARY_PATH', the macro adds the 9948 appropriate run time search path options to the `LIBINTL' and 9949 `LTLIBINTL' variables. This works on most systems, but not on 9950 some operating systems with limited shared library support, like 9951 SCO. 9952 9953 * GNU `libintl' relies on POSIX/XSI `iconv'. The macro checks for 9954 linker options needed to use iconv and appends them to the 9955 `LIBINTL' and `LTLIBINTL' variables. 9956 9957 9958File: gettext.info, Node: AM_GNU_GETTEXT_VERSION, Next: AM_GNU_GETTEXT_NEED, Prev: AM_GNU_GETTEXT, Up: autoconf macros 9959 996013.5.2 AM_GNU_GETTEXT_VERSION in `gettext.m4' 9961--------------------------------------------- 9962 9963 The `AM_GNU_GETTEXT_VERSION' macro declares the version number of 9964the GNU gettext infrastructure that is used by the package. 9965 9966 The use of this macro is optional; only the `autopoint' program makes 9967use of it (*note CVS Issues::). 9968 9969 9970File: gettext.info, Node: AM_GNU_GETTEXT_NEED, Next: AM_GNU_GETTEXT_INTL_SUBDIR, Prev: AM_GNU_GETTEXT_VERSION, Up: autoconf macros 9971 997213.5.3 AM_GNU_GETTEXT_NEED in `gettext.m4' 9973------------------------------------------ 9974 9975 The `AM_GNU_GETTEXT_NEED' macro declares a constraint regarding the 9976GNU gettext implementation. The syntax is 9977 9978 AM_GNU_GETTEXT_NEED([NEEDSYMBOL]) 9979 9980 If NEEDSYMBOL is `need-ngettext', then GNU gettext implementations 9981(in libc or libintl) without the `ngettext()' function will be ignored. 9982If NEEDSYMBOL is `need-formatstring-macros', then GNU gettext 9983implementations that don't support the ISO C 99 `<inttypes.h>' 9984formatstring macros will be ignored. 9985 9986 The optional second argument of `AM_GNU_GETTEXT' is also taken into 9987account. 9988 9989 The `AM_GNU_GETTEXT_NEED' invocations can occur before or after the 9990`AM_GNU_GETTEXT' invocation; the order doesn't matter. 9991 9992 9993File: gettext.info, Node: AM_GNU_GETTEXT_INTL_SUBDIR, Next: AM_PO_SUBDIRS, Prev: AM_GNU_GETTEXT_NEED, Up: autoconf macros 9994 999513.5.4 AM_GNU_GETTEXT_INTL_SUBDIR in `intldir.m4' 9996------------------------------------------------- 9997 9998 The `AM_GNU_GETTEXT_INTL_SUBDIR' macro specifies that the 9999`AM_GNU_GETTEXT' macro, although invoked with the first argument 10000`external', should also prepare for building the `intl/' subdirectory. 10001 10002 The `AM_GNU_GETTEXT_INTL_SUBDIR' invocation can occur before or after 10003the `AM_GNU_GETTEXT' invocation; the order doesn't matter. 10004 10005 The use of this macro requires GNU automake 1.10 or newer and GNU 10006autoconf 2.61 or newer. 10007 10008 10009File: gettext.info, Node: AM_PO_SUBDIRS, Next: AM_XGETTEXT_OPTION, Prev: AM_GNU_GETTEXT_INTL_SUBDIR, Up: autoconf macros 10010 1001113.5.5 AM_PO_SUBDIRS in `po.m4' 10012------------------------------- 10013 10014 The `AM_PO_SUBDIRS' macro prepares the `po/' directories of the 10015package for building. This macro should be used in internationalized 10016programs written in other programming languages than C, C++, Objective 10017C, for example `sh', `Python', `Lisp'. See *note Programming 10018Languages:: for a list of programming languages that support 10019localization through PO files. 10020 10021 The `AM_PO_SUBDIRS' macro determines whether internationalization 10022should be used. If so, it sets the `USE_NLS' variable to `yes', 10023otherwise to `no'. It also determines the right values for Makefile 10024variables in each `po/' directory. 10025 10026 10027File: gettext.info, Node: AM_XGETTEXT_OPTION, Next: AM_ICONV, Prev: AM_PO_SUBDIRS, Up: autoconf macros 10028 1002913.5.6 AM_XGETTEXT_OPTION in `po.m4' 10030------------------------------------ 10031 10032 The `AM_XGETTEXT_OPTION' macro registers a command-line option to be 10033used in the invocations of `xgettext' in the `po/' directories of the 10034package. 10035 10036 For example, if you have a source file that defines a function 10037`error_at_line' whose fifth argument is a format string, you can use 10038 AM_XGETTEXT_OPTION([--flag=error_at_line:5:c-format]) 10039 to instruct `xgettext' to mark all translatable strings in `gettext' 10040invocations that occur as fifth argument to this function as `c-format'. 10041 10042 See *note xgettext Invocation:: for the list of options that 10043`xgettext' accepts. 10044 10045 The use of this macro is an alternative to the use of the 10046`XGETTEXT_OPTIONS' variable in `po/Makevars'. 10047 10048 10049File: gettext.info, Node: AM_ICONV, Prev: AM_XGETTEXT_OPTION, Up: autoconf macros 10050 1005113.5.7 AM_ICONV in `iconv.m4' 10052----------------------------- 10053 10054 The `AM_ICONV' macro tests for the presence of the POSIX/XSI `iconv' 10055function family in either the C library or a separate `libiconv' 10056library. If found, it sets the `am_cv_func_iconv' variable to `yes'; 10057it defines `HAVE_ICONV' to 1 in the autoconf generated configuration 10058file (usually called `config.h'); it defines `ICONV_CONST' to `const' 10059or to empty, depending on whether the second argument of `iconv()' is 10060of type `const char **' or `char **'; it sets the variables `LIBICONV' 10061and `LTLIBICONV' to the linker options for use in a Makefile 10062(`LIBICONV' for use without libtool, `LTLIBICONV' for use with 10063libtool); it adds an `-I' option to `CPPFLAGS' if necessary. If not 10064found, it sets `LIBICONV' and `LTLIBICONV' to empty and doesn't change 10065`CPPFLAGS'. 10066 10067 The complexities that `AM_ICONV' deals with are the following: 10068 10069 * Some operating systems have `iconv' in the C library, for example 10070 glibc. Some have it in a separate library `libiconv', for example 10071 OSF/1 or FreeBSD. Regardless of the operating system, GNU 10072 `libiconv' might have been installed. In that case, it should be 10073 used instead of the operating system's native `iconv'. 10074 10075 * GNU `libiconv', if installed, is not necessarily already in the 10076 search path (`CPPFLAGS' for the include file search path, 10077 `LDFLAGS' for the library search path). 10078 10079 * GNU `libiconv' is binary incompatible with some operating system's 10080 native `iconv', for example on FreeBSD. Use of an `iconv.h' and 10081 `libiconv.so' that don't fit together would produce program 10082 crashes. 10083 10084 * GNU `libiconv', if installed, is not necessarily already in the 10085 run time library search path. To avoid the need for setting an 10086 environment variable like `LD_LIBRARY_PATH', the macro adds the 10087 appropriate run time search path options to the `LIBICONV' 10088 variable. This works on most systems, but not on some operating 10089 systems with limited shared library support, like SCO. 10090 10091 `iconv.m4' is distributed with the GNU gettext package because 10092`gettext.m4' relies on it. 10093 10094 10095File: gettext.info, Node: CVS Issues, Next: Release Management, Prev: autoconf macros, Up: Maintainers 10096 1009713.6 Integrating with CVS 10098========================= 10099 10100 Many projects use CVS for distributed development, version control 10101and source backup. This section gives some advice how to manage the 10102uses of `cvs', `gettextize', `autopoint' and `autoconf'. 10103 10104* Menu: 10105 10106* Distributed CVS:: Avoiding version mismatch in distributed development 10107* Files under CVS:: Files to put under CVS version control 10108* autopoint Invocation:: Invoking the `autopoint' Program 10109 10110 10111File: gettext.info, Node: Distributed CVS, Next: Files under CVS, Prev: CVS Issues, Up: CVS Issues 10112 1011313.6.1 Avoiding version mismatch in distributed development 10114----------------------------------------------------------- 10115 10116 In a project development with multiple developers, using CVS, there 10117should be a single developer who occasionally - when there is desire to 10118upgrade to a new `gettext' version - runs `gettextize' and performs the 10119changes listed in *note Adjusting Files::, and then commits his changes 10120to the CVS. 10121 10122 It is highly recommended that all developers on a project use the 10123same version of GNU `gettext' in the package. In other words, if a 10124developer runs `gettextize', he should go the whole way, make the 10125necessary remaining changes and commit his changes to the CVS. 10126Otherwise the following damages will likely occur: 10127 10128 * Apparent version mismatch between developers. Since some `gettext' 10129 specific portions in `configure.ac', `configure.in' and 10130 `Makefile.am', `Makefile.in' files depend on the `gettext' 10131 version, the use of infrastructure files belonging to different 10132 `gettext' versions can easily lead to build errors. 10133 10134 * Hidden version mismatch. Such version mismatch can also lead to 10135 malfunctioning of the package, that may be undiscovered by the 10136 developers. The worst case of hidden version mismatch is that 10137 internationalization of the package doesn't work at all. 10138 10139 * Release risks. All developers implicitly perform constant testing 10140 on a package. This is important in the days and weeks before a 10141 release. If the guy who makes the release tar files uses a 10142 different version of GNU `gettext' than the other developers, the 10143 distribution will be less well tested than if all had been using 10144 the same `gettext' version. For example, it is possible that a 10145 platform specific bug goes undiscovered due to this constellation. 10146 10147 10148File: gettext.info, Node: Files under CVS, Next: autopoint Invocation, Prev: Distributed CVS, Up: CVS Issues 10149 1015013.6.2 Files to put under CVS version control 10151--------------------------------------------- 10152 10153 There are basically three ways to deal with generated files in the 10154context of a CVS repository, such as `configure' generated from 10155`configure.ac', `PARSER.c' generated from `PARSER.y', or 10156`po/Makefile.in.in' autoinstalled by `gettextize' or `autopoint'. 10157 10158 1. All generated files are always committed into the repository. 10159 10160 2. All generated files are committed into the repository occasionally, 10161 for example each time a release is made. 10162 10163 3. Generated files are never committed into the repository. 10164 10165 Each of these three approaches has different advantages and 10166drawbacks. 10167 10168 1. The advantage is that anyone can check out the CVS at any moment 10169 and gets a working build. The drawbacks are: 1a. It requires 10170 some frequent "cvs commit" actions by the maintainers. 1b. The 10171 repository grows in size quite fast. 10172 10173 2. The advantage is that anyone can check out the CVS, and the usual 10174 "./configure; make" will work. The drawbacks are: 2a. The one who 10175 checks out the repository needs tools like GNU `automake', GNU 10176 `autoconf', GNU `m4' installed in his PATH; sometimes he even 10177 needs particular versions of them. 2b. When a release is made and 10178 a commit is made on the generated files, the other developers get 10179 conflicts on the generated files after doing "cvs update". 10180 Although these conflicts are easy to resolve, they are annoying. 10181 10182 3. The advantage is less work for the maintainers. The drawback is 10183 that anyone who checks out the CVS not only needs tools like GNU 10184 `automake', GNU `autoconf', GNU `m4' installed in his PATH, but 10185 also that he needs to perform a package specific pre-build step 10186 before being able to "./configure; make". 10187 10188 For the first and second approach, all files modified or brought in 10189by the occasional `gettextize' invocation and update should be 10190committed into the CVS. 10191 10192 For the third approach, the maintainer can omit from the CVS 10193repository all the files that `gettextize' mentions as "copy". 10194Instead, he adds to the `configure.ac' or `configure.in' a line of the 10195form 10196 10197 AM_GNU_GETTEXT_VERSION(0.17) 10198 10199and adds to the package's pre-build script an invocation of 10200`autopoint'. For everyone who checks out the CVS, this `autopoint' 10201invocation will copy into the right place the `gettext' infrastructure 10202files that have been omitted from the CVS. 10203 10204 The version number used as argument to `AM_GNU_GETTEXT_VERSION' is 10205the version of the `gettext' infrastructure that the package wants to 10206use. It is also the minimum version number of the `autopoint' program. 10207So, if you write `AM_GNU_GETTEXT_VERSION(0.11.5)' then the developers 10208can have any version >= 0.11.5 installed; the package will work with 10209the 0.11.5 infrastructure in all developers' builds. When the 10210maintainer then runs gettextize from, say, version 0.12.1 on the 10211package, the occurrence of `AM_GNU_GETTEXT_VERSION(0.11.5)' will be 10212changed into `AM_GNU_GETTEXT_VERSION(0.12.1)', and all other developers 10213that use the CVS will henceforth need to have GNU `gettext' 0.12.1 or 10214newer installed. 10215 10216 10217File: gettext.info, Node: autopoint Invocation, Prev: Files under CVS, Up: CVS Issues 10218 1021913.6.3 Invoking the `autopoint' Program 10220--------------------------------------- 10221 10222 autopoint [OPTION]... 10223 10224 The `autopoint' program copies standard gettext infrastructure files 10225into a source package. It extracts from a macro call of the form 10226`AM_GNU_GETTEXT_VERSION(VERSION)', found in the package's 10227`configure.in' or `configure.ac' file, the gettext version used by the 10228package, and copies the infrastructure files belonging to this version 10229into the package. 10230 1023113.6.3.1 Options 10232................ 10233 10234`-f' 10235`--force' 10236 Force overwriting of files that already exist. 10237 10238`-n' 10239`--dry-run' 10240 Print modifications but don't perform them. All file copying 10241 actions that `autopoint' would normally execute are inhibited and 10242 instead only listed on standard output. 10243 10244 1024513.6.3.2 Informative output 10246........................... 10247 10248`--help' 10249 Display this help and exit. 10250 10251`--version' 10252 Output version information and exit. 10253 10254 10255 `autopoint' supports the GNU `gettext' versions from 0.10.35 to the 10256current one, 0.17. In order to apply `autopoint' to a package using a 10257`gettext' version newer than 0.17, you need to install this same 10258version of GNU `gettext' at least. 10259 10260 In packages using GNU `automake', an invocation of `autopoint' 10261should be followed by invocations of `aclocal' and then `autoconf' and 10262`autoheader'. The reason is that `autopoint' installs some autoconf 10263macro files, which are used by `aclocal' to create `aclocal.m4', and 10264the latter is used by `autoconf' to create the package's `configure' 10265script and by `autoheader' to create the package's `config.h.in' 10266include file template. 10267 10268 The name `autopoint' is an abbreviation of `auto-po-intl-m4'; the 10269tool copies or updates mostly files in the `po', `intl', `m4' 10270directories. 10271 10272 10273File: gettext.info, Node: Release Management, Prev: CVS Issues, Up: Maintainers 10274 1027513.7 Creating a Distribution Tarball 10276==================================== 10277 10278 In projects that use GNU `automake', the usual commands for creating 10279a distribution tarball, `make dist' or `make distcheck', automatically 10280update the PO files as needed. 10281 10282 If GNU `automake' is not used, the maintainer needs to perform this 10283update before making a release: 10284 10285 $ ./configure 10286 $ (cd po; make update-po) 10287 $ make distclean 10288 10289 10290File: gettext.info, Node: Installers, Next: Programming Languages, Prev: Maintainers, Up: Top 10291 1029214 The Installer's and Distributor's View 10293***************************************** 10294 10295 By default, packages fully using GNU `gettext', internally, are 10296installed in such a way that they to allow translation of messages. At 10297_configuration_ time, those packages should automatically detect 10298whether the underlying host system already provides the GNU `gettext' 10299functions. If not, the GNU `gettext' library should be automatically 10300prepared and used. Installers may use special options at configuration 10301time for changing this behavior. The command `./configure 10302--with-included-gettext' bypasses system `gettext' to use the included 10303GNU `gettext' instead, while `./configure --disable-nls' produces 10304programs totally unable to translate messages. 10305 10306 Internationalized packages have usually many `LL.po' files. Unless 10307translations are disabled, all those available are installed together 10308with the package. However, the environment variable `LINGUAS' may be 10309set, prior to configuration, to limit the installed set. `LINGUAS' 10310should then contain a space separated list of two-letter codes, stating 10311which languages are allowed. 10312 10313 10314File: gettext.info, Node: Programming Languages, Next: Conclusion, Prev: Installers, Up: Top 10315 1031615 Other Programming Languages 10317****************************** 10318 10319 While the presentation of `gettext' focuses mostly on C and 10320implicitly applies to C++ as well, its scope is far broader than that: 10321Many programming languages, scripting languages and other textual data 10322like GUI resources or package descriptions can make use of the gettext 10323approach. 10324 10325* Menu: 10326 10327* Language Implementors:: The Language Implementor's View 10328* Programmers for other Languages:: The Programmer's View 10329* Translators for other Languages:: The Translator's View 10330* Maintainers for other Languages:: The Maintainer's View 10331* List of Programming Languages:: Individual Programming Languages 10332* List of Data Formats:: Internationalizable Data 10333 10334 10335File: gettext.info, Node: Language Implementors, Next: Programmers for other Languages, Prev: Programming Languages, Up: Programming Languages 10336 1033715.1 The Language Implementor's View 10338==================================== 10339 10340 All programming and scripting languages that have the notion of 10341strings are eligible to supporting `gettext'. Supporting `gettext' 10342means the following: 10343 10344 1. You should add to the language a syntax for translatable strings. 10345 In principle, a function call of `gettext' would do, but a 10346 shorthand syntax helps keeping the legibility of internationalized 10347 programs. For example, in C we use the syntax `_("string")', and 10348 in GNU awk we use the shorthand `_"string"'. 10349 10350 2. You should arrange that evaluation of such a translatable string at 10351 runtime calls the `gettext' function, or performs equivalent 10352 processing. 10353 10354 3. Similarly, you should make the functions `ngettext', `dcgettext', 10355 `dcngettext' available from within the language. These functions 10356 are less often used, but are nevertheless necessary for particular 10357 purposes: `ngettext' for correct plural handling, and `dcgettext' 10358 and `dcngettext' for obeying other locale-related environment 10359 variables than `LC_MESSAGES', such as `LC_TIME' or `LC_MONETARY'. 10360 For these latter functions, you need to make the `LC_*' constants, 10361 available in the C header `<locale.h>', referenceable from within 10362 the language, usually either as enumeration values or as strings. 10363 10364 4. You should allow the programmer to designate a message domain, 10365 either by making the `textdomain' function available from within 10366 the language, or by introducing a magic variable called 10367 `TEXTDOMAIN'. Similarly, you should allow the programmer to 10368 designate where to search for message catalogs, by providing 10369 access to the `bindtextdomain' function. 10370 10371 5. You should either perform a `setlocale (LC_ALL, "")' call during 10372 the startup of your language runtime, or allow the programmer to 10373 do so. Remember that gettext will act as a no-op if the 10374 `LC_MESSAGES' and `LC_CTYPE' locale categories are not both set. 10375 10376 6. A programmer should have a way to extract translatable strings 10377 from a program into a PO file. The GNU `xgettext' program is being 10378 extended to support very different programming languages. Please 10379 contact the GNU `gettext' maintainers to help them doing this. If 10380 the string extractor is best integrated into your language's 10381 parser, GNU `xgettext' can function as a front end to your string 10382 extractor. 10383 10384 7. The language's library should have a string formatting facility 10385 where the arguments of a format string are denoted by a positional 10386 number or a name. This is needed because for some languages and 10387 some messages with more than one substitutable argument, the 10388 translation will need to output the substituted arguments in 10389 different order. *Note c-format Flag::. 10390 10391 8. If the language has more than one implementation, and not all of 10392 the implementations use `gettext', but the programs should be 10393 portable across implementations, you should provide a no-i18n 10394 emulation, that makes the other implementations accept programs 10395 written for yours, without actually translating the strings. 10396 10397 9. To help the programmer in the task of marking translatable strings, 10398 which is sometimes performed using the Emacs PO mode (*note 10399 Marking::), you are welcome to contact the GNU `gettext' 10400 maintainers, so they can add support for your language to 10401 `po-mode.el'. 10402 10403 On the implementation side, three approaches are possible, with 10404different effects on portability and copyright: 10405 10406 * You may integrate the GNU `gettext''s `intl/' directory in your 10407 package, as described in *note Maintainers::. This allows you to 10408 have internationalization on all kinds of platforms. Note that 10409 when you then distribute your package, it legally falls under the 10410 GNU General Public License, and the GNU project will be glad about 10411 your contribution to the Free Software pool. 10412 10413 * You may link against GNU `gettext' functions if they are found in 10414 the C library. For example, an autoconf test for `gettext()' and 10415 `ngettext()' will detect this situation. For the moment, this test 10416 will succeed on GNU systems and not on other platforms. No severe 10417 copyright restrictions apply. 10418 10419 * You may emulate or reimplement the GNU `gettext' functionality. 10420 This has the advantage of full portability and no copyright 10421 restrictions, but also the drawback that you have to reimplement 10422 the GNU `gettext' features (such as the `LANGUAGE' environment 10423 variable, the locale aliases database, the automatic charset 10424 conversion, and plural handling). 10425 10426 10427File: gettext.info, Node: Programmers for other Languages, Next: Translators for other Languages, Prev: Language Implementors, Up: Programming Languages 10428 1042915.2 The Programmer's View 10430========================== 10431 10432 For the programmer, the general procedure is the same as for the C 10433language. The Emacs PO mode marking supports other languages, and the 10434GNU `xgettext' string extractor recognizes other languages based on the 10435file extension or a command-line option. In some languages, 10436`setlocale' is not needed because it is already performed by the 10437underlying language runtime. 10438 10439 10440File: gettext.info, Node: Translators for other Languages, Next: Maintainers for other Languages, Prev: Programmers for other Languages, Up: Programming Languages 10441 1044215.3 The Translator's View 10443========================== 10444 10445 The translator works exactly as in the C language case. The only 10446difference is that when translating format strings, she has to be aware 10447of the language's particular syntax for positional arguments in format 10448strings. 10449 10450* Menu: 10451 10452* c-format:: C Format Strings 10453* objc-format:: Objective C Format Strings 10454* sh-format:: Shell Format Strings 10455* python-format:: Python Format Strings 10456* lisp-format:: Lisp Format Strings 10457* elisp-format:: Emacs Lisp Format Strings 10458* librep-format:: librep Format Strings 10459* scheme-format:: Scheme Format Strings 10460* smalltalk-format:: Smalltalk Format Strings 10461* java-format:: Java Format Strings 10462* csharp-format:: C# Format Strings 10463* awk-format:: awk Format Strings 10464* object-pascal-format:: Object Pascal Format Strings 10465* ycp-format:: YCP Format Strings 10466* tcl-format:: Tcl Format Strings 10467* perl-format:: Perl Format Strings 10468* php-format:: PHP Format Strings 10469* gcc-internal-format:: GCC internal Format Strings 10470* qt-format:: Qt Format Strings 10471* kde-format:: KDE Format Strings 10472* boost-format:: Boost Format Strings 10473 10474 10475File: gettext.info, Node: c-format, Next: objc-format, Prev: Translators for other Languages, Up: Translators for other Languages 10476 1047715.3.1 C Format Strings 10478----------------------- 10479 10480 C format strings are described in POSIX (IEEE P1003.1 2001), section 10481XSH 3 fprintf(), 10482`http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html'. 10483See also the fprintf() manual page, 10484`http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php', 10485`http://informatik.fh-wuerzburg.de/student/i510/man/printf.html'. 10486 10487 Although format strings with positions that reorder arguments, such 10488as 10489 10490 "Only %2$d bytes free on '%1$s'." 10491 10492which is semantically equivalent to 10493 10494 "'%s' has only %d bytes free." 10495 10496are a POSIX/XSI feature and not specified by ISO C 99, translators can 10497rely on this reordering ability: On the few platforms where `printf()', 10498`fprintf()' etc. don't support this feature natively, `libintl.a' or 10499`libintl.so' provides replacement functions, and GNU `<libintl.h>' 10500activates these replacement functions automatically. 10501 10502 As a special feature for Farsi (Persian) and maybe Arabic, 10503translators can insert an `I' flag into numeric format directives. For 10504example, the translation of `"%d"' can be `"%Id"'. The effect of this 10505flag, on systems with GNU `libc', is that in the output, the ASCII 10506digits are replaced with the `outdigits' defined in the `LC_CTYPE' 10507locale category. On other systems, the `gettext' function removes this 10508flag, so that it has no effect. 10509 10510 Note that the programmer should _not_ put this flag into the 10511untranslated string. (Putting the `I' format directive flag into an 10512MSGID string would lead to undefined behaviour on platforms without 10513glibc when NLS is disabled.) 10514 10515 10516File: gettext.info, Node: objc-format, Next: sh-format, Prev: c-format, Up: Translators for other Languages 10517 1051815.3.2 Objective C Format Strings 10519--------------------------------- 10520 10521 Objective C format strings are like C format strings. They support 10522an additional format directive: "$@", which when executed consumes an 10523argument of type `Object *'. 10524 10525 10526File: gettext.info, Node: sh-format, Next: python-format, Prev: objc-format, Up: Translators for other Languages 10527 1052815.3.3 Shell Format Strings 10529--------------------------- 10530 10531 Shell format strings, as supported by GNU gettext and the `envsubst' 10532program, are strings with references to shell variables in the form 10533`$VARIABLE' or `${VARIABLE}'. References of the form 10534`${VARIABLE-DEFAULT}', `${VARIABLE:-DEFAULT}', `${VARIABLE=DEFAULT}', 10535`${VARIABLE:=DEFAULT}', `${VARIABLE+REPLACEMENT}', 10536`${VARIABLE:+REPLACEMENT}', `${VARIABLE?IGNORED}', 10537`${VARIABLE:?IGNORED}', that would be valid inside shell scripts, are 10538not supported. The VARIABLE names must consist solely of alphanumeric 10539or underscore ASCII characters, not start with a digit and be nonempty; 10540otherwise such a variable reference is ignored. 10541 10542 10543File: gettext.info, Node: python-format, Next: lisp-format, Prev: sh-format, Up: Translators for other Languages 10544 1054515.3.4 Python Format Strings 10546---------------------------- 10547 10548 Python format strings are described in Python Library reference / 105492. Built-in Types, Exceptions and Functions / 2.2. Built-in Types / 105502.2.6. Sequence Types / 2.2.6.2. String Formatting Operations. 10551`http://www.python.org/doc/2.2.1/lib/typesseq-strings.html'. 10552 10553 10554File: gettext.info, Node: lisp-format, Next: elisp-format, Prev: python-format, Up: Translators for other Languages 10555 1055615.3.5 Lisp Format Strings 10557-------------------------- 10558 10559 Lisp format strings are described in the Common Lisp HyperSpec, 10560chapter 22.3 Formatted Output, 10561`http://www.lisp.org/HyperSpec/Body/sec_22-3.html'. 10562 10563 10564File: gettext.info, Node: elisp-format, Next: librep-format, Prev: lisp-format, Up: Translators for other Languages 10565 1056615.3.6 Emacs Lisp Format Strings 10567-------------------------------- 10568 10569 Emacs Lisp format strings are documented in the Emacs Lisp reference, 10570section Formatting Strings, 10571`http://www.gnu.org/manual/elisp-manual-21-2.8/html_chapter/elisp_4.html#SEC75'. 10572Note that as of version 21, XEmacs supports numbered argument 10573specifications in format strings while FSF Emacs doesn't. 10574 10575 10576File: gettext.info, Node: librep-format, Next: scheme-format, Prev: elisp-format, Up: Translators for other Languages 10577 1057815.3.7 librep Format Strings 10579---------------------------- 10580 10581 librep format strings are documented in the librep manual, section 10582Formatted Output, 10583`http://librep.sourceforge.net/librep-manual.html#Formatted%20Output', 10584`http://www.gwinnup.org/research/docs/librep.html#SEC122'. 10585 10586 10587File: gettext.info, Node: scheme-format, Next: smalltalk-format, Prev: librep-format, Up: Translators for other Languages 10588 1058915.3.8 Scheme Format Strings 10590---------------------------- 10591 10592 Scheme format strings are documented in the SLIB manual, section 10593Format Specification. 10594 10595 10596File: gettext.info, Node: smalltalk-format, Next: java-format, Prev: scheme-format, Up: Translators for other Languages 10597 1059815.3.9 Smalltalk Format Strings 10599------------------------------- 10600 10601 Smalltalk format strings are described in the GNU Smalltalk 10602documentation, class `CharArray', methods `bindWith:' and 10603`bindWithArguments:'. 10604`http://www.gnu.org/software/smalltalk/gst-manual/gst_68.html#SEC238'. 10605In summary, a directive starts with `%' and is followed by `%' or a 10606nonzero digit (`1' to `9'). 10607 10608 10609File: gettext.info, Node: java-format, Next: csharp-format, Prev: smalltalk-format, Up: Translators for other Languages 10610 1061115.3.10 Java Format Strings 10612--------------------------- 10613 10614 Java format strings are described in the JDK documentation for class 10615`java.text.MessageFormat', 10616`http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html'. 10617See also the ICU documentation 10618`http://oss.software.ibm.com/icu/apiref/classMessageFormat.html'. 10619 10620 10621File: gettext.info, Node: csharp-format, Next: awk-format, Prev: java-format, Up: Translators for other Languages 10622 1062315.3.11 C# Format Strings 10624------------------------- 10625 10626 C# format strings are described in the .NET documentation for class 10627`System.String' and in 10628`http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpConFormattingOverview.asp'. 10629 10630 10631File: gettext.info, Node: awk-format, Next: object-pascal-format, Prev: csharp-format, Up: Translators for other Languages 10632 1063315.3.12 awk Format Strings 10634-------------------------- 10635 10636 awk format strings are described in the gawk documentation, section 10637Printf, `http://www.gnu.org/manual/gawk/html_node/Printf.html#Printf'. 10638 10639 10640File: gettext.info, Node: object-pascal-format, Next: ycp-format, Prev: awk-format, Up: Translators for other Languages 10641 1064215.3.13 Object Pascal Format Strings 10643------------------------------------ 10644 10645 Where is this documented? 10646 10647 10648File: gettext.info, Node: ycp-format, Next: tcl-format, Prev: object-pascal-format, Up: Translators for other Languages 10649 1065015.3.14 YCP Format Strings 10651-------------------------- 10652 10653 YCP sformat strings are described in the libycp documentation 10654`file:/usr/share/doc/packages/libycp/YCP-builtins.html'. In summary, a 10655directive starts with `%' and is followed by `%' or a nonzero digit 10656(`1' to `9'). 10657 10658 10659File: gettext.info, Node: tcl-format, Next: perl-format, Prev: ycp-format, Up: Translators for other Languages 10660 1066115.3.15 Tcl Format Strings 10662-------------------------- 10663 10664 Tcl format strings are described in the `format.n' manual page, 10665`http://www.scriptics.com/man/tcl8.3/TclCmd/format.htm'. 10666 10667 10668File: gettext.info, Node: perl-format, Next: php-format, Prev: tcl-format, Up: Translators for other Languages 10669 1067015.3.16 Perl Format Strings 10671--------------------------- 10672 10673 There are two kinds format strings in Perl: those acceptable to the 10674Perl built-in function `printf', labelled as `perl-format', and those 10675acceptable to the `libintl-perl' function `__x', labelled as 10676`perl-brace-format'. 10677 10678 Perl `printf' format strings are described in the `sprintf' section 10679of `man perlfunc'. 10680 10681 Perl brace format strings are described in the 10682`Locale::TextDomain(3pm)' manual page of the CPAN package libintl-perl. 10683In brief, Perl format uses placeholders put between braces (`{' and 10684`}'). The placeholder must have the syntax of simple identifiers. 10685 10686 10687File: gettext.info, Node: php-format, Next: gcc-internal-format, Prev: perl-format, Up: Translators for other Languages 10688 1068915.3.17 PHP Format Strings 10690-------------------------- 10691 10692 PHP format strings are described in the documentation of the PHP 10693function `sprintf', in `phpdoc/manual/function.sprintf.html' or 10694`http://www.php.net/manual/en/function.sprintf.php'. 10695 10696 10697File: gettext.info, Node: gcc-internal-format, Next: qt-format, Prev: php-format, Up: Translators for other Languages 10698 1069915.3.18 GCC internal Format Strings 10700----------------------------------- 10701 10702 These format strings are used inside the GCC sources. In such a 10703format string, a directive starts with `%', is optionally followed by a 10704size specifier `l', an optional flag `+', another optional flag `#', 10705and is finished by a specifier: `%' denotes a literal percent sign, `c' 10706denotes a character, `s' denotes a string, `i' and `d' denote an 10707integer, `o', `u', `x' denote an unsigned integer, `.*s' denotes a 10708string preceded by a width specification, `H' denotes a `location_t *' 10709pointer, `D' denotes a general declaration, `F' denotes a function 10710declaration, `T' denotes a type, `A' denotes a function argument, `C' 10711denotes a tree code, `E' denotes an expression, `L' denotes a 10712programming language, `O' denotes a binary operator, `P' denotes a 10713function parameter, `Q' denotes an assignment operator, `V' denotes a 10714const/volatile qualifier. 10715 10716 10717File: gettext.info, Node: qt-format, Next: kde-format, Prev: gcc-internal-format, Up: Translators for other Languages 10718 1071915.3.19 Qt Format Strings 10720------------------------- 10721 10722 Qt format strings are described in the documentation of the QString 10723class `file:/usr/lib/qt-4.3.0/doc/html/qstring.html'. In summary, a 10724directive consists of a `%' followed by a digit. The same directive 10725cannot occur more than once in a format string. 10726 10727 10728File: gettext.info, Node: kde-format, Next: boost-format, Prev: qt-format, Up: Translators for other Languages 10729 1073015.3.20 KDE Format Strings 10731-------------------------- 10732 10733 KDE 4 format strings are defined as follows: A directive consists of 10734a `%' followed by a non-zero decimal number. If a `%n' occurs in a 10735format strings, all of `%1', ..., `%(n-1)' must occur as well, except 10736possibly one of them. 10737 10738 10739File: gettext.info, Node: boost-format, Prev: kde-format, Up: Translators for other Languages 10740 1074115.3.21 Boost Format Strings 10742---------------------------- 10743 10744 Boost format strings are described in the documentation of the 10745`boost::format' class, at 10746`http://www.boost.org/libs/format/doc/format.html'. In summary, a 10747directive has either the same syntax as in a C format string, such as 10748`%1$+5d', or may be surrounded by vertical bars, such as `%|1$+5d|' or 10749`%|1$+5|', or consists of just an argument number between percent 10750signs, such as `%1%'. 10751 10752 10753File: gettext.info, Node: Maintainers for other Languages, Next: List of Programming Languages, Prev: Translators for other Languages, Up: Programming Languages 10754 1075515.4 The Maintainer's View 10756========================== 10757 10758 For the maintainer, the general procedure differs from the C language 10759case in two ways. 10760 10761 * For those languages that don't use GNU gettext, the `intl/' 10762 directory is not needed and can be omitted. This means that the 10763 maintainer calls the `gettextize' program without the `--intl' 10764 option, and that he invokes the `AM_GNU_GETTEXT' autoconf macro via 10765 `AM_GNU_GETTEXT([external])'. 10766 10767 * If only a single programming language is used, the 10768 `XGETTEXT_OPTIONS' variable in `po/Makevars' (*note po/Makevars::) 10769 should be adjusted to match the `xgettext' options for that 10770 particular programming language. If the package uses more than 10771 one programming language with `gettext' support, it becomes 10772 necessary to change the POT file construction rule in 10773 `po/Makefile.in.in'. It is recommended to make one `xgettext' 10774 invocation per programming language, each with the options 10775 appropriate for that language, and to combine the resulting files 10776 using `msgcat'. 10777 10778 10779File: gettext.info, Node: List of Programming Languages, Next: List of Data Formats, Prev: Maintainers for other Languages, Up: Programming Languages 10780 1078115.5 Individual Programming Languages 10782===================================== 10783 10784* Menu: 10785 10786* C:: C, C++, Objective C 10787* sh:: sh - Shell Script 10788* bash:: bash - Bourne-Again Shell Script 10789* Python:: Python 10790* Common Lisp:: GNU clisp - Common Lisp 10791* clisp C:: GNU clisp C sources 10792* Emacs Lisp:: Emacs Lisp 10793* librep:: librep 10794* Scheme:: GNU guile - Scheme 10795* Smalltalk:: GNU Smalltalk 10796* Java:: Java 10797* C#:: C# 10798* gawk:: GNU awk 10799* Pascal:: Pascal - Free Pascal Compiler 10800* wxWidgets:: wxWidgets library 10801* YCP:: YCP - YaST2 scripting language 10802* Tcl:: Tcl - Tk's scripting language 10803* Perl:: Perl 10804* PHP:: PHP Hypertext Preprocessor 10805* Pike:: Pike 10806* GCC-source:: GNU Compiler Collection sources 10807 10808 10809File: gettext.info, Node: C, Next: sh, Prev: List of Programming Languages, Up: List of Programming Languages 10810 1081115.5.1 C, C++, Objective C 10812-------------------------- 10813 10814RPMs 10815 gcc, gpp, gobjc, glibc, gettext 10816 10817File extension 10818 For C: `c', `h'. 10819 For C++: `C', `c++', `cc', `cxx', `cpp', `hpp'. 10820 For Objective C: `m'. 10821 10822String syntax 10823 `"abc"' 10824 10825gettext shorthand 10826 `_("abc")' 10827 10828gettext/ngettext functions 10829 `gettext', `dgettext', `dcgettext', `ngettext', `dngettext', 10830 `dcngettext' 10831 10832textdomain 10833 `textdomain' function 10834 10835bindtextdomain 10836 `bindtextdomain' function 10837 10838setlocale 10839 Programmer must call `setlocale (LC_ALL, "")' 10840 10841Prerequisite 10842 `#include <libintl.h>' 10843 `#include <locale.h>' 10844 `#define _(string) gettext (string)' 10845 10846Use or emulate GNU gettext 10847 Use 10848 10849Extractor 10850 `xgettext -k_' 10851 10852Formatting with positions 10853 `fprintf "%2$d %1$d"' 10854 In C++: `autosprintf "%2$d %1$d"' (*note Introduction: 10855 (autosprintf)Top.) 10856 10857Portability 10858 autoconf (gettext.m4) and #if ENABLE_NLS 10859 10860po-mode marking 10861 yes 10862 10863 The following examples are available in the `examples' directory: 10864`hello-c', `hello-c-gnome', `hello-c++', `hello-c++-qt', 10865`hello-c++-kde', `hello-c++-gnome', `hello-c++-wxwidgets', 10866`hello-objc', `hello-objc-gnustep', `hello-objc-gnome'. 10867 10868 10869File: gettext.info, Node: sh, Next: bash, Prev: C, Up: List of Programming Languages 10870 1087115.5.2 sh - Shell Script 10872------------------------ 10873 10874RPMs 10875 bash, gettext 10876 10877File extension 10878 `sh' 10879 10880String syntax 10881 `"abc"', `'abc'', `abc' 10882 10883gettext shorthand 10884 `"`gettext \"abc\"`"' 10885 10886gettext/ngettext functions 10887 `gettext', `ngettext' programs 10888 `eval_gettext', `eval_ngettext' shell functions 10889 10890textdomain 10891 environment variable `TEXTDOMAIN' 10892 10893bindtextdomain 10894 environment variable `TEXTDOMAINDIR' 10895 10896setlocale 10897 automatic 10898 10899Prerequisite 10900 `. gettext.sh' 10901 10902Use or emulate GNU gettext 10903 use 10904 10905Extractor 10906 `xgettext' 10907 10908Formatting with positions 10909 -- 10910 10911Portability 10912 fully portable 10913 10914po-mode marking 10915 -- 10916 10917 An example is available in the `examples' directory: `hello-sh'. 10918 10919* Menu: 10920 10921* Preparing Shell Scripts:: Preparing Shell Scripts for Internationalization 10922* gettext.sh:: Contents of `gettext.sh' 10923* gettext Invocation:: Invoking the `gettext' program 10924* ngettext Invocation:: Invoking the `ngettext' program 10925* envsubst Invocation:: Invoking the `envsubst' program 10926* eval_gettext Invocation:: Invoking the `eval_gettext' function 10927* eval_ngettext Invocation:: Invoking the `eval_ngettext' function 10928 10929 10930File: gettext.info, Node: Preparing Shell Scripts, Next: gettext.sh, Prev: sh, Up: sh 10931 1093215.5.2.1 Preparing Shell Scripts for Internationalization 10933......................................................... 10934 10935 Preparing a shell script for internationalization is conceptually 10936similar to the steps described in *note Sources::. The concrete steps 10937for shell scripts are as follows. 10938 10939 1. Insert the line 10940 10941 . gettext.sh 10942 10943 near the top of the script. `gettext.sh' is a shell function 10944 library that provides the functions `eval_gettext' (see *note 10945 eval_gettext Invocation::) and `eval_ngettext' (see *note 10946 eval_ngettext Invocation::). You have to ensure that `gettext.sh' 10947 can be found in the `PATH'. 10948 10949 2. Set and export the `TEXTDOMAIN' and `TEXTDOMAINDIR' environment 10950 variables. Usually `TEXTDOMAIN' is the package or program name, 10951 and `TEXTDOMAINDIR' is the absolute pathname corresponding to 10952 `$prefix/share/locale', where `$prefix' is the installation 10953 location. 10954 10955 TEXTDOMAIN=@PACKAGE@ 10956 export TEXTDOMAIN 10957 TEXTDOMAINDIR=@LOCALEDIR@ 10958 export TEXTDOMAINDIR 10959 10960 3. Prepare the strings for translation, as described in *note 10961 Preparing Strings::. 10962 10963 4. Simplify translatable strings so that they don't contain command 10964 substitution (`"`...`"' or `"$(...)"'), variable access with 10965 defaulting (like `${VARIABLE-DEFAULT}'), access to positional 10966 arguments (like `$0', `$1', ...) or highly volatile shell 10967 variables (like `$?'). This can always be done through simple 10968 local code restructuring. For example, 10969 10970 echo "Usage: $0 [OPTION] FILE..." 10971 10972 becomes 10973 10974 program_name=$0 10975 echo "Usage: $program_name [OPTION] FILE..." 10976 10977 Similarly, 10978 10979 echo "Remaining files: `ls | wc -l`" 10980 10981 becomes 10982 10983 filecount="`ls | wc -l`" 10984 echo "Remaining files: $filecount" 10985 10986 5. For each translatable string, change the output command `echo' or 10987 `$echo' to `gettext' (if the string contains no references to 10988 shell variables) or to `eval_gettext' (if it refers to shell 10989 variables), followed by a no-argument `echo' command (to account 10990 for the terminating newline). Similarly, for cases with plural 10991 handling, replace a conditional `echo' command with an invocation 10992 of `ngettext' or `eval_ngettext', followed by a no-argument `echo' 10993 command. 10994 10995 When doing this, you also need to add an extra backslash before 10996 the dollar sign in references to shell variables, so that the 10997 `eval_gettext' function receives the translatable string before 10998 the variable values are substituted into it. For example, 10999 11000 echo "Remaining files: $filecount" 11001 11002 becomes 11003 11004 eval_gettext "Remaining files: \$filecount"; echo 11005 11006 If the output command is not `echo', you can make it use `echo' 11007 nevertheless, through the use of backquotes. However, note that 11008 inside backquotes, backslashes must be doubled to be effective 11009 (because the backquoting eats one level of backslashes). For 11010 example, assuming that `error' is a shell function that signals an 11011 error, 11012 11013 error "file not found: $filename" 11014 11015 is first transformed into 11016 11017 error "`echo \"file not found: \$filename\"`" 11018 11019 which then becomes 11020 11021 error "`eval_gettext \"file not found: \\\$filename\"`" 11022 11023 11024File: gettext.info, Node: gettext.sh, Next: gettext Invocation, Prev: Preparing Shell Scripts, Up: sh 11025 1102615.5.2.2 Contents of `gettext.sh' 11027................................. 11028 11029 `gettext.sh', contained in the run-time package of GNU gettext, 11030provides the following: 11031 11032 * $echo The variable `echo' is set to a command that outputs its 11033 first argument and a newline, without interpreting backslashes in 11034 the argument string. 11035 11036 * eval_gettext See *note eval_gettext Invocation::. 11037 11038 * eval_ngettext See *note eval_ngettext Invocation::. 11039 11040 11041File: gettext.info, Node: gettext Invocation, Next: ngettext Invocation, Prev: gettext.sh, Up: sh 11042 1104315.5.2.3 Invoking the `gettext' program 11044....................................... 11045 11046 gettext [OPTION] [[TEXTDOMAIN] MSGID] 11047 gettext [OPTION] -s [MSGID]... 11048 11049 The `gettext' program displays the native language translation of a 11050textual message. 11051 11052*Arguments* 11053 11054`-d TEXTDOMAIN' 11055`--domain=TEXTDOMAIN' 11056 Retrieve translated messages from TEXTDOMAIN. Usually a TEXTDOMAIN 11057 corresponds to a package, a program, or a module of a program. 11058 11059`-e' 11060 Enable expansion of some escape sequences. This option is for 11061 compatibility with the `echo' program or shell built-in. The 11062 escape sequences `\a', `\b', `\c', `\f', `\n', `\r', `\t', `\v', 11063 `\\', and `\' followed by one to three octal digits, are 11064 interpreted like the System V `echo' program did. 11065 11066`-E' 11067 This option is only for compatibility with the `echo' program or 11068 shell built-in. It has no effect. 11069 11070`-h' 11071`--help' 11072 Display this help and exit. 11073 11074`-n' 11075 Suppress trailing newline. By default, `gettext' adds a newline to 11076 the output. 11077 11078`-V' 11079`--version' 11080 Output version information and exit. 11081 11082`[TEXTDOMAIN] MSGID' 11083 Retrieve translated message corresponding to MSGID from TEXTDOMAIN. 11084 11085 11086 If the TEXTDOMAIN parameter is not given, the domain is determined 11087from the environment variable `TEXTDOMAIN'. If the message catalog is 11088not found in the regular directory, another location can be specified 11089with the environment variable `TEXTDOMAINDIR'. 11090 11091 When used with the `-s' option the program behaves like the `echo' 11092command. But it does not simply copy its arguments to stdout. Instead 11093those messages found in the selected catalog are translated. 11094 11095 11096File: gettext.info, Node: ngettext Invocation, Next: envsubst Invocation, Prev: gettext Invocation, Up: sh 11097 1109815.5.2.4 Invoking the `ngettext' program 11099........................................ 11100 11101 ngettext [OPTION] [TEXTDOMAIN] MSGID MSGID-PLURAL COUNT 11102 11103 The `ngettext' program displays the native language translation of a 11104textual message whose grammatical form depends on a number. 11105 11106*Arguments* 11107 11108`-d TEXTDOMAIN' 11109`--domain=TEXTDOMAIN' 11110 Retrieve translated messages from TEXTDOMAIN. Usually a TEXTDOMAIN 11111 corresponds to a package, a program, or a module of a program. 11112 11113`-e' 11114 Enable expansion of some escape sequences. This option is for 11115 compatibility with the `gettext' program. The escape sequences 11116 `\a', `\b', `\c', `\f', `\n', `\r', `\t', `\v', `\\', and `\' 11117 followed by one to three octal digits, are interpreted like the 11118 System V `echo' program did. 11119 11120`-E' 11121 This option is only for compatibility with the `gettext' program. 11122 It has no effect. 11123 11124`-h' 11125`--help' 11126 Display this help and exit. 11127 11128`-V' 11129`--version' 11130 Output version information and exit. 11131 11132`TEXTDOMAIN' 11133 Retrieve translated message from TEXTDOMAIN. 11134 11135`MSGID MSGID-PLURAL' 11136 Translate MSGID (English singular) / MSGID-PLURAL (English plural). 11137 11138`COUNT' 11139 Choose singular/plural form based on this value. 11140 11141 11142 If the TEXTDOMAIN parameter is not given, the domain is determined 11143from the environment variable `TEXTDOMAIN'. If the message catalog is 11144not found in the regular directory, another location can be specified 11145with the environment variable `TEXTDOMAINDIR'. 11146 11147 11148File: gettext.info, Node: envsubst Invocation, Next: eval_gettext Invocation, Prev: ngettext Invocation, Up: sh 11149 1115015.5.2.5 Invoking the `envsubst' program 11151........................................ 11152 11153 envsubst [OPTION] [SHELL-FORMAT] 11154 11155 The `envsubst' program substitutes the values of environment 11156variables. 11157 11158*Operation mode* 11159 11160`-v' 11161`--variables' 11162 Output the variables occurring in SHELL-FORMAT. 11163 11164 11165*Informative output* 11166 11167`-h' 11168`--help' 11169 Display this help and exit. 11170 11171`-V' 11172`--version' 11173 Output version information and exit. 11174 11175 11176 In normal operation mode, standard input is copied to standard 11177output, with references to environment variables of the form 11178`$VARIABLE' or `${VARIABLE}' being replaced with the corresponding 11179values. If a SHELL-FORMAT is given, only those environment variables 11180that are referenced in SHELL-FORMAT are substituted; otherwise all 11181environment variables references occurring in standard input are 11182substituted. 11183 11184 These substitutions are a subset of the substitutions that a shell 11185performs on unquoted and double-quoted strings. Other kinds of 11186substitutions done by a shell, such as `${VARIABLE-DEFAULT}' or 11187`$(COMMAND-LIST)' or ``COMMAND-LIST`', are not performed by the 11188`envsubst' program, due to security reasons. 11189 11190 When `--variables' is used, standard input is ignored, and the output 11191consists of the environment variables that are referenced in 11192SHELL-FORMAT, one per line. 11193 11194 11195File: gettext.info, Node: eval_gettext Invocation, Next: eval_ngettext Invocation, Prev: envsubst Invocation, Up: sh 11196 1119715.5.2.6 Invoking the `eval_gettext' function 11198............................................. 11199 11200 eval_gettext MSGID 11201 11202 This function outputs the native language translation of a textual 11203message, performing dollar-substitution on the result. Note that only 11204shell variables mentioned in MSGID will be dollar-substituted in the 11205result. 11206 11207 11208File: gettext.info, Node: eval_ngettext Invocation, Prev: eval_gettext Invocation, Up: sh 11209 1121015.5.2.7 Invoking the `eval_ngettext' function 11211.............................................. 11212 11213 eval_ngettext MSGID MSGID-PLURAL COUNT 11214 11215 This function outputs the native language translation of a textual 11216message whose grammatical form depends on a number, performing 11217dollar-substitution on the result. Note that only shell variables 11218mentioned in MSGID or MSGID-PLURAL will be dollar-substituted in the 11219result. 11220 11221 11222File: gettext.info, Node: bash, Next: Python, Prev: sh, Up: List of Programming Languages 11223 1122415.5.3 bash - Bourne-Again Shell Script 11225--------------------------------------- 11226 11227 GNU `bash' 2.0 or newer has a special shorthand for translating a 11228string and substituting variable values in it: `$"msgid"'. But the use 11229of this construct is *discouraged*, due to the security holes it opens 11230and due to its portability problems. 11231 11232 The security holes of `$"..."' come from the fact that after looking 11233up the translation of the string, `bash' processes it like it processes 11234any double-quoted string: dollar and backquote processing, like `eval' 11235does. 11236 11237 1. In a locale whose encoding is one of BIG5, BIG5-HKSCS, GBK, 11238 GB18030, SHIFT_JIS, JOHAB, some double-byte characters have a 11239 second byte whose value is `0x60'. For example, the byte sequence 11240 `\xe0\x60' is a single character in these locales. Many versions 11241 of `bash' (all versions up to bash-2.05, and newer versions on 11242 platforms without `mbsrtowcs()' function) don't know about 11243 character boundaries and see a backquote character where there is 11244 only a particular Chinese character. Thus it can start executing 11245 part of the translation as a command list. This situation can 11246 occur even without the translator being aware of it: if the 11247 translator provides translations in the UTF-8 encoding, it is the 11248 `gettext()' function which will, during its conversion from the 11249 translator's encoding to the user's locale's encoding, produce the 11250 dangerous `\x60' bytes. 11251 11252 2. A translator could - voluntarily or inadvertently - use backquotes 11253 `"`...`"' or dollar-parentheses `"$(...)"' in her translations. 11254 The enclosed strings would be executed as command lists by the 11255 shell. 11256 11257 The portability problem is that `bash' must be built with 11258internationalization support; this is normally not the case on systems 11259that don't have the `gettext()' function in libc. 11260 11261 11262File: gettext.info, Node: Python, Next: Common Lisp, Prev: bash, Up: List of Programming Languages 11263 1126415.5.4 Python 11265------------- 11266 11267RPMs 11268 python 11269 11270File extension 11271 `py' 11272 11273String syntax 11274 `'abc'', `u'abc'', `r'abc'', `ur'abc'', 11275 `"abc"', `u"abc"', `r"abc"', `ur"abc"', 11276 `'''abc'''', `u'''abc'''', `r'''abc'''', `ur'''abc'''', 11277 `"""abc"""', `u"""abc"""', `r"""abc"""', `ur"""abc"""' 11278 11279gettext shorthand 11280 `_('abc')' etc. 11281 11282gettext/ngettext functions 11283 `gettext.gettext', `gettext.dgettext', `gettext.ngettext', 11284 `gettext.dngettext', also `ugettext', `ungettext' 11285 11286textdomain 11287 `gettext.textdomain' function, or `gettext.install(DOMAIN)' 11288 function 11289 11290bindtextdomain 11291 `gettext.bindtextdomain' function, or 11292 `gettext.install(DOMAIN,LOCALEDIR)' function 11293 11294setlocale 11295 not used by the gettext emulation 11296 11297Prerequisite 11298 `import gettext' 11299 11300Use or emulate GNU gettext 11301 emulate 11302 11303Extractor 11304 `xgettext' 11305 11306Formatting with positions 11307 `'...%(ident)d...' % { 'ident': value }' 11308 11309Portability 11310 fully portable 11311 11312po-mode marking 11313 -- 11314 11315 An example is available in the `examples' directory: `hello-python'. 11316 11317 11318File: gettext.info, Node: Common Lisp, Next: clisp C, Prev: Python, Up: List of Programming Languages 11319 1132015.5.5 GNU clisp - Common Lisp 11321------------------------------ 11322 11323RPMs 11324 clisp 2.28 or newer 11325 11326File extension 11327 `lisp' 11328 11329String syntax 11330 `"abc"' 11331 11332gettext shorthand 11333 `(_ "abc")', `(ENGLISH "abc")' 11334 11335gettext/ngettext functions 11336 `i18n:gettext', `i18n:ngettext' 11337 11338textdomain 11339 `i18n:textdomain' 11340 11341bindtextdomain 11342 `i18n:textdomaindir' 11343 11344setlocale 11345 automatic 11346 11347Prerequisite 11348 -- 11349 11350Use or emulate GNU gettext 11351 use 11352 11353Extractor 11354 `xgettext -k_ -kENGLISH' 11355 11356Formatting with positions 11357 `format "~1@*~D ~0@*~D"' 11358 11359Portability 11360 On platforms without gettext, no translation. 11361 11362po-mode marking 11363 -- 11364 11365 An example is available in the `examples' directory: `hello-clisp'. 11366 11367 11368File: gettext.info, Node: clisp C, Next: Emacs Lisp, Prev: Common Lisp, Up: List of Programming Languages 11369 1137015.5.6 GNU clisp C sources 11371-------------------------- 11372 11373RPMs 11374 clisp 11375 11376File extension 11377 `d' 11378 11379String syntax 11380 `"abc"' 11381 11382gettext shorthand 11383 `ENGLISH ? "abc" : ""' 11384 `GETTEXT("abc")' 11385 `GETTEXTL("abc")' 11386 11387gettext/ngettext functions 11388 `clgettext', `clgettextl' 11389 11390textdomain 11391 -- 11392 11393bindtextdomain 11394 -- 11395 11396setlocale 11397 automatic 11398 11399Prerequisite 11400 `#include "lispbibl.c"' 11401 11402Use or emulate GNU gettext 11403 use 11404 11405Extractor 11406 `clisp-xgettext' 11407 11408Formatting with positions 11409 `fprintf "%2$d %1$d"' 11410 11411Portability 11412 On platforms without gettext, no translation. 11413 11414po-mode marking 11415 -- 11416 11417 11418File: gettext.info, Node: Emacs Lisp, Next: librep, Prev: clisp C, Up: List of Programming Languages 11419 1142015.5.7 Emacs Lisp 11421----------------- 11422 11423RPMs 11424 emacs, xemacs 11425 11426File extension 11427 `el' 11428 11429String syntax 11430 `"abc"' 11431 11432gettext shorthand 11433 `(_"abc")' 11434 11435gettext/ngettext functions 11436 `gettext', `dgettext' (xemacs only) 11437 11438textdomain 11439 `domain' special form (xemacs only) 11440 11441bindtextdomain 11442 `bind-text-domain' function (xemacs only) 11443 11444setlocale 11445 automatic 11446 11447Prerequisite 11448 -- 11449 11450Use or emulate GNU gettext 11451 use 11452 11453Extractor 11454 `xgettext' 11455 11456Formatting with positions 11457 `format "%2$d %1$d"' 11458 11459Portability 11460 Only XEmacs. Without `I18N3' defined at build time, no 11461 translation. 11462 11463po-mode marking 11464 -- 11465 11466 11467File: gettext.info, Node: librep, Next: Scheme, Prev: Emacs Lisp, Up: List of Programming Languages 11468 1146915.5.8 librep 11470------------- 11471 11472RPMs 11473 librep 0.15.3 or newer 11474 11475File extension 11476 `jl' 11477 11478String syntax 11479 `"abc"' 11480 11481gettext shorthand 11482 `(_"abc")' 11483 11484gettext/ngettext functions 11485 `gettext' 11486 11487textdomain 11488 `textdomain' function 11489 11490bindtextdomain 11491 `bindtextdomain' function 11492 11493setlocale 11494 -- 11495 11496Prerequisite 11497 `(require 'rep.i18n.gettext)' 11498 11499Use or emulate GNU gettext 11500 use 11501 11502Extractor 11503 `xgettext' 11504 11505Formatting with positions 11506 `format "%2$d %1$d"' 11507 11508Portability 11509 On platforms without gettext, no translation. 11510 11511po-mode marking 11512 -- 11513 11514 An example is available in the `examples' directory: `hello-librep'. 11515 11516 11517File: gettext.info, Node: Scheme, Next: Smalltalk, Prev: librep, Up: List of Programming Languages 11518 1151915.5.9 GNU guile - Scheme 11520------------------------- 11521 11522RPMs 11523 guile 11524 11525File extension 11526 `scm' 11527 11528String syntax 11529 `"abc"' 11530 11531gettext shorthand 11532 `(_ "abc")' 11533 11534gettext/ngettext functions 11535 `gettext', `ngettext' 11536 11537textdomain 11538 `textdomain' 11539 11540bindtextdomain 11541 `bindtextdomain' 11542 11543setlocale 11544 `(catch #t (lambda () (setlocale LC_ALL "")) (lambda args #f))' 11545 11546Prerequisite 11547 `(use-modules (ice-9 format))' 11548 11549Use or emulate GNU gettext 11550 use 11551 11552Extractor 11553 `xgettext -k_' 11554 11555Formatting with positions 11556 -- 11557 11558Portability 11559 On platforms without gettext, no translation. 11560 11561po-mode marking 11562 -- 11563 11564 An example is available in the `examples' directory: `hello-guile'. 11565 11566 11567File: gettext.info, Node: Smalltalk, Next: Java, Prev: Scheme, Up: List of Programming Languages 11568 1156915.5.10 GNU Smalltalk 11570--------------------- 11571 11572RPMs 11573 smalltalk 11574 11575File extension 11576 `st' 11577 11578String syntax 11579 `'abc'' 11580 11581gettext shorthand 11582 `NLS ? 'abc'' 11583 11584gettext/ngettext functions 11585 `LcMessagesDomain>>#at:', `LcMessagesDomain>>#at:plural:with:' 11586 11587textdomain 11588 `LcMessages>>#domain:localeDirectory:' (returns a 11589 `LcMessagesDomain' object). 11590 Example: `I18N Locale default messages domain: 'gettext' 11591 localeDirectory: /usr/local/share/locale'' 11592 11593bindtextdomain 11594 `LcMessages>>#domain:localeDirectory:', see above. 11595 11596setlocale 11597 Automatic if you use `I18N Locale default'. 11598 11599Prerequisite 11600 `PackageLoader fileInPackage: 'I18N'!' 11601 11602Use or emulate GNU gettext 11603 emulate 11604 11605Extractor 11606 `xgettext' 11607 11608Formatting with positions 11609 `'%1 %2' bindWith: 'Hello' with: 'world'' 11610 11611Portability 11612 fully portable 11613 11614po-mode marking 11615 -- 11616 11617 An example is available in the `examples' directory: 11618`hello-smalltalk'. 11619 11620 11621File: gettext.info, Node: Java, Next: C#, Prev: Smalltalk, Up: List of Programming Languages 11622 1162315.5.11 Java 11624------------ 11625 11626RPMs 11627 java, java2 11628 11629File extension 11630 `java' 11631 11632String syntax 11633 "abc" 11634 11635gettext shorthand 11636 _("abc") 11637 11638gettext/ngettext functions 11639 `GettextResource.gettext', `GettextResource.ngettext', 11640 `GettextResource.pgettext', `GettextResource.npgettext' 11641 11642textdomain 11643 --, use `ResourceBundle.getResource' instead 11644 11645bindtextdomain 11646 --, use CLASSPATH instead 11647 11648setlocale 11649 automatic 11650 11651Prerequisite 11652 -- 11653 11654Use or emulate GNU gettext 11655 --, uses a Java specific message catalog format 11656 11657Extractor 11658 `xgettext -k_' 11659 11660Formatting with positions 11661 `MessageFormat.format "{1,number} {0,number}"' 11662 11663Portability 11664 fully portable 11665 11666po-mode marking 11667 -- 11668 11669 Before marking strings as internationalizable, uses of the string 11670concatenation operator need to be converted to `MessageFormat' 11671applications. For example, `"file "+filename+" not found"' becomes 11672`MessageFormat.format("file {0} not found", new Object[] { filename })'. 11673Only after this is done, can the strings be marked and extracted. 11674 11675 GNU gettext uses the native Java internationalization mechanism, 11676namely `ResourceBundle's. There are two formats of `ResourceBundle's: 11677`.properties' files and `.class' files. The `.properties' format is a 11678text file which the translators can directly edit, like PO files, but 11679which doesn't support plural forms. Whereas the `.class' format is 11680compiled from `.java' source code and can support plural forms 11681(provided it is accessed through an appropriate API, see below). 11682 11683 To convert a PO file to a `.properties' file, the `msgcat' program 11684can be used with the option `--properties-output'. To convert a 11685`.properties' file back to a PO file, the `msgcat' program can be used 11686with the option `--properties-input'. All the tools that manipulate PO 11687files can work with `.properties' files as well, if given the 11688`--properties-input' and/or `--properties-output' option. 11689 11690 To convert a PO file to a ResourceBundle class, the `msgfmt' program 11691can be used with the option `--java' or `--java2'. To convert a 11692ResourceBundle back to a PO file, the `msgunfmt' program can be used 11693with the option `--java'. 11694 11695 Two different programmatic APIs can be used to access 11696ResourceBundles. Note that both APIs work with all kinds of 11697ResourceBundles, whether GNU gettext generated classes, or other 11698`.class' or `.properties' files. 11699 11700 1. The `java.util.ResourceBundle' API. 11701 11702 In particular, its `getString' function returns a string 11703 translation. Note that a missing translation yields a 11704 `MissingResourceException'. 11705 11706 This has the advantage of being the standard API. And it does not 11707 require any additional libraries, only the `msgcat' generated 11708 `.properties' files or the `msgfmt' generated `.class' files. But 11709 it cannot do plural handling, even if the resource was generated 11710 by `msgfmt' from a PO file with plural handling. 11711 11712 2. The `gnu.gettext.GettextResource' API. 11713 11714 Reference documentation in Javadoc 1.1 style format is in the 11715 javadoc2 directory (javadoc2/index.html). 11716 11717 Its `gettext' function returns a string translation. Note that 11718 when a translation is missing, the MSGID argument is returned 11719 unchanged. 11720 11721 This has the advantage of having the `ngettext' function for plural 11722 handling and the `pgettext' and `npgettext' for strings constraint 11723 to a particular context. 11724 11725 To use this API, one needs the `libintl.jar' file which is part of 11726 the GNU gettext package and distributed under the LGPL. 11727 11728 Four examples, using the second API, are available in the `examples' 11729directory: `hello-java', `hello-java-awt', `hello-java-swing', 11730`hello-java-qtjambi'. 11731 11732 Now, to make use of the API and define a shorthand for `getString', 11733there are three idioms that you can choose from: 11734 11735 * (This one assumes Java 1.5 or newer.) In a unique class of your 11736 project, say `Util', define a static variable holding the 11737 `ResourceBundle' instance and the shorthand: 11738 11739 private static ResourceBundle myResources = 11740 ResourceBundle.getBundle("domain-name"); 11741 public static String _(String s) { 11742 return myResources.getString(s); 11743 } 11744 11745 All classes containing internationalized strings then contain 11746 11747 import static Util._; 11748 11749 and the shorthand is used like this: 11750 11751 System.out.println(_("Operation completed.")); 11752 11753 * In a unique class of your project, say `Util', define a static 11754 variable holding the `ResourceBundle' instance: 11755 11756 public static ResourceBundle myResources = 11757 ResourceBundle.getBundle("domain-name"); 11758 11759 All classes containing internationalized strings then contain 11760 11761 private static ResourceBundle res = Util.myResources; 11762 private static String _(String s) { return res.getString(s); } 11763 11764 and the shorthand is used like this: 11765 11766 System.out.println(_("Operation completed.")); 11767 11768 * You add a class with a very short name, say `S', containing just 11769 the definition of the resource bundle and of the shorthand: 11770 11771 public class S { 11772 public static ResourceBundle myResources = 11773 ResourceBundle.getBundle("domain-name"); 11774 public static String _(String s) { 11775 return myResources.getString(s); 11776 } 11777 } 11778 11779 and the shorthand is used like this: 11780 11781 System.out.println(S._("Operation completed.")); 11782 11783 Which of the three idioms you choose, will depend on whether your 11784project requires portability to Java versions prior to Java 1.5 and, if 11785so, whether copying two lines of codes into every class is more 11786acceptable in your project than a class with a single-letter name. 11787 11788 11789File: gettext.info, Node: C#, Next: gawk, Prev: Java, Up: List of Programming Languages 11790 1179115.5.12 C# 11792---------- 11793 11794RPMs 11795 pnet, pnetlib 0.6.2 or newer, or mono 0.29 or newer 11796 11797File extension 11798 `cs' 11799 11800String syntax 11801 `"abc"', `@"abc"' 11802 11803gettext shorthand 11804 _("abc") 11805 11806gettext/ngettext functions 11807 `GettextResourceManager.GetString', 11808 `GettextResourceManager.GetPluralString' 11809 `GettextResourceManager.GetParticularString' 11810 `GettextResourceManager.GetParticularPluralString' 11811 11812textdomain 11813 `new GettextResourceManager(domain)' 11814 11815bindtextdomain 11816 --, compiled message catalogs are located in subdirectories of the 11817 directory containing the executable 11818 11819setlocale 11820 automatic 11821 11822Prerequisite 11823 -- 11824 11825Use or emulate GNU gettext 11826 --, uses a C# specific message catalog format 11827 11828Extractor 11829 `xgettext -k_' 11830 11831Formatting with positions 11832 `String.Format "{1} {0}"' 11833 11834Portability 11835 fully portable 11836 11837po-mode marking 11838 -- 11839 11840 Before marking strings as internationalizable, uses of the string 11841concatenation operator need to be converted to `String.Format' 11842invocations. For example, `"file "+filename+" not found"' becomes 11843`String.Format("file {0} not found", filename)'. Only after this is 11844done, can the strings be marked and extracted. 11845 11846 GNU gettext uses the native C#/.NET internationalization mechanism, 11847namely the classes `ResourceManager' and `ResourceSet'. Applications 11848use the `ResourceManager' methods to retrieve the native language 11849translation of strings. An instance of `ResourceSet' is the in-memory 11850representation of a message catalog file. The `ResourceManager' loads 11851and accesses `ResourceSet' instances as needed to look up the 11852translations. 11853 11854 There are two formats of `ResourceSet's that can be directly loaded 11855by the C# runtime: `.resources' files and `.dll' files. 11856 11857 * The `.resources' format is a binary file usually generated through 11858 the `resgen' or `monoresgen' utility, but which doesn't support 11859 plural forms. `.resources' files can also be embedded in .NET 11860 `.exe' files. This only affects whether a file system access is 11861 performed to load the message catalog; it doesn't affect the 11862 contents of the message catalog. 11863 11864 * On the other hand, the `.dll' format is a binary file that is 11865 compiled from `.cs' source code and can support plural forms 11866 (provided it is accessed through the GNU gettext API, see below). 11867 11868 Note that these .NET `.dll' and `.exe' files are not tied to a 11869particular platform; their file format and GNU gettext for C# can be 11870used on any platform. 11871 11872 To convert a PO file to a `.resources' file, the `msgfmt' program 11873can be used with the option `--csharp-resources'. To convert a 11874`.resources' file back to a PO file, the `msgunfmt' program can be used 11875with the option `--csharp-resources'. You can also, in some cases, use 11876the `resgen' program (from the `pnet' package) or the `monoresgen' 11877program (from the `mono'/`mcs' package). These programs can also 11878convert a `.resources' file back to a PO file. But beware: as of this 11879writing (January 2004), the `monoresgen' converter is quite buggy and 11880the `resgen' converter ignores the encoding of the PO files. 11881 11882 To convert a PO file to a `.dll' file, the `msgfmt' program can be 11883used with the option `--csharp'. The result will be a `.dll' file 11884containing a subclass of `GettextResourceSet', which itself is a 11885subclass of `ResourceSet'. To convert a `.dll' file containing a 11886`GettextResourceSet' subclass back to a PO file, the `msgunfmt' program 11887can be used with the option `--csharp'. 11888 11889 The advantages of the `.dll' format over the `.resources' format are: 11890 11891 1. Freedom to localize: Users can add their own translations to an 11892 application after it has been built and distributed. Whereas when 11893 the programmer uses a `ResourceManager' constructor provided by 11894 the system, the set of `.resources' files for an application must 11895 be specified when the application is built and cannot be extended 11896 afterwards. 11897 11898 2. Plural handling: A message catalog in `.dll' format supports the 11899 plural handling function `GetPluralString'. Whereas `.resources' 11900 files can only contain data and only support lookups that depend 11901 on a single string. 11902 11903 3. Context handling: A message catalog in `.dll' format supports the 11904 query-with-context functions `GetParticularString' and 11905 `GetParticularPluralString'. Whereas `.resources' files can only 11906 contain data and only support lookups that depend on a single 11907 string. 11908 11909 4. The `GettextResourceManager' that loads the message catalogs in 11910 `.dll' format also provides for inheritance on a per-message basis. 11911 For example, in Austrian (`de_AT') locale, translations from the 11912 German (`de') message catalog will be used for messages not found 11913 in the Austrian message catalog. This has the consequence that 11914 the Austrian translators need only translate those few messages 11915 for which the translation into Austrian differs from the German 11916 one. Whereas when working with `.resources' files, each message 11917 catalog must provide the translations of all messages by itself. 11918 11919 5. The `GettextResourceManager' that loads the message catalogs in 11920 `.dll' format also provides for a fallback: The English MSGID is 11921 returned when no translation can be found. Whereas when working 11922 with `.resources' files, a language-neutral `.resources' file must 11923 explicitly be provided as a fallback. 11924 11925 On the side of the programmatic APIs, the programmer can use either 11926the standard `ResourceManager' API and the GNU `GettextResourceManager' 11927API. The latter is an extension of the former, because 11928`GettextResourceManager' is a subclass of `ResourceManager'. 11929 11930 1. The `System.Resources.ResourceManager' API. 11931 11932 This API works with resources in `.resources' format. 11933 11934 The creation of the `ResourceManager' is done through 11935 new ResourceManager(domainname, Assembly.GetExecutingAssembly()) 11936 The `GetString' function returns a string's translation. Note 11937 that this function returns null when a translation is missing 11938 (i.e. not even found in the fallback resource file). 11939 11940 2. The `GNU.Gettext.GettextResourceManager' API. 11941 11942 This API works with resources in `.dll' format. 11943 11944 Reference documentation is in the csharpdoc directory 11945 (csharpdoc/index.html). 11946 11947 The creation of the `ResourceManager' is done through 11948 new GettextResourceManager(domainname) 11949 11950 The `GetString' function returns a string's translation. Note 11951 that when a translation is missing, the MSGID argument is returned 11952 unchanged. 11953 11954 The `GetPluralString' function returns a string translation with 11955 plural handling, like the `ngettext' function in C. 11956 11957 The `GetParticularString' function returns a string's translation, 11958 specific to a particular context, like the `pgettext' function in 11959 C. Note that when a translation is missing, the MSGID argument is 11960 returned unchanged. 11961 11962 The `GetParticularPluralString' function returns a string 11963 translation, specific to a particular context, with plural 11964 handling, like the `npgettext' function in C. 11965 11966 To use this API, one needs the `GNU.Gettext.dll' file which is 11967 part of the GNU gettext package and distributed under the LGPL. 11968 11969 You can also mix both approaches: use the 11970`GNU.Gettext.GettextResourceManager' constructor, but otherwise use 11971only the `ResourceManager' type and only the `GetString' method. This 11972is appropriate when you want to profit from the tools for PO files, but 11973don't want to change an existing source code that uses 11974`ResourceManager' and don't (yet) need the `GetPluralString' method. 11975 11976 Two examples, using the second API, are available in the `examples' 11977directory: `hello-csharp', `hello-csharp-forms'. 11978 11979 Now, to make use of the API and define a shorthand for `GetString', 11980there are two idioms that you can choose from: 11981 11982 * In a unique class of your project, say `Util', define a static 11983 variable holding the `ResourceManager' instance: 11984 11985 public static GettextResourceManager MyResourceManager = 11986 new GettextResourceManager("domain-name"); 11987 11988 All classes containing internationalized strings then contain 11989 11990 private static GettextResourceManager Res = Util.MyResourceManager; 11991 private static String _(String s) { return Res.GetString(s); } 11992 11993 and the shorthand is used like this: 11994 11995 Console.WriteLine(_("Operation completed.")); 11996 11997 * You add a class with a very short name, say `S', containing just 11998 the definition of the resource manager and of the shorthand: 11999 12000 public class S { 12001 public static GettextResourceManager MyResourceManager = 12002 new GettextResourceManager("domain-name"); 12003 public static String _(String s) { 12004 return MyResourceManager.GetString(s); 12005 } 12006 } 12007 12008 and the shorthand is used like this: 12009 12010 Console.WriteLine(S._("Operation completed.")); 12011 12012 Which of the two idioms you choose, will depend on whether copying 12013two lines of codes into every class is more acceptable in your project 12014than a class with a single-letter name. 12015 12016 12017File: gettext.info, Node: gawk, Next: Pascal, Prev: C#, Up: List of Programming Languages 12018 1201915.5.13 GNU awk 12020--------------- 12021 12022RPMs 12023 gawk 3.1 or newer 12024 12025File extension 12026 `awk' 12027 12028String syntax 12029 `"abc"' 12030 12031gettext shorthand 12032 `_"abc"' 12033 12034gettext/ngettext functions 12035 `dcgettext', missing `dcngettext' in gawk-3.1.0 12036 12037textdomain 12038 `TEXTDOMAIN' variable 12039 12040bindtextdomain 12041 `bindtextdomain' function 12042 12043setlocale 12044 automatic, but missing `setlocale (LC_MESSAGES, "")' in gawk-3.1.0 12045 12046Prerequisite 12047 -- 12048 12049Use or emulate GNU gettext 12050 use 12051 12052Extractor 12053 `xgettext' 12054 12055Formatting with positions 12056 `printf "%2$d %1$d"' (GNU awk only) 12057 12058Portability 12059 On platforms without gettext, no translation. On non-GNU awks, 12060 you must define `dcgettext', `dcngettext' and `bindtextdomain' 12061 yourself. 12062 12063po-mode marking 12064 -- 12065 12066 An example is available in the `examples' directory: `hello-gawk'. 12067 12068 12069File: gettext.info, Node: Pascal, Next: wxWidgets, Prev: gawk, Up: List of Programming Languages 12070 1207115.5.14 Pascal - Free Pascal Compiler 12072------------------------------------- 12073 12074RPMs 12075 fpk 12076 12077File extension 12078 `pp', `pas' 12079 12080String syntax 12081 `'abc'' 12082 12083gettext shorthand 12084 automatic 12085 12086gettext/ngettext functions 12087 --, use `ResourceString' data type instead 12088 12089textdomain 12090 --, use `TranslateResourceStrings' function instead 12091 12092bindtextdomain 12093 --, use `TranslateResourceStrings' function instead 12094 12095setlocale 12096 automatic, but uses only LANG, not LC_MESSAGES or LC_ALL 12097 12098Prerequisite 12099 `{$mode delphi}' or `{$mode objfpc}' 12100 `uses gettext;' 12101 12102Use or emulate GNU gettext 12103 emulate partially 12104 12105Extractor 12106 `ppc386' followed by `xgettext' or `rstconv' 12107 12108Formatting with positions 12109 `uses sysutils;' 12110 `format "%1:d %0:d"' 12111 12112Portability 12113 ? 12114 12115po-mode marking 12116 -- 12117 12118 The Pascal compiler has special support for the `ResourceString' data 12119type. It generates a `.rst' file. This is then converted to a `.pot' 12120file by use of `xgettext' or `rstconv'. At runtime, a `.mo' file 12121corresponding to translations of this `.pot' file can be loaded using 12122the `TranslateResourceStrings' function in the `gettext' unit. 12123 12124 An example is available in the `examples' directory: `hello-pascal'. 12125 12126 12127File: gettext.info, Node: wxWidgets, Next: YCP, Prev: Pascal, Up: List of Programming Languages 12128 1212915.5.15 wxWidgets library 12130------------------------- 12131 12132RPMs 12133 wxGTK, gettext 12134 12135File extension 12136 `cpp' 12137 12138String syntax 12139 `"abc"' 12140 12141gettext shorthand 12142 `_("abc")' 12143 12144gettext/ngettext functions 12145 `wxLocale::GetString', `wxGetTranslation' 12146 12147textdomain 12148 `wxLocale::AddCatalog' 12149 12150bindtextdomain 12151 `wxLocale::AddCatalogLookupPathPrefix' 12152 12153setlocale 12154 `wxLocale::Init', `wxSetLocale' 12155 12156Prerequisite 12157 `#include <wx/intl.h>' 12158 12159Use or emulate GNU gettext 12160 emulate, see `include/wx/intl.h' and `src/common/intl.cpp' 12161 12162Extractor 12163 `xgettext' 12164 12165Formatting with positions 12166 wxString::Format supports positions if and only if the system has 12167 `wprintf()', `vswprintf()' functions and they support positions 12168 according to POSIX. 12169 12170Portability 12171 fully portable 12172 12173po-mode marking 12174 yes 12175 12176 12177File: gettext.info, Node: YCP, Next: Tcl, Prev: wxWidgets, Up: List of Programming Languages 12178 1217915.5.16 YCP - YaST2 scripting language 12180-------------------------------------- 12181 12182RPMs 12183 libycp, libycp-devel, yast2-core, yast2-core-devel 12184 12185File extension 12186 `ycp' 12187 12188String syntax 12189 `"abc"' 12190 12191gettext shorthand 12192 `_("abc")' 12193 12194gettext/ngettext functions 12195 `_()' with 1 or 3 arguments 12196 12197textdomain 12198 `textdomain' statement 12199 12200bindtextdomain 12201 -- 12202 12203setlocale 12204 -- 12205 12206Prerequisite 12207 -- 12208 12209Use or emulate GNU gettext 12210 use 12211 12212Extractor 12213 `xgettext' 12214 12215Formatting with positions 12216 `sformat "%2 %1"' 12217 12218Portability 12219 fully portable 12220 12221po-mode marking 12222 -- 12223 12224 An example is available in the `examples' directory: `hello-ycp'. 12225 12226 12227File: gettext.info, Node: Tcl, Next: Perl, Prev: YCP, Up: List of Programming Languages 12228 1222915.5.17 Tcl - Tk's scripting language 12230------------------------------------- 12231 12232RPMs 12233 tcl 12234 12235File extension 12236 `tcl' 12237 12238String syntax 12239 `"abc"' 12240 12241gettext shorthand 12242 `[_ "abc"]' 12243 12244gettext/ngettext functions 12245 `::msgcat::mc' 12246 12247textdomain 12248 -- 12249 12250bindtextdomain 12251 --, use `::msgcat::mcload' instead 12252 12253setlocale 12254 automatic, uses LANG, but ignores LC_MESSAGES and LC_ALL 12255 12256Prerequisite 12257 `package require msgcat' 12258 `proc _ {s} {return [::msgcat::mc $s]}' 12259 12260Use or emulate GNU gettext 12261 --, uses a Tcl specific message catalog format 12262 12263Extractor 12264 `xgettext -k_' 12265 12266Formatting with positions 12267 `format "%2\$d %1\$d"' 12268 12269Portability 12270 fully portable 12271 12272po-mode marking 12273 -- 12274 12275 Two examples are available in the `examples' directory: `hello-tcl', 12276`hello-tcl-tk'. 12277 12278 Before marking strings as internationalizable, substitutions of 12279variables into the string need to be converted to `format' 12280applications. For example, `"file $filename not found"' becomes 12281`[format "file %s not found" $filename]'. Only after this is done, can 12282the strings be marked and extracted. After marking, this example 12283becomes `[format [_ "file %s not found"] $filename]' or `[msgcat::mc 12284"file %s not found" $filename]'. Note that the `msgcat::mc' function 12285implicitly calls `format' when more than one argument is given. 12286 12287 12288File: gettext.info, Node: Perl, Next: PHP, Prev: Tcl, Up: List of Programming Languages 12289 1229015.5.18 Perl 12291------------ 12292 12293RPMs 12294 perl 12295 12296File extension 12297 `pl', `PL', `pm', `cgi' 12298 12299String syntax 12300 * `"abc"' 12301 12302 * `'abc'' 12303 12304 * `qq (abc)' 12305 12306 * `q (abc)' 12307 12308 * `qr /abc/' 12309 12310 * `qx (/bin/date)' 12311 12312 * `/pattern match/' 12313 12314 * `?pattern match?' 12315 12316 * `s/substitution/operators/' 12317 12318 * `$tied_hash{"message"}' 12319 12320 * `$tied_hash_reference->{"message"}' 12321 12322 * etc., issue the command `man perlsyn' for details 12323 12324 12325gettext shorthand 12326 `__' (double underscore) 12327 12328gettext/ngettext functions 12329 `gettext', `dgettext', `dcgettext', `ngettext', `dngettext', 12330 `dcngettext' 12331 12332textdomain 12333 `textdomain' function 12334 12335bindtextdomain 12336 `bindtextdomain' function 12337 12338bind_textdomain_codeset 12339 `bind_textdomain_codeset' function 12340 12341setlocale 12342 Use `setlocale (LC_ALL, "");' 12343 12344Prerequisite 12345 `use POSIX;' 12346 `use Locale::TextDomain;' (included in the package libintl-perl 12347 which is available on the Comprehensive Perl Archive Network CPAN, 12348 http://www.cpan.org/). 12349 12350Use or emulate GNU gettext 12351 platform dependent: gettext_pp emulates, gettext_xs uses GNU 12352 gettext 12353 12354Extractor 12355 `xgettext -k__ -k\$__ -k%__ -k__x -k__n:1,2 -k__nx:1,2 -k__xn:1,2 12356 -kN__ -k' 12357 12358Formatting with positions 12359 Both kinds of format strings support formatting with positions. 12360 `printf "%2\$d %1\$d", ...' (requires Perl 5.8.0 or newer) 12361 `__expand("[new] replaces [old]", old => $oldvalue, new => 12362 $newvalue)' 12363 12364Portability 12365 The `libintl-perl' package is platform independent but is not part 12366 of the Perl core. The programmer is responsible for providing a 12367 dummy implementation of the required functions if the package is 12368 not installed on the target system. 12369 12370po-mode marking 12371 -- 12372 12373Documentation 12374 Included in `libintl-perl', available on CPAN 12375 (http://www.cpan.org/). 12376 12377 12378 An example is available in the `examples' directory: `hello-perl'. 12379 12380 The `xgettext' parser backend for Perl differs significantly from 12381the parser backends for other programming languages, just as Perl 12382itself differs significantly from other programming languages. The 12383Perl parser backend offers many more string marking facilities than the 12384other backends but it also has some Perl specific limitations, the 12385worst probably being its imperfectness. 12386 12387* Menu: 12388 12389* General Problems:: General Problems Parsing Perl Code 12390* Default Keywords:: Which Keywords Will xgettext Look For? 12391* Special Keywords:: How to Extract Hash Keys 12392* Quote-like Expressions:: What are Strings And Quote-like Expressions? 12393* Interpolation I:: Invalid String Interpolation 12394* Interpolation II:: Valid String Interpolation 12395* Parentheses:: When To Use Parentheses 12396* Long Lines:: How To Grok with Long Lines 12397* Perl Pitfalls:: Bugs, Pitfalls, and Things That Do Not Work 12398 12399 12400File: gettext.info, Node: General Problems, Next: Default Keywords, Up: Perl 12401 1240215.5.18.1 General Problems Parsing Perl Code 12403............................................ 12404 12405 It is often heard that only Perl can parse Perl. This is not true. 12406Perl cannot be _parsed_ at all, it can only be _executed_. Perl has 12407various built-in ambiguities that can only be resolved at runtime. 12408 12409 The following example may illustrate one common problem: 12410 12411 print gettext "Hello World!"; 12412 12413 Although this example looks like a bullet-proof case of a function 12414invocation, it is not: 12415 12416 open gettext, ">testfile" or die; 12417 print gettext "Hello world!" 12418 12419 In this context, the string `gettext' looks more like a file handle. 12420But not necessarily: 12421 12422 use Locale::Messages qw (:libintl_h); 12423 open gettext ">testfile" or die; 12424 print gettext "Hello world!"; 12425 12426 Now, the file is probably syntactically incorrect, provided that the 12427module `Locale::Messages' found first in the Perl include path exports a 12428function `gettext'. But what if the module `Locale::Messages' really 12429looks like this? 12430 12431 use vars qw (*gettext); 12432 12433 1; 12434 12435 In this case, the string `gettext' will be interpreted as a file 12436handle again, and the above example will create a file `testfile' and 12437write the string "Hello world!" into it. Even advanced control flow 12438analysis will not really help: 12439 12440 if (0.5 < rand) { 12441 eval "use Sane"; 12442 } else { 12443 eval "use InSane"; 12444 } 12445 print gettext "Hello world!"; 12446 12447 If the module `Sane' exports a function `gettext' that does what we 12448expect, and the module `InSane' opens a file for writing and associates 12449the _handle_ `gettext' with this output stream, we are clueless again 12450about what will happen at runtime. It is completely unpredictable. 12451The truth is that Perl has so many ways to fill its symbol table at 12452runtime that it is impossible to interpret a particular piece of code 12453without executing it. 12454 12455 Of course, `xgettext' will not execute your Perl sources while 12456scanning for translatable strings, but rather use heuristics in order 12457to guess what you meant. 12458 12459 Another problem is the ambiguity of the slash and the question mark. 12460Their interpretation depends on the context: 12461 12462 # A pattern match. 12463 print "OK\n" if /foobar/; 12464 12465 # A division. 12466 print 1 / 2; 12467 12468 # Another pattern match. 12469 print "OK\n" if ?foobar?; 12470 12471 # Conditional. 12472 print $x ? "foo" : "bar"; 12473 12474 The slash may either act as the division operator or introduce a 12475pattern match, whereas the question mark may act as the ternary 12476conditional operator or as a pattern match, too. Other programming 12477languages like `awk' present similar problems, but the consequences of a 12478misinterpretation are particularly nasty with Perl sources. In `awk' 12479for instance, a statement can never exceed one line and the parser can 12480recover from a parsing error at the next newline and interpret the rest 12481of the input stream correctly. Perl is different, as a pattern match 12482is terminated by the next appearance of the delimiter (the slash or the 12483question mark) in the input stream, regardless of the semantic context. 12484If a slash is really a division sign but mis-interpreted as a pattern 12485match, the rest of the input file is most probably parsed incorrectly. 12486 12487 If you find that `xgettext' fails to extract strings from portions 12488of your sources, you should therefore look out for slashes and/or 12489question marks preceding these sections. You may have come across a 12490bug in `xgettext''s Perl parser (and of course you should report that 12491bug). In the meantime you should consider to reformulate your code in 12492a manner less challenging to `xgettext'. 12493 12494 12495File: gettext.info, Node: Default Keywords, Next: Special Keywords, Prev: General Problems, Up: Perl 12496 1249715.5.18.2 Which keywords will xgettext look for? 12498................................................ 12499 12500 Unless you instruct `xgettext' otherwise by invoking it with one of 12501the options `--keyword' or `-k', it will recognize the following 12502keywords in your Perl sources: 12503 12504 * `gettext' 12505 12506 * `dgettext' 12507 12508 * `dcgettext' 12509 12510 * `ngettext:1,2' 12511 12512 The first (singular) and the second (plural) argument will be 12513 extracted. 12514 12515 * `dngettext:1,2' 12516 12517 The first (singular) and the second (plural) argument will be 12518 extracted. 12519 12520 * `dcngettext:1,2' 12521 12522 The first (singular) and the second (plural) argument will be 12523 extracted. 12524 12525 * `gettext_noop' 12526 12527 * `%gettext' 12528 12529 The keys of lookups into the hash `%gettext' will be extracted. 12530 12531 * `$gettext' 12532 12533 The keys of lookups into the hash reference `$gettext' will be 12534 extracted. 12535 12536 12537 12538File: gettext.info, Node: Special Keywords, Next: Quote-like Expressions, Prev: Default Keywords, Up: Perl 12539 1254015.5.18.3 How to Extract Hash Keys 12541.................................. 12542 12543 Translating messages at runtime is normally performed by looking up 12544the original string in the translation database and returning the 12545translated version. The "natural" Perl implementation is a hash 12546lookup, and, of course, `xgettext' supports such practice. 12547 12548 print __"Hello world!"; 12549 print $__{"Hello world!"}; 12550 print $__->{"Hello world!"}; 12551 print $$__{"Hello world!"}; 12552 12553 The above four lines all do the same thing. The Perl module 12554`Locale::TextDomain' exports by default a hash `%__' that is tied to 12555the function `__()'. It also exports a reference `$__' to `%__'. 12556 12557 If an argument to the `xgettext' option `--keyword', resp. `-k' 12558starts with a percent sign, the rest of the keyword is interpreted as 12559the name of a hash. If it starts with a dollar sign, the rest of the 12560keyword is interpreted as a reference to a hash. 12561 12562 Note that you can omit the quotation marks (single or double) around 12563the hash key (almost) whenever Perl itself allows it: 12564 12565 print $gettext{Error}; 12566 12567 The exact rule is: You can omit the surrounding quotes, when the hash 12568key is a valid C (!) identifier, i.e. when it starts with an underscore 12569or an ASCII letter and is followed by an arbitrary number of 12570underscores, ASCII letters or digits. Other Unicode characters are 12571_not_ allowed, regardless of the `use utf8' pragma. 12572 12573 12574File: gettext.info, Node: Quote-like Expressions, Next: Interpolation I, Prev: Special Keywords, Up: Perl 12575 1257615.5.18.4 What are Strings And Quote-like Expressions? 12577...................................................... 12578 12579 Perl offers a plethora of different string constructs. Those that 12580can be used either as arguments to functions or inside braces for hash 12581lookups are generally supported by `xgettext'. 12582 12583 * *double-quoted strings* 12584 print gettext "Hello World!"; 12585 12586 * *single-quoted strings* 12587 print gettext 'Hello World!'; 12588 12589 * *the operator qq* 12590 print gettext qq |Hello World!|; 12591 print gettext qq <E-mail: <guido\@imperia.net>>; 12592 12593 The operator `qq' is fully supported. You can use arbitrary 12594 delimiters, including the four bracketing delimiters (round, angle, 12595 square, curly) that nest. 12596 12597 * *the operator q* 12598 print gettext q |Hello World!|; 12599 print gettext q <E-mail: <guido@imperia.net>>; 12600 12601 The operator `q' is fully supported. You can use arbitrary 12602 delimiters, including the four bracketing delimiters (round, angle, 12603 square, curly) that nest. 12604 12605 * *the operator qx* 12606 print gettext qx ;LANGUAGE=C /bin/date; 12607 print gettext qx [/usr/bin/ls | grep '^[A-Z]*']; 12608 12609 The operator `qx' is fully supported. You can use arbitrary 12610 delimiters, including the four bracketing delimiters (round, angle, 12611 square, curly) that nest. 12612 12613 The example is actually a useless use of `gettext'. It will 12614 invoke the `gettext' function on the output of the command 12615 specified with the `qx' operator. The feature was included in 12616 order to make the interface consistent (the parser will extract 12617 all strings and quote-like expressions). 12618 12619 * *here documents* 12620 print gettext <<'EOF'; 12621 program not found in $PATH 12622 EOF 12623 12624 print ngettext <<EOF, <<"EOF"; 12625 one file deleted 12626 EOF 12627 several files deleted 12628 EOF 12629 12630 Here-documents are recognized. If the delimiter is enclosed in 12631 single quotes, the string is not interpolated. If it is enclosed 12632 in double quotes or has no quotes at all, the string is 12633 interpolated. 12634 12635 Delimiters that start with a digit are not supported! 12636 12637 12638 12639File: gettext.info, Node: Interpolation I, Next: Interpolation II, Prev: Quote-like Expressions, Up: Perl 12640 1264115.5.18.5 Invalid Uses Of String Interpolation 12642.............................................. 12643 12644 Perl is capable of interpolating variables into strings. This offers 12645some nice features in localized programs but can also lead to problems. 12646 12647 A common error is a construct like the following: 12648 12649 print gettext "This is the program $0!\n"; 12650 12651 Perl will interpolate at runtime the value of the variable `$0' into 12652the argument of the `gettext()' function. Hence, this argument is not 12653a string constant but a variable argument (`$0' is a global variable 12654that holds the name of the Perl script being executed). The 12655interpolation is performed by Perl before the string argument is passed 12656to `gettext()' and will therefore depend on the name of the script 12657which can only be determined at runtime. Consequently, it is almost 12658impossible that a translation can be looked up at runtime (except if, 12659by accident, the interpolated string is found in the message catalog). 12660 12661 The `xgettext' program will therefore terminate parsing with a fatal 12662error if it encounters a variable inside of an extracted string. In 12663general, this will happen for all kinds of string interpolations that 12664cannot be safely performed at compile time. If you absolutely know 12665what you are doing, you can always circumvent this behavior: 12666 12667 my $know_what_i_am_doing = "This is program $0!\n"; 12668 print gettext $know_what_i_am_doing; 12669 12670 Since the parser only recognizes strings and quote-like expressions, 12671but not variables or other terms, the above construct will be accepted. 12672You will have to find another way, however, to let your original string 12673make it into your message catalog. 12674 12675 If invoked with the option `--extract-all', resp. `-a', variable 12676interpolation will be accepted. Rationale: You will generally use this 12677option in order to prepare your sources for internationalization. 12678 12679 Please see the manual page `man perlop' for details of strings and 12680quote-like expressions that are subject to interpolation and those that 12681are not. Safe interpolations (that will not lead to a fatal error) are: 12682 12683 * the escape sequences `\t' (tab, HT, TAB), `\n' (newline, NL), `\r' 12684 (return, CR), `\f' (form feed, FF), `\b' (backspace, BS), `\a' 12685 (alarm, bell, BEL), and `\e' (escape, ESC). 12686 12687 * octal chars, like `\033' 12688 Note that octal escapes in the range of 400-777 are translated 12689 into a UTF-8 representation, regardless of the presence of the 12690 `use utf8' pragma. 12691 12692 * hex chars, like `\x1b' 12693 12694 * wide hex chars, like `\x{263a}' 12695 Note that this escape is translated into a UTF-8 representation, 12696 regardless of the presence of the `use utf8' pragma. 12697 12698 * control chars, like `\c[' (CTRL-[) 12699 12700 * named Unicode chars, like `\N{LATIN CAPITAL LETTER C WITH CEDILLA}' 12701 Note that this escape is translated into a UTF-8 representation, 12702 regardless of the presence of the `use utf8' pragma. 12703 12704 The following escapes are considered partially safe: 12705 12706 * `\l' lowercase next char 12707 12708 * `\u' uppercase next char 12709 12710 * `\L' lowercase till \E 12711 12712 * `\U' uppercase till \E 12713 12714 * `\E' end case modification 12715 12716 * `\Q' quote non-word characters till \E 12717 12718 12719 These escapes are only considered safe if the string consists of 12720ASCII characters only. Translation of characters outside the range 12721defined by ASCII is locale-dependent and can actually only be performed 12722at runtime; `xgettext' doesn't do these locale-dependent translations 12723at extraction time. 12724 12725 Except for the modifier `\Q', these translations, albeit valid, are 12726generally useless and only obfuscate your sources. If a translation 12727can be safely performed at compile time you can just as well write what 12728you mean. 12729 12730 12731File: gettext.info, Node: Interpolation II, Next: Parentheses, Prev: Interpolation I, Up: Perl 12732 1273315.5.18.6 Valid Uses Of String Interpolation 12734............................................ 12735 12736 Perl is often used to generate sources for other programming 12737languages or arbitrary file formats. Web applications that output HTML 12738code make a prominent example for such usage. 12739 12740 You will often come across situations where you want to intersperse 12741code written in the target (programming) language with translatable 12742messages, like in the following HTML example: 12743 12744 print gettext <<EOF; 12745 <h1>My Homepage</h1> 12746 <script language="JavaScript"><!-- 12747 for (i = 0; i < 100; ++i) { 12748 alert ("Thank you so much for visiting my homepage!"); 12749 } 12750 //--></script> 12751 EOF 12752 12753 The parser will extract the entire here document, and it will appear 12754entirely in the resulting PO file, including the JavaScript snippet 12755embedded in the HTML code. If you exaggerate with constructs like the 12756above, you will run the risk that the translators of your package will 12757look out for a less challenging project. You should consider an 12758alternative expression here: 12759 12760 print <<EOF; 12761 <h1>$gettext{"My Homepage"}</h1> 12762 <script language="JavaScript"><!-- 12763 for (i = 0; i < 100; ++i) { 12764 alert ("$gettext{'Thank you so much for visiting my homepage!'}"); 12765 } 12766 //--></script> 12767 EOF 12768 12769 Only the translatable portions of the code will be extracted here, 12770and the resulting PO file will begrudgingly improve in terms of 12771readability. 12772 12773 You can interpolate hash lookups in all strings or quote-like 12774expressions that are subject to interpolation (see the manual page `man 12775perlop' for details). Double interpolation is invalid, however: 12776 12777 # TRANSLATORS: Replace "the earth" with the name of your planet. 12778 print gettext qq{Welcome to $gettext->{"the earth"}}; 12779 12780 The `qq'-quoted string is recognized as an argument to `xgettext' in 12781the first place, and checked for invalid variable interpolation. The 12782dollar sign of hash-dereferencing will therefore terminate the parser 12783with an "invalid interpolation" error. 12784 12785 It is valid to interpolate hash lookups in regular expressions: 12786 12787 if ($var =~ /$gettext{"the earth"}/) { 12788 print gettext "Match!\n"; 12789 } 12790 s/$gettext{"U. S. A."}/$gettext{"U. S. A."} $gettext{"(dial +0)"}/g; 12791 12792 12793File: gettext.info, Node: Parentheses, Next: Long Lines, Prev: Interpolation II, Up: Perl 12794 1279515.5.18.7 When To Use Parentheses 12796................................. 12797 12798 In Perl, parentheses around function arguments are mostly optional. 12799`xgettext' will always assume that all recognized keywords (except for 12800hashes and hash references) are names of properly prototyped functions, 12801and will (hopefully) only require parentheses where Perl itself 12802requires them. All constructs in the following example are therefore 12803ok to use: 12804 12805 print gettext ("Hello World!\n"); 12806 print gettext "Hello World!\n"; 12807 print dgettext ($package => "Hello World!\n"); 12808 print dgettext $package, "Hello World!\n"; 12809 12810 # The "fat comma" => turns the left-hand side argument into a 12811 # single-quoted string! 12812 print dgettext smellovision => "Hello World!\n"; 12813 12814 # The following assignment only works with prototyped functions. 12815 # Otherwise, the functions will act as "greedy" list operators and 12816 # eat up all following arguments. 12817 my $anonymous_hash = { 12818 planet => gettext "earth", 12819 cakes => ngettext "one cake", "several cakes", $n, 12820 still => $works, 12821 }; 12822 # The same without fat comma: 12823 my $other_hash = { 12824 'planet', gettext "earth", 12825 'cakes', ngettext "one cake", "several cakes", $n, 12826 'still', $works, 12827 }; 12828 12829 # Parentheses are only significant for the first argument. 12830 print dngettext 'package', ("one cake", "several cakes", $n), $discarded; 12831 12832 12833File: gettext.info, Node: Long Lines, Next: Perl Pitfalls, Prev: Parentheses, Up: Perl 12834 1283515.5.18.8 How To Grok with Long Lines 12836..................................... 12837 12838 The necessity of long messages can often lead to a cumbersome or 12839unreadable coding style. Perl has several options that may prevent you 12840from writing unreadable code, and `xgettext' does its best to do 12841likewise. This is where the dot operator (the string concatenation 12842operator) may come in handy: 12843 12844 print gettext ("This is a very long" 12845 . " message that is still" 12846 . " readable, because" 12847 . " it is split into" 12848 . " multiple lines.\n"); 12849 12850 Perl is smart enough to concatenate these constant string fragments 12851into one long string at compile time, and so is `xgettext'. You will 12852only find one long message in the resulting POT file. 12853 12854 Note that the future Perl 6 will probably use the underscore (`_') 12855as the string concatenation operator, and the dot (`.') for 12856dereferencing. This new syntax is not yet supported by `xgettext'. 12857 12858 If embedded newline characters are not an issue, or even desired, you 12859may also insert newline characters inside quoted strings wherever you 12860feel like it: 12861 12862 print gettext ("<em>In HTML output 12863 embedded newlines are generally no 12864 problem, since adjacent whitespace 12865 is always rendered into a single 12866 space character.</em>"); 12867 12868 You may also consider to use here documents: 12869 12870 print gettext <<EOF; 12871 <em>In HTML output 12872 embedded newlines are generally no 12873 problem, since adjacent whitespace 12874 is always rendered into a single 12875 space character.</em> 12876 EOF 12877 12878 Please do not forget that the line breaks are real, i.e. they 12879translate into newline characters that will consequently show up in the 12880resulting POT file. 12881 12882 12883File: gettext.info, Node: Perl Pitfalls, Prev: Long Lines, Up: Perl 12884 1288515.5.18.9 Bugs, Pitfalls, And Things That Do Not Work 12886..................................................... 12887 12888 The foregoing sections should have proven that `xgettext' is quite 12889smart in extracting translatable strings from Perl sources. Yet, some 12890more or less exotic constructs that could be expected to work, actually 12891do not work. 12892 12893 One of the more relevant limitations can be found in the 12894implementation of variable interpolation inside quoted strings. Only 12895simple hash lookups can be used there: 12896 12897 print <<EOF; 12898 $gettext{"The dot operator" 12899 . " does not work" 12900 . "here!"} 12901 Likewise, you cannot @{[ gettext ("interpolate function calls") ]} 12902 inside quoted strings or quote-like expressions. 12903 EOF 12904 12905 This is valid Perl code and will actually trigger invocations of the 12906`gettext' function at runtime. Yet, the Perl parser in `xgettext' will 12907fail to recognize the strings. A less obvious example can be found in 12908the interpolation of regular expressions: 12909 12910 s/<!--START_OF_WEEK-->/gettext ("Sunday")/e; 12911 12912 The modifier `e' will cause the substitution to be interpreted as an 12913evaluable statement. Consequently, at runtime the function `gettext()' 12914is called, but again, the parser fails to extract the string "Sunday". 12915Use a temporary variable as a simple workaround if you really happen to 12916need this feature: 12917 12918 my $sunday = gettext "Sunday"; 12919 s/<!--START_OF_WEEK-->/$sunday/; 12920 12921 Hash slices would also be handy but are not recognized: 12922 12923 my @weekdays = @gettext{'Sunday', 'Monday', 'Tuesday', 'Wednesday', 12924 'Thursday', 'Friday', 'Saturday'}; 12925 # Or even: 12926 @weekdays = @gettext{qw (Sunday Monday Tuesday Wednesday Thursday 12927 Friday Saturday) }; 12928 12929 This is perfectly valid usage of the tied hash `%gettext' but the 12930strings are not recognized and therefore will not be extracted. 12931 12932 Another caveat of the current version is its rudimentary support for 12933non-ASCII characters in identifiers. You may encounter serious 12934problems if you use identifiers with characters outside the range of 12935'A'-'Z', 'a'-'z', '0'-'9' and the underscore '_'. 12936 12937 Maybe some of these missing features will be implemented in future 12938versions, but since you can always make do without them at minimal 12939effort, these todos have very low priority. 12940 12941 A nasty problem are brace format strings that already contain braces 12942as part of the normal text, for example the usage strings typically 12943encountered in programs: 12944 12945 die "usage: $0 {OPTIONS} FILENAME...\n"; 12946 12947 If you want to internationalize this code with Perl brace format 12948strings, you will run into a problem: 12949 12950 die __x ("usage: {program} {OPTIONS} FILENAME...\n", program => $0); 12951 12952 Whereas `{program}' is a placeholder, `{OPTIONS}' is not and should 12953probably be translated. Yet, there is no way to teach the Perl parser 12954in `xgettext' to recognize the first one, and leave the other one alone. 12955 12956 There are two possible work-arounds for this problem. If you are 12957sure that your program will run under Perl 5.8.0 or newer (these Perl 12958versions handle positional parameters in `printf()') or if you are sure 12959that the translator will not have to reorder the arguments in her 12960translation - for example if you have only one brace placeholder in 12961your string, or if it describes a syntax, like in this one -, you can 12962mark the string as `no-perl-brace-format' and use `printf()': 12963 12964 # xgettext: no-perl-brace-format 12965 die sprintf ("usage: %s {OPTIONS} FILENAME...\n", $0); 12966 12967 If you want to use the more portable Perl brace format, you will 12968have to do put placeholders in place of the literal braces: 12969 12970 die __x ("usage: {program} {[}OPTIONS{]} FILENAME...\n", 12971 program => $0, '[' => '{', ']' => '}'); 12972 12973 Perl brace format strings know no escaping mechanism. No matter how 12974this escaping mechanism looked like, it would either give the 12975programmer a hard time, make translating Perl brace format strings 12976heavy-going, or result in a performance penalty at runtime, when the 12977format directives get executed. Most of the time you will happily get 12978along with `printf()' for this special case. 12979 12980 12981File: gettext.info, Node: PHP, Next: Pike, Prev: Perl, Up: List of Programming Languages 12982 1298315.5.19 PHP Hypertext Preprocessor 12984---------------------------------- 12985 12986RPMs 12987 mod_php4, mod_php4-core, phpdoc 12988 12989File extension 12990 `php', `php3', `php4' 12991 12992String syntax 12993 `"abc"', `'abc'' 12994 12995gettext shorthand 12996 `_("abc")' 12997 12998gettext/ngettext functions 12999 `gettext', `dgettext', `dcgettext'; starting with PHP 4.2.0 also 13000 `ngettext', `dngettext', `dcngettext' 13001 13002textdomain 13003 `textdomain' function 13004 13005bindtextdomain 13006 `bindtextdomain' function 13007 13008setlocale 13009 Programmer must call `setlocale (LC_ALL, "")' 13010 13011Prerequisite 13012 -- 13013 13014Use or emulate GNU gettext 13015 use 13016 13017Extractor 13018 `xgettext' 13019 13020Formatting with positions 13021 `printf "%2\$d %1\$d"' 13022 13023Portability 13024 On platforms without gettext, the functions are not available. 13025 13026po-mode marking 13027 -- 13028 13029 An example is available in the `examples' directory: `hello-php'. 13030 13031 13032File: gettext.info, Node: Pike, Next: GCC-source, Prev: PHP, Up: List of Programming Languages 13033 1303415.5.20 Pike 13035------------ 13036 13037RPMs 13038 roxen 13039 13040File extension 13041 `pike' 13042 13043String syntax 13044 `"abc"' 13045 13046gettext shorthand 13047 -- 13048 13049gettext/ngettext functions 13050 `gettext', `dgettext', `dcgettext' 13051 13052textdomain 13053 `textdomain' function 13054 13055bindtextdomain 13056 `bindtextdomain' function 13057 13058setlocale 13059 `setlocale' function 13060 13061Prerequisite 13062 `import Locale.Gettext;' 13063 13064Use or emulate GNU gettext 13065 use 13066 13067Extractor 13068 -- 13069 13070Formatting with positions 13071 -- 13072 13073Portability 13074 On platforms without gettext, the functions are not available. 13075 13076po-mode marking 13077 -- 13078 13079 13080File: gettext.info, Node: GCC-source, Prev: Pike, Up: List of Programming Languages 13081 1308215.5.21 GNU Compiler Collection sources 13083--------------------------------------- 13084 13085RPMs 13086 gcc 13087 13088File extension 13089 `c', `h'. 13090 13091String syntax 13092 `"abc"' 13093 13094gettext shorthand 13095 `_("abc")' 13096 13097gettext/ngettext functions 13098 `gettext', `dgettext', `dcgettext', `ngettext', `dngettext', 13099 `dcngettext' 13100 13101textdomain 13102 `textdomain' function 13103 13104bindtextdomain 13105 `bindtextdomain' function 13106 13107setlocale 13108 Programmer must call `setlocale (LC_ALL, "")' 13109 13110Prerequisite 13111 `#include "intl.h"' 13112 13113Use or emulate GNU gettext 13114 Use 13115 13116Extractor 13117 `xgettext -k_' 13118 13119Formatting with positions 13120 -- 13121 13122Portability 13123 Uses autoconf macros 13124 13125po-mode marking 13126 yes 13127 13128 13129File: gettext.info, Node: List of Data Formats, Prev: List of Programming Languages, Up: Programming Languages 13130 1313115.6 Internationalizable Data 13132============================= 13133 13134 Here is a list of other data formats which can be internationalized 13135using GNU gettext. 13136 13137* Menu: 13138 13139* POT:: POT - Portable Object Template 13140* RST:: Resource String Table 13141* Glade:: Glade - GNOME user interface description 13142 13143 13144File: gettext.info, Node: POT, Next: RST, Prev: List of Data Formats, Up: List of Data Formats 13145 1314615.6.1 POT - Portable Object Template 13147------------------------------------- 13148 13149RPMs 13150 gettext 13151 13152File extension 13153 `pot', `po' 13154 13155Extractor 13156 `xgettext' 13157 13158 13159File: gettext.info, Node: RST, Next: Glade, Prev: POT, Up: List of Data Formats 13160 1316115.6.2 Resource String Table 13162---------------------------- 13163 13164RPMs 13165 fpk 13166 13167File extension 13168 `rst' 13169 13170Extractor 13171 `xgettext', `rstconv' 13172 13173 13174File: gettext.info, Node: Glade, Prev: RST, Up: List of Data Formats 13175 1317615.6.3 Glade - GNOME user interface description 13177----------------------------------------------- 13178 13179RPMs 13180 glade, libglade, glade2, libglade2, intltool 13181 13182File extension 13183 `glade', `glade2' 13184 13185Extractor 13186 `xgettext', `libglade-xgettext', `xml-i18n-extract', 13187 `intltool-extract' 13188 13189 13190File: gettext.info, Node: Conclusion, Next: Language Codes, Prev: Programming Languages, Up: Top 13191 1319216 Concluding Remarks 13193********************* 13194 13195 We would like to conclude this GNU `gettext' manual by presenting an 13196history of the Translation Project so far. We finally give a few 13197pointers for those who want to do further research or readings about 13198Native Language Support matters. 13199 13200* Menu: 13201 13202* History:: History of GNU `gettext' 13203* References:: Related Readings 13204 13205 13206File: gettext.info, Node: History, Next: References, Prev: Conclusion, Up: Conclusion 13207 1320816.1 History of GNU `gettext' 13209============================= 13210 13211 Internationalization concerns and algorithms have been informally 13212and casually discussed for years in GNU, sometimes around GNU `libc', 13213maybe around the incoming `Hurd', or otherwise (nobody clearly 13214remembers). And even then, when the work started for real, this was 13215somewhat independently of these previous discussions. 13216 13217 This all began in July 1994, when Patrick D'Cruze had the idea and 13218initiative of internationalizing version 3.9.2 of GNU `fileutils'. He 13219then asked Jim Meyering, the maintainer, how to get those changes 13220folded into an official release. That first draft was full of 13221`#ifdef's and somewhat disconcerting, and Jim wanted to find nicer 13222ways. Patrick and Jim shared some tries and experimentations in this 13223area. Then, feeling that this might eventually have a deeper impact on 13224GNU, Jim wanted to know what standards were, and contacted Richard 13225Stallman, who very quickly and verbally described an overall design for 13226what was meant to become `glocale', at that time. 13227 13228 Jim implemented `glocale' and got a lot of exhausting feedback from 13229Patrick and Richard, of course, but also from Mitchum DSouza (who wrote 13230a `catgets'-like package), Roland McGrath, maybe David MacKenzie, 13231Fran��ois Pinard, and Paul Eggert, all pushing and pulling in various 13232directions, not always compatible, to the extent that after a couple of 13233test releases, `glocale' was torn apart. In particular, Paul Eggert - 13234always keeping an eye on developments in Solaris - advocated the use of 13235the `gettext' API over `glocale''s `catgets'-based API. 13236 13237 While Jim took some distance and time and became dad for a second 13238time, Roland wanted to get GNU `libc' internationalized, and got Ulrich 13239Drepper involved in that project. Instead of starting from `glocale', 13240Ulrich rewrote something from scratch, but more conforming to the set 13241of guidelines who emerged out of the `glocale' effort. Then, Ulrich 13242got people from the previous forum to involve themselves into this new 13243project, and the switch from `glocale' to what was first named 13244`msgutils', renamed `nlsutils', and later `gettext', became officially 13245accepted by Richard in May 1995 or so. 13246 13247 Let's summarize by saying that Ulrich Drepper wrote GNU `gettext' in 13248April 1995. The first official release of the package, including PO 13249mode, occurred in July 1995, and was numbered 0.7. Other people 13250contributed to the effort by providing a discussion forum around 13251Ulrich, writing little pieces of code, or testing. These are quoted in 13252the `THANKS' file which comes with the GNU `gettext' distribution. 13253 13254 While this was being done, Fran��ois adapted half a dozen of GNU 13255packages to `glocale' first, then later to `gettext', putting them in 13256pretest, so providing along the way an effective user environment for 13257fine tuning the evolving tools. He also took the responsibility of 13258organizing and coordinating the Translation Project. After nearly a 13259year of informal exchanges between people from many countries, 13260translator teams started to exist in May 1995, through the creation and 13261support by Patrick D'Cruze of twenty unmoderated mailing lists for that 13262many native languages, and two moderated lists: one for reaching all 13263teams at once, the other for reaching all willing maintainers of 13264internationalized free software packages. 13265 13266 Fran��ois also wrote PO mode in June 1995 with the collaboration of 13267Greg McGary, as a kind of contribution to Ulrich's package. He also 13268gave a hand with the GNU `gettext' Texinfo manual. 13269 13270 In 1997, Ulrich Drepper released the GNU libc 2.0, which included the 13271`gettext', `textdomain' and `bindtextdomain' functions. 13272 13273 In 2000, Ulrich Drepper added plural form handling (the `ngettext' 13274function) to GNU libc. Later, in 2001, he released GNU libc 2.2.x, 13275which is the first free C library with full internationalization 13276support. 13277 13278 Ulrich being quite busy in his role of General Maintainer of GNU 13279libc, he handed over the GNU `gettext' maintenance to Bruno Haible in 132802000. Bruno added the plural form handling to the tools as well, added 13281support for UTF-8 and CJK locales, and wrote a few new tools for 13282manipulating PO files. 13283 13284 13285File: gettext.info, Node: References, Prev: History, Up: Conclusion 13286 1328716.2 Related Readings 13288===================== 13289 13290 * NOTE: * This documentation section is outdated and needs to be 13291revised. 13292 13293 Eugene H. Dorr (`dorre@well.com') maintains an interesting 13294bibliography on internationalization matters, called 13295`Internationalization Reference List', which is available as: 13296 ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt 13297 13298 Michael Gschwind (`mike@vlsivie.tuwien.ac.at') maintains a 13299Frequently Asked Questions (FAQ) list, entitled `Programming for 13300Internationalisation'. This FAQ discusses writing programs which can 13301handle different language conventions, character sets, etc.; and is 13302applicable to all character set encodings, with particular emphasis on 13303ISO 8859-1. It is regularly published in Usenet groups 13304`comp.unix.questions', `comp.std.internat', 13305`comp.software.international', `comp.lang.c', `comp.windows.x', 13306`comp.std.c', `comp.answers' and `news.answers'. The home location of 13307this document is: 13308 ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming 13309 13310 Patrick D'Cruze (`pdcruze@li.org') wrote a tutorial about NLS 13311matters, and Jochen Hein (`Hein@student.tu-clausthal.de') took over the 13312responsibility of maintaining it. It may be found as: 13313 ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/... 13314 ...locale-tutorial-0.8.txt.gz 13315 This site is mirrored in: 13316 ftp://ftp.ibp.fr/pub/linux/sunsite/ 13317 13318 A French version of the same tutorial should be findable at: 13319 ftp://ftp.ibp.fr/pub/linux/french/docs/ 13320 together with French translations of many Linux-related documents. 13321 13322 13323File: gettext.info, Node: Language Codes, Next: Country Codes, Prev: Conclusion, Up: Top 13324 13325Appendix A Language Codes 13326************************* 13327 13328 The ISO 639 standard defines two-letter codes for many languages, and 13329three-letter codes for more rarely used languages. All abbreviations 13330for languages used in the Translation Project should come from this 13331standard. 13332 13333* Menu: 13334 13335* Usual Language Codes:: Two-letter ISO 639 language codes 13336* Rare Language Codes:: Three-letter ISO 639 language codes 13337 13338 13339File: gettext.info, Node: Usual Language Codes, Next: Rare Language Codes, Prev: Language Codes, Up: Language Codes 13340 13341A.1 Usual Language Codes 13342======================== 13343 13344 For the commonly used languages, the ISO 639-1 standard defines 13345two-letter codes. 13346 13347`aa' 13348 Afar. 13349 13350`ab' 13351 Abkhazian. 13352 13353`ad' 13354 Adangme. 13355 13356`ae' 13357 Avestan. 13358 13359`af' 13360 Afrikaans. 13361 13362`ak' 13363 Akan. 13364 13365`am' 13366 Amharic. 13367 13368`an' 13369 Aragonese. 13370 13371`ar' 13372 Arabic. 13373 13374`as' 13375 Assamese. 13376 13377`av' 13378 Avaric. 13379 13380`ay' 13381 Aymara. 13382 13383`az' 13384 Azerbaijani. 13385 13386`ba' 13387 Bashkir. 13388 13389`be' 13390 Byelorussian; Belarusian. 13391 13392`bg' 13393 Bulgarian. 13394 13395`bh' 13396 Bihari. 13397 13398`bi' 13399 Bislama. 13400 13401`bm' 13402 Bambara. 13403 13404`bn' 13405 Bengali; Bangla. 13406 13407`bo' 13408 Tibetan. 13409 13410`br' 13411 Breton. 13412 13413`bs' 13414 Bosnian. 13415 13416`ca' 13417 Catalan. 13418 13419`ce' 13420 Chechen. 13421 13422`ch' 13423 Chamorro. 13424 13425`co' 13426 Corsican. 13427 13428`cr' 13429 Cree. 13430 13431`cs' 13432 Czech. 13433 13434`cu' 13435 Church Slavic. 13436 13437`cv' 13438 Chuvash. 13439 13440`cy' 13441 Welsh. 13442 13443`da' 13444 Danish. 13445 13446`de' 13447 German. 13448 13449`dv' 13450 Divehi; Maldivian. 13451 13452`dz' 13453 Dzongkha; Bhutani. 13454 13455`ee' 13456 ��w��. 13457 13458`el' 13459 Greek. 13460 13461`en' 13462 English. 13463 13464`eo' 13465 Esperanto. 13466 13467`es' 13468 Spanish. 13469 13470`et' 13471 Estonian. 13472 13473`eu' 13474 Basque. 13475 13476`fa' 13477 Persian. 13478 13479`ff' 13480 Fulah. 13481 13482`fi' 13483 Finnish. 13484 13485`fj' 13486 Fijian; Fiji. 13487 13488`fo' 13489 Faroese. 13490 13491`fr' 13492 French. 13493 13494`fy' 13495 Western Frisian. 13496 13497`ga' 13498 Irish. 13499 13500`gd' 13501 Scots; Gaelic. 13502 13503`gl' 13504 Galician. 13505 13506`gn' 13507 Guarani. 13508 13509`gu' 13510 Gujarati. 13511 13512`gv' 13513 Manx. 13514 13515`ha' 13516 Hausa. 13517 13518`he' 13519 Hebrew (formerly iw). 13520 13521`hi' 13522 Hindi. 13523 13524`ho' 13525 Hiri Motu. 13526 13527`hr' 13528 Croatian. 13529 13530`ht' 13531 Haitian; Haitian Creole. 13532 13533`hu' 13534 Hungarian. 13535 13536`hy' 13537 Armenian. 13538 13539`hz' 13540 Herero. 13541 13542`ia' 13543 Interlingua. 13544 13545`id' 13546 Indonesian (formerly in). 13547 13548`ie' 13549 Interlingue. 13550 13551`ig' 13552 Igbo. 13553 13554`ii' 13555 Sichuan Yi. 13556 13557`ik' 13558 Inupiak; Inupiaq. 13559 13560`io' 13561 Ido. 13562 13563`is' 13564 Icelandic. 13565 13566`it' 13567 Italian. 13568 13569`iu' 13570 Inuktitut. 13571 13572`ja' 13573 Japanese. 13574 13575`jv' 13576 Javanese. 13577 13578`ka' 13579 Georgian. 13580 13581`kg' 13582 Kongo. 13583 13584`ki' 13585 Kikuyu; Gikuyu. 13586 13587`kj' 13588 Kuanyama; Kwanyama. 13589 13590`kk' 13591 Kazakh. 13592 13593`kl' 13594 Kalaallisut; Greenlandic. 13595 13596`km' 13597 Khmer; Cambodian. 13598 13599`kn' 13600 Kannada. 13601 13602`ko' 13603 Korean. 13604 13605`kr' 13606 Kanuri. 13607 13608`ks' 13609 Kashmiri. 13610 13611`ku' 13612 Kurdish. 13613 13614`kv' 13615 Komi. 13616 13617`kw' 13618 Cornish. 13619 13620`ky' 13621 Kirghiz. 13622 13623`la' 13624 Latin. 13625 13626`lb' 13627 Letzeburgesch; Luxembourgish. 13628 13629`lg' 13630 Ganda. 13631 13632`li' 13633 Limburgish; Limburger; Limburgan. 13634 13635`ln' 13636 Lingala. 13637 13638`lo' 13639 Lao; Laotian. 13640 13641`lt' 13642 Lithuanian. 13643 13644`lu' 13645 Luba-Katanga. 13646 13647`lv' 13648 Latvian; Lettish. 13649 13650`mg' 13651 Malagasy. 13652 13653`mh' 13654 Marshallese. 13655 13656`mi' 13657 Maori. 13658 13659`mk' 13660 Macedonian. 13661 13662`ml' 13663 Malayalam. 13664 13665`mn' 13666 Mongolian. 13667 13668`mo' 13669 Moldavian. 13670 13671`mr' 13672 Marathi. 13673 13674`ms' 13675 Malay. 13676 13677`mt' 13678 Maltese. 13679 13680`my' 13681 Burmese. 13682 13683`na' 13684 Nauru. 13685 13686`nb' 13687 Norwegian Bokm��l. 13688 13689`nd' 13690 Ndebele, North. 13691 13692`ne' 13693 Nepali. 13694 13695`ng' 13696 Ndonga. 13697 13698`nl' 13699 Dutch. 13700 13701`nn' 13702 Norwegian Nynorsk. 13703 13704`no' 13705 Norwegian. 13706 13707`nr' 13708 Ndebele, South. 13709 13710`nv' 13711 Navajo; Navaho. 13712 13713`ny' 13714 Chichewa; Nyanja. 13715 13716`oc' 13717 Occitan; Proven��al. 13718 13719`oj' 13720 Ojibwa. 13721 13722`om' 13723 (Afan) Oromo. 13724 13725`or' 13726 Oriya. 13727 13728`os' 13729 Ossetian; Ossetic. 13730 13731`pa' 13732 Panjabi; Punjabi. 13733 13734`pi' 13735 Pali. 13736 13737`pl' 13738 Polish. 13739 13740`ps' 13741 Pashto, Pushto. 13742 13743`pt' 13744 Portuguese. 13745 13746`qu' 13747 Quechua. 13748 13749`rm' 13750 Rhaeto-Romance. 13751 13752`rn' 13753 Rundi; Kirundi. 13754 13755`ro' 13756 Romanian. 13757 13758`ru' 13759 Russian. 13760 13761`rw' 13762 Kinyarwanda. 13763 13764`sa' 13765 Sanskrit. 13766 13767`sc' 13768 Sardinian. 13769 13770`sd' 13771 Sindhi. 13772 13773`se' 13774 Northern Sami. 13775 13776`sg' 13777 Sango; Sangro. 13778 13779`si' 13780 Sinhala; Sinhalese. 13781 13782`sk' 13783 Slovak. 13784 13785`sl' 13786 Slovenian. 13787 13788`sm' 13789 Samoan. 13790 13791`sn' 13792 Shona. 13793 13794`so' 13795 Somali. 13796 13797`sq' 13798 Albanian. 13799 13800`sr' 13801 Serbian. 13802 13803`ss' 13804 Swati; Siswati. 13805 13806`st' 13807 Sesotho; Sotho, Southern. 13808 13809`su' 13810 Sundanese. 13811 13812`sv' 13813 Swedish. 13814 13815`sw' 13816 Swahili. 13817 13818`ta' 13819 Tamil. 13820 13821`te' 13822 Telugu. 13823 13824`tg' 13825 Tajik. 13826 13827`th' 13828 Thai. 13829 13830`ti' 13831 Tigrinya. 13832 13833`tk' 13834 Turkmen. 13835 13836`tl' 13837 Tagalog. 13838 13839`tn' 13840 Tswana; Setswana. 13841 13842`to' 13843 Tonga. 13844 13845`tr' 13846 Turkish. 13847 13848`ts' 13849 Tsonga. 13850 13851`tt' 13852 Tatar. 13853 13854`tw' 13855 Twi. 13856 13857`ty' 13858 Tahitian. 13859 13860`ug' 13861 Uighur. 13862 13863`uk' 13864 Ukrainian. 13865 13866`ur' 13867 Urdu. 13868 13869`uz' 13870 Uzbek. 13871 13872`ve' 13873 Venda. 13874 13875`vi' 13876 Vietnamese. 13877 13878`vo' 13879 Volap��k; Volapuk. 13880 13881`wa' 13882 Walloon. 13883 13884`wo' 13885 Wolof. 13886 13887`xh' 13888 Xhosa. 13889 13890`yi' 13891 Yiddish (formerly ji). 13892 13893`yo' 13894 Yoruba. 13895 13896`za' 13897 Zhuang. 13898 13899`zh' 13900 Chinese. 13901 13902`zu' 13903 Zulu. 13904 13905 13906File: gettext.info, Node: Rare Language Codes, Prev: Usual Language Codes, Up: Language Codes 13907 13908A.2 Rare Language Codes 13909======================= 13910 13911 For rarely used languages, the ISO 639-2 standard defines 13912three-letter codes. Here is the current list, reduced to only living 13913languages with at least one million of speakers. 13914 13915`ace' 13916 Achinese. 13917 13918`awa' 13919 Awadhi. 13920 13921`bad' 13922 Banda. 13923 13924`bal' 13925 Baluchi. 13926 13927`ban' 13928 Balinese. 13929 13930`bem' 13931 Bemba. 13932 13933`bho' 13934 Bhojpuri. 13935 13936`bik' 13937 Bikol. 13938 13939`bin' 13940 Bini. 13941 13942`btk' 13943 Batak (Indonesia). 13944 13945`bug' 13946 Buginese. 13947 13948`ceb' 13949 Cebuano. 13950 13951`din' 13952 Dinka. 13953 13954`doi' 13955 Dogri. 13956 13957`fil' 13958 Filipino; Pilipino. 13959 13960`fon' 13961 Fon. 13962 13963`gon' 13964 Gondi. 13965 13966`gsw' 13967 Alemani; Swiss German. 13968 13969`hil' 13970 Hiligaynon. 13971 13972`hmn' 13973 Hmong. 13974 13975`ilo' 13976 Iloko. 13977 13978`kab' 13979 Kabyle. 13980 13981`kam' 13982 Kamba. 13983 13984`kbd' 13985 Kabardian. 13986 13987`kmb' 13988 Kimbundu. 13989 13990`kok' 13991 Konkani. 13992 13993`kru' 13994 Kurukh. 13995 13996`lua' 13997 Luba-Lulua. 13998 13999`luo' 14000 Luo (Kenya and Tanzania). 14001 14002`mad' 14003 Madurese. 14004 14005`mag' 14006 Magahi. 14007 14008`mai' 14009 Maithili. 14010 14011`mak' 14012 Makasar. 14013 14014`man' 14015 Mandingo. 14016 14017`men' 14018 Mende. 14019 14020`min' 14021 Minangkabau. 14022 14023`mni' 14024 Manipuri. 14025 14026`mos' 14027 Mossi. 14028 14029`mwr' 14030 Marwari. 14031 14032`nap' 14033 Neapolitan. 14034 14035`nso' 14036 Pedi; Sepedi; Northern Sotho. 14037 14038`nym' 14039 Nyamwezi. 14040 14041`nyn' 14042 Nyankole. 14043 14044`pag' 14045 Pangasinan. 14046 14047`pam' 14048 Pampanga. 14049 14050`raj' 14051 Rajasthani. 14052 14053`sas' 14054 Sasak. 14055 14056`sat' 14057 Santali. 14058 14059`scn' 14060 Sicilian. 14061 14062`shn' 14063 Shan. 14064 14065`sid' 14066 Sidamo. 14067 14068`srr' 14069 Serer. 14070 14071`suk' 14072 Sukuma. 14073 14074`sus' 14075 Susu. 14076 14077`tem' 14078 Timne. 14079 14080`tiv' 14081 Tiv. 14082 14083`tum' 14084 Tumbuka. 14085 14086`umb' 14087 Umbundu. 14088 14089`wal' 14090 Walamo. 14091 14092`war' 14093 Waray. 14094 14095`yao' 14096 Yao. 14097 14098 14099File: gettext.info, Node: Country Codes, Next: Licenses, Prev: Language Codes, Up: Top 14100 14101Appendix B Country Codes 14102************************ 14103 14104 The ISO 3166 standard defines two character codes for many countries 14105and territories. All abbreviations for countries used in the 14106Translation Project should come from this standard. 14107 14108`AD' 14109 Andorra. 14110 14111`AE' 14112 United Arab Emirates. 14113 14114`AF' 14115 Afghanistan. 14116 14117`AG' 14118 Antigua and Barbuda. 14119 14120`AI' 14121 Anguilla. 14122 14123`AL' 14124 Albania. 14125 14126`AM' 14127 Armenia. 14128 14129`AN' 14130 Netherlands Antilles. 14131 14132`AO' 14133 Angola. 14134 14135`AQ' 14136 Antarctica. 14137 14138`AR' 14139 Argentina. 14140 14141`AS' 14142 Samoa (American). 14143 14144`AT' 14145 Austria. 14146 14147`AU' 14148 Australia. 14149 14150`AW' 14151 Aruba. 14152 14153`AX' 14154 Aaland Islands. 14155 14156`AZ' 14157 Azerbaijan. 14158 14159`BA' 14160 Bosnia and Herzegovina. 14161 14162`BB' 14163 Barbados. 14164 14165`BD' 14166 Bangladesh. 14167 14168`BE' 14169 Belgium. 14170 14171`BF' 14172 Burkina Faso. 14173 14174`BG' 14175 Bulgaria. 14176 14177`BH' 14178 Bahrain. 14179 14180`BI' 14181 Burundi. 14182 14183`BJ' 14184 Benin. 14185 14186`BM' 14187 Bermuda. 14188 14189`BN' 14190 Brunei. 14191 14192`BO' 14193 Bolivia. 14194 14195`BR' 14196 Brazil. 14197 14198`BS' 14199 Bahamas. 14200 14201`BT' 14202 Bhutan. 14203 14204`BV' 14205 Bouvet Island. 14206 14207`BW' 14208 Botswana. 14209 14210`BY' 14211 Belarus. 14212 14213`BZ' 14214 Belize. 14215 14216`CA' 14217 Canada. 14218 14219`CC' 14220 Cocos (Keeling) Islands. 14221 14222`CD' 14223 Congo (Dem. Rep.). 14224 14225`CF' 14226 Central African Republic. 14227 14228`CG' 14229 Congo (Rep.). 14230 14231`CH' 14232 Switzerland. 14233 14234`CI' 14235 C��te d'Ivoire. 14236 14237`CK' 14238 Cook Islands. 14239 14240`CL' 14241 Chile. 14242 14243`CM' 14244 Cameroon. 14245 14246`CN' 14247 China. 14248 14249`CO' 14250 Colombia. 14251 14252`CR' 14253 Costa Rica. 14254 14255`CU' 14256 Cuba. 14257 14258`CV' 14259 Cape Verde. 14260 14261`CX' 14262 Christmas Island. 14263 14264`CY' 14265 Cyprus. 14266 14267`CZ' 14268 Czech Republic. 14269 14270`DE' 14271 Germany. 14272 14273`DJ' 14274 Djibouti. 14275 14276`DK' 14277 Denmark. 14278 14279`DM' 14280 Dominica. 14281 14282`DO' 14283 Dominican Republic. 14284 14285`DZ' 14286 Algeria. 14287 14288`EC' 14289 Ecuador. 14290 14291`EE' 14292 Estonia. 14293 14294`EG' 14295 Egypt. 14296 14297`EH' 14298 Western Sahara. 14299 14300`ER' 14301 Eritrea. 14302 14303`ES' 14304 Spain. 14305 14306`ET' 14307 Ethiopia. 14308 14309`FI' 14310 Finland. 14311 14312`FJ' 14313 Fiji. 14314 14315`FK' 14316 Falkland Islands. 14317 14318`FM' 14319 Micronesia. 14320 14321`FO' 14322 Faeroe Islands. 14323 14324`FR' 14325 France. 14326 14327`GA' 14328 Gabon. 14329 14330`GB' 14331 Britain (United Kingdom). 14332 14333`GD' 14334 Grenada. 14335 14336`GE' 14337 Georgia. 14338 14339`GF' 14340 French Guiana. 14341 14342`GG' 14343 Guernsey. 14344 14345`GH' 14346 Ghana. 14347 14348`GI' 14349 Gibraltar. 14350 14351`GL' 14352 Greenland. 14353 14354`GM' 14355 Gambia. 14356 14357`GN' 14358 Guinea. 14359 14360`GP' 14361 Guadeloupe. 14362 14363`GQ' 14364 Equatorial Guinea. 14365 14366`GR' 14367 Greece. 14368 14369`GS' 14370 South Georgia and the South Sandwich Islands. 14371 14372`GT' 14373 Guatemala. 14374 14375`GU' 14376 Guam. 14377 14378`GW' 14379 Guinea-Bissau. 14380 14381`GY' 14382 Guyana. 14383 14384`HK' 14385 Hong Kong. 14386 14387`HM' 14388 Heard Island and McDonald Islands. 14389 14390`HN' 14391 Honduras. 14392 14393`HR' 14394 Croatia. 14395 14396`HT' 14397 Haiti. 14398 14399`HU' 14400 Hungary. 14401 14402`ID' 14403 Indonesia. 14404 14405`IE' 14406 Ireland. 14407 14408`IL' 14409 Israel. 14410 14411`IM' 14412 Isle of Man. 14413 14414`IN' 14415 India. 14416 14417`IO' 14418 British Indian Ocean Territory. 14419 14420`IQ' 14421 Iraq. 14422 14423`IR' 14424 Iran. 14425 14426`IS' 14427 Iceland. 14428 14429`IT' 14430 Italy. 14431 14432`JE' 14433 Jersey. 14434 14435`JM' 14436 Jamaica. 14437 14438`JO' 14439 Jordan. 14440 14441`JP' 14442 Japan. 14443 14444`KE' 14445 Kenya. 14446 14447`KG' 14448 Kyrgyzstan. 14449 14450`KH' 14451 Cambodia. 14452 14453`KI' 14454 Kiribati. 14455 14456`KM' 14457 Comoros. 14458 14459`KN' 14460 St Kitts and Nevis. 14461 14462`KP' 14463 Korea (North). 14464 14465`KR' 14466 Korea (South). 14467 14468`KW' 14469 Kuwait. 14470 14471`KY' 14472 Cayman Islands. 14473 14474`KZ' 14475 Kazakhstan. 14476 14477`LA' 14478 Laos. 14479 14480`LB' 14481 Lebanon. 14482 14483`LC' 14484 St Lucia. 14485 14486`LI' 14487 Liechtenstein. 14488 14489`LK' 14490 Sri Lanka. 14491 14492`LR' 14493 Liberia. 14494 14495`LS' 14496 Lesotho. 14497 14498`LT' 14499 Lithuania. 14500 14501`LU' 14502 Luxembourg. 14503 14504`LV' 14505 Latvia. 14506 14507`LY' 14508 Libya. 14509 14510`MA' 14511 Morocco. 14512 14513`MC' 14514 Monaco. 14515 14516`MD' 14517 Moldova. 14518 14519`ME' 14520 Montenegro. 14521 14522`MG' 14523 Madagascar. 14524 14525`MH' 14526 Marshall Islands. 14527 14528`MK' 14529 Macedonia. 14530 14531`ML' 14532 Mali. 14533 14534`MM' 14535 Myanmar (Burma). 14536 14537`MN' 14538 Mongolia. 14539 14540`MO' 14541 Macao. 14542 14543`MP' 14544 Northern Mariana Islands. 14545 14546`MQ' 14547 Martinique. 14548 14549`MR' 14550 Mauritania. 14551 14552`MS' 14553 Montserrat. 14554 14555`MT' 14556 Malta. 14557 14558`MU' 14559 Mauritius. 14560 14561`MV' 14562 Maldives. 14563 14564`MW' 14565 Malawi. 14566 14567`MX' 14568 Mexico. 14569 14570`MY' 14571 Malaysia. 14572 14573`MZ' 14574 Mozambique. 14575 14576`NA' 14577 Namibia. 14578 14579`NC' 14580 New Caledonia. 14581 14582`NE' 14583 Niger. 14584 14585`NF' 14586 Norfolk Island. 14587 14588`NG' 14589 Nigeria. 14590 14591`NI' 14592 Nicaragua. 14593 14594`NL' 14595 Netherlands. 14596 14597`NO' 14598 Norway. 14599 14600`NP' 14601 Nepal. 14602 14603`NR' 14604 Nauru. 14605 14606`NU' 14607 Niue. 14608 14609`NZ' 14610 New Zealand. 14611 14612`OM' 14613 Oman. 14614 14615`PA' 14616 Panama. 14617 14618`PE' 14619 Peru. 14620 14621`PF' 14622 French Polynesia. 14623 14624`PG' 14625 Papua New Guinea. 14626 14627`PH' 14628 Philippines. 14629 14630`PK' 14631 Pakistan. 14632 14633`PL' 14634 Poland. 14635 14636`PM' 14637 St Pierre and Miquelon. 14638 14639`PN' 14640 Pitcairn. 14641 14642`PR' 14643 Puerto Rico. 14644 14645`PS' 14646 Palestine. 14647 14648`PT' 14649 Portugal. 14650 14651`PW' 14652 Palau. 14653 14654`PY' 14655 Paraguay. 14656 14657`QA' 14658 Qatar. 14659 14660`RE' 14661 Reunion. 14662 14663`RO' 14664 Romania. 14665 14666`RS' 14667 Serbia. 14668 14669`RU' 14670 Russia. 14671 14672`RW' 14673 Rwanda. 14674 14675`SA' 14676 Saudi Arabia. 14677 14678`SB' 14679 Solomon Islands. 14680 14681`SC' 14682 Seychelles. 14683 14684`SD' 14685 Sudan. 14686 14687`SE' 14688 Sweden. 14689 14690`SG' 14691 Singapore. 14692 14693`SH' 14694 St Helena. 14695 14696`SI' 14697 Slovenia. 14698 14699`SJ' 14700 Svalbard and Jan Mayen. 14701 14702`SK' 14703 Slovakia. 14704 14705`SL' 14706 Sierra Leone. 14707 14708`SM' 14709 San Marino. 14710 14711`SN' 14712 Senegal. 14713 14714`SO' 14715 Somalia. 14716 14717`SR' 14718 Suriname. 14719 14720`ST' 14721 Sao Tome and Principe. 14722 14723`SV' 14724 El Salvador. 14725 14726`SY' 14727 Syria. 14728 14729`SZ' 14730 Swaziland. 14731 14732`TC' 14733 Turks and Caicos Islands. 14734 14735`TD' 14736 Chad. 14737 14738`TF' 14739 French Southern and Antarctic Lands. 14740 14741`TG' 14742 Togo. 14743 14744`TH' 14745 Thailand. 14746 14747`TJ' 14748 Tajikistan. 14749 14750`TK' 14751 Tokelau. 14752 14753`TL' 14754 Timor-Leste. 14755 14756`TM' 14757 Turkmenistan. 14758 14759`TN' 14760 Tunisia. 14761 14762`TO' 14763 Tonga. 14764 14765`TR' 14766 Turkey. 14767 14768`TT' 14769 Trinidad and Tobago. 14770 14771`TV' 14772 Tuvalu. 14773 14774`TW' 14775 Taiwan. 14776 14777`TZ' 14778 Tanzania. 14779 14780`UA' 14781 Ukraine. 14782 14783`UG' 14784 Uganda. 14785 14786`UM' 14787 US minor outlying islands. 14788 14789`US' 14790 United States. 14791 14792`UY' 14793 Uruguay. 14794 14795`UZ' 14796 Uzbekistan. 14797 14798`VA' 14799 Vatican City. 14800 14801`VC' 14802 St Vincent and the Grenadines. 14803 14804`VE' 14805 Venezuela. 14806 14807`VG' 14808 Virgin Islands (UK). 14809 14810`VI' 14811 Virgin Islands (US). 14812 14813`VN' 14814 Vietnam. 14815 14816`VU' 14817 Vanuatu. 14818 14819`WF' 14820 Wallis and Futuna. 14821 14822`WS' 14823 Samoa (Western). 14824 14825`YE' 14826 Yemen. 14827 14828`YT' 14829 Mayotte. 14830 14831`ZA' 14832 South Africa. 14833 14834`ZM' 14835 Zambia. 14836 14837`ZW' 14838 Zimbabwe. 14839 14840 14841File: gettext.info, Node: Licenses, Next: Program Index, Prev: Country Codes, Up: Top 14842 14843Appendix C Licenses 14844******************* 14845 14846 The files of this package are covered by the licenses indicated in 14847each particular file or directory. Here is a summary: 14848 14849 * The `libintl' and `libasprintf' libraries are covered by the GNU 14850 Library General Public License (LGPL). A copy of the license is 14851 included in *note GNU LGPL::. 14852 14853 * The executable programs of this package and the `libgettextpo' 14854 library are covered by the GNU General Public License (GPL). A 14855 copy of the license is included in *note GNU GPL::. 14856 14857 * This manual is free documentation. It is dually licensed under the 14858 GNU FDL and the GNU GPL. This means that you can redistribute this 14859 manual under either of these two licenses, at your choice. 14860 This manual is covered by the GNU FDL. Permission is granted to 14861 copy, distribute and/or modify this document under the terms of the 14862 GNU Free Documentation License (FDL), either version 1.2 of the 14863 License, or (at your option) any later version published by the 14864 Free Software Foundation (FSF); with no Invariant Sections, with no 14865 Front-Cover Text, and with no Back-Cover Texts. A copy of the 14866 license is included in *note GNU FDL::. 14867 This manual is covered by the GNU GPL. You can redistribute it 14868 and/or modify it under the terms of the GNU General Public License 14869 (GPL), either version 2 of the License, or (at your option) any 14870 later version published by the Free Software Foundation (FSF). A 14871 copy of the license is included in *note GNU GPL::. 14872 14873* Menu: 14874 14875* GNU GPL:: GNU General Public License 14876* GNU LGPL:: GNU Lesser General Public License 14877* GNU FDL:: GNU Free Documentation License 14878 14879 14880File: gettext.info, Node: GNU GPL, Next: GNU LGPL, Up: Licenses 14881 14882C.1 GNU GENERAL PUBLIC LICENSE 14883============================== 14884 14885 Version 2, June 1991 14886 14887 Copyright (C) 1989, 1991 Free Software Foundation, Inc. 14888 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA 14889 14890 Everyone is permitted to copy and distribute verbatim copies 14891 of this license document, but changing it is not allowed. 14892 14893Preamble 14894-------- 14895 14896 The licenses for most software are designed to take away your 14897freedom to share and change it. By contrast, the GNU General Public 14898License is intended to guarantee your freedom to share and change free 14899software--to make sure the software is free for all its users. This 14900General Public License applies to most of the Free Software 14901Foundation's software and to any other program whose authors commit to 14902using it. (Some other Free Software Foundation software is covered by 14903the GNU Library General Public License instead.) You can apply it to 14904your programs, too. 14905 14906 When we speak of free software, we are referring to freedom, not 14907price. Our General Public Licenses are designed to make sure that you 14908have the freedom to distribute copies of free software (and charge for 14909this service if you wish), that you receive source code or can get it 14910if you want it, that you can change the software or use pieces of it in 14911new free programs; and that you know you can do these things. 14912 14913 To protect your rights, we need to make restrictions that forbid 14914anyone to deny you these rights or to ask you to surrender the rights. 14915These restrictions translate to certain responsibilities for you if you 14916distribute copies of the software, or if you modify it. 14917 14918 For example, if you distribute copies of such a program, whether 14919gratis or for a fee, you must give the recipients all the rights that 14920you have. You must make sure that they, too, receive or can get the 14921source code. And you must show them these terms so they know their 14922rights. 14923 14924 We protect your rights with two steps: (1) copyright the software, 14925and (2) offer you this license which gives you legal permission to copy, 14926distribute and/or modify the software. 14927 14928 Also, for each author's protection and ours, we want to make certain 14929that everyone understands that there is no warranty for this free 14930software. If the software is modified by someone else and passed on, we 14931want its recipients to know that what they have is not the original, so 14932that any problems introduced by others will not reflect on the original 14933authors' reputations. 14934 14935 Finally, any free program is threatened constantly by software 14936patents. We wish to avoid the danger that redistributors of a free 14937program will individually obtain patent licenses, in effect making the 14938program proprietary. To prevent this, we have made it clear that any 14939patent must be licensed for everyone's free use or not licensed at all. 14940 14941 The precise terms and conditions for copying, distribution and 14942modification follow. 14943 14944 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 14945 14946 0. This License applies to any program or other work which contains a 14947 notice placed by the copyright holder saying it may be distributed 14948 under the terms of this General Public License. The "Program", 14949 below, refers to any such program or work, and a "work based on 14950 the Program" means either the Program or any derivative work under 14951 copyright law: that is to say, a work containing the Program or a 14952 portion of it, either verbatim or with modifications and/or 14953 translated into another language. (Hereinafter, translation is 14954 included without limitation in the term "modification".) Each 14955 licensee is addressed as "you". 14956 14957 Activities other than copying, distribution and modification are 14958 not covered by this License; they are outside its scope. The act 14959 of running the Program is not restricted, and the output from the 14960 Program is covered only if its contents constitute a work based on 14961 the Program (independent of having been made by running the 14962 Program). Whether that is true depends on what the Program does. 14963 14964 1. You may copy and distribute verbatim copies of the Program's 14965 source code as you receive it, in any medium, provided that you 14966 conspicuously and appropriately publish on each copy an appropriate 14967 copyright notice and disclaimer of warranty; keep intact all the 14968 notices that refer to this License and to the absence of any 14969 warranty; and give any other recipients of the Program a copy of 14970 this License along with the Program. 14971 14972 You may charge a fee for the physical act of transferring a copy, 14973 and you may at your option offer warranty protection in exchange 14974 for a fee. 14975 14976 2. You may modify your copy or copies of the Program or any portion 14977 of it, thus forming a work based on the Program, and copy and 14978 distribute such modifications or work under the terms of Section 1 14979 above, provided that you also meet all of these conditions: 14980 14981 a. You must cause the modified files to carry prominent notices 14982 stating that you changed the files and the date of any change. 14983 14984 b. You must cause any work that you distribute or publish, that 14985 in whole or in part contains or is derived from the Program 14986 or any part thereof, to be licensed as a whole at no charge 14987 to all third parties under the terms of this License. 14988 14989 c. If the modified program normally reads commands interactively 14990 when run, you must cause it, when started running for such 14991 interactive use in the most ordinary way, to print or display 14992 an announcement including an appropriate copyright notice and 14993 a notice that there is no warranty (or else, saying that you 14994 provide a warranty) and that users may redistribute the 14995 program under these conditions, and telling the user how to 14996 view a copy of this License. (Exception: if the Program 14997 itself is interactive but does not normally print such an 14998 announcement, your work based on the Program is not required 14999 to print an announcement.) 15000 15001 These requirements apply to the modified work as a whole. If 15002 identifiable sections of that work are not derived from the 15003 Program, and can be reasonably considered independent and separate 15004 works in themselves, then this License, and its terms, do not 15005 apply to those sections when you distribute them as separate 15006 works. But when you distribute the same sections as part of a 15007 whole which is a work based on the Program, the distribution of 15008 the whole must be on the terms of this License, whose permissions 15009 for other licensees extend to the entire whole, and thus to each 15010 and every part regardless of who wrote it. 15011 15012 Thus, it is not the intent of this section to claim rights or 15013 contest your rights to work written entirely by you; rather, the 15014 intent is to exercise the right to control the distribution of 15015 derivative or collective works based on the Program. 15016 15017 In addition, mere aggregation of another work not based on the 15018 Program with the Program (or with a work based on the Program) on 15019 a volume of a storage or distribution medium does not bring the 15020 other work under the scope of this License. 15021 15022 3. You may copy and distribute the Program (or a work based on it, 15023 under Section 2) in object code or executable form under the terms 15024 of Sections 1 and 2 above provided that you also do one of the 15025 following: 15026 15027 a. Accompany it with the complete corresponding machine-readable 15028 source code, which must be distributed under the terms of 15029 Sections 1 and 2 above on a medium customarily used for 15030 software interchange; or, 15031 15032 b. Accompany it with a written offer, valid for at least three 15033 years, to give any third party, for a charge no more than your 15034 cost of physically performing source distribution, a complete 15035 machine-readable copy of the corresponding source code, to be 15036 distributed under the terms of Sections 1 and 2 above on a 15037 medium customarily used for software interchange; or, 15038 15039 c. Accompany it with the information you received as to the offer 15040 to distribute corresponding source code. (This alternative is 15041 allowed only for noncommercial distribution and only if you 15042 received the program in object code or executable form with 15043 such an offer, in accord with Subsection b above.) 15044 15045 The source code for a work means the preferred form of the work for 15046 making modifications to it. For an executable work, complete 15047 source code means all the source code for all modules it contains, 15048 plus any associated interface definition files, plus the scripts 15049 used to control compilation and installation of the executable. 15050 However, as a special exception, the source code distributed need 15051 not include anything that is normally distributed (in either 15052 source or binary form) with the major components (compiler, 15053 kernel, and so on) of the operating system on which the executable 15054 runs, unless that component itself accompanies the executable. 15055 15056 If distribution of executable or object code is made by offering 15057 access to copy from a designated place, then offering equivalent 15058 access to copy the source code from the same place counts as 15059 distribution of the source code, even though third parties are not 15060 compelled to copy the source along with the object code. 15061 15062 4. You may not copy, modify, sublicense, or distribute the Program 15063 except as expressly provided under this License. Any attempt 15064 otherwise to copy, modify, sublicense or distribute the Program is 15065 void, and will automatically terminate your rights under this 15066 License. However, parties who have received copies, or rights, 15067 from you under this License will not have their licenses 15068 terminated so long as such parties remain in full compliance. 15069 15070 5. You are not required to accept this License, since you have not 15071 signed it. However, nothing else grants you permission to modify 15072 or distribute the Program or its derivative works. These actions 15073 are prohibited by law if you do not accept this License. 15074 Therefore, by modifying or distributing the Program (or any work 15075 based on the Program), you indicate your acceptance of this 15076 License to do so, and all its terms and conditions for copying, 15077 distributing or modifying the Program or works based on it. 15078 15079 6. Each time you redistribute the Program (or any work based on the 15080 Program), the recipient automatically receives a license from the 15081 original licensor to copy, distribute or modify the Program 15082 subject to these terms and conditions. You may not impose any 15083 further restrictions on the recipients' exercise of the rights 15084 granted herein. You are not responsible for enforcing compliance 15085 by third parties to this License. 15086 15087 7. If, as a consequence of a court judgment or allegation of patent 15088 infringement or for any other reason (not limited to patent 15089 issues), conditions are imposed on you (whether by court order, 15090 agreement or otherwise) that contradict the conditions of this 15091 License, they do not excuse you from the conditions of this 15092 License. If you cannot distribute so as to satisfy simultaneously 15093 your obligations under this License and any other pertinent 15094 obligations, then as a consequence you may not distribute the 15095 Program at all. For example, if a patent license would not permit 15096 royalty-free redistribution of the Program by all those who 15097 receive copies directly or indirectly through you, then the only 15098 way you could satisfy both it and this License would be to refrain 15099 entirely from distribution of the Program. 15100 15101 If any portion of this section is held invalid or unenforceable 15102 under any particular circumstance, the balance of the section is 15103 intended to apply and the section as a whole is intended to apply 15104 in other circumstances. 15105 15106 It is not the purpose of this section to induce you to infringe any 15107 patents or other property right claims or to contest validity of 15108 any such claims; this section has the sole purpose of protecting 15109 the integrity of the free software distribution system, which is 15110 implemented by public license practices. Many people have made 15111 generous contributions to the wide range of software distributed 15112 through that system in reliance on consistent application of that 15113 system; it is up to the author/donor to decide if he or she is 15114 willing to distribute software through any other system and a 15115 licensee cannot impose that choice. 15116 15117 This section is intended to make thoroughly clear what is believed 15118 to be a consequence of the rest of this License. 15119 15120 8. If the distribution and/or use of the Program is restricted in 15121 certain countries either by patents or by copyrighted interfaces, 15122 the original copyright holder who places the Program under this 15123 License may add an explicit geographical distribution limitation 15124 excluding those countries, so that distribution is permitted only 15125 in or among countries not thus excluded. In such case, this 15126 License incorporates the limitation as if written in the body of 15127 this License. 15128 15129 9. The Free Software Foundation may publish revised and/or new 15130 versions of the General Public License from time to time. Such 15131 new versions will be similar in spirit to the present version, but 15132 may differ in detail to address new problems or concerns. 15133 15134 Each version is given a distinguishing version number. If the 15135 Program specifies a version number of this License which applies 15136 to it and "any later version", you have the option of following 15137 the terms and conditions either of that version or of any later 15138 version published by the Free Software Foundation. If the Program 15139 does not specify a version number of this License, you may choose 15140 any version ever published by the Free Software Foundation. 15141 15142 10. If you wish to incorporate parts of the Program into other free 15143 programs whose distribution conditions are different, write to the 15144 author to ask for permission. For software which is copyrighted 15145 by the Free Software Foundation, write to the Free Software 15146 Foundation; we sometimes make exceptions for this. Our decision 15147 will be guided by the two goals of preserving the free status of 15148 all derivatives of our free software and of promoting the sharing 15149 and reuse of software generally. 15150 15151 NO WARRANTY 15152 15153 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO 15154 WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE 15155 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 15156 HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT 15157 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT 15158 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 15159 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE 15160 QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE 15161 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY 15162 SERVICING, REPAIR OR CORRECTION. 15163 15164 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 15165 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY 15166 MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE 15167 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, 15168 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR 15169 INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 15170 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU 15171 OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY 15172 OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN 15173 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 15174 15175 END OF TERMS AND CONDITIONS 15176 15177Appendix: How to Apply These Terms to Your New Programs 15178------------------------------------------------------- 15179 15180 If you develop a new program, and you want it to be of the greatest 15181possible use to the public, the best way to achieve this is to make it 15182free software which everyone can redistribute and change under these 15183terms. 15184 15185 To do so, attach the following notices to the program. It is safest 15186to attach them to the start of each source file to most effectively 15187convey the exclusion of warranty; and each file should have at least 15188the "copyright" line and a pointer to where the full notice is found. 15189 15190 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. 15191 Copyright (C) YYYY NAME OF AUTHOR 15192 15193 This program is free software; you can redistribute it and/or modify 15194 it under the terms of the GNU General Public License as published by 15195 the Free Software Foundation; either version 2 of the License, or 15196 (at your option) any later version. 15197 15198 This program is distributed in the hope that it will be useful, 15199 but WITHOUT ANY WARRANTY; without even the implied warranty of 15200 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15201 GNU General Public License for more details. 15202 15203 You should have received a copy of the GNU General Public License 15204 along with this program; if not, write to the Free Software 15205 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 15206 15207 Also add information on how to contact you by electronic and paper 15208mail. 15209 15210 If the program is interactive, make it output a short notice like 15211this when it starts in an interactive mode: 15212 15213 Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR 15214 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 15215 This is free software, and you are welcome to redistribute it 15216 under certain conditions; type `show c' for details. 15217 15218 The hypothetical commands `show w' and `show c' should show the 15219appropriate parts of the General Public License. Of course, the 15220commands you use may be called something other than `show w' and `show 15221c'; they could even be mouse-clicks or menu items--whatever suits your 15222program. 15223 15224 You should also get your employer (if you work as a programmer) or 15225your school, if any, to sign a "copyright disclaimer" for the program, 15226if necessary. Here is a sample; alter the names: 15227 15228 Yoyodyne, Inc., hereby disclaims all copyright interest in the program 15229 `Gnomovision' (which makes passes at compilers) written by James Hacker. 15230 15231 SIGNATURE OF TY COON, 1 April 1989 15232 Ty Coon, President of Vice 15233 15234 This General Public License does not permit incorporating your 15235program into proprietary programs. If your program is a subroutine 15236library, you may consider it more useful to permit linking proprietary 15237applications with the library. If this is what you want to do, use the 15238GNU Library General Public License instead of this License. 15239 15240 15241File: gettext.info, Node: GNU LGPL, Next: GNU FDL, Prev: GNU GPL, Up: Licenses 15242 15243C.2 GNU LESSER GENERAL PUBLIC LICENSE 15244===================================== 15245 15246 Version 2.1, February 1999 15247 15248 Copyright (C) 1991, 1999 Free Software Foundation, Inc. 15249 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA 15250 15251 Everyone is permitted to copy and distribute verbatim copies 15252 of this license document, but changing it is not allowed. 15253 15254 [This is the first released version of the Lesser GPL. It also counts 15255 as the successor of the GNU Library Public License, version 2, hence the 15256 version number 2.1.] 15257 15258Preamble 15259-------- 15260 15261 The licenses for most software are designed to take away your 15262freedom to share and change it. By contrast, the GNU General Public 15263Licenses are intended to guarantee your freedom to share and change 15264free software--to make sure the software is free for all its users. 15265 15266 This license, the Lesser General Public License, applies to some 15267specially designated software--typically libraries--of the Free 15268Software Foundation and other authors who decide to use it. You can use 15269it too, but we suggest you first think carefully about whether this 15270license or the ordinary General Public License is the better strategy to 15271use in any particular case, based on the explanations below. 15272 15273 When we speak of free software, we are referring to freedom of use, 15274not price. Our General Public Licenses are designed to make sure that 15275you have the freedom to distribute copies of free software (and charge 15276for this service if you wish); that you receive source code or can get 15277it if you want it; that you can change the software and use pieces of it 15278in new free programs; and that you are informed that you can do these 15279things. 15280 15281 To protect your rights, we need to make restrictions that forbid 15282distributors to deny you these rights or to ask you to surrender these 15283rights. These restrictions translate to certain responsibilities for 15284you if you distribute copies of the library or if you modify it. 15285 15286 For example, if you distribute copies of the library, whether gratis 15287or for a fee, you must give the recipients all the rights that we gave 15288you. You must make sure that they, too, receive or can get the source 15289code. If you link other code with the library, you must provide 15290complete object files to the recipients, so that they can relink them 15291with the library after making changes to the library and recompiling 15292it. And you must show them these terms so they know their rights. 15293 15294 We protect your rights with a two-step method: (1) we copyright the 15295library, and (2) we offer you this license, which gives you legal 15296permission to copy, distribute and/or modify the library. 15297 15298 To protect each distributor, we want to make it very clear that 15299there is no warranty for the free library. Also, if the library is 15300modified by someone else and passed on, the recipients should know that 15301what they have is not the original version, so that the original 15302author's reputation will not be affected by problems that might be 15303introduced by others. 15304 15305 Finally, software patents pose a constant threat to the existence of 15306any free program. We wish to make sure that a company cannot 15307effectively restrict the users of a free program by obtaining a 15308restrictive license from a patent holder. Therefore, we insist that 15309any patent license obtained for a version of the library must be 15310consistent with the full freedom of use specified in this license. 15311 15312 Most GNU software, including some libraries, is covered by the 15313ordinary GNU General Public License. This license, the GNU Lesser 15314General Public License, applies to certain designated libraries, and is 15315quite different from the ordinary General Public License. We use this 15316license for certain libraries in order to permit linking those 15317libraries into non-free programs. 15318 15319 When a program is linked with a library, whether statically or using 15320a shared library, the combination of the two is legally speaking a 15321combined work, a derivative of the original library. The ordinary 15322General Public License therefore permits such linking only if the 15323entire combination fits its criteria of freedom. The Lesser General 15324Public License permits more lax criteria for linking other code with 15325the library. 15326 15327 We call this license the "Lesser" General Public License because it 15328does _Less_ to protect the user's freedom than the ordinary General 15329Public License. It also provides other free software developers Less 15330of an advantage over competing non-free programs. These disadvantages 15331are the reason we use the ordinary General Public License for many 15332libraries. However, the Lesser license provides advantages in certain 15333special circumstances. 15334 15335 For example, on rare occasions, there may be a special need to 15336encourage the widest possible use of a certain library, so that it 15337becomes a de-facto standard. To achieve this, non-free programs must be 15338allowed to use the library. A more frequent case is that a free 15339library does the same job as widely used non-free libraries. In this 15340case, there is little to gain by limiting the free library to free 15341software only, so we use the Lesser General Public License. 15342 15343 In other cases, permission to use a particular library in non-free 15344programs enables a greater number of people to use a large body of free 15345software. For example, permission to use the GNU C Library in non-free 15346programs enables many more people to use the whole GNU operating 15347system, as well as its variant, the GNU/Linux operating system. 15348 15349 Although the Lesser General Public License is Less protective of the 15350users' freedom, it does ensure that the user of a program that is 15351linked with the Library has the freedom and the wherewithal to run that 15352program using a modified version of the Library. 15353 15354 The precise terms and conditions for copying, distribution and 15355modification follow. Pay close attention to the difference between a 15356"work based on the library" and a "work that uses the library". The 15357former contains code derived from the library, whereas the latter must 15358be combined with the library in order to run. 15359 15360 GNU LESSER GENERAL PUBLIC LICENSE 15361 15362 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 15363 15364 0. This License Agreement applies to any software library or other 15365 program which contains a notice placed by the copyright holder or 15366 other authorized party saying it may be distributed under the 15367 terms of this Lesser General Public License (also called "this 15368 License"). Each licensee is addressed as "you". 15369 15370 A "library" means a collection of software functions and/or data 15371 prepared so as to be conveniently linked with application programs 15372 (which use some of those functions and data) to form executables. 15373 15374 The "Library", below, refers to any such software library or work 15375 which has been distributed under these terms. A "work based on the 15376 Library" means either the Library or any derivative work under 15377 copyright law: that is to say, a work containing the Library or a 15378 portion of it, either verbatim or with modifications and/or 15379 translated straightforwardly into another language. (Hereinafter, 15380 translation is included without limitation in the term 15381 "modification".) 15382 15383 "Source code" for a work means the preferred form of the work for 15384 making modifications to it. For a library, complete source code 15385 means all the source code for all modules it contains, plus any 15386 associated interface definition files, plus the scripts used to 15387 control compilation and installation of the library. 15388 15389 Activities other than copying, distribution and modification are 15390 not covered by this License; they are outside its scope. The act 15391 of running a program using the Library is not restricted, and 15392 output from such a program is covered only if its contents 15393 constitute a work based on the Library (independent of the use of 15394 the Library in a tool for writing it). Whether that is true 15395 depends on what the Library does and what the program that uses 15396 the Library does. 15397 15398 1. You may copy and distribute verbatim copies of the Library's 15399 complete source code as you receive it, in any medium, provided 15400 that you conspicuously and appropriately publish on each copy an 15401 appropriate copyright notice and disclaimer of warranty; keep 15402 intact all the notices that refer to this License and to the 15403 absence of any warranty; and distribute a copy of this License 15404 along with the Library. 15405 15406 You may charge a fee for the physical act of transferring a copy, 15407 and you may at your option offer warranty protection in exchange 15408 for a fee. 15409 15410 2. You may modify your copy or copies of the Library or any portion 15411 of it, thus forming a work based on the Library, and copy and 15412 distribute such modifications or work under the terms of Section 1 15413 above, provided that you also meet all of these conditions: 15414 15415 a. The modified work must itself be a software library. 15416 15417 b. You must cause the files modified to carry prominent notices 15418 stating that you changed the files and the date of any change. 15419 15420 c. You must cause the whole of the work to be licensed at no 15421 charge to all third parties under the terms of this License. 15422 15423 d. If a facility in the modified Library refers to a function or 15424 a table of data to be supplied by an application program that 15425 uses the facility, other than as an argument passed when the 15426 facility is invoked, then you must make a good faith effort 15427 to ensure that, in the event an application does not supply 15428 such function or table, the facility still operates, and 15429 performs whatever part of its purpose remains meaningful. 15430 15431 (For example, a function in a library to compute square roots 15432 has a purpose that is entirely well-defined independent of the 15433 application. Therefore, Subsection 2d requires that any 15434 application-supplied function or table used by this function 15435 must be optional: if the application does not supply it, the 15436 square root function must still compute square roots.) 15437 15438 These requirements apply to the modified work as a whole. If 15439 identifiable sections of that work are not derived from the 15440 Library, and can be reasonably considered independent and separate 15441 works in themselves, then this License, and its terms, do not 15442 apply to those sections when you distribute them as separate 15443 works. But when you distribute the same sections as part of a 15444 whole which is a work based on the Library, the distribution of 15445 the whole must be on the terms of this License, whose permissions 15446 for other licensees extend to the entire whole, and thus to each 15447 and every part regardless of who wrote it. 15448 15449 Thus, it is not the intent of this section to claim rights or 15450 contest your rights to work written entirely by you; rather, the 15451 intent is to exercise the right to control the distribution of 15452 derivative or collective works based on the Library. 15453 15454 In addition, mere aggregation of another work not based on the 15455 Library with the Library (or with a work based on the Library) on 15456 a volume of a storage or distribution medium does not bring the 15457 other work under the scope of this License. 15458 15459 3. You may opt to apply the terms of the ordinary GNU General Public 15460 License instead of this License to a given copy of the Library. 15461 To do this, you must alter all the notices that refer to this 15462 License, so that they refer to the ordinary GNU General Public 15463 License, version 2, instead of to this License. (If a newer 15464 version than version 2 of the ordinary GNU General Public License 15465 has appeared, then you can specify that version instead if you 15466 wish.) Do not make any other change in these notices. 15467 15468 Once this change is made in a given copy, it is irreversible for 15469 that copy, so the ordinary GNU General Public License applies to 15470 all subsequent copies and derivative works made from that copy. 15471 15472 This option is useful when you wish to copy part of the code of 15473 the Library into a program that is not a library. 15474 15475 4. You may copy and distribute the Library (or a portion or 15476 derivative of it, under Section 2) in object code or executable 15477 form under the terms of Sections 1 and 2 above provided that you 15478 accompany it with the complete corresponding machine-readable 15479 source code, which must be distributed under the terms of Sections 15480 1 and 2 above on a medium customarily used for software 15481 interchange. 15482 15483 If distribution of object code is made by offering access to copy 15484 from a designated place, then offering equivalent access to copy 15485 the source code from the same place satisfies the requirement to 15486 distribute the source code, even though third parties are not 15487 compelled to copy the source along with the object code. 15488 15489 5. A program that contains no derivative of any portion of the 15490 Library, but is designed to work with the Library by being 15491 compiled or linked with it, is called a "work that uses the 15492 Library". Such a work, in isolation, is not a derivative work of 15493 the Library, and therefore falls outside the scope of this License. 15494 15495 However, linking a "work that uses the Library" with the Library 15496 creates an executable that is a derivative of the Library (because 15497 it contains portions of the Library), rather than a "work that 15498 uses the library". The executable is therefore covered by this 15499 License. Section 6 states terms for distribution of such 15500 executables. 15501 15502 When a "work that uses the Library" uses material from a header 15503 file that is part of the Library, the object code for the work may 15504 be a derivative work of the Library even though the source code is 15505 not. Whether this is true is especially significant if the work 15506 can be linked without the Library, or if the work is itself a 15507 library. The threshold for this to be true is not precisely 15508 defined by law. 15509 15510 If such an object file uses only numerical parameters, data 15511 structure layouts and accessors, and small macros and small inline 15512 functions (ten lines or less in length), then the use of the object 15513 file is unrestricted, regardless of whether it is legally a 15514 derivative work. (Executables containing this object code plus 15515 portions of the Library will still fall under Section 6.) 15516 15517 Otherwise, if the work is a derivative of the Library, you may 15518 distribute the object code for the work under the terms of Section 15519 6. Any executables containing that work also fall under Section 6, 15520 whether or not they are linked directly with the Library itself. 15521 15522 6. As an exception to the Sections above, you may also combine or 15523 link a "work that uses the Library" with the Library to produce a 15524 work containing portions of the Library, and distribute that work 15525 under terms of your choice, provided that the terms permit 15526 modification of the work for the customer's own use and reverse 15527 engineering for debugging such modifications. 15528 15529 You must give prominent notice with each copy of the work that the 15530 Library is used in it and that the Library and its use are covered 15531 by this License. You must supply a copy of this License. If the 15532 work during execution displays copyright notices, you must include 15533 the copyright notice for the Library among them, as well as a 15534 reference directing the user to the copy of this License. Also, 15535 you must do one of these things: 15536 15537 a. Accompany the work with the complete corresponding 15538 machine-readable source code for the Library including 15539 whatever changes were used in the work (which must be 15540 distributed under Sections 1 and 2 above); and, if the work 15541 is an executable linked with the Library, with the complete 15542 machine-readable "work that uses the Library", as object code 15543 and/or source code, so that the user can modify the Library 15544 and then relink to produce a modified executable containing 15545 the modified Library. (It is understood that the user who 15546 changes the contents of definitions files in the Library will 15547 not necessarily be able to recompile the application to use 15548 the modified definitions.) 15549 15550 b. Use a suitable shared library mechanism for linking with the 15551 Library. A suitable mechanism is one that (1) uses at run 15552 time a copy of the library already present on the user's 15553 computer system, rather than copying library functions into 15554 the executable, and (2) will operate properly with a modified 15555 version of the library, if the user installs one, as long as 15556 the modified version is interface-compatible with the version 15557 that the work was made with. 15558 15559 c. Accompany the work with a written offer, valid for at least 15560 three years, to give the same user the materials specified in 15561 Subsection 6a, above, for a charge no more than the cost of 15562 performing this distribution. 15563 15564 d. If distribution of the work is made by offering access to copy 15565 from a designated place, offer equivalent access to copy the 15566 above specified materials from the same place. 15567 15568 e. Verify that the user has already received a copy of these 15569 materials or that you have already sent this user a copy. 15570 15571 For an executable, the required form of the "work that uses the 15572 Library" must include any data and utility programs needed for 15573 reproducing the executable from it. However, as a special 15574 exception, the materials to be distributed need not include 15575 anything that is normally distributed (in either source or binary 15576 form) with the major components (compiler, kernel, and so on) of 15577 the operating system on which the executable runs, unless that 15578 component itself accompanies the executable. 15579 15580 It may happen that this requirement contradicts the license 15581 restrictions of other proprietary libraries that do not normally 15582 accompany the operating system. Such a contradiction means you 15583 cannot use both them and the Library together in an executable 15584 that you distribute. 15585 15586 7. You may place library facilities that are a work based on the 15587 Library side-by-side in a single library together with other 15588 library facilities not covered by this License, and distribute 15589 such a combined library, provided that the separate distribution 15590 of the work based on the Library and of the other library 15591 facilities is otherwise permitted, and provided that you do these 15592 two things: 15593 15594 a. Accompany the combined library with a copy of the same work 15595 based on the Library, uncombined with any other library 15596 facilities. This must be distributed under the terms of the 15597 Sections above. 15598 15599 b. Give prominent notice with the combined library of the fact 15600 that part of it is a work based on the Library, and explaining 15601 where to find the accompanying uncombined form of the same 15602 work. 15603 15604 8. You may not copy, modify, sublicense, link with, or distribute the 15605 Library except as expressly provided under this License. Any 15606 attempt otherwise to copy, modify, sublicense, link with, or 15607 distribute the Library is void, and will automatically terminate 15608 your rights under this License. However, parties who have 15609 received copies, or rights, from you under this License will not 15610 have their licenses terminated so long as such parties remain in 15611 full compliance. 15612 15613 9. You are not required to accept this License, since you have not 15614 signed it. However, nothing else grants you permission to modify 15615 or distribute the Library or its derivative works. These actions 15616 are prohibited by law if you do not accept this License. 15617 Therefore, by modifying or distributing the Library (or any work 15618 based on the Library), you indicate your acceptance of this 15619 License to do so, and all its terms and conditions for copying, 15620 distributing or modifying the Library or works based on it. 15621 15622 10. Each time you redistribute the Library (or any work based on the 15623 Library), the recipient automatically receives a license from the 15624 original licensor to copy, distribute, link with or modify the 15625 Library subject to these terms and conditions. You may not impose 15626 any further restrictions on the recipients' exercise of the rights 15627 granted herein. You are not responsible for enforcing compliance 15628 by third parties with this License. 15629 15630 11. If, as a consequence of a court judgment or allegation of patent 15631 infringement or for any other reason (not limited to patent 15632 issues), conditions are imposed on you (whether by court order, 15633 agreement or otherwise) that contradict the conditions of this 15634 License, they do not excuse you from the conditions of this 15635 License. If you cannot distribute so as to satisfy simultaneously 15636 your obligations under this License and any other pertinent 15637 obligations, then as a consequence you may not distribute the 15638 Library at all. For example, if a patent license would not permit 15639 royalty-free redistribution of the Library by all those who 15640 receive copies directly or indirectly through you, then the only 15641 way you could satisfy both it and this License would be to refrain 15642 entirely from distribution of the Library. 15643 15644 If any portion of this section is held invalid or unenforceable 15645 under any particular circumstance, the balance of the section is 15646 intended to apply, and the section as a whole is intended to apply 15647 in other circumstances. 15648 15649 It is not the purpose of this section to induce you to infringe any 15650 patents or other property right claims or to contest validity of 15651 any such claims; this section has the sole purpose of protecting 15652 the integrity of the free software distribution system which is 15653 implemented by public license practices. Many people have made 15654 generous contributions to the wide range of software distributed 15655 through that system in reliance on consistent application of that 15656 system; it is up to the author/donor to decide if he or she is 15657 willing to distribute software through any other system and a 15658 licensee cannot impose that choice. 15659 15660 This section is intended to make thoroughly clear what is believed 15661 to be a consequence of the rest of this License. 15662 15663 12. If the distribution and/or use of the Library is restricted in 15664 certain countries either by patents or by copyrighted interfaces, 15665 the original copyright holder who places the Library under this 15666 License may add an explicit geographical distribution limitation 15667 excluding those countries, so that distribution is permitted only 15668 in or among countries not thus excluded. In such case, this 15669 License incorporates the limitation as if written in the body of 15670 this License. 15671 15672 13. The Free Software Foundation may publish revised and/or new 15673 versions of the Lesser General Public License from time to time. 15674 Such new versions will be similar in spirit to the present version, 15675 but may differ in detail to address new problems or concerns. 15676 15677 Each version is given a distinguishing version number. If the 15678 Library specifies a version number of this License which applies 15679 to it and "any later version", you have the option of following 15680 the terms and conditions either of that version or of any later 15681 version published by the Free Software Foundation. If the Library 15682 does not specify a license version number, you may choose any 15683 version ever published by the Free Software Foundation. 15684 15685 14. If you wish to incorporate parts of the Library into other free 15686 programs whose distribution conditions are incompatible with these, 15687 write to the author to ask for permission. For software which is 15688 copyrighted by the Free Software Foundation, write to the Free 15689 Software Foundation; we sometimes make exceptions for this. Our 15690 decision will be guided by the two goals of preserving the free 15691 status of all derivatives of our free software and of promoting 15692 the sharing and reuse of software generally. 15693 15694 NO WARRANTY 15695 15696 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO 15697 WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE 15698 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 15699 HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT 15700 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT 15701 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 15702 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE 15703 QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE 15704 LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY 15705 SERVICING, REPAIR OR CORRECTION. 15706 15707 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 15708 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY 15709 MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE 15710 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, 15711 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR 15712 INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF 15713 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU 15714 OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY 15715 OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN 15716 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 15717 15718 END OF TERMS AND CONDITIONS 15719 15720How to Apply These Terms to Your New Libraries 15721---------------------------------------------- 15722 15723 If you develop a new library, and you want it to be of the greatest 15724possible use to the public, we recommend making it free software that 15725everyone can redistribute and change. You can do so by permitting 15726redistribution under these terms (or, alternatively, under the terms of 15727the ordinary General Public License). 15728 15729 To apply these terms, attach the following notices to the library. 15730It is safest to attach them to the start of each source file to most 15731effectively convey the exclusion of warranty; and each file should have 15732at least the "copyright" line and a pointer to where the full notice is 15733found. 15734 15735 ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES. 15736 Copyright (C) YEAR NAME OF AUTHOR 15737 15738 This library is free software; you can redistribute it and/or modify it 15739 under the terms of the GNU Lesser General Public License as published by 15740 the Free Software Foundation; either version 2.1 of the License, or (at 15741 your option) any later version. 15742 15743 This library is distributed in the hope that it will be useful, but 15744 WITHOUT ANY WARRANTY; without even the implied warranty of 15745 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15746 Lesser General Public License for more details. 15747 15748 You should have received a copy of the GNU Lesser General Public 15749 License along with this library; if not, write to the Free Software 15750 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 15751 USA. 15752 15753 Also add information on how to contact you by electronic and paper 15754mail. 15755 15756 You should also get your employer (if you work as a programmer) or 15757your school, if any, to sign a "copyright disclaimer" for the library, 15758if necessary. Here is a sample; alter the names: 15759 15760 Yoyodyne, Inc., hereby disclaims all copyright interest in the library 15761 `Frob' (a library for tweaking knobs) written by James Random Hacker. 15762 15763 SIGNATURE OF TY COON, 1 April 1990 15764 Ty Coon, President of Vice 15765 15766 That's all there is to it! 15767 15768 15769File: gettext.info, Node: GNU FDL, Prev: GNU LGPL, Up: Licenses 15770 15771C.3 GNU Free Documentation License 15772================================== 15773 15774 Version 1.2, November 2002 15775 15776 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 15777 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA 15778 15779 Everyone is permitted to copy and distribute verbatim copies 15780 of this license document, but changing it is not allowed. 15781 15782 0. PREAMBLE 15783 15784 The purpose of this License is to make a manual, textbook, or other 15785 functional and useful document "free" in the sense of freedom: to 15786 assure everyone the effective freedom to copy and redistribute it, 15787 with or without modifying it, either commercially or 15788 noncommercially. Secondarily, this License preserves for the 15789 author and publisher a way to get credit for their work, while not 15790 being considered responsible for modifications made by others. 15791 15792 This License is a kind of "copyleft", which means that derivative 15793 works of the document must themselves be free in the same sense. 15794 It complements the GNU General Public License, which is a copyleft 15795 license designed for free software. 15796 15797 We have designed this License in order to use it for manuals for 15798 free software, because free software needs free documentation: a 15799 free program should come with manuals providing the same freedoms 15800 that the software does. But this License is not limited to 15801 software manuals; it can be used for any textual work, regardless 15802 of subject matter or whether it is published as a printed book. 15803 We recommend this License principally for works whose purpose is 15804 instruction or reference. 15805 15806 1. APPLICABILITY AND DEFINITIONS 15807 15808 This License applies to any manual or other work, in any medium, 15809 that contains a notice placed by the copyright holder saying it 15810 can be distributed under the terms of this License. Such a notice 15811 grants a world-wide, royalty-free license, unlimited in duration, 15812 to use that work under the conditions stated herein. The 15813 "Document", below, refers to any such manual or work. Any member 15814 of the public is a licensee, and is addressed as "you". You 15815 accept the license if you copy, modify or distribute the work in a 15816 way requiring permission under copyright law. 15817 15818 A "Modified Version" of the Document means any work containing the 15819 Document or a portion of it, either copied verbatim, or with 15820 modifications and/or translated into another language. 15821 15822 A "Secondary Section" is a named appendix or a front-matter section 15823 of the Document that deals exclusively with the relationship of the 15824 publishers or authors of the Document to the Document's overall 15825 subject (or to related matters) and contains nothing that could 15826 fall directly within that overall subject. (Thus, if the Document 15827 is in part a textbook of mathematics, a Secondary Section may not 15828 explain any mathematics.) The relationship could be a matter of 15829 historical connection with the subject or with related matters, or 15830 of legal, commercial, philosophical, ethical or political position 15831 regarding them. 15832 15833 The "Invariant Sections" are certain Secondary Sections whose 15834 titles are designated, as being those of Invariant Sections, in 15835 the notice that says that the Document is released under this 15836 License. If a section does not fit the above definition of 15837 Secondary then it is not allowed to be designated as Invariant. 15838 The Document may contain zero Invariant Sections. If the Document 15839 does not identify any Invariant Sections then there are none. 15840 15841 The "Cover Texts" are certain short passages of text that are 15842 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 15843 that says that the Document is released under this License. A 15844 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 15845 be at most 25 words. 15846 15847 A "Transparent" copy of the Document means a machine-readable copy, 15848 represented in a format whose specification is available to the 15849 general public, that is suitable for revising the document 15850 straightforwardly with generic text editors or (for images 15851 composed of pixels) generic paint programs or (for drawings) some 15852 widely available drawing editor, and that is suitable for input to 15853 text formatters or for automatic translation to a variety of 15854 formats suitable for input to text formatters. A copy made in an 15855 otherwise Transparent file format whose markup, or absence of 15856 markup, has been arranged to thwart or discourage subsequent 15857 modification by readers is not Transparent. An image format is 15858 not Transparent if used for any substantial amount of text. A 15859 copy that is not "Transparent" is called "Opaque". 15860 15861 Examples of suitable formats for Transparent copies include plain 15862 ASCII without markup, Texinfo input format, LaTeX input format, 15863 SGML or XML using a publicly available DTD, and 15864 standard-conforming simple HTML, PostScript or PDF designed for 15865 human modification. Examples of transparent image formats include 15866 PNG, XCF and JPG. Opaque formats include proprietary formats that 15867 can be read and edited only by proprietary word processors, SGML or 15868 XML for which the DTD and/or processing tools are not generally 15869 available, and the machine-generated HTML, PostScript or PDF 15870 produced by some word processors for output purposes only. 15871 15872 The "Title Page" means, for a printed book, the title page itself, 15873 plus such following pages as are needed to hold, legibly, the 15874 material this License requires to appear in the title page. For 15875 works in formats which do not have any title page as such, "Title 15876 Page" means the text near the most prominent appearance of the 15877 work's title, preceding the beginning of the body of the text. 15878 15879 A section "Entitled XYZ" means a named subunit of the Document 15880 whose title either is precisely XYZ or contains XYZ in parentheses 15881 following text that translates XYZ in another language. (Here XYZ 15882 stands for a specific section name mentioned below, such as 15883 "Acknowledgements", "Dedications", "Endorsements", or "History".) 15884 To "Preserve the Title" of such a section when you modify the 15885 Document means that it remains a section "Entitled XYZ" according 15886 to this definition. 15887 15888 The Document may include Warranty Disclaimers next to the notice 15889 which states that this License applies to the Document. These 15890 Warranty Disclaimers are considered to be included by reference in 15891 this License, but only as regards disclaiming warranties: any other 15892 implication that these Warranty Disclaimers may have is void and 15893 has no effect on the meaning of this License. 15894 15895 2. VERBATIM COPYING 15896 15897 You may copy and distribute the Document in any medium, either 15898 commercially or noncommercially, provided that this License, the 15899 copyright notices, and the license notice saying this License 15900 applies to the Document are reproduced in all copies, and that you 15901 add no other conditions whatsoever to those of this License. You 15902 may not use technical measures to obstruct or control the reading 15903 or further copying of the copies you make or distribute. However, 15904 you may accept compensation in exchange for copies. If you 15905 distribute a large enough number of copies you must also follow 15906 the conditions in section 3. 15907 15908 You may also lend copies, under the same conditions stated above, 15909 and you may publicly display copies. 15910 15911 3. COPYING IN QUANTITY 15912 15913 If you publish printed copies (or copies in media that commonly 15914 have printed covers) of the Document, numbering more than 100, and 15915 the Document's license notice requires Cover Texts, you must 15916 enclose the copies in covers that carry, clearly and legibly, all 15917 these Cover Texts: Front-Cover Texts on the front cover, and 15918 Back-Cover Texts on the back cover. Both covers must also clearly 15919 and legibly identify you as the publisher of these copies. The 15920 front cover must present the full title with all words of the 15921 title equally prominent and visible. You may add other material 15922 on the covers in addition. Copying with changes limited to the 15923 covers, as long as they preserve the title of the Document and 15924 satisfy these conditions, can be treated as verbatim copying in 15925 other respects. 15926 15927 If the required texts for either cover are too voluminous to fit 15928 legibly, you should put the first ones listed (as many as fit 15929 reasonably) on the actual cover, and continue the rest onto 15930 adjacent pages. 15931 15932 If you publish or distribute Opaque copies of the Document 15933 numbering more than 100, you must either include a 15934 machine-readable Transparent copy along with each Opaque copy, or 15935 state in or with each Opaque copy a computer-network location from 15936 which the general network-using public has access to download 15937 using public-standard network protocols a complete Transparent 15938 copy of the Document, free of added material. If you use the 15939 latter option, you must take reasonably prudent steps, when you 15940 begin distribution of Opaque copies in quantity, to ensure that 15941 this Transparent copy will remain thus accessible at the stated 15942 location until at least one year after the last time you 15943 distribute an Opaque copy (directly or through your agents or 15944 retailers) of that edition to the public. 15945 15946 It is requested, but not required, that you contact the authors of 15947 the Document well before redistributing any large number of 15948 copies, to give them a chance to provide you with an updated 15949 version of the Document. 15950 15951 4. MODIFICATIONS 15952 15953 You may copy and distribute a Modified Version of the Document 15954 under the conditions of sections 2 and 3 above, provided that you 15955 release the Modified Version under precisely this License, with 15956 the Modified Version filling the role of the Document, thus 15957 licensing distribution and modification of the Modified Version to 15958 whoever possesses a copy of it. In addition, you must do these 15959 things in the Modified Version: 15960 15961 A. Use in the Title Page (and on the covers, if any) a title 15962 distinct from that of the Document, and from those of 15963 previous versions (which should, if there were any, be listed 15964 in the History section of the Document). You may use the 15965 same title as a previous version if the original publisher of 15966 that version gives permission. 15967 15968 B. List on the Title Page, as authors, one or more persons or 15969 entities responsible for authorship of the modifications in 15970 the Modified Version, together with at least five of the 15971 principal authors of the Document (all of its principal 15972 authors, if it has fewer than five), unless they release you 15973 from this requirement. 15974 15975 C. State on the Title page the name of the publisher of the 15976 Modified Version, as the publisher. 15977 15978 D. Preserve all the copyright notices of the Document. 15979 15980 E. Add an appropriate copyright notice for your modifications 15981 adjacent to the other copyright notices. 15982 15983 F. Include, immediately after the copyright notices, a license 15984 notice giving the public permission to use the Modified 15985 Version under the terms of this License, in the form shown in 15986 the Addendum below. 15987 15988 G. Preserve in that license notice the full lists of Invariant 15989 Sections and required Cover Texts given in the Document's 15990 license notice. 15991 15992 H. Include an unaltered copy of this License. 15993 15994 I. Preserve the section Entitled "History", Preserve its Title, 15995 and add to it an item stating at least the title, year, new 15996 authors, and publisher of the Modified Version as given on 15997 the Title Page. If there is no section Entitled "History" in 15998 the Document, create one stating the title, year, authors, 15999 and publisher of the Document as given on its Title Page, 16000 then add an item describing the Modified Version as stated in 16001 the previous sentence. 16002 16003 J. Preserve the network location, if any, given in the Document 16004 for public access to a Transparent copy of the Document, and 16005 likewise the network locations given in the Document for 16006 previous versions it was based on. These may be placed in 16007 the "History" section. You may omit a network location for a 16008 work that was published at least four years before the 16009 Document itself, or if the original publisher of the version 16010 it refers to gives permission. 16011 16012 K. For any section Entitled "Acknowledgements" or "Dedications", 16013 Preserve the Title of the section, and preserve in the 16014 section all the substance and tone of each of the contributor 16015 acknowledgements and/or dedications given therein. 16016 16017 L. Preserve all the Invariant Sections of the Document, 16018 unaltered in their text and in their titles. Section numbers 16019 or the equivalent are not considered part of the section 16020 titles. 16021 16022 M. Delete any section Entitled "Endorsements". Such a section 16023 may not be included in the Modified Version. 16024 16025 N. Do not retitle any existing section to be Entitled 16026 "Endorsements" or to conflict in title with any Invariant 16027 Section. 16028 16029 O. Preserve any Warranty Disclaimers. 16030 16031 If the Modified Version includes new front-matter sections or 16032 appendices that qualify as Secondary Sections and contain no 16033 material copied from the Document, you may at your option 16034 designate some or all of these sections as invariant. To do this, 16035 add their titles to the list of Invariant Sections in the Modified 16036 Version's license notice. These titles must be distinct from any 16037 other section titles. 16038 16039 You may add a section Entitled "Endorsements", provided it contains 16040 nothing but endorsements of your Modified Version by various 16041 parties--for example, statements of peer review or that the text 16042 has been approved by an organization as the authoritative 16043 definition of a standard. 16044 16045 You may add a passage of up to five words as a Front-Cover Text, 16046 and a passage of up to 25 words as a Back-Cover Text, to the end 16047 of the list of Cover Texts in the Modified Version. Only one 16048 passage of Front-Cover Text and one of Back-Cover Text may be 16049 added by (or through arrangements made by) any one entity. If the 16050 Document already includes a cover text for the same cover, 16051 previously added by you or by arrangement made by the same entity 16052 you are acting on behalf of, you may not add another; but you may 16053 replace the old one, on explicit permission from the previous 16054 publisher that added the old one. 16055 16056 The author(s) and publisher(s) of the Document do not by this 16057 License give permission to use their names for publicity for or to 16058 assert or imply endorsement of any Modified Version. 16059 16060 5. COMBINING DOCUMENTS 16061 16062 You may combine the Document with other documents released under 16063 this License, under the terms defined in section 4 above for 16064 modified versions, provided that you include in the combination 16065 all of the Invariant Sections of all of the original documents, 16066 unmodified, and list them all as Invariant Sections of your 16067 combined work in its license notice, and that you preserve all 16068 their Warranty Disclaimers. 16069 16070 The combined work need only contain one copy of this License, and 16071 multiple identical Invariant Sections may be replaced with a single 16072 copy. If there are multiple Invariant Sections with the same name 16073 but different contents, make the title of each such section unique 16074 by adding at the end of it, in parentheses, the name of the 16075 original author or publisher of that section if known, or else a 16076 unique number. Make the same adjustment to the section titles in 16077 the list of Invariant Sections in the license notice of the 16078 combined work. 16079 16080 In the combination, you must combine any sections Entitled 16081 "History" in the various original documents, forming one section 16082 Entitled "History"; likewise combine any sections Entitled 16083 "Acknowledgements", and any sections Entitled "Dedications". You 16084 must delete all sections Entitled "Endorsements." 16085 16086 6. COLLECTIONS OF DOCUMENTS 16087 16088 You may make a collection consisting of the Document and other 16089 documents released under this License, and replace the individual 16090 copies of this License in the various documents with a single copy 16091 that is included in the collection, provided that you follow the 16092 rules of this License for verbatim copying of each of the 16093 documents in all other respects. 16094 16095 You may extract a single document from such a collection, and 16096 distribute it individually under this License, provided you insert 16097 a copy of this License into the extracted document, and follow 16098 this License in all other respects regarding verbatim copying of 16099 that document. 16100 16101 7. AGGREGATION WITH INDEPENDENT WORKS 16102 16103 A compilation of the Document or its derivatives with other 16104 separate and independent documents or works, in or on a volume of 16105 a storage or distribution medium, is called an "aggregate" if the 16106 copyright resulting from the compilation is not used to limit the 16107 legal rights of the compilation's users beyond what the individual 16108 works permit. When the Document is included in an aggregate, this 16109 License does not apply to the other works in the aggregate which 16110 are not themselves derivative works of the Document. 16111 16112 If the Cover Text requirement of section 3 is applicable to these 16113 copies of the Document, then if the Document is less than one half 16114 of the entire aggregate, the Document's Cover Texts may be placed 16115 on covers that bracket the Document within the aggregate, or the 16116 electronic equivalent of covers if the Document is in electronic 16117 form. Otherwise they must appear on printed covers that bracket 16118 the whole aggregate. 16119 16120 8. TRANSLATION 16121 16122 Translation is considered a kind of modification, so you may 16123 distribute translations of the Document under the terms of section 16124 4. Replacing Invariant Sections with translations requires special 16125 permission from their copyright holders, but you may include 16126 translations of some or all Invariant Sections in addition to the 16127 original versions of these Invariant Sections. You may include a 16128 translation of this License, and all the license notices in the 16129 Document, and any Warranty Disclaimers, provided that you also 16130 include the original English version of this License and the 16131 original versions of those notices and disclaimers. In case of a 16132 disagreement between the translation and the original version of 16133 this License or a notice or disclaimer, the original version will 16134 prevail. 16135 16136 If a section in the Document is Entitled "Acknowledgements", 16137 "Dedications", or "History", the requirement (section 4) to 16138 Preserve its Title (section 1) will typically require changing the 16139 actual title. 16140 16141 9. TERMINATION 16142 16143 You may not copy, modify, sublicense, or distribute the Document 16144 except as expressly provided for under this License. Any other 16145 attempt to copy, modify, sublicense or distribute the Document is 16146 void, and will automatically terminate your rights under this 16147 License. However, parties who have received copies, or rights, 16148 from you under this License will not have their licenses 16149 terminated so long as such parties remain in full compliance. 16150 16151 10. FUTURE REVISIONS OF THIS LICENSE 16152 16153 The Free Software Foundation may publish new, revised versions of 16154 the GNU Free Documentation License from time to time. Such new 16155 versions will be similar in spirit to the present version, but may 16156 differ in detail to address new problems or concerns. See 16157 `http://www.gnu.org/copyleft/'. 16158 16159 Each version of the License is given a distinguishing version 16160 number. If the Document specifies that a particular numbered 16161 version of this License "or any later version" applies to it, you 16162 have the option of following the terms and conditions either of 16163 that specified version or of any later version that has been 16164 published (not as a draft) by the Free Software Foundation. If 16165 the Document does not specify a version number of this License, 16166 you may choose any version ever published (not as a draft) by the 16167 Free Software Foundation. 16168 16169ADDENDUM: How to use this License for your documents 16170---------------------------------------------------- 16171 16172 To use this License in a document you have written, include a copy of 16173the License in the document and put the following copyright and license 16174notices just after the title page: 16175 16176 Copyright (C) YEAR YOUR NAME. 16177 Permission is granted to copy, distribute and/or modify this document 16178 under the terms of the GNU Free Documentation License, Version 1.2 16179 or any later version published by the Free Software Foundation; 16180 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 16181 Texts. A copy of the license is included in the section entitled ``GNU 16182 Free Documentation License''. 16183 16184 If you have Invariant Sections, Front-Cover Texts and Back-Cover 16185Texts, replace the "with...Texts." line with this: 16186 16187 with the Invariant Sections being LIST THEIR TITLES, with 16188 the Front-Cover Texts being LIST, and with the Back-Cover Texts 16189 being LIST. 16190 16191 If you have Invariant Sections without Cover Texts, or some other 16192combination of the three, merge those two alternatives to suit the 16193situation. 16194 16195 If your document contains nontrivial examples of program code, we 16196recommend releasing these examples in parallel under your choice of 16197free software license, such as the GNU General Public License, to 16198permit their use in free software. 16199 16200 16201File: gettext.info, Node: Program Index, Next: Option Index, Prev: Licenses, Up: Top 16202 16203Program Index 16204************* 16205 16206[index] 16207* Menu: 16208 16209* autopoint: autopoint Invocation. (line 6) 16210* envsubst: envsubst Invocation. (line 6) 16211* gettext <1>: gettext Invocation. (line 6) 16212* gettext: sh. (line 19) 16213* gettextize: gettextize Invocation. 16214 (line 34) 16215* msgattrib: msgattrib Invocation. (line 6) 16216* msgcat: msgcat Invocation. (line 6) 16217* msgcmp: msgcmp Invocation. (line 6) 16218* msgcomm: msgcomm Invocation. (line 6) 16219* msgconv: msgconv Invocation. (line 6) 16220* msgen: msgen Invocation. (line 6) 16221* msgexec: msgexec Invocation. (line 6) 16222* msgfilter: msgfilter Invocation. (line 6) 16223* msgfmt: msgfmt Invocation. (line 6) 16224* msggrep: msggrep Invocation. (line 6) 16225* msginit: msginit Invocation. (line 6) 16226* msgmerge: msgmerge Invocation. (line 6) 16227* msgunfmt: msgunfmt Invocation. (line 6) 16228* msguniq: msguniq Invocation. (line 6) 16229* ngettext <1>: ngettext Invocation. (line 6) 16230* ngettext: sh. (line 19) 16231* recode-sr-latin: msgfilter Invocation. (line 85) 16232* xgettext: xgettext Invocation. (line 6) 16233 16234 16235File: gettext.info, Node: Option Index, Next: Variable Index, Prev: Program Index, Up: Top 16236 16237Option Index 16238************ 16239 16240[index] 16241* Menu: 16242 16243* --add-comments, xgettext option: xgettext Invocation. (line 97) 16244* --add-location, msgattrib option: msgattrib Invocation. 16245 (line 127) 16246* --add-location, msgcat option: msgcat Invocation. (line 114) 16247* --add-location, msgcomm option: msgcomm Invocation. (line 95) 16248* --add-location, msgconv option: msgconv Invocation. (line 74) 16249* --add-location, msgen option: msgen Invocation. (line 70) 16250* --add-location, msgfilter option: msgfilter Invocation. 16251 (line 128) 16252* --add-location, msggrep option: msggrep Invocation. (line 152) 16253* --add-location, msgmerge option: msgmerge Invocation. (line 139) 16254* --add-location, msguniq option: msguniq Invocation. (line 92) 16255* --add-location, xgettext option: xgettext Invocation. (line 286) 16256* --alignment, msgfmt option: msgfmt Invocation. (line 209) 16257* --backup, msgmerge option: msgmerge Invocation. (line 65) 16258* --boost, xgettext option: xgettext Invocation. (line 252) 16259* --c++, xgettext option: xgettext Invocation. (line 64) 16260* --check, msgfmt option: msgfmt Invocation. (line 146) 16261* --check-accelerators, msgfmt option: msgfmt Invocation. (line 187) 16262* --check-compatibility, msgfmt option: msgfmt Invocation. (line 183) 16263* --check-domain, msgfmt option: msgfmt Invocation. (line 178) 16264* --check-format, msgfmt option: msgfmt Invocation. (line 150) 16265* --check-header, msgfmt option: msgfmt Invocation. (line 173) 16266* --clear-fuzzy, msgattrib option: msgattrib Invocation. 16267 (line 71) 16268* --clear-obsolete, msgattrib option: msgattrib Invocation. 16269 (line 77) 16270* --clear-previous, msgattrib option: msgattrib Invocation. 16271 (line 80) 16272* --color, msgcat option <1>: The --color option. (line 6) 16273* --color, msgcat option: msgcat Invocation. (line 95) 16274* --comment, msggrep option: msggrep Invocation. (line 93) 16275* --compendium, msgmerge option: msgmerge Invocation. (line 36) 16276* --copyright-holder, xgettext option: xgettext Invocation. (line 336) 16277* --csharp, msgfmt option: msgfmt Invocation. (line 36) 16278* --csharp, msgunfmt option: msgunfmt Invocation. (line 19) 16279* --csharp-resources, msgfmt option: msgfmt Invocation. (line 40) 16280* --csharp-resources, msgunfmt option: msgunfmt Invocation. (line 23) 16281* --debug, xgettext option: xgettext Invocation. (line 256) 16282* --default-domain, xgettext option: xgettext Invocation. (line 36) 16283* --directory, msgattrib option: msgattrib Invocation. 16284 (line 19) 16285* --directory, msgcat option: msgcat Invocation. (line 32) 16286* --directory, msgcmp option: msgcmp Invocation. (line 27) 16287* --directory, msgcomm option: msgcomm Invocation. (line 30) 16288* --directory, msgconv option: msgconv Invocation. (line 19) 16289* --directory, msgen option: msgen Invocation. (line 25) 16290* --directory, msgexec option: msgexec Invocation. (line 44) 16291* --directory, msgfilter option: msgfilter Invocation. 16292 (line 20) 16293* --directory, msgfmt option: msgfmt Invocation. (line 18) 16294* --directory, msggrep option: msggrep Invocation. (line 19) 16295* --directory, msgmerge option: msgmerge Invocation. (line 30) 16296* --directory, msguniq option: msguniq Invocation. (line 26) 16297* --directory, xgettext option: xgettext Invocation. (line 24) 16298* --domain, gettext option: gettext Invocation. (line 16) 16299* --domain, msggrep option: msggrep Invocation. (line 77) 16300* --domain, ngettext option: ngettext Invocation. (line 15) 16301* --dry-run, autopoint option: autopoint Invocation. 16302 (line 24) 16303* --dry-run, gettextize option: gettextize Invocation. 16304 (line 72) 16305* --exclude-file, xgettext option: xgettext Invocation. (line 92) 16306* --expression, msgfilter option: msgfilter Invocation. 16307 (line 70) 16308* --extended-regexp, msggrep option: msggrep Invocation. (line 101) 16309* --extract-all, xgettext option: xgettext Invocation. (line 106) 16310* --extracted-comment, msggrep option: msggrep Invocation. (line 97) 16311* --file, msgfilter option: msgfilter Invocation. 16312 (line 74) 16313* --file, msggrep option: msggrep Invocation. (line 113) 16314* --files-from, msgcat option: msgcat Invocation. (line 27) 16315* --files-from, msgcomm option: msgcomm Invocation. (line 25) 16316* --files-from, xgettext option: xgettext Invocation. (line 19) 16317* --fixed-strings, msggrep option: msggrep Invocation. (line 105) 16318* --flag, xgettext option: xgettext Invocation. (line 199) 16319* --force, autopoint option: autopoint Invocation. 16320 (line 20) 16321* --force, gettextize option: gettextize Invocation. 16322 (line 40) 16323* --force-po, msgattrib option: msgattrib Invocation. 16324 (line 116) 16325* --force-po, msgcat option: msgcat Invocation. (line 103) 16326* --force-po, msgcomm option: msgcomm Invocation. (line 84) 16327* --force-po, msgconv option: msgconv Invocation. (line 64) 16328* --force-po, msgen option: msgen Invocation. (line 60) 16329* --force-po, msgfilter option: msgfilter Invocation. 16330 (line 114) 16331* --force-po, msggrep option: msggrep Invocation. (line 143) 16332* --force-po, msgmerge option: msgmerge Invocation. (line 129) 16333* --force-po, msgunfmt option: msgunfmt Invocation. (line 108) 16334* --force-po, msguniq option: msguniq Invocation. (line 81) 16335* --force-po, xgettext option: xgettext Invocation. (line 273) 16336* --foreign-user, xgettext option: xgettext Invocation. (line 351) 16337* --from-code, xgettext option: xgettext Invocation. (line 74) 16338* --fuzzy, msgattrib option: msgattrib Invocation. 16339 (line 91) 16340* --help, autopoint option: autopoint Invocation. 16341 (line 33) 16342* --help, envsubst option: envsubst Invocation. (line 22) 16343* --help, gettext option: gettext Invocation. (line 32) 16344* --help, gettextize option: gettextize Invocation. 16345 (line 77) 16346* --help, msgattrib option: msgattrib Invocation. 16347 (line 172) 16348* --help, msgcat option: msgcat Invocation. (line 159) 16349* --help, msgcmp option: msgcmp Invocation. (line 67) 16350* --help, msgcomm option: msgcomm Invocation. (line 143) 16351* --help, msgconv option: msgconv Invocation. (line 119) 16352* --help, msgen option: msgen Invocation. (line 115) 16353* --help, msgexec option: msgexec Invocation. (line 69) 16354* --help, msgfilter option: msgfilter Invocation. 16355 (line 173) 16356* --help, msgfmt option: msgfmt Invocation. (line 222) 16357* --help, msggrep option: msggrep Invocation. (line 195) 16358* --help, msginit option: msginit Invocation. (line 90) 16359* --help, msgmerge option: msgmerge Invocation. (line 184) 16360* --help, msgunfmt option: msgunfmt Invocation. (line 153) 16361* --help, msguniq option: msguniq Invocation. (line 137) 16362* --help, ngettext option: ngettext Invocation. (line 31) 16363* --help, xgettext option: xgettext Invocation. (line 404) 16364* --ignore-case, msggrep option: msggrep Invocation. (line 117) 16365* --ignore-file, msgattrib option: msgattrib Invocation. 16366 (line 87) 16367* --indent, msgattrib option: msgattrib Invocation. 16368 (line 120) 16369* --indent, msgcat option: msgcat Invocation. (line 107) 16370* --indent, msgcomm option: msgcomm Invocation. (line 88) 16371* --indent, msgconv option: msgconv Invocation. (line 68) 16372* --indent, msgen option: msgen Invocation. (line 64) 16373* --indent, msgfilter option: msgfilter Invocation. 16374 (line 117) 16375* --indent, msggrep option: msggrep Invocation. (line 146) 16376* --indent, msgmerge option: msgmerge Invocation. (line 133) 16377* --indent, msgunfmt option: msgunfmt Invocation. (line 112) 16378* --indent, msguniq option: msguniq Invocation. (line 85) 16379* --indent, xgettext option: xgettext Invocation. (line 277) 16380* --input, msgexec option: msgexec Invocation. (line 40) 16381* --input, msgfilter option: msgfilter Invocation. 16382 (line 16) 16383* --input, msginit option: msginit Invocation. (line 16) 16384* --intl, gettextize option: gettextize Invocation. 16385 (line 43) 16386* --invert-match, msggrep option: msggrep Invocation. (line 121) 16387* --java, msgfmt option: msgfmt Invocation. (line 30) 16388* --java, msgunfmt option: msgunfmt Invocation. (line 16) 16389* --java2, msgfmt option: msgfmt Invocation. (line 33) 16390* --join-existing, xgettext option: xgettext Invocation. (line 88) 16391* --kde, xgettext option: xgettext Invocation. (line 248) 16392* --keep-header, msgfilter option: msgfilter Invocation. 16393 (line 120) 16394* --keyword, xgettext option: xgettext Invocation. (line 114) 16395* --language, xgettext option: xgettext Invocation. (line 56) 16396* --less-than, msgcat option: msgcat Invocation. (line 55) 16397* --less-than, msgcomm option: msgcomm Invocation. (line 53) 16398* --locale, msgfmt option: msgfmt Invocation. (line 79) 16399* --locale, msginit option: msginit Invocation. (line 52) 16400* --locale, msgunfmt option: msgunfmt Invocation. (line 47) 16401* --location, msggrep option: msggrep Invocation. (line 72) 16402* --more-than, msgcat option: msgcat Invocation. (line 60) 16403* --more-than, msgcomm option: msgcomm Invocation. (line 58) 16404* --msgctxt, msggrep option: msggrep Invocation. (line 81) 16405* --msgid, msggrep option: msggrep Invocation. (line 85) 16406* --msgid-bugs-address, xgettext option: xgettext Invocation. (line 364) 16407* --msgstr, msggrep option: msggrep Invocation. (line 89) 16408* --msgstr-prefix, xgettext option: xgettext Invocation. (line 392) 16409* --msgstr-suffix, xgettext option: xgettext Invocation. (line 396) 16410* --multi-domain, msgcmp option: msgcmp Invocation. (line 36) 16411* --multi-domain, msgmerge option: msgmerge Invocation. (line 101) 16412* --no-changelog, gettextize option: gettextize Invocation. 16413 (line 58) 16414* --no-fuzzy, msgattrib option: msgattrib Invocation. 16415 (line 47) 16416* --no-fuzzy-matching, msgmerge option: msgmerge Invocation. (line 105) 16417* --no-hash, msgfmt option: msgfmt Invocation. (line 212) 16418* --no-location, msgattrib option: msgattrib Invocation. 16419 (line 123) 16420* --no-location, msgcat option: msgcat Invocation. (line 110) 16421* --no-location, msgcomm option: msgcomm Invocation. (line 91) 16422* --no-location, msgconv option: msgconv Invocation. (line 71) 16423* --no-location, msgen option: msgen Invocation. (line 67) 16424* --no-location, msgfilter option: msgfilter Invocation. 16425 (line 125) 16426* --no-location, msggrep option: msggrep Invocation. (line 149) 16427* --no-location, msgmerge option: msgmerge Invocation. (line 136) 16428* --no-location, msguniq option: msguniq Invocation. (line 88) 16429* --no-location, xgettext option: xgettext Invocation. (line 280) 16430* --no-obsolete, msgattrib option: msgattrib Invocation. 16431 (line 53) 16432* --no-translator, msginit option: msginit Invocation. (line 58) 16433* --no-wrap, msgattrib option: msgattrib Invocation. 16434 (line 152) 16435* --no-wrap, msgcat option: msgcat Invocation. (line 139) 16436* --no-wrap, msgcomm option: msgcomm Invocation. (line 120) 16437* --no-wrap, msgconv option: msgconv Invocation. (line 99) 16438* --no-wrap, msgen option: msgen Invocation. (line 95) 16439* --no-wrap, msgfilter option: msgfilter Invocation. 16440 (line 153) 16441* --no-wrap, msggrep option: msggrep Invocation. (line 177) 16442* --no-wrap, msginit option: msginit Invocation. (line 79) 16443* --no-wrap, msgmerge option: msgmerge Invocation. (line 164) 16444* --no-wrap, msgunfmt option: msgunfmt Invocation. (line 137) 16445* --no-wrap, msguniq option: msguniq Invocation. (line 117) 16446* --no-wrap, xgettext option: xgettext Invocation. (line 310) 16447* --obsolete, msgattrib option: msgattrib Invocation. 16448 (line 95) 16449* --omit-header, msgcomm option: msgcomm Invocation. (line 135) 16450* --omit-header, xgettext option: xgettext Invocation. (line 325) 16451* --only-file, msgattrib option: msgattrib Invocation. 16452 (line 83) 16453* --only-fuzzy, msgattrib option: msgattrib Invocation. 16454 (line 50) 16455* --only-obsolete, msgattrib option: msgattrib Invocation. 16456 (line 56) 16457* --output, xgettext option: xgettext Invocation. (line 40) 16458* --output-dir, xgettext option: xgettext Invocation. (line 45) 16459* --output-file, msgattrib option: msgattrib Invocation. 16460 (line 31) 16461* --output-file, msgcat option: msgcat Invocation. (line 44) 16462* --output-file, msgcomm option: msgcomm Invocation. (line 42) 16463* --output-file, msgconv option: msgconv Invocation. (line 31) 16464* --output-file, msgen option: msgen Invocation. (line 37) 16465* --output-file, msgfilter option: msgfilter Invocation. 16466 (line 32) 16467* --output-file, msgfmt option: msgfmt Invocation. (line 54) 16468* --output-file, msggrep option: msggrep Invocation. (line 31) 16469* --output-file, msginit option: msginit Invocation. (line 27) 16470* --output-file, msgmerge option: msgmerge Invocation. (line 53) 16471* --output-file, msgunfmt option: msgunfmt Invocation. (line 98) 16472* --output-file, msguniq option: msguniq Invocation. (line 38) 16473* --package-name, xgettext option: xgettext Invocation. (line 357) 16474* --package-version, xgettext option: xgettext Invocation. (line 360) 16475* --po-dir, gettextize option: gettextize Invocation. 16476 (line 51) 16477* --previous, msgmerge option: msgmerge Invocation. (line 109) 16478* --properties-input, msgattrib option: msgattrib Invocation. 16479 (line 104) 16480* --properties-input, msgcat option: msgcat Invocation. (line 74) 16481* --properties-input, msgcmp option: msgcmp Invocation. (line 54) 16482* --properties-input, msgcomm option: msgcomm Invocation. (line 72) 16483* --properties-input, msgconv option: msgconv Invocation. (line 52) 16484* --properties-input, msgen option: msgen Invocation. (line 48) 16485* --properties-input, msgexec option: msgexec Invocation. (line 56) 16486* --properties-input, msgfilter option: msgfilter Invocation. 16487 (line 102) 16488* --properties-input, msgfmt option: msgfmt Invocation. (line 133) 16489* --properties-input, msggrep option: msggrep Invocation. (line 131) 16490* --properties-input, msginit option: msginit Invocation. (line 39) 16491* --properties-input, msgmerge option: msgmerge Invocation. (line 117) 16492* --properties-input, msguniq option: msguniq Invocation. (line 61) 16493* --properties-output, msgattrib option: msgattrib Invocation. 16494 (line 136) 16495* --properties-output, msgcat option: msgcat Invocation. (line 123) 16496* --properties-output, msgcomm option: msgcomm Invocation. (line 104) 16497* --properties-output, msgconv option: msgconv Invocation. (line 83) 16498* --properties-output, msgen option: msgen Invocation. (line 79) 16499* --properties-output, msgfilter option: msgfilter Invocation. 16500 (line 137) 16501* --properties-output, msggrep option: msggrep Invocation. (line 161) 16502* --properties-output, msginit option: msginit Invocation. (line 63) 16503* --properties-output, msgmerge option: msgmerge Invocation. (line 148) 16504* --properties-output, msgunfmt option: msgunfmt Invocation. (line 121) 16505* --properties-output, msguniq option: msguniq Invocation. (line 101) 16506* --properties-output, xgettext option: xgettext Invocation. (line 294) 16507* --qt, msgfmt option: msgfmt Invocation. (line 46) 16508* --qt, xgettext option: xgettext Invocation. (line 244) 16509* --quiet, msgfilter option: msgfilter Invocation. 16510 (line 79) 16511* --quiet, msgmerge option: msgmerge Invocation. (line 197) 16512* --regexp=, msggrep option: msggrep Invocation. (line 109) 16513* --repeated, msguniq option: msguniq Invocation. (line 49) 16514* --resource, msgfmt option: msgfmt Invocation. (line 75) 16515* --resource, msgunfmt option: msgunfmt Invocation. (line 43) 16516* --set-fuzzy, msgattrib option: msgattrib Invocation. 16517 (line 68) 16518* --set-obsolete, msgattrib option: msgattrib Invocation. 16519 (line 74) 16520* --silent, msgfilter option: msgfilter Invocation. 16521 (line 79) 16522* --silent, msgmerge option: msgmerge Invocation. (line 197) 16523* --sort-by-file, msgattrib option: msgattrib Invocation. 16524 (line 164) 16525* --sort-by-file, msgcat option: msgcat Invocation. (line 151) 16526* --sort-by-file, msgcomm option: msgcomm Invocation. (line 132) 16527* --sort-by-file, msgconv option: msgconv Invocation. (line 111) 16528* --sort-by-file, msgen option: msgen Invocation. (line 107) 16529* --sort-by-file, msgfilter option: msgfilter Invocation. 16530 (line 165) 16531* --sort-by-file, msggrep option: msggrep Invocation. (line 187) 16532* --sort-by-file, msgmerge option: msgmerge Invocation. (line 176) 16533* --sort-by-file, msguniq option: msguniq Invocation. (line 129) 16534* --sort-by-file, xgettext option: xgettext Invocation. (line 322) 16535* --sort-output, msgattrib option: msgattrib Invocation. 16536 (line 159) 16537* --sort-output, msgcat option: msgcat Invocation. (line 146) 16538* --sort-output, msgcomm option: msgcomm Invocation. (line 127) 16539* --sort-output, msgconv option: msgconv Invocation. (line 106) 16540* --sort-output, msgen option: msgen Invocation. (line 102) 16541* --sort-output, msgfilter option: msgfilter Invocation. 16542 (line 160) 16543* --sort-output, msggrep option: msggrep Invocation. (line 183) 16544* --sort-output, msgmerge option: msgmerge Invocation. (line 171) 16545* --sort-output, msgunfmt option: msgunfmt Invocation. (line 144) 16546* --sort-output, msguniq option: msguniq Invocation. (line 124) 16547* --sort-output, xgettext option: xgettext Invocation. (line 317) 16548* --statistics, msgfmt option: msgfmt Invocation. (line 229) 16549* --strict, msgattrib option: msgattrib Invocation. 16550 (line 130) 16551* --strict, msgcat option: msgcat Invocation. (line 117) 16552* --strict, msgcomm option: msgcomm Invocation. (line 98) 16553* --strict, msgconv option: msgconv Invocation. (line 77) 16554* --strict, msgen option: msgen Invocation. (line 73) 16555* --strict, msgfilter option: msgfilter Invocation. 16556 (line 131) 16557* --strict, msgfmt option: msgfmt Invocation. (line 57) 16558* --strict, msggrep option: msggrep Invocation. (line 155) 16559* --strict, msgmerge option: msgmerge Invocation. (line 142) 16560* --strict, msgunfmt option: msgunfmt Invocation. (line 115) 16561* --strict, msguniq option: msguniq Invocation. (line 95) 16562* --strict, xgettext option: xgettext Invocation. (line 289) 16563* --stringtable-input, msgattrib option: msgattrib Invocation. 16564 (line 108) 16565* --stringtable-input, msgcat option: msgcat Invocation. (line 78) 16566* --stringtable-input, msgcmp option: msgcmp Invocation. (line 58) 16567* --stringtable-input, msgcomm option: msgcomm Invocation. (line 76) 16568* --stringtable-input, msgen option: msgen Invocation. (line 52) 16569* --stringtable-input, msgexec option: msgexec Invocation. (line 60) 16570* --stringtable-input, msgfilter option: msgfilter Invocation. 16571 (line 106) 16572* --stringtable-input, msgfmt option: msgfmt Invocation. (line 137) 16573* --stringtable-input, msggrep option: msggrep Invocation. (line 135) 16574* --stringtable-input, msginit option: msginit Invocation. (line 43) 16575* --stringtable-input, msgmerge option: msgmerge Invocation. (line 121) 16576* --stringtable-input, msgonv option: msgconv Invocation. (line 56) 16577* --stringtable-input, msguniq option: msguniq Invocation. (line 65) 16578* --stringtable-output, msgattrib option: msgattrib Invocation. 16579 (line 141) 16580* --stringtable-output, msgcat option: msgcat Invocation. (line 128) 16581* --stringtable-output, msgcomm option: msgcomm Invocation. (line 109) 16582* --stringtable-output, msgconv option: msgconv Invocation. (line 88) 16583* --stringtable-output, msgen option: msgen Invocation. (line 84) 16584* --stringtable-output, msgfilter option: msgfilter Invocation. 16585 (line 142) 16586* --stringtable-output, msggrep option: msggrep Invocation. (line 166) 16587* --stringtable-output, msginit option: msginit Invocation. (line 68) 16588* --stringtable-output, msgmerge option: msgmerge Invocation. (line 153) 16589* --stringtable-output, msgunfmt option: msgunfmt Invocation. (line 126) 16590* --stringtable-output, msguniq option: msguniq Invocation. (line 106) 16591* --stringtable-output, xgettext option: xgettext Invocation. (line 299) 16592* --style, msgcat option <1>: The --style option. (line 6) 16593* --style, msgcat option: msgcat Invocation. (line 99) 16594* --suffix, msgmerge option: msgmerge Invocation. (line 68) 16595* --symlink, gettextize option: gettextize Invocation. 16596 (line 63) 16597* --tcl, msgfmt option: msgfmt Invocation. (line 43) 16598* --tcl, msgunfmt option: msgunfmt Invocation. (line 26) 16599* --to-code, msgcat option: msgcat Invocation. (line 87) 16600* --to-code, msgconv option: msgconv Invocation. (line 42) 16601* --to-code, msguniq option: msguniq Invocation. (line 74) 16602* --translated, msgattrib option: msgattrib Invocation. 16603 (line 41) 16604* --trigraphs, xgettext option: xgettext Invocation. (line 239) 16605* --unique, msgcat option: msgcat Invocation. (line 65) 16606* --unique, msgcomm option: msgcomm Invocation. (line 63) 16607* --unique, msguniq option: msguniq Invocation. (line 53) 16608* --untranslated, msgattrib option: msgattrib Invocation. 16609 (line 44) 16610* --update, msgmerge option: msgmerge Invocation. (line 45) 16611* --use-first, msgcat option: msgcat Invocation. (line 90) 16612* --use-first, msguniq option: msguniq Invocation. (line 77) 16613* --use-fuzzy, msgcmp option: msgcmp Invocation. (line 39) 16614* --use-fuzzy, msgfmt option: msgfmt Invocation. (line 199) 16615* --use-untranslated, msgcmp option: msgcmp Invocation. (line 45) 16616* --variables, envsubst option: envsubst Invocation. (line 15) 16617* --verbose, msgfmt option: msgfmt Invocation. (line 233) 16618* --verbose, msgmerge option: msgmerge Invocation. (line 192) 16619* --verbose, msgunfmt option: msgunfmt Invocation. (line 161) 16620* --version, autopoint option: autopoint Invocation. 16621 (line 36) 16622* --version, envsubst option: envsubst Invocation. (line 26) 16623* --version, gettext option: gettext Invocation. (line 40) 16624* --version, gettextize option: gettextize Invocation. 16625 (line 80) 16626* --version, msgattrib option: msgattrib Invocation. 16627 (line 176) 16628* --version, msgcat option: msgcat Invocation. (line 163) 16629* --version, msgcmp option: msgcmp Invocation. (line 71) 16630* --version, msgcomm option: msgcomm Invocation. (line 147) 16631* --version, msgconv option: msgconv Invocation. (line 123) 16632* --version, msgen option: msgen Invocation. (line 119) 16633* --version, msgexec option: msgexec Invocation. (line 73) 16634* --version, msgfilter option: msgfilter Invocation. 16635 (line 177) 16636* --version, msgfmt option: msgfmt Invocation. (line 226) 16637* --version, msggrep option: msggrep Invocation. (line 199) 16638* --version, msginit option: msginit Invocation. (line 94) 16639* --version, msgmerge option: msgmerge Invocation. (line 188) 16640* --version, msgunfmt option: msgunfmt Invocation. (line 157) 16641* --version, msguniq option: msguniq Invocation. (line 141) 16642* --version, ngettext option: ngettext Invocation. (line 35) 16643* --version, xgettext option: xgettext Invocation. (line 408) 16644* --width, msgattrib option: msgattrib Invocation. 16645 (line 146) 16646* --width, msgcat option: msgcat Invocation. (line 133) 16647* --width, msgcomm option: msgcomm Invocation. (line 114) 16648* --width, msgconv option: msgconv Invocation. (line 93) 16649* --width, msgen option: msgen Invocation. (line 89) 16650* --width, msgfilter option: msgfilter Invocation. 16651 (line 147) 16652* --width, msggrep option: msggrep Invocation. (line 171) 16653* --width, msginit option: msginit Invocation. (line 73) 16654* --width, msgmerge option: msgmerge Invocation. (line 158) 16655* --width, msgunfmt option: msgunfmt Invocation. (line 131) 16656* --width, msguniq option: msguniq Invocation. (line 111) 16657* --width, xgettext option: xgettext Invocation. (line 304) 16658* -<, msgcat option: msgcat Invocation. (line 55) 16659* -<, msgcomm option: msgcomm Invocation. (line 53) 16660* ->, msgcat option: msgcat Invocation. (line 60) 16661* ->, msgcomm option: msgcomm Invocation. (line 58) 16662* -a, msgfmt option: msgfmt Invocation. (line 209) 16663* -a, xgettext option: xgettext Invocation. (line 106) 16664* -C, msgfmt option: msgfmt Invocation. (line 183) 16665* -c, msgfmt option: msgfmt Invocation. (line 146) 16666* -C, msggrep option: msggrep Invocation. (line 93) 16667* -C, msgmerge option: msgmerge Invocation. (line 36) 16668* -c, xgettext option: xgettext Invocation. (line 97) 16669* -C, xgettext option: xgettext Invocation. (line 64) 16670* -d, autopoint option: autopoint Invocation. 16671 (line 24) 16672* -d, gettext option: gettext Invocation. (line 16) 16673* -d, gettextize option: gettextize Invocation. 16674 (line 72) 16675* -D, msgattrib option: msgattrib Invocation. 16676 (line 19) 16677* -D, msgcat option: msgcat Invocation. (line 32) 16678* -D, msgcmp option: msgcmp Invocation. (line 27) 16679* -D, msgcomm option: msgcomm Invocation. (line 30) 16680* -D, msgconv option: msgconv Invocation. (line 19) 16681* -D, msgen option: msgen Invocation. (line 25) 16682* -D, msgexec option: msgexec Invocation. (line 44) 16683* -D, msgfilter option: msgfilter Invocation. 16684 (line 20) 16685* -d, msgfmt option: msgfmt Invocation. (line 84) 16686* -D, msgfmt option: msgfmt Invocation. (line 18) 16687* -D, msggrep option: msggrep Invocation. (line 19) 16688* -D, msgmerge option: msgmerge Invocation. (line 30) 16689* -d, msgunfmt option: msgunfmt Invocation. (line 70) 16690* -d, msguniq option: msguniq Invocation. (line 49) 16691* -D, msguniq option: msguniq Invocation. (line 26) 16692* -d, ngettext option: ngettext Invocation. (line 15) 16693* -d, xgettext option: xgettext Invocation. (line 36) 16694* -D, xgettext option: xgettext Invocation. (line 24) 16695* -E, gettext option: gettext Invocation. (line 27) 16696* -e, gettext option: gettext Invocation. (line 20) 16697* -e, msgfilter option: msgfilter Invocation. 16698 (line 70) 16699* -e, msggrep option: msggrep Invocation. (line 109) 16700* -E, msggrep option: msggrep Invocation. (line 101) 16701* -E, ngettext option: ngettext Invocation. (line 26) 16702* -e, ngettext option: ngettext Invocation. (line 19) 16703* -f, autopoint option: autopoint Invocation. 16704 (line 20) 16705* -f, gettextize option: gettextize Invocation. 16706 (line 40) 16707* -F, msgattrib option: msgattrib Invocation. 16708 (line 164) 16709* -F, msgcat option: msgcat Invocation. (line 151) 16710* -f, msgcat option: msgcat Invocation. (line 27) 16711* -F, msgcomm option: msgcomm Invocation. (line 132) 16712* -f, msgcomm option: msgcomm Invocation. (line 25) 16713* -F, msgconv option: msgconv Invocation. (line 111) 16714* -F, msgen option: msgen Invocation. (line 107) 16715* -F, msgfilter option: msgfilter Invocation. 16716 (line 165) 16717* -f, msgfilter option: msgfilter Invocation. 16718 (line 74) 16719* -f, msgfmt option: msgfmt Invocation. (line 199) 16720* -f, msggrep option: msggrep Invocation. (line 113) 16721* -F, msggrep option: msggrep Invocation. (line 105) 16722* -F, msgmerge option: msgmerge Invocation. (line 176) 16723* -F, msguniq option: msguniq Invocation. (line 129) 16724* -F, xgettext option: xgettext Invocation. (line 322) 16725* -f, xgettext option: xgettext Invocation. (line 19) 16726* -h, envsubst option: envsubst Invocation. (line 22) 16727* -h, gettext option: gettext Invocation. (line 32) 16728* -h, msgattrib option: msgattrib Invocation. 16729 (line 172) 16730* -h, msgcat option: msgcat Invocation. (line 159) 16731* -h, msgcmp option: msgcmp Invocation. (line 67) 16732* -h, msgcomm option: msgcomm Invocation. (line 143) 16733* -h, msgconv option: msgconv Invocation. (line 119) 16734* -h, msgen option: msgen Invocation. (line 115) 16735* -h, msgexec option: msgexec Invocation. (line 69) 16736* -h, msgfilter option: msgfilter Invocation. 16737 (line 173) 16738* -h, msgfmt option: msgfmt Invocation. (line 222) 16739* -h, msggrep option: msggrep Invocation. (line 195) 16740* -h, msginit option: msginit Invocation. (line 90) 16741* -h, msgmerge option: msgmerge Invocation. (line 184) 16742* -h, msgunfmt option: msgunfmt Invocation. (line 153) 16743* -h, msguniq option: msguniq Invocation. (line 137) 16744* -h, ngettext option: ngettext Invocation. (line 31) 16745* -h, xgettext option: xgettext Invocation. (line 404) 16746* -i, msgattrib option: msgattrib Invocation. 16747 (line 120) 16748* -i, msgcat option: msgcat Invocation. (line 107) 16749* -i, msgcomm option: msgcomm Invocation. (line 88) 16750* -i, msgconv option: msgconv Invocation. (line 68) 16751* -i, msgen option: msgen Invocation. (line 64) 16752* -i, msgexec option: msgexec Invocation. (line 40) 16753* -i, msgfilter option: msgfilter Invocation. 16754 (line 16) 16755* -i, msggrep option: msggrep Invocation. (line 117) 16756* -i, msginit option: msginit Invocation. (line 16) 16757* -i, msgmerge option: msgmerge Invocation. (line 133) 16758* -i, msgunfmt option: msgunfmt Invocation. (line 112) 16759* -i, msguniq option: msguniq Invocation. (line 85) 16760* -i, xgettext option: xgettext Invocation. (line 277) 16761* -j, msgfmt option: msgfmt Invocation. (line 30) 16762* -J, msggrep option: msggrep Invocation. (line 81) 16763* -j, msgunfmt option: msgunfmt Invocation. (line 16) 16764* -j, xgettext option: xgettext Invocation. (line 88) 16765* -K, msggrep option: msggrep Invocation. (line 85) 16766* -k, xgettext option: xgettext Invocation. (line 114) 16767* -l, msgfmt option: msgfmt Invocation. (line 79) 16768* -l, msginit option: msginit Invocation. (line 52) 16769* -l, msgunfmt option: msgunfmt Invocation. (line 47) 16770* -L, xgettext option: xgettext Invocation. (line 56) 16771* -m, msgcmp option: msgcmp Invocation. (line 36) 16772* -M, msggrep option: msggrep Invocation. (line 77) 16773* -m, msgmerge option: msgmerge Invocation. (line 101) 16774* -M, xgettext option: xgettext Invocation. (line 396) 16775* -m, xgettext option: xgettext Invocation. (line 392) 16776* -n, gettext option: gettext Invocation. (line 35) 16777* -n, msgattrib option: msgattrib Invocation. 16778 (line 127) 16779* -n, msgcat option: msgcat Invocation. (line 114) 16780* -n, msgcomm option: msgcomm Invocation. (line 95) 16781* -n, msgfilter option: msgfilter Invocation. 16782 (line 79) 16783* -N, msggrep option: msggrep Invocation. (line 72) 16784* -N, msgmerge option: msgmerge Invocation. (line 105) 16785* -n, msguniq option: msguniq Invocation. (line 92) 16786* -n, xgettext option: xgettext Invocation. (line 286) 16787* -o, msgattrib option: msgattrib Invocation. 16788 (line 31) 16789* -o, msgcat option: msgcat Invocation. (line 44) 16790* -o, msgcomm option: msgcomm Invocation. (line 42) 16791* -o, msgconv option: msgconv Invocation. (line 31) 16792* -o, msgen option: msgen Invocation. (line 37) 16793* -o, msgfilter option: msgfilter Invocation. 16794 (line 32) 16795* -o, msgfmt option: msgfmt Invocation. (line 54) 16796* -o, msggrep option: msggrep Invocation. (line 31) 16797* -o, msginit option: msginit Invocation. (line 27) 16798* -o, msgmerge option: msgmerge Invocation. (line 53) 16799* -o, msgunfmt option: msgunfmt Invocation. (line 98) 16800* -o, msguniq option: msguniq Invocation. (line 38) 16801* -o, xgettext option: xgettext Invocation. (line 40) 16802* -p, msgattrib option: msgattrib Invocation. 16803 (line 136) 16804* -P, msgattrib option: msgattrib Invocation. 16805 (line 104) 16806* -p, msgcat option: msgcat Invocation. (line 123) 16807* -P, msgcat option: msgcat Invocation. (line 74) 16808* -P, msgcmp option: msgcmp Invocation. (line 54) 16809* -p, msgcomm option: msgcomm Invocation. (line 104) 16810* -P, msgcomm option: msgcomm Invocation. (line 72) 16811* -p, msgconv option: msgconv Invocation. (line 83) 16812* -P, msgconv option: msgconv Invocation. (line 52) 16813* -p, msgen option: msgen Invocation. (line 79) 16814* -P, msgen option: msgen Invocation. (line 48) 16815* -P, msgexec option: msgexec Invocation. (line 56) 16816* -p, msgfilter option: msgfilter Invocation. 16817 (line 137) 16818* -P, msgfilter option: msgfilter Invocation. 16819 (line 102) 16820* -P, msgfmt option: msgfmt Invocation. (line 133) 16821* -p, msggrep option: msggrep Invocation. (line 161) 16822* -P, msggrep option: msggrep Invocation. (line 131) 16823* -p, msginit option: msginit Invocation. (line 63) 16824* -P, msginit option: msginit Invocation. (line 39) 16825* -p, msgmerge option: msgmerge Invocation. (line 148) 16826* -P, msgmerge option: msgmerge Invocation. (line 117) 16827* -p, msgunfmt option: msgunfmt Invocation. (line 121) 16828* -p, msguniq option: msguniq Invocation. (line 101) 16829* -P, msguniq option: msguniq Invocation. (line 61) 16830* -p, xgettext option: xgettext Invocation. (line 45) 16831* -q, msgmerge option: msgmerge Invocation. (line 197) 16832* -r, msgfmt option: msgfmt Invocation. (line 75) 16833* -r, msgunfmt option: msgunfmt Invocation. (line 43) 16834* -s, msgattrib option: msgattrib Invocation. 16835 (line 159) 16836* -s, msgcat option: msgcat Invocation. (line 146) 16837* -s, msgcomm option: msgcomm Invocation. (line 127) 16838* -s, msgconv option: msgconv Invocation. (line 106) 16839* -s, msgen option: msgen Invocation. (line 102) 16840* -s, msgfilter option: msgfilter Invocation. 16841 (line 160) 16842* -s, msgmerge option: msgmerge Invocation. (line 171) 16843* -s, msgunfmt option: msgunfmt Invocation. (line 144) 16844* -s, msguniq option: msguniq Invocation. (line 124) 16845* -s, xgettext option: xgettext Invocation. (line 317) 16846* -t, msgcat option: msgcat Invocation. (line 87) 16847* -t, msgconv option: msgconv Invocation. (line 42) 16848* -T, msggrep option: msggrep Invocation. (line 89) 16849* -t, msguniq option: msguniq Invocation. (line 74) 16850* -T, xgettext option: xgettext Invocation. (line 239) 16851* -u, msgcat option: msgcat Invocation. (line 65) 16852* -u, msgcomm option: msgcomm Invocation. (line 63) 16853* -U, msgmerge option: msgmerge Invocation. (line 45) 16854* -u, msguniq option: msguniq Invocation. (line 53) 16855* -V, envsubst option: envsubst Invocation. (line 26) 16856* -v, envsubst option: envsubst Invocation. (line 15) 16857* -V, gettext option: gettext Invocation. (line 40) 16858* -V, msgattrib option: msgattrib Invocation. 16859 (line 176) 16860* -V, msgcat option: msgcat Invocation. (line 163) 16861* -V, msgcmp option: msgcmp Invocation. (line 71) 16862* -V, msgcomm option: msgcomm Invocation. (line 147) 16863* -V, msgconv option: msgconv Invocation. (line 123) 16864* -V, msgen option: msgen Invocation. (line 119) 16865* -V, msgexec option: msgexec Invocation. (line 73) 16866* -V, msgfilter option: msgfilter Invocation. 16867 (line 177) 16868* -v, msgfmt option: msgfmt Invocation. (line 233) 16869* -V, msgfmt option: msgfmt Invocation. (line 226) 16870* -V, msggrep option: msggrep Invocation. (line 199) 16871* -v, msggrep option: msggrep Invocation. (line 121) 16872* -V, msginit option: msginit Invocation. (line 94) 16873* -v, msgmerge option: msgmerge Invocation. (line 192) 16874* -V, msgmerge option: msgmerge Invocation. (line 188) 16875* -v, msgunfmt option: msgunfmt Invocation. (line 161) 16876* -V, msgunfmt option: msgunfmt Invocation. (line 157) 16877* -V, msguniq option: msguniq Invocation. (line 141) 16878* -V, ngettext option: ngettext Invocation. (line 35) 16879* -V, xgettext option: xgettext Invocation. (line 408) 16880* -w, msgattrib option: msgattrib Invocation. 16881 (line 146) 16882* -w, msgcat option: msgcat Invocation. (line 133) 16883* -w, msgcomm option: msgcomm Invocation. (line 114) 16884* -w, msgconv option: msgconv Invocation. (line 93) 16885* -w, msgen option: msgen Invocation. (line 89) 16886* -w, msgfilter option: msgfilter Invocation. 16887 (line 147) 16888* -w, msggrep option: msggrep Invocation. (line 171) 16889* -w, msginit option: msginit Invocation. (line 73) 16890* -w, msgmerge option: msgmerge Invocation. (line 158) 16891* -w, msgunfmt option: msgunfmt Invocation. (line 131) 16892* -w, msguniq option: msguniq Invocation. (line 111) 16893* -w, xgettext option: xgettext Invocation. (line 304) 16894* -X, msggrep option: msggrep Invocation. (line 97) 16895* -x, xgettext option: xgettext Invocation. (line 92) 16896 16897 16898File: gettext.info, Node: Variable Index, Next: PO Mode Index, Prev: Option Index, Up: Top 16899 16900Variable Index 16901************** 16902 16903[index] 16904* Menu: 16905 16906* GETTEXT_LOG_UNTRANSLATED, environment variable: Prioritizing messages. 16907 (line 23) 16908* LANG, environment variable <1>: gettext grok. (line 32) 16909* LANG, environment variable: Locale Environment Variables. 16910 (line 17) 16911* LANGUAGE, environment variable <1>: po/Rules-*. (line 11) 16912* LANGUAGE, environment variable <2>: gettext grok. (line 28) 16913* LANGUAGE, environment variable: Locale Environment Variables. 16914 (line 11) 16915* LC_ALL, environment variable <1>: gettext grok. (line 28) 16916* LC_ALL, environment variable: Locale Environment Variables. 16917 (line 11) 16918* LC_COLLATE, environment variable <1>: gettext grok. (line 30) 16919* LC_COLLATE, environment variable: Locale Environment Variables. 16920 (line 13) 16921* LC_CTYPE, environment variable <1>: gettext grok. (line 30) 16922* LC_CTYPE, environment variable: Locale Environment Variables. 16923 (line 13) 16924* LC_MESSAGES, environment variable <1>: gettext grok. (line 30) 16925* LC_MESSAGES, environment variable: Locale Environment Variables. 16926 (line 13) 16927* LC_MONETARY, environment variable <1>: gettext grok. (line 30) 16928* LC_MONETARY, environment variable: Locale Environment Variables. 16929 (line 13) 16930* LC_NUMERIC, environment variable <1>: gettext grok. (line 30) 16931* LC_NUMERIC, environment variable: Locale Environment Variables. 16932 (line 13) 16933* LC_TIME, environment variable <1>: gettext grok. (line 30) 16934* LC_TIME, environment variable: Locale Environment Variables. 16935 (line 13) 16936* LINGUAS, environment variable: Installers. (line 17) 16937* MSGEXEC_LOCATION, environment variable: msgexec Invocation. (line 18) 16938* MSGEXEC_MSGCTXT, environment variable: msgexec Invocation. (line 18) 16939* MSGEXEC_MSGID, environment variable: msgexec Invocation. (line 18) 16940* PO_STYLE, environment variable: The --style option. (line 10) 16941* TERM, environment variable: The TERM variable. (line 6) 16942* TEXTDOMAIN, environment variable: sh. (line 23) 16943* TEXTDOMAINDIR, environment variable: sh. (line 26) 16944 16945 16946File: gettext.info, Node: PO Mode Index, Next: Autoconf Macro Index, Prev: Variable Index, Up: Top 16947 16948PO Mode Index 16949************* 16950 16951[index] 16952* Menu: 16953 16954* #, PO Mode command: Modifying Comments. (line 24) 16955* ,, PO Mode command: Marking. (line 44) 16956* ., PO Mode command: Entry Positioning. (line 20) 16957* .emacs customizations: Installation. (line 13) 16958* 0, PO Mode command: Main PO Commands. (line 40) 16959* <, PO Mode command: Entry Positioning. (line 29) 16960* =, PO Mode command: Main PO Commands. (line 47) 16961* >, PO Mode command: Entry Positioning. (line 32) 16962* ?, PO Mode command: Main PO Commands. (line 44) 16963* _, PO Mode command: Main PO Commands. (line 30) 16964* a, PO Mode command: Auxiliary. (line 40) 16965* A, PO Mode command: Auxiliary. (line 28) 16966* a, PO Mode command: Auxiliary. (line 21) 16967* auxiliary PO file: Auxiliary. (line 13) 16968* C-c C-a, PO Mode command <1>: Auxiliary. (line 25) 16969* C-c C-a, PO Mode command: Subedit. (line 17) 16970* C-c C-c, PO Mode command: Subedit. (line 11) 16971* C-c C-k, PO Mode command: Subedit. (line 14) 16972* C-j, PO Mode command: Modifying Translations. 16973 (line 26) 16974* commands: Main PO Commands. (line 6) 16975* comment out PO file entry: Obsolete Entries. (line 47) 16976* consulting program sources: C Sources Context. (line 6) 16977* consulting translations to other languages: Auxiliary. (line 6) 16978* current entry of a PO file: Entry Positioning. (line 6) 16979* cut and paste for translated strings: Modifying Translations. 16980 (line 74) 16981* DEL, PO Mode command <1>: Obsolete Entries. (line 32) 16982* DEL, PO Mode command: Fuzzy Entries. (line 60) 16983* editing comments: Modifying Comments. (line 6) 16984* editing multiple entries: Subedit. (line 62) 16985* editing translations: Modifying Translations. 16986 (line 6) 16987* etags, using for marking strings: Marking. (line 17) 16988* exiting PO subedit: Subedit. (line 20) 16989* find source fragment for a PO file entry: C Sources Context. 16990 (line 33) 16991* h, PO Mode command: Main PO Commands. (line 44) 16992* installing PO mode: Installation. (line 13) 16993* K, PO Mode command: Modifying Comments. (line 27) 16994* k, PO Mode command <1>: Modifying Translations. 16995 (line 30) 16996* k, PO Mode command: Untranslated Entries. 16997 (line 32) 16998* LFD, PO Mode command: Modifying Translations. 16999 (line 26) 17000* looking at the source to aid translation: C Sources Context. 17001 (line 6) 17002* m, PO Mode command: Entry Positioning. (line 35) 17003* M-,, PO Mode command: Marking. (line 48) 17004* M-., PO Mode command: Marking. (line 51) 17005* M-A, PO Mode command: Auxiliary. (line 32) 17006* M-S, PO Mode command: C Sources Context. (line 89) 17007* M-s, PO Mode command: C Sources Context. (line 53) 17008* M-S, PO Mode command: C Sources Context. (line 49) 17009* M-s, PO Mode command: C Sources Context. (line 41) 17010* marking strings for translation: Marking. (line 6) 17011* moving by fuzzy entries: Fuzzy Entries. (line 24) 17012* moving by obsolete entries: Obsolete Entries. (line 22) 17013* moving by translated entries: Translated Entries. (line 12) 17014* moving by untranslated entries: Untranslated Entries. 17015 (line 18) 17016* moving through a PO file: Entry Positioning. (line 14) 17017* n, PO Mode command: Entry Positioning. (line 23) 17018* next-error, stepping through PO file validation results: Main PO Commands. 17019 (line 99) 17020* normalize, PO Mode command: Auxiliary. (line 64) 17021* O, PO Mode command: Obsolete Entries. (line 36) 17022* o, PO Mode command: Obsolete Entries. (line 36) 17023* O, PO Mode command: Obsolete Entries. (line 29) 17024* o, PO Mode command: Obsolete Entries. (line 26) 17025* obsolete active entry: Obsolete Entries. (line 47) 17026* p, PO Mode command: Entry Positioning. (line 26) 17027* pending subedits: Subedit. (line 73) 17028* po-auto-edit-with-msgid, PO Mode variable: Modifying Translations. 17029 (line 57) 17030* po-auto-fuzzy-on-edit, PO Mode variable: Translated Entries. 17031 (line 28) 17032* po-auto-select-on-unfuzzy, PO Mode variable: Fuzzy Entries. (line 44) 17033* po-confirm-and-quit, PO Mode command: Main PO Commands. (line 62) 17034* po-consider-as-auxiliary, PO Mode command: Auxiliary. (line 36) 17035* po-consider-source-path, PO Mode command: C Sources Context. 17036 (line 89) 17037* po-current-entry, PO Mode command: Entry Positioning. (line 46) 17038* po-cycle-auxiliary, PO Mode command: Auxiliary. (line 40) 17039* po-cycle-source-reference, PO Mode command: C Sources Context. 17040 (line 53) 17041* po-edit-comment, PO Mode command: Modifying Comments. (line 46) 17042* po-edit-msgstr, PO Mode command: Modifying Translations. 17043 (line 42) 17044* po-exchange-location, PO Mode command: Entry Positioning. (line 106) 17045* po-fade-out-entry, PO Mode command <1>: Obsolete Entries. (line 47) 17046* po-fade-out-entry, PO Mode command: Fuzzy Entries. (line 60) 17047* po-first-entry, PO Mode command: Entry Positioning. (line 74) 17048* po-help, PO Mode command: Main PO Commands. (line 83) 17049* po-ignore-as-auxiliary, PO Mode command: Auxiliary. (line 36) 17050* po-ignore-source-path, PO Mode command: C Sources Context. (line 89) 17051* po-kill-comment, PO Mode command: Modifying Comments. (line 60) 17052* po-kill-msgstr, PO Mode command <1>: Modifying Translations. 17053 (line 74) 17054* po-kill-msgstr, PO Mode command: Untranslated Entries. 17055 (line 40) 17056* po-kill-ring-save-comment, PO Mode command: Modifying Comments. 17057 (line 60) 17058* po-kill-ring-save-msgstr, PO Mode command: Modifying Translations. 17059 (line 74) 17060* po-last-entry, PO Mode command: Entry Positioning. (line 74) 17061* po-mark-translatable, PO Mode command: Marking. (line 98) 17062* po-msgid-to-msgstr, PO Mode command: Modifying Translations. 17063 (line 52) 17064* po-next-entry, PO Mode command: Entry Positioning. (line 69) 17065* po-next-fuzzy-entry, PO Mode command: Fuzzy Entries. (line 39) 17066* po-next-obsolete-entry, PO Mode command: Obsolete Entries. (line 36) 17067* po-next-translated-entry, PO Mode command: Translated Entries. 17068 (line 23) 17069* po-next-untranslated-entry, PO Mode command: Untranslated Entries. 17070 (line 35) 17071* po-normalize, PO Mode command: Normalizing. (line 31) 17072* po-other-window, PO Mode command: Main PO Commands. (line 72) 17073* po-pop-location, PO Mode command: Entry Positioning. (line 92) 17074* po-previous-entry, PO Mode command: Entry Positioning. (line 69) 17075* po-previous-fuzzy-entry, PO Mode command: Fuzzy Entries. (line 39) 17076* po-previous-obsolete-entry, PO Mode command: Obsolete Entries. 17077 (line 36) 17078* po-previous-translated-entry, PO Mode command: Translated Entries. 17079 (line 23) 17080* po-previous-untransted-entry, PO Mode command: Untranslated Entries. 17081 (line 35) 17082* po-push-location, PO Mode command: Entry Positioning. (line 92) 17083* po-quit, PO Mode command: Main PO Commands. (line 62) 17084* po-select-auxiliary, PO Mode command: Auxiliary. (line 49) 17085* po-select-mark-and-mark, PO Mode command: Marking. (line 98) 17086* po-select-source-reference, PO Mode command: C Sources Context. 17087 (line 53) 17088* po-statistics, PO Mode command: Main PO Commands. (line 87) 17089* po-subedit-abort, PO Mode command: Subedit. (line 27) 17090* po-subedit-cycle-auxiliary, PO Mode command: Subedit. (line 35) 17091* po-subedit-exit, PO Mode command: Subedit. (line 20) 17092* po-subedit-mode-hook, PO Mode variable: Modifying Comments. (line 57) 17093* po-tags-search, PO Mode command: Marking. (line 56) 17094* po-undo, PO Mode command: Main PO Commands. (line 53) 17095* po-unfuzzy, PO Mode command: Fuzzy Entries. (line 44) 17096* po-validate, PO Mode command: Main PO Commands. (line 92) 17097* po-yank-comment, PO Mode command: Modifying Comments. (line 60) 17098* po-yank-msgstr, PO Mode command: Modifying Translations. 17099 (line 98) 17100* q, PO Mode command: Main PO Commands. (line 62) 17101* Q, PO Mode command: Main PO Commands. (line 62) 17102* q, PO Mode command: Main PO Commands. (line 36) 17103* Q, PO Mode command: Main PO Commands. (line 33) 17104* r, PO Mode command: Entry Positioning. (line 39) 17105* RET, PO Mode command: Modifying Translations. 17106 (line 22) 17107* S, PO Mode command: C Sources Context. (line 89) 17108* s, PO Mode command: C Sources Context. (line 53) 17109* S, PO Mode command: C Sources Context. (line 45) 17110* s, PO Mode command: C Sources Context. (line 37) 17111* starting a string translation: Modifying Translations. 17112 (line 63) 17113* string normalization in entries: Normalizing. (line 30) 17114* subedit minor mode: Subedit. (line 6) 17115* T, PO Mode command: Translated Entries. (line 23) 17116* t, PO Mode command: Translated Entries. (line 23) 17117* T, PO Mode command: Translated Entries. (line 19) 17118* t, PO Mode command: Translated Entries. (line 16) 17119* TAB, PO Mode command: Fuzzy Entries. (line 36) 17120* TAGS, and marking translatable strings: Marking. (line 31) 17121* U, PO Mode command: Untranslated Entries. 17122 (line 35) 17123* u, PO Mode command: Untranslated Entries. 17124 (line 35) 17125* U, PO Mode command: Untranslated Entries. 17126 (line 28) 17127* u, PO Mode command: Untranslated Entries. 17128 (line 25) 17129* use the source, Luke: C Sources Context. (line 6) 17130* using obsolete translations to make new entries: Modifying Translations. 17131 (line 124) 17132* using translation compendia: Compendium. (line 6) 17133* V, PO Mode command: Main PO Commands. (line 50) 17134* W, PO Mode command: Modifying Comments. (line 31) 17135* w, PO Mode command: Modifying Translations. 17136 (line 34) 17137* x, PO Mode command: Entry Positioning. (line 42) 17138* Y, PO Mode command: Modifying Comments. (line 35) 17139* y, PO Mode command: Modifying Translations. 17140 (line 38) 17141* Z, PO Mode command: Fuzzy Entries. (line 39) 17142* z, PO Mode command: Fuzzy Entries. (line 39) 17143* Z, PO Mode command: Fuzzy Entries. (line 33) 17144* z, PO Mode command: Fuzzy Entries. (line 30) 17145 17146 17147File: gettext.info, Node: Autoconf Macro Index, Next: Index, Prev: PO Mode Index, Up: Top 17148 17149Autoconf Macro Index 17150******************** 17151 17152[index] 17153* Menu: 17154 17155* AM_GNU_GETTEXT: AM_GNU_GETTEXT. (line 6) 17156* AM_GNU_GETTEXT_INTL_SUBDIR: AM_GNU_GETTEXT_INTL_SUBDIR. 17157 (line 6) 17158* AM_GNU_GETTEXT_NEED: AM_GNU_GETTEXT_NEED. (line 6) 17159* AM_GNU_GETTEXT_VERSION: AM_GNU_GETTEXT_VERSION. 17160 (line 6) 17161* AM_ICONV: AM_ICONV. (line 6) 17162* AM_PO_SUBDIRS: AM_PO_SUBDIRS. (line 6) 17163* AM_XGETTEXT_OPTION: AM_XGETTEXT_OPTION. (line 6) 17164 17165 17166File: gettext.info, Node: Index, Prev: Autoconf Macro Index, Up: Top 17167 17168General Index 17169************* 17170 17171[index] 17172* Menu: 17173 17174* _, a macro to mark strings for translation: Mark Keywords. (line 45) 17175* _nl_msg_cat_cntr: gettext grok. (line 62) 17176* ABOUT-NLS file: Installing Localizations. 17177 (line 13) 17178* acconfig.h file: acconfig. (line 6) 17179* accumulating translations: Creating Compendia. (line 14) 17180* aclocal.m4 file: aclocal. (line 6) 17181* adding keywords, xgettext: xgettext Invocation. (line 117) 17182* ambiguities: Preparing Strings. (line 41) 17183* apply a filter to translations: msgfilter Invocation. 17184 (line 8) 17185* apply command to all translations in a catalog: msgexec Invocation. 17186 (line 8) 17187* Arabic digits: c-format. (line 28) 17188* attribute manipulation: msgattrib Invocation. 17189 (line 8) 17190* attribute, fuzzy: Fuzzy Entries. (line 6) 17191* attributes of a PO file entry: Fuzzy Entries. (line 6) 17192* attributes, manipulating: Manipulating. (line 56) 17193* autoconf macros for gettext: autoconf macros. (line 6) 17194* autopoint program, usage: autopoint Invocation. 17195 (line 6) 17196* auxiliary PO file: Auxiliary. (line 13) 17197* available translations: Installing Localizations. 17198 (line 6) 17199* awk: gawk. (line 6) 17200* awk-format flag: PO Files. (line 149) 17201* backup old file, and msgmerge program: msgmerge Invocation. (line 65) 17202* bash: bash. (line 6) 17203* bibliography: References. (line 6) 17204* big picture: Overview. (line 6) 17205* bind_textdomain_codeset: Charset conversion. (line 28) 17206* Boost format strings: xgettext Invocation. (line 252) 17207* boost-format flag: PO Files. (line 189) 17208* bug report address: Introduction. (line 24) 17209* C and C-like languages: C. (line 6) 17210* C trigraphs: xgettext Invocation. (line 239) 17211* C#: C#. (line 6) 17212* C# mode, and msgfmt program: msgfmt Invocation. (line 36) 17213* C# mode, and msgunfmt program: msgunfmt Invocation. (line 19) 17214* C# resources mode, and msgfmt program: msgfmt Invocation. (line 40) 17215* C# resources mode, and msgunfmt program: msgunfmt Invocation. 17216 (line 23) 17217* C#, string concatenation: Preparing Strings. (line 168) 17218* c-format flag: PO Files. (line 90) 17219* c-format, and xgettext: c-format Flag. (line 48) 17220* catalog encoding and msgexec output: msgexec Invocation. (line 25) 17221* catclose, a catgets function: Interface to catgets. 17222 (line 44) 17223* catgets, a catgets function: Interface to catgets. 17224 (line 25) 17225* catgets, X/Open specification: catgets. (line 6) 17226* catopen, a catgets function: Interface to catgets. 17227 (line 13) 17228* character encoding: Aspects. (line 67) 17229* charset conversion at runtime: Charset conversion. (line 6) 17230* charset of PO files: Header Entry. (line 65) 17231* check format strings: msgfmt Invocation. (line 150) 17232* checking of translations: Manipulating. (line 41) 17233* clisp: Common Lisp. (line 6) 17234* clisp C sources: clisp C. (line 6) 17235* codeset: Aspects. (line 67) 17236* comments in PO files: PO Files. (line 288) 17237* comments, automatic: PO Files. (line 36) 17238* comments, extracted: PO Files. (line 36) 17239* comments, translator: PO Files. (line 36) 17240* Common Lisp: Common Lisp. (line 6) 17241* compare PO files: msgcmp Invocation. (line 8) 17242* comparison of interfaces: Comparison. (line 6) 17243* compatibility with X/Open msgfmt: msgfmt Invocation. (line 183) 17244* compendium: Compendium. (line 6) 17245* compendium, creating: Creating Compendia. (line 6) 17246* concatenate PO files: msgcat Invocation. (line 8) 17247* concatenating PO files into a compendium: Creating Compendia. 17248 (line 14) 17249* concatenation of strings: Preparing Strings. (line 117) 17250* config.h.in file: config.h.in. (line 6) 17251* context: Contexts. (line 6) 17252* context, argument specification in xgettext: xgettext Invocation. 17253 (line 117) 17254* context, in MO files: MO Files. (line 63) 17255* context, in PO files: PO Files. (line 193) 17256* control characters: Preparing Strings. (line 190) 17257* convert binary message catalog into PO file: msgunfmt Invocation. 17258 (line 8) 17259* convert translations to a different encoding: msgconv Invocation. 17260 (line 8) 17261* converting a package to use gettext: Prerequisites. (line 6) 17262* country codes: Country Codes. (line 6) 17263* create new PO file: msginit Invocation. (line 8) 17264* creating a new PO file: Creating. (line 6) 17265* creating compendia: Creating Compendia. (line 6) 17266* csharp-format flag: PO Files. (line 145) 17267* currency symbols: Aspects. (line 79) 17268* date format: Aspects. (line 84) 17269* dcngettext: Plural forms. (line 128) 17270* dcpgettext: Contexts. (line 56) 17271* dcpgettext_expr: Contexts. (line 112) 17272* debugging messages marked as format strings: xgettext Invocation. 17273 (line 256) 17274* dialect: Manipulating. (line 28) 17275* disabling NLS: lib/gettext.h. (line 6) 17276* distribution tarball: Release Management. (line 6) 17277* dngettext: Plural forms. (line 120) 17278* dollar substitution: envsubst Invocation. (line 8) 17279* domain ambiguities: Ambiguities. (line 6) 17280* dpgettext: Contexts. (line 56) 17281* dpgettext_expr: Contexts. (line 112) 17282* duplicate elimination: Manipulating. (line 45) 17283* duplicate removal: msguniq Invocation. (line 8) 17284* editing comments in PO files: Modifying Comments. (line 6) 17285* Editing PO Files: Editing. (line 6) 17286* editing translations: Modifying Translations. 17287 (line 6) 17288* elisp-format flag: PO Files. (line 125) 17289* Emacs Lisp: Emacs Lisp. (line 6) 17290* Emacs PO Mode: PO Mode. (line 6) 17291* encoding: Aspects. (line 67) 17292* encoding conversion: Manipulating. (line 17) 17293* encoding conversion at runtime: Charset conversion. (line 6) 17294* encoding for your language: Header Entry. (line 94) 17295* encoding list: Header Entry. (line 78) 17296* encoding of PO files: Header Entry. (line 65) 17297* environment variables: envsubst Invocation. (line 8) 17298* envsubst program, usage: envsubst Invocation. (line 6) 17299* eval_gettext function, usage: eval_gettext Invocation. 17300 (line 6) 17301* eval_ngettext function, usage: eval_ngettext Invocation. 17302 (line 6) 17303* evolution of packages: Overview. (line 127) 17304* extracting parts of a PO file into a compendium: Creating Compendia. 17305 (line 65) 17306* FDL, GNU Free Documentation License: GNU FDL. (line 6) 17307* file format, .mo: MO Files. (line 6) 17308* file format, .po: PO Files. (line 6) 17309* files, .po and .mo: Files. (line 6) 17310* files, .pot: Overview. (line 67) 17311* filter messages according to attributes: msgattrib Invocation. 17312 (line 8) 17313* find common messages: msgcomm Invocation. (line 8) 17314* force use of fuzzy entries: msgfmt Invocation. (line 199) 17315* format strings: c-format Flag. (line 6) 17316* Free Pascal: Pascal. (line 6) 17317* function attribute, __format__: xgettext Invocation. (line 203) 17318* function attribute, __format_arg__: xgettext Invocation. (line 217) 17319* fuzzy entries: Fuzzy Entries. (line 6) 17320* fuzzy flag: PO Files. (line 80) 17321* gawk: gawk. (line 6) 17322* gcc-internal-format flag: PO Files. (line 177) 17323* GCC-source: GCC-source. (line 6) 17324* generate binary message catalog from PO file: msgfmt Invocation. 17325 (line 8) 17326* generate translation catalog in English: msgen Invocation. (line 8) 17327* gettext files: Adjusting Files. (line 6) 17328* gettext installation: Installation. (line 6) 17329* gettext interface: Interface to gettext. 17330 (line 6) 17331* gettext program, usage: gettext Invocation. (line 6) 17332* gettext vs catgets: Comparison. (line 6) 17333* gettext, a programmer's view: gettext. (line 6) 17334* gettext.h file: lib/gettext.h. (line 6) 17335* gettextize program, usage: gettextize Invocation. 17336 (line 34) 17337* GNOME PO file editor: Gtranslator. (line 6) 17338* GPL, GNU General Public License: GNU GPL. (line 6) 17339* GUI programs: Contexts. (line 6) 17340* guile: Scheme. (line 6) 17341* hash table, inside MO files: MO Files. (line 47) 17342* he, she, and they: Introduction. (line 15) 17343* header entry of a PO file: Header Entry. (line 6) 17344* help option: Preparing Strings. (line 109) 17345* history of GNU gettext: History. (line 6) 17346* i18n: Concepts. (line 6) 17347* importing PO files: Normalizing. (line 55) 17348* include file libintl.h <1>: lib/gettext.h. (line 29) 17349* include file libintl.h <2>: Comparison. (line 33) 17350* include file libintl.h <3>: Importing. (line 11) 17351* include file libintl.h: Overview. (line 57) 17352* initialization: Triggering. (line 6) 17353* initialize new PO file: msginit Invocation. (line 8) 17354* initialize translations from a compendium: Using Compendia. (line 12) 17355* installing gettext: Installation. (line 6) 17356* interface to catgets: Interface to catgets. 17357 (line 6) 17358* internationalization: Concepts. (line 16) 17359* inttypes.h: Preparing Strings. (line 133) 17360* ISO 3166: Country Codes. (line 6) 17361* ISO 639: Language Codes. (line 6) 17362* Java: Java. (line 6) 17363* Java mode, and msgfmt program: msgfmt Invocation. (line 30) 17364* Java mode, and msgunfmt program: msgunfmt Invocation. (line 16) 17365* Java, string concatenation: Preparing Strings. (line 168) 17366* java-format flag: PO Files. (line 141) 17367* KDE format strings: xgettext Invocation. (line 248) 17368* KDE PO file editor: KBabel. (line 6) 17369* kde-format flag: PO Files. (line 185) 17370* keyboard accelerator checking: msgfmt Invocation. (line 187) 17371* l10n: Concepts. (line 6) 17372* language codes: Language Codes. (line 6) 17373* language selection: Locale Environment Variables. 17374 (line 6) 17375* language selection at runtime: gettext grok. (line 14) 17376* large package: Ambiguities. (line 6) 17377* LGPL, GNU Lesser General Public License: GNU LGPL. (line 6) 17378* libiconv library: AM_ICONV. (line 21) 17379* libintl for C#: C#. (line 178) 17380* libintl for Java: Java. (line 105) 17381* libintl library: AM_GNU_GETTEXT. (line 53) 17382* librep Lisp: librep. (line 6) 17383* librep-format flag: PO Files. (line 129) 17384* License, GNU FDL: GNU FDL. (line 6) 17385* License, GNU GPL: GNU GPL. (line 6) 17386* License, GNU LGPL: GNU LGPL. (line 6) 17387* Licenses: Licenses. (line 6) 17388* LINGUAS file: po/LINGUAS. (line 6) 17389* link with libintl: Overview. (line 62) 17390* Linux <1>: Header Entry. (line 91) 17391* Linux <2>: Overview. (line 62) 17392* Linux: Aspects. (line 125) 17393* Lisp: Common Lisp. (line 6) 17394* lisp-format flag: PO Files. (line 121) 17395* list of translation teams, where to find: Header Entry. (line 59) 17396* locale categories: Aspects. (line 61) 17397* locale category, LC_ALL: Triggering. (line 23) 17398* locale category, LC_COLLATE: Triggering. (line 53) 17399* locale category, LC_CTYPE <1>: Triggering. (line 23) 17400* locale category, LC_CTYPE: Aspects. (line 67) 17401* locale category, LC_MESSAGES <1>: Triggering. (line 53) 17402* locale category, LC_MESSAGES: Aspects. (line 108) 17403* locale category, LC_MONETARY <1>: Triggering. (line 53) 17404* locale category, LC_MONETARY: Aspects. (line 79) 17405* locale category, LC_NUMERIC <1>: Triggering. (line 53) 17406* locale category, LC_NUMERIC: Aspects. (line 94) 17407* locale category, LC_RESPONSES: Triggering. (line 53) 17408* locale category, LC_TIME <1>: Triggering. (line 53) 17409* locale category, LC_TIME: Aspects. (line 84) 17410* locale program: Header Entry. (line 71) 17411* localization: Concepts. (line 26) 17412* lookup message translation <1>: eval_gettext Invocation. 17413 (line 8) 17414* lookup message translation: gettext Invocation. (line 9) 17415* lookup plural message translation <1>: eval_ngettext Invocation. 17416 (line 8) 17417* lookup plural message translation: ngettext Invocation. (line 8) 17418* magic signature of MO files: MO Files. (line 9) 17419* Makefile.in.in extensions: po/Rules-*. (line 6) 17420* Makevars file: po/Makevars. (line 6) 17421* manipulating PO files: Manipulating. (line 6) 17422* marking Perl sources: Perl. (line 93) 17423* marking string initializers: Special cases. (line 6) 17424* marking strings that require translation: Mark Keywords. (line 6) 17425* marking strings, preparations: Preparing Strings. (line 6) 17426* marking translatable strings: Overview. (line 34) 17427* markup: Preparing Strings. (line 190) 17428* menu entries: Contexts. (line 6) 17429* menu, keyboard accelerator support: msgfmt Invocation. (line 187) 17430* merge PO files: msgcat Invocation. (line 8) 17431* merging two PO files: Manipulating. (line 10) 17432* message catalog files location: Locating Catalogs. (line 6) 17433* messages: Aspects. (line 108) 17434* migration from earlier versions of gettext: Prerequisites. (line 6) 17435* mkinstalldirs file: mkinstalldirs. (line 6) 17436* mnemonics of menu entries: msgfmt Invocation. (line 187) 17437* MO file's format: MO Files. (line 6) 17438* modify message attributes: msgattrib Invocation. 17439 (line 62) 17440* msgattrib program, usage: msgattrib Invocation. 17441 (line 6) 17442* msgcat program, usage: msgcat Invocation. (line 6) 17443* msgcmp program, usage: msgcmp Invocation. (line 6) 17444* msgcomm program, usage: msgcomm Invocation. (line 6) 17445* msgconv program, usage: msgconv Invocation. (line 6) 17446* msgctxt: PO Files. (line 193) 17447* msgen program, usage: msgen Invocation. (line 6) 17448* msgexec program, usage: msgexec Invocation. (line 6) 17449* msgfilter filter and catalog encoding: msgfilter Invocation. 17450 (line 46) 17451* msgfilter program, usage: msgfilter Invocation. 17452 (line 6) 17453* msgfmt program, usage: msgfmt Invocation. (line 6) 17454* msggrep program, usage: msggrep Invocation. (line 6) 17455* msgid: PO Files. (line 56) 17456* msgid_plural: PO Files. (line 213) 17457* msginit program, usage: msginit Invocation. (line 6) 17458* msgmerge program, usage: msgmerge Invocation. (line 6) 17459* msgstr: PO Files. (line 56) 17460* msgunfmt program, usage: msgunfmt Invocation. (line 6) 17461* msguniq program, usage: msguniq Invocation. (line 6) 17462* multi-line strings: Normalizing. (line 65) 17463* N_, a convenience macro: Comparison. (line 41) 17464* Native Language Support: Concepts. (line 51) 17465* Natural Language Support: Concepts. (line 51) 17466* newlines in PO files: PO Files. (line 283) 17467* ngettext: Plural forms. (line 84) 17468* ngettext program, usage: ngettext Invocation. (line 6) 17469* NLS: Concepts. (line 51) 17470* no-awk-format flag: PO Files. (line 150) 17471* no-boost-format flag: PO Files. (line 190) 17472* no-c-format flag: PO Files. (line 91) 17473* no-c-format, and xgettext: c-format Flag. (line 48) 17474* no-csharp-format flag: PO Files. (line 146) 17475* no-elisp-format flag: PO Files. (line 126) 17476* no-gcc-internal-format flag: PO Files. (line 178) 17477* no-java-format flag: PO Files. (line 142) 17478* no-kde-format flag: PO Files. (line 186) 17479* no-librep-format flag: PO Files. (line 130) 17480* no-lisp-format flag: PO Files. (line 122) 17481* no-objc-format flag: PO Files. (line 110) 17482* no-object-pascal-format flag: PO Files. (line 154) 17483* no-perl-brace-format flag: PO Files. (line 170) 17484* no-perl-format flag: PO Files. (line 166) 17485* no-php-format flag: PO Files. (line 174) 17486* no-python-format flag: PO Files. (line 118) 17487* no-qt-format flag: PO Files. (line 182) 17488* no-scheme-format flag: PO Files. (line 134) 17489* no-sh-format flag: PO Files. (line 114) 17490* no-smalltalk-format flag: PO Files. (line 138) 17491* no-tcl-format flag: PO Files. (line 162) 17492* no-ycp-format flag: PO Files. (line 158) 17493* nplurals, in a PO file header: Plural forms. (line 145) 17494* number format: Aspects. (line 94) 17495* objc-format flag: PO Files. (line 109) 17496* Object Pascal: Pascal. (line 6) 17497* object-pascal-format flag: PO Files. (line 153) 17498* obsolete entries: Obsolete Entries. (line 6) 17499* optimization of gettext functions: Optimized gettext. (line 6) 17500* orthography: Manipulating. (line 28) 17501* outdigits: c-format. (line 28) 17502* output to stdout, xgettext: xgettext Invocation. (line 48) 17503* overview of gettext: Overview. (line 6) 17504* package and version declaration in configure.ac: configure.ac. 17505 (line 9) 17506* package build and installation options: Installers. (line 6) 17507* package distributor's view of gettext: Installers. (line 6) 17508* package installer's view of gettext: Installers. (line 6) 17509* package maintainer's view of gettext: Maintainers. (line 6) 17510* paragraphs: Preparing Strings. (line 101) 17511* Pascal: Pascal. (line 6) 17512* Perl: Perl. (line 6) 17513* Perl default keywords: Default Keywords. (line 6) 17514* Perl invalid string interpolation: Interpolation I. (line 6) 17515* Perl long lines: Long Lines. (line 6) 17516* Perl parentheses: Parentheses. (line 6) 17517* Perl pitfalls: Perl Pitfalls. (line 6) 17518* Perl quote-like expressions: Quote-like Expressions. 17519 (line 6) 17520* Perl special keywords for hash-lookups: Special Keywords. (line 6) 17521* Perl valid string interpolation: Interpolation II. (line 6) 17522* perl-brace-format flag: PO Files. (line 169) 17523* perl-format flag: PO Files. (line 165) 17524* pgettext: Contexts. (line 33) 17525* pgettext_expr: Contexts. (line 112) 17526* PHP: PHP. (line 6) 17527* php-format flag: PO Files. (line 173) 17528* Pike: Pike. (line 6) 17529* plural form formulas: Plural forms. (line 165) 17530* plural forms: Plural forms. (line 6) 17531* plural forms, in MO files: MO Files. (line 66) 17532* plural forms, in PO files: PO Files. (line 213) 17533* plural, in a PO file header: Plural forms. (line 145) 17534* PO files' format: PO Files. (line 6) 17535* PO mode (Emacs) commands: Main PO Commands. (line 6) 17536* PO template file: Template. (line 6) 17537* po_file_domains: libgettextpo. (line 41) 17538* po_file_free: libgettextpo. (line 36) 17539* po_file_read: libgettextpo. (line 30) 17540* po_message_iterator: libgettextpo. (line 50) 17541* po_message_iterator_free: libgettextpo. (line 57) 17542* po_message_msgid: libgettextpo. (line 70) 17543* po_message_msgid_plural: libgettextpo. (line 75) 17544* po_message_msgstr: libgettextpo. (line 80) 17545* po_message_msgstr_plural: libgettextpo. (line 86) 17546* po_next_message: libgettextpo. (line 62) 17547* portability problems with sed: msgfilter Invocation. 17548 (line 57) 17549* POTFILES.in file: po/POTFILES.in. (line 6) 17550* preparing programs for translation: Sources. (line 6) 17551* preparing shell scripts for translation: Preparing Shell Scripts. 17552 (line 6) 17553* problems with catgets interface: Problems with catgets. 17554 (line 6) 17555* programming languages: Language Implementors. 17556 (line 6) 17557* Python: Python. (line 6) 17558* python-format flag: PO Files. (line 117) 17559* Qt format strings: xgettext Invocation. (line 244) 17560* Qt mode, and msgfmt program: msgfmt Invocation. (line 46) 17561* qt-format flag: PO Files. (line 181) 17562* quotation marks <1>: po/Rules-*. (line 11) 17563* quotation marks: Header Entry. (line 145) 17564* quote characters, use in PO files: Header Entry. (line 145) 17565* recode-sr-latin program: msgfilter Invocation. 17566 (line 85) 17567* related reading: References. (line 6) 17568* release: Release Management. (line 6) 17569* RST: RST. (line 6) 17570* Scheme: Scheme. (line 6) 17571* scheme-format flag: PO Files. (line 133) 17572* scripting languages: Language Implementors. 17573 (line 6) 17574* search messages in a catalog: msggrep Invocation. (line 8) 17575* selecting message language: Locale Environment Variables. 17576 (line 6) 17577* sentences: Preparing Strings. (line 44) 17578* setting up gettext at build time: Installers. (line 6) 17579* setting up gettext at run time: Locale Environment Variables. 17580 (line 6) 17581* several domains: Ambiguities. (line 6) 17582* sex: Introduction. (line 15) 17583* sh-format flag: PO Files. (line 113) 17584* she, he, and they: Introduction. (line 15) 17585* shell format string: envsubst Invocation. (line 8) 17586* shell scripts: sh. (line 6) 17587* Smalltalk: Smalltalk. (line 6) 17588* smalltalk-format flag: PO Files. (line 137) 17589* sorting msgcat output: msgcat Invocation. (line 146) 17590* sorting msgmerge output: msgmerge Invocation. (line 171) 17591* sorting msgunfmt output: msgunfmt Invocation. (line 144) 17592* sorting output of xgettext: xgettext Invocation. (line 317) 17593* specifying plural form in a PO file: Plural forms. (line 145) 17594* standard output, and msgcat: msgcat Invocation. (line 47) 17595* standard output, and msgmerge program: msgmerge Invocation. (line 56) 17596* string concatenation: Preparing Strings. (line 117) 17597* string normalization in entries: Normalizing. (line 6) 17598* style: Preparing Strings. (line 24) 17599* supported languages, xgettext: xgettext Invocation. (line 56) 17600* Tcl: Tcl. (line 6) 17601* Tcl mode, and msgfmt program: msgfmt Invocation. (line 43) 17602* Tcl mode, and msgunfmt program: msgunfmt Invocation. (line 26) 17603* tcl-format flag: PO Files. (line 161) 17604* template PO file: Overview. (line 67) 17605* testing .po files for equivalence: xgettext Invocation. (line 327) 17606* Tk's scripting language: Tcl. (line 6) 17607* translated entries: Translated Entries. (line 6) 17608* translating menu entries: Contexts. (line 6) 17609* translation aspects: Aspects. (line 6) 17610* Translation Matrix: Installing Localizations. 17611 (line 6) 17612* Translation Project: Why. (line 17) 17613* turning off NLS support: lib/gettext.h. (line 6) 17614* tutorial of gettext usage: Overview. (line 6) 17615* unify duplicate translations: msguniq Invocation. (line 8) 17616* untranslated entries: Untranslated Entries. 17617 (line 6) 17618* update translations from a compendium: Using Compendia. (line 20) 17619* upgrading to new versions of gettext: Prerequisites. (line 6) 17620* version control for backup files, msgmerge: msgmerge Invocation. 17621 (line 71) 17622* wxWidgets library: wxWidgets. (line 6) 17623* xargs, and output from msgexec: msgexec Invocation. (line 14) 17624* xgettext program, usage: xgettext Invocation. (line 6) 17625* xmodmap program, and typing quotation marks: Header Entry. (line 157) 17626* YaST2 scripting language: YCP. (line 6) 17627* YCP: YCP. (line 6) 17628* ycp-format flag: PO Files. (line 157) 17629 17630 17631 17632Tag Table: 17633Node: Top2956 17634Node: Introduction17210 17635Node: Why18833 17636Ref: Why-Footnote-122047 17637Node: Concepts22203 17638Node: Aspects25624 17639Node: Files32158 17640Node: Overview34067 17641Node: Users44003 17642Node: System Installation44914 17643Node: Setting the GUI Locale46606 17644Node: Setting the POSIX Locale47982 17645Node: Locale Names48921 17646Node: Locale Environment Variables51326 17647Node: The LANGUAGE variable53539 17648Node: Installing Localizations55439 17649Node: PO Files56794 17650Ref: PO Files-Footnote-168222 17651Node: Sources68349 17652Node: Importing69575 17653Node: Triggering70258 17654Node: Preparing Strings73458 17655Node: Mark Keywords82501 17656Node: Marking86814 17657Node: c-format Flag94544 17658Node: Special cases98463 17659Node: Bug Report Address101206 17660Node: Names103171 17661Node: Libraries106777 17662Node: Template109814 17663Node: xgettext Invocation110539 17664Node: Creating125664 17665Node: msginit Invocation126549 17666Node: Header Entry129175 17667Node: Updating136226 17668Node: msgmerge Invocation136441 17669Node: Editing141596 17670Node: KBabel141954 17671Node: Gtranslator142092 17672Node: PO Mode142234 17673Node: Installation143888 17674Node: Main PO Commands145852 17675Node: Entry Positioning150940 17676Node: Normalizing156408 17677Node: Translated Entries160902 17678Node: Fuzzy Entries162260 17679Node: Untranslated Entries165441 17680Node: Obsolete Entries167373 17681Node: Modifying Translations170598 17682Node: Modifying Comments178567 17683Node: Subedit182994 17684Node: C Sources Context186890 17685Node: Auxiliary192014 17686Node: Compendium195230 17687Node: Creating Compendia195845 17688Node: Using Compendia198329 17689Node: Manipulating199269 17690Node: msgcat Invocation203097 17691Node: msgconv Invocation207623 17692Node: msggrep Invocation210802 17693Node: msgfilter Invocation216686 17694Node: msguniq Invocation222594 17695Node: msgcomm Invocation226483 17696Node: msgcmp Invocation230528 17697Node: msgattrib Invocation232540 17698Node: msgen Invocation237225 17699Node: msgexec Invocation240560 17700Node: Colorizing243139 17701Node: The --color option244168 17702Node: The TERM variable245800 17703Node: The --style option247252 17704Node: Style rules248560 17705Node: Customizing less255302 17706Node: libgettextpo256705 17707Node: Binaries261821 17708Node: msgfmt Invocation262165 17709Node: msgunfmt Invocation269170 17710Node: MO Files273332 17711Node: Programmers281576 17712Node: catgets282758 17713Node: Interface to catgets284172 17714Node: Problems with catgets286181 17715Node: gettext287096 17716Node: Interface to gettext288599 17717Node: Ambiguities290929 17718Node: Locating Catalogs293644 17719Ref: Locating Catalogs-Footnote-1294874 17720Ref: Locating Catalogs-Footnote-2295100 17721Node: Charset conversion295249 17722Node: Contexts297703 17723Node: Plural forms303209 17724Ref: Plural forms-Footnote-1317408 17725Node: Optimized gettext317530 17726Node: Comparison318869 17727Node: Using libintl.a323139 17728Node: gettext grok323582 17729Node: Temp Programmers326223 17730Node: Temp Implementations326751 17731Node: Temp catgets328131 17732Node: Temp WSI329832 17733Node: Temp Notes331834 17734Node: Translators332337 17735Node: Trans Intro 0332800 17736Node: Trans Intro 1335549 17737Node: Discussions337513 17738Node: Organization341171 17739Node: Central Coordination343247 17740Node: National Teams344390 17741Node: Sub-Cultures346917 17742Node: Organizational Ideas347854 17743Node: Mailing Lists348875 17744Node: Information Flow350698 17745Node: Prioritizing messages352949 17746Node: Maintainers357248 17747Node: Flat and Non-Flat359204 17748Node: Prerequisites360697 17749Node: gettextize Invocation364854 17750Node: Adjusting Files372263 17751Node: po/POTFILES.in374050 17752Node: po/LINGUAS375299 17753Node: po/Makevars376991 17754Node: po/Rules-*377933 17755Node: configure.ac379404 17756Node: config.guess382418 17757Node: mkinstalldirs383773 17758Node: aclocal384178 17759Node: acconfig386162 17760Node: config.h.in386662 17761Node: Makefile388130 17762Node: src/Makefile390727 17763Node: lib/gettext.h395117 17764Node: autoconf macros397365 17765Node: AM_GNU_GETTEXT398207 17766Node: AM_GNU_GETTEXT_VERSION402172 17767Node: AM_GNU_GETTEXT_NEED402627 17768Node: AM_GNU_GETTEXT_INTL_SUBDIR403520 17769Node: AM_PO_SUBDIRS404175 17770Node: AM_XGETTEXT_OPTION404970 17771Node: AM_ICONV405840 17772Node: CVS Issues408055 17773Node: Distributed CVS408646 17774Node: Files under CVS410574 17775Node: autopoint Invocation413848 17776Node: Release Management415688 17777Node: Installers416201 17778Node: Programming Languages417428 17779Node: Language Implementors418254 17780Node: Programmers for other Languages423082 17781Node: Translators for other Languages423666 17782Node: c-format425246 17783Node: objc-format426965 17784Node: sh-format427320 17785Node: python-format428125 17786Node: lisp-format428566 17787Node: elisp-format428895 17788Node: librep-format429388 17789Node: scheme-format429791 17790Node: smalltalk-format430070 17791Node: java-format430573 17792Node: csharp-format431024 17793Node: awk-format431402 17794Node: object-pascal-format431730 17795Node: ycp-format431962 17796Node: tcl-format432364 17797Node: perl-format432662 17798Node: php-format433410 17799Node: gcc-internal-format433778 17800Node: qt-format434823 17801Node: kde-format435258 17802Node: boost-format435664 17803Node: Maintainers for other Languages436212 17804Node: List of Programming Languages437450 17805Node: C438733 17806Node: sh440033 17807Node: Preparing Shell Scripts441307 17808Node: gettext.sh444699 17809Node: gettext Invocation445249 17810Node: ngettext Invocation447004 17811Node: envsubst Invocation448592 17812Node: eval_gettext Invocation450013 17813Node: eval_ngettext Invocation450474 17814Node: bash450988 17815Node: Python452967 17816Node: Common Lisp454117 17817Node: clisp C454917 17818Node: Emacs Lisp455632 17819Node: librep456358 17820Node: Scheme457093 17821Node: Smalltalk457877 17822Node: Java458911 17823Node: C#464707 17824Node: gawk473933 17825Node: Pascal474845 17826Node: wxWidgets476153 17827Node: YCP477060 17828Node: Tcl477799 17829Node: Perl479209 17830Node: General Problems482217 17831Node: Default Keywords485878 17832Node: Special Keywords486833 17833Node: Quote-like Expressions488349 17834Node: Interpolation I490627 17835Node: Interpolation II494420 17836Node: Parentheses496788 17837Node: Long Lines498309 17838Node: Perl Pitfalls500157 17839Node: PHP504402 17840Node: Pike505333 17841Node: GCC-source505994 17842Node: List of Data Formats506741 17843Node: POT507210 17844Node: RST507468 17845Node: Glade507694 17846Node: Conclusion508054 17847Node: History508560 17848Node: References512830 17849Node: Language Codes514477 17850Node: Usual Language Codes514992 17851Node: Rare Language Codes519366 17852Node: Country Codes521026 17853Node: Licenses526915 17854Node: GNU GPL528760 17855Node: GNU LGPL547943 17856Node: GNU FDL576082 17857Node: Program Index598471 17858Node: Option Index600357 17859Node: Variable Index647235 17860Node: PO Mode Index650142 17861Node: Autoconf Macro Index663978 17862Node: Index664785 17863 17864End Tag Table 17865 17866 17867Local Variables: 17868coding: utf-8 17869End: 17870