1This is gettext.info, produced by makeinfo version 4.8 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-2006 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 59This manual documents the GNU gettext tools and the GNU libintl library, 60version 0.16.1. 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* Matrix:: The Current `ABOUT-NLS' Matrix 105* End Users:: Magic for End Users 106 107Preparing Program Sources 108 109* Importing:: Importing the `gettext' declaration 110* Triggering:: Triggering `gettext' Operations 111* Preparing Strings:: Preparing Translatable Strings 112* Mark Keywords:: How Marks Appear in Sources 113* Marking:: Marking Translatable Strings 114* c-format Flag:: Telling something about the following string 115* Special cases:: Special Cases of Translatable Strings 116* Names:: Marking Proper Names for Translation 117* Libraries:: Preparing Library Sources 118 119Making the PO Template File 120 121* xgettext Invocation:: Invoking the `xgettext' Program 122 123Creating a New PO File 124 125* msginit Invocation:: Invoking the `msginit' Program 126* Header Entry:: Filling in the Header Entry 127 128Updating Existing PO Files 129 130* msgmerge Invocation:: Invoking the `msgmerge' Program 131 132Editing PO Files 133 134* KBabel:: KDE's PO File Editor 135* Gtranslator:: GNOME's PO File Editor 136* PO Mode:: Emacs's PO File Editor 137 138Emacs's PO File Editor 139 140* Installation:: Completing GNU `gettext' Installation 141* Main PO Commands:: Main Commands 142* Entry Positioning:: Entry Positioning 143* Normalizing:: Normalizing Strings in Entries 144* Translated Entries:: Translated Entries 145* Fuzzy Entries:: Fuzzy Entries 146* Untranslated Entries:: Untranslated Entries 147* Obsolete Entries:: Obsolete Entries 148* Modifying Translations:: Modifying Translations 149* Modifying Comments:: Modifying Comments 150* Subedit:: Mode for Editing Translations 151* C Sources Context:: C Sources Context 152* Auxiliary:: Consulting Auxiliary PO Files 153* Compendium:: Using Translation Compendia 154 155Using Translation Compendia 156 157* Creating Compendia:: Merging translations for later use 158* Using Compendia:: Using older translations if they fit 159 160Manipulating PO Files 161 162* msgcat Invocation:: Invoking the `msgcat' Program 163* msgconv Invocation:: Invoking the `msgconv' Program 164* msggrep Invocation:: Invoking the `msggrep' Program 165* msgfilter Invocation:: Invoking the `msgfilter' Program 166* msguniq Invocation:: Invoking the `msguniq' Program 167* msgcomm Invocation:: Invoking the `msgcomm' Program 168* msgcmp Invocation:: Invoking the `msgcmp' Program 169* msgattrib Invocation:: Invoking the `msgattrib' Program 170* msgen Invocation:: Invoking the `msgen' Program 171* msgexec Invocation:: Invoking the `msgexec' Program 172* libgettextpo:: Writing your own programs that process PO files 173 174Producing Binary MO Files 175 176* msgfmt Invocation:: Invoking the `msgfmt' Program 177* msgunfmt Invocation:: Invoking the `msgunfmt' Program 178* MO Files:: The Format of GNU MO Files 179 180The Programmer's View 181 182* catgets:: About `catgets' 183* gettext:: About `gettext' 184* Comparison:: Comparing the two interfaces 185* Using libintl.a:: Using libintl.a in own programs 186* gettext grok:: Being a `gettext' grok 187* Temp Programmers:: Temporary Notes for the Programmers Chapter 188 189About `catgets' 190 191* Interface to catgets:: The interface 192* Problems with catgets:: Problems with the `catgets' interface?! 193 194About `gettext' 195 196* Interface to gettext:: The interface 197* Ambiguities:: Solving ambiguities 198* Locating Catalogs:: Locating message catalog files 199* Charset conversion:: How to request conversion to Unicode 200* Contexts:: Solving ambiguities in GUI programs 201* Plural forms:: Additional functions for handling plurals 202* Optimized gettext:: Optimization of the *gettext functions 203 204Temporary Notes for the Programmers Chapter 205 206* Temp Implementations:: Temporary - Two Possible Implementations 207* Temp catgets:: Temporary - About `catgets' 208* Temp WSI:: Temporary - Why a single implementation 209* Temp Notes:: Temporary - Notes 210 211The Translator's View 212 213* Trans Intro 0:: Introduction 0 214* Trans Intro 1:: Introduction 1 215* Discussions:: Discussions 216* Organization:: Organization 217* Information Flow:: Information Flow 218* Prioritizing messages:: How to find which messages to translate first 219 220Organization 221 222* Central Coordination:: Central Coordination 223* National Teams:: National Teams 224* Mailing Lists:: Mailing Lists 225 226National Teams 227 228* Sub-Cultures:: Sub-Cultures 229* Organizational Ideas:: Organizational Ideas 230 231The Maintainer's View 232 233* Flat and Non-Flat:: Flat or Non-Flat Directory Structures 234* Prerequisites:: Prerequisite Works 235* gettextize Invocation:: Invoking the `gettextize' Program 236* Adjusting Files:: Files You Must Create or Alter 237* autoconf macros:: Autoconf macros for use in `configure.in' 238* CVS Issues:: Integrating with CVS 239* Release Management:: Creating a Distribution Tarball 240 241Files You Must Create or Alter 242 243* po/POTFILES.in:: `POTFILES.in' in `po/' 244* po/LINGUAS:: `LINGUAS' in `po/' 245* po/Makevars:: `Makevars' in `po/' 246* po/Rules-*:: Extending `Makefile' in `po/' 247* configure.in:: `configure.in' at top level 248* config.guess:: `config.guess', `config.sub' at top level 249* mkinstalldirs:: `mkinstalldirs' at top level 250* aclocal:: `aclocal.m4' at top level 251* acconfig:: `acconfig.h' at top level 252* config.h.in:: `config.h.in' at top level 253* Makefile:: `Makefile.in' at top level 254* src/Makefile:: `Makefile.in' in `src/' 255* lib/gettext.h:: `gettext.h' in `lib/' 256 257Autoconf macros for use in `configure.in' 258 259* AM_GNU_GETTEXT:: AM_GNU_GETTEXT in `gettext.m4' 260* AM_GNU_GETTEXT_VERSION:: AM_GNU_GETTEXT_VERSION in `gettext.m4' 261* AM_GNU_GETTEXT_NEED:: AM_GNU_GETTEXT_NEED in `gettext.m4' 262* AM_GNU_GETTEXT_INTL_SUBDIR:: AM_GNU_GETTEXT_INTL_SUBDIR in `intldir.m4' 263* AM_PO_SUBDIRS:: AM_PO_SUBDIRS in `po.m4' 264* AM_ICONV:: AM_ICONV in `iconv.m4' 265 266Integrating with CVS 267 268* Distributed CVS:: Avoiding version mismatch in distributed development 269* Files under CVS:: Files to put under CVS version control 270* autopoint Invocation:: Invoking the `autopoint' Program 271 272Other Programming Languages 273 274* Language Implementors:: The Language Implementor's View 275* Programmers for other Languages:: The Programmer's View 276* Translators for other Languages:: The Translator's View 277* Maintainers for other Languages:: The Maintainer's View 278* List of Programming Languages:: Individual Programming Languages 279* List of Data Formats:: Internationalizable Data 280 281The Translator's View 282 283* c-format:: C Format Strings 284* objc-format:: Objective C Format Strings 285* sh-format:: Shell Format Strings 286* python-format:: Python Format Strings 287* lisp-format:: Lisp Format Strings 288* elisp-format:: Emacs Lisp Format Strings 289* librep-format:: librep Format Strings 290* scheme-format:: Scheme Format Strings 291* smalltalk-format:: Smalltalk Format Strings 292* java-format:: Java Format Strings 293* csharp-format:: C# Format Strings 294* awk-format:: awk Format Strings 295* object-pascal-format:: Object Pascal Format Strings 296* ycp-format:: YCP Format Strings 297* tcl-format:: Tcl Format Strings 298* perl-format:: Perl Format Strings 299* php-format:: PHP Format Strings 300* gcc-internal-format:: GCC internal Format Strings 301* qt-format:: Qt Format Strings 302* boost-format:: Boost Format Strings 303 304Individual Programming Languages 305 306* C:: C, C++, Objective C 307* sh:: sh - Shell Script 308* bash:: bash - Bourne-Again Shell Script 309* Python:: Python 310* Common Lisp:: GNU clisp - Common Lisp 311* clisp C:: GNU clisp C sources 312* Emacs Lisp:: Emacs Lisp 313* librep:: librep 314* Scheme:: GNU guile - Scheme 315* Smalltalk:: GNU Smalltalk 316* Java:: Java 317* C#:: C# 318* gawk:: GNU awk 319* Pascal:: Pascal - Free Pascal Compiler 320* wxWidgets:: wxWidgets library 321* YCP:: YCP - YaST2 scripting language 322* Tcl:: Tcl - Tk's scripting language 323* Perl:: Perl 324* PHP:: PHP Hypertext Preprocessor 325* Pike:: Pike 326* GCC-source:: GNU Compiler Collection sources 327 328sh - Shell Script 329 330* Preparing Shell Scripts:: Preparing Shell Scripts for Internationalization 331* gettext.sh:: Contents of `gettext.sh' 332* gettext Invocation:: Invoking the `gettext' program 333* ngettext Invocation:: Invoking the `ngettext' program 334* envsubst Invocation:: Invoking the `envsubst' program 335* eval_gettext Invocation:: Invoking the `eval_gettext' function 336* eval_ngettext Invocation:: Invoking the `eval_ngettext' function 337 338Perl 339 340* General Problems:: General Problems Parsing Perl Code 341* Default Keywords:: Which Keywords Will xgettext Look For? 342* Special Keywords:: How to Extract Hash Keys 343* Quote-like Expressions:: What are Strings And Quote-like Expressions? 344* Interpolation I:: Invalid String Interpolation 345* Interpolation II:: Valid String Interpolation 346* Parentheses:: When To Use Parentheses 347* Long Lines:: How To Grok with Long Lines 348* Perl Pitfalls:: Bugs, Pitfalls, and Things That Do Not Work 349 350Internationalizable Data 351 352* POT:: POT - Portable Object Template 353* RST:: Resource String Table 354* Glade:: Glade - GNOME user interface description 355 356Concluding Remarks 357 358* History:: History of GNU `gettext' 359* References:: Related Readings 360 361Language Codes 362 363* Usual Language Codes:: Two-letter ISO 639 language codes 364* Rare Language Codes:: Three-letter ISO 639 language codes 365 366Licenses 367 368* GNU GPL:: GNU General Public License 369* GNU LGPL:: GNU Lesser General Public License 370* GNU FDL:: GNU Free Documentation License 371 372 373File: gettext.info, Node: Introduction, Next: Users, Prev: Top, Up: Top 374 3751 Introduction 376************** 377 378This chapter explains the goals sought in the creation of GNU `gettext' 379and the free Translation Project. Then, it explains a few broad 380concepts around Native Language Support, and positions message 381translation with regard to other aspects of national and cultural 382variance, as they apply to programs. It also surveys those files used 383to convey the translations. It explains how the various tools interact 384in the initial generation of these files, and later, how the maintenance 385cycle should usually operate. 386 387 In this manual, we use _he_ when speaking of the programmer or 388maintainer, _she_ when speaking of the translator, and _they_ when 389speaking of the installers or end users of the translated program. 390This is only a convenience for clarifying the documentation. It is 391_absolutely_ not meant to imply that some roles are more appropriate to 392males or females. Besides, as you might guess, GNU `gettext' is meant 393to be useful for people using computers, whatever their sex, race, 394religion or nationality! 395 396 Please send suggestions and corrections to: 397 398 Internet address: 399 bug-gnu-gettext@gnu.org 400 401Please include the manual's edition number and update date in your 402messages. 403 404* Menu: 405 406* Why:: The Purpose of GNU `gettext' 407* Concepts:: I18n, L10n, and Such 408* Aspects:: Aspects in Native Language Support 409* Files:: Files Conveying Translations 410* Overview:: Overview of GNU `gettext' 411 412 413File: gettext.info, Node: Why, Next: Concepts, Prev: Introduction, Up: Introduction 414 4151.1 The Purpose of GNU `gettext' 416================================ 417 418Usually, programs are written and documented in English, and use 419English at execution time to interact with users. This is true not 420only of GNU software, but also of a great deal of commercial and free 421software. Using a common language is quite handy for communication 422between developers, maintainers and users from all countries. On the 423other hand, most people are less comfortable with English than with 424their own native language, and would prefer to use their mother tongue 425for day to day's work, as far as possible. Many would simply _love_ to 426see their computer screen showing a lot less of English, and far more 427of their own language. 428 429 However, to many people, this dream might appear so far fetched that 430they may believe it is not even worth spending time thinking about it. 431They have no confidence at all that the dream might ever become true. 432Yet some have not lost hope, and have organized themselves. The 433Translation Project is a formalization of this hope into a workable 434structure, which has a good chance to get all of us nearer the 435achievement of a truly multi-lingual set of programs. 436 437 GNU `gettext' is an important step for the Translation Project, as 438it is an asset on which we may build many other steps. This package 439offers to programmers, translators and even users, a well integrated 440set of tools and documentation. Specifically, the GNU `gettext' 441utilities are a set of tools that provides a framework within which 442other free packages may produce multi-lingual messages. These tools 443include 444 445 * A set of conventions about how programs should be written to 446 support message catalogs. 447 448 * A directory and file naming organization for the message catalogs 449 themselves. 450 451 * A runtime library supporting the retrieval of translated messages. 452 453 * A few stand-alone programs to massage in various ways the sets of 454 translatable strings, or already translated strings. 455 456 * A library supporting the parsing and creation of files containing 457 translated messages. 458 459 * A special mode for Emacs(1) which helps preparing these sets and 460 bringing them up to date. 461 462 GNU `gettext' is designed to minimize the impact of 463internationalization on program sources, keeping this impact as small 464and hardly noticeable as possible. Internationalization has better 465chances of succeeding if it is very light weighted, or at least, appear 466to be so, when looking at program sources. 467 468 The Translation Project also uses the GNU `gettext' distribution as 469a vehicle for documenting its structure and methods. This goes beyond 470the strict technicalities of documenting the GNU `gettext' proper. By 471so doing, translators will find in a single place, as far as possible, 472all they need to know for properly doing their translating work. Also, 473this supplemental documentation might also help programmers, and even 474curious users, in understanding how GNU `gettext' is related to the 475remainder of the Translation Project, and consequently, have a glimpse 476at the _big picture_. 477 478 ---------- Footnotes ---------- 479 480 (1) In this manual, all mentions of Emacs refers to either GNU Emacs 481or to XEmacs, which people sometimes call FSF Emacs and Lucid Emacs, 482respectively. 483 484 485File: gettext.info, Node: Concepts, Next: Aspects, Prev: Why, Up: Introduction 486 4871.2 I18n, L10n, and Such 488======================== 489 490Two long words appear all the time when we discuss support of native 491language in programs, and these words have a precise meaning, worth 492being explained here, once and for all in this document. The words are 493_internationalization_ and _localization_. Many people, tired of 494writing these long words over and over again, took the habit of writing 495"i18n" and "l10n" instead, quoting the first and last letter of each 496word, and replacing the run of intermediate letters by a number merely 497telling how many such letters there are. But in this manual, in the 498sake of clarity, we will patiently write the names in full, each time... 499 500 By "internationalization", one refers to the operation by which a 501program, or a set of programs turned into a package, is made aware of 502and able to support multiple languages. This is a generalization 503process, by which the programs are untied from calling only English 504strings or other English specific habits, and connected to generic ways 505of doing the same, instead. Program developers may use various 506techniques to internationalize their programs. Some of these have been 507standardized. GNU `gettext' offers one of these standards. *Note 508Programmers::. 509 510 By "localization", one means the operation by which, in a set of 511programs already internationalized, one gives the program all needed 512information so that it can adapt itself to handle its input and output 513in a fashion which is correct for some native language and cultural 514habits. This is a particularisation process, by which generic methods 515already implemented in an internationalized program are used in 516specific ways. The programming environment puts several functions to 517the programmers disposal which allow this runtime configuration. The 518formal description of specific set of cultural habits for some country, 519together with all associated translations targeted to the same native 520language, is called the "locale" for this language or country. Users 521achieve localization of programs by setting proper values to special 522environment variables, prior to executing those programs, identifying 523which locale should be used. 524 525 In fact, locale message support is only one component of the cultural 526data that makes up a particular locale. There are a whole host of 527routines and functions provided to aid programmers in developing 528internationalized software and which allow them to access the data 529stored in a particular locale. When someone presently refers to a 530particular locale, they are obviously referring to the data stored 531within that particular locale. Similarly, if a programmer is referring 532to "accessing the locale routines", they are referring to the complete 533suite of routines that access all of the locale's information. 534 535 One uses the expression "Native Language Support", or merely NLS, 536for speaking of the overall activity or feature encompassing both 537internationalization and localization, allowing for multi-lingual 538interactions in a program. In a nutshell, one could say that 539internationalization is the operation by which further localizations 540are made possible. 541 542 Also, very roughly said, when it comes to multi-lingual messages, 543internationalization is usually taken care of by programmers, and 544localization is usually taken care of by translators. 545 546 547File: gettext.info, Node: Aspects, Next: Files, Prev: Concepts, Up: Introduction 548 5491.3 Aspects in Native Language Support 550====================================== 551 552For a totally multi-lingual distribution, there are many things to 553translate beyond output messages. 554 555 * As of today, GNU `gettext' offers a complete toolset for 556 translating messages output by C programs. Perl scripts and shell 557 scripts will also need to be translated. Even if there are today 558 some hooks by which this can be done, these hooks are not 559 integrated as well as they should be. 560 561 * Some programs, like `autoconf' or `bison', are able to produce 562 other programs (or scripts). Even if the generating programs 563 themselves are internationalized, the generated programs they 564 produce may need internationalization on their own, and this 565 indirect internationalization could be automated right from the 566 generating program. In fact, quite usually, generating and 567 generated programs could be internationalized independently, as 568 the effort needed is fairly orthogonal. 569 570 * A few programs include textual tables which might need translation 571 themselves, independently of the strings contained in the program 572 itself. For example, RFC 1345 gives an English description for 573 each character which the `recode' program is able to reconstruct 574 at execution. Since these descriptions are extracted from the RFC 575 by mechanical means, translating them properly would require a 576 prior translation of the RFC itself. 577 578 * Almost all programs accept options, which are often worded out so 579 to be descriptive for the English readers; one might want to 580 consider offering translated versions for program options as well. 581 582 * Many programs read, interpret, compile, or are somewhat driven by 583 input files which are texts containing keywords, identifiers, or 584 replies which are inherently translatable. For example, one may 585 want `gcc' to allow diacriticized characters in identifiers or use 586 translated keywords; `rm -i' might accept something else than `y' 587 or `n' for replies, etc. Even if the program will eventually make 588 most of its output in the foreign languages, one has to decide 589 whether the input syntax, option values, etc., are to be localized 590 or not. 591 592 * The manual accompanying a package, as well as all documentation 593 files in the distribution, could surely be translated, too. 594 Translating a manual, with the intent of later keeping up with 595 updates, is a major undertaking in itself, generally. 596 597 598 As we already stressed, translation is only one aspect of locales. 599Other internationalization aspects are system services and are handled 600in GNU `libc'. There are many attributes that are needed to define a 601country's cultural conventions. These attributes include beside the 602country's native language, the formatting of the date and time, the 603representation of numbers, the symbols for currency, etc. These local 604"rules" are termed the country's locale. The locale represents the 605knowledge needed to support the country's native attributes. 606 607 There are a few major areas which may vary between countries and 608hence, define what a locale must describe. The following list helps 609putting multi-lingual messages into the proper context of other tasks 610related to locales. See the GNU `libc' manual for details. 611 612_Characters and Codesets_ 613 The codeset most commonly used through out the USA and most English 614 speaking parts of the world is the ASCII codeset. However, there 615 are many characters needed by various locales that are not found 616 within this codeset. The 8-bit ISO 8859-1 code set has most of 617 the special characters needed to handle the major European 618 languages. However, in many cases, choosing ISO 8859-1 is 619 nevertheless not adequate: it doesn't even handle the major 620 European currency. Hence each locale will need to specify which 621 codeset they need to use and will need to have the appropriate 622 character handling routines to cope with the codeset. 623 624_Currency_ 625 The symbols used vary from country to country as does the position 626 used by the symbol. Software needs to be able to transparently 627 display currency figures in the native mode for each locale. 628 629_Dates_ 630 The format of date varies between locales. For example, Christmas 631 day in 1994 is written as 12/25/94 in the USA and as 25/12/94 in 632 Australia. Other countries might use ISO 8601 dates, etc. 633 634 Time of the day may be noted as HH:MM, HH.MM, or otherwise. Some 635 locales require time to be specified in 24-hour mode rather than 636 as AM or PM. Further, the nature and yearly extent of the 637 Daylight Saving correction vary widely between countries. 638 639_Numbers_ 640 Numbers can be represented differently in different locales. For 641 example, the following numbers are all written correctly for their 642 respective locales: 643 644 12,345.67 English 645 12.345,67 German 646 12345,67 French 647 1,2345.67 Asia 648 649 Some programs could go further and use different unit systems, like 650 English units or Metric units, or even take into account variants 651 about how numbers are spelled in full. 652 653_Messages_ 654 The most obvious area is the language support within a locale. 655 This is where GNU `gettext' provides the means for developers and 656 users to easily change the language that the software uses to 657 communicate to the user. 658 659 660 Components of locale outside of message handling are standardized in 661the ISO C standard and the SUSV2 specification. GNU `libc' fully 662implements this, and most other modern systems provide a more or less 663reasonable support for at least some of the missing components. 664 665 666File: gettext.info, Node: Files, Next: Overview, Prev: Aspects, Up: Introduction 667 6681.4 Files Conveying Translations 669================================ 670 671The letters PO in `.po' files means Portable Object, to distinguish it 672from `.mo' files, where MO stands for Machine Object. This paradigm, 673as well as the PO file format, is inspired by the NLS standard 674developed by Uniforum, and first implemented by Sun in their Solaris 675system. 676 677 PO files are meant to be read and edited by humans, and associate 678each original, translatable string of a given package with its 679translation in a particular target language. A single PO file is 680dedicated to a single target language. If a package supports many 681languages, there is one such PO file per language supported, and each 682package has its own set of PO files. These PO files are best created by 683the `xgettext' program, and later updated or refreshed through the 684`msgmerge' program. Program `xgettext' extracts all marked messages 685from a set of C files and initializes a PO file with empty 686translations. Program `msgmerge' takes care of adjusting PO files 687between releases of the corresponding sources, commenting obsolete 688entries, initializing new ones, and updating all source line 689references. Files ending with `.pot' are kind of base translation 690files found in distributions, in PO file format. 691 692 MO files are meant to be read by programs, and are binary in nature. 693A few systems already offer tools for creating and handling MO files as 694part of the Native Language Support coming with the system, but the 695format of these MO files is often different from system to system, and 696non-portable. The tools already provided with these systems don't 697support all the features of GNU `gettext'. Therefore GNU `gettext' 698uses its own format for MO files. Files ending with `.gmo' are really 699MO files, when it is known that these files use the GNU format. 700 701 702File: gettext.info, Node: Overview, Prev: Files, Up: Introduction 703 7041.5 Overview of GNU `gettext' 705============================= 706 707The following diagram summarizes the relation between the files handled 708by GNU `gettext' and the tools acting on these files. It is followed 709by somewhat detailed explanations, which you should read while keeping 710an eye on the diagram. Having a clear understanding of these 711interrelations will surely help programmers, translators and 712maintainers. 713 714 Original C Sources ---> Preparation ---> Marked C Sources ---. 715 | 716 .---------<--- GNU gettext Library | 717 .--- make <---+ | 718 | `---------<--------------------+---------------' 719 | | 720 | .-----<--- PACKAGE.pot <--- xgettext <---' .---<--- PO Compendium 721 | | | ^ 722 | | `---. | 723 | `---. +---> PO editor ---. 724 | +----> msgmerge ------> LANG.po ---->--------' | 725 | .---' | 726 | | | 727 | `-------------<---------------. | 728 | +--- New LANG.po <--------------------' 729 | .--- LANG.gmo <--- msgfmt <---' 730 | | 731 | `---> install ---> /.../LANG/PACKAGE.mo ---. 732 | +---> "Hello world!" 733 `-------> install ---> /.../bin/PROGRAM -------' 734 735 As a programmer, the first step to bringing GNU `gettext' into your 736package is identifying, right in the C sources, those strings which are 737meant to be translatable, and those which are untranslatable. This 738tedious job can be done a little more comfortably using emacs PO mode, 739but you can use any means familiar to you for modifying your C sources. 740Beside this some other simple, standard changes are needed to properly 741initialize the translation library. *Note Sources::, for more 742information about all this. 743 744 For newly written software the strings of course can and should be 745marked while writing it. The `gettext' approach makes this very easy. 746Simply put the following lines at the beginning of each file or in a 747central header file: 748 749 #define _(String) (String) 750 #define N_(String) String 751 #define textdomain(Domain) 752 #define bindtextdomain(Package, Directory) 753 754Doing this allows you to prepare the sources for internationalization. 755Later when you feel ready for the step to use the `gettext' library 756simply replace these definitions by the following: 757 758 #include <libintl.h> 759 #define _(String) gettext (String) 760 #define gettext_noop(String) String 761 #define N_(String) gettext_noop (String) 762 763and link against `libintl.a' or `libintl.so'. Note that on GNU 764systems, you don't need to link with `libintl' because the `gettext' 765library functions are already contained in GNU libc. That is all you 766have to change. 767 768 Once the C sources have been modified, the `xgettext' program is 769used to find and extract all translatable strings, and create a PO 770template file out of all these. This `PACKAGE.pot' file contains all 771original program strings. It has sets of pointers to exactly where in 772C sources each string is used. All translations are set to empty. The 773letter `t' in `.pot' marks this as a Template PO file, not yet oriented 774towards any particular language. *Note xgettext Invocation::, for more 775details about how one calls the `xgettext' program. If you are 776_really_ lazy, you might be interested at working a lot more right 777away, and preparing the whole distribution setup (*note Maintainers::). 778By doing so, you spare yourself typing the `xgettext' command, as 779`make' should now generate the proper things automatically for you! 780 781 The first time through, there is no `LANG.po' yet, so the `msgmerge' 782step may be skipped and replaced by a mere copy of `PACKAGE.pot' to 783`LANG.po', where LANG represents the target language. See *Note 784Creating:: for details. 785 786 Then comes the initial translation of messages. Translation in 787itself is a whole matter, still exclusively meant for humans, and whose 788complexity far overwhelms the level of this manual. Nevertheless, a 789few hints are given in some other chapter of this manual (*note 790Translators::). You will also find there indications about how to 791contact translating teams, or becoming part of them, for sharing your 792translating concerns with others who target the same native language. 793 794 While adding the translated messages into the `LANG.po' PO file, if 795you are not using one of the dedicated PO file editors (*note 796Editing::), you are on your own for ensuring that your efforts fully 797respect the PO file format, and quoting conventions (*note PO Files::). 798This is surely not an impossible task, as this is the way many people 799have handled PO files around 1995. On the other hand, by using a PO 800file editor, most details of PO file format are taken care of for you, 801but you have to acquire some familiarity with PO file editor itself. 802 803 If some common translations have already been saved into a compendium 804PO file, translators may use PO mode for initializing untranslated 805entries from the compendium, and also save selected translations into 806the compendium, updating it (*note Compendium::). Compendium files are 807meant to be exchanged between members of a given translation team. 808 809 Programs, or packages of programs, are dynamic in nature: users write 810bug reports and suggestion for improvements, maintainers react by 811modifying programs in various ways. The fact that a package has 812already been internationalized should not make maintainers shy of 813adding new strings, or modifying strings already translated. They just 814do their job the best they can. For the Translation Project to work 815smoothly, it is important that maintainers do not carry translation 816concerns on their already loaded shoulders, and that translators be 817kept as free as possible of programming concerns. 818 819 The only concern maintainers should have is carefully marking new 820strings as translatable, when they should be, and do not otherwise 821worry about them being translated, as this will come in proper time. 822Consequently, when programs and their strings are adjusted in various 823ways by maintainers, and for matters usually unrelated to translation, 824`xgettext' would construct `PACKAGE.pot' files which are evolving over 825time, so the translations carried by `LANG.po' are slowly fading out of 826date. 827 828 It is important for translators (and even maintainers) to understand 829that package translation is a continuous process in the lifetime of a 830package, and not something which is done once and for all at the start. 831After an initial burst of translation activity for a given package, 832interventions are needed once in a while, because here and there, 833translated entries become obsolete, and new untranslated entries 834appear, needing translation. 835 836 The `msgmerge' program has the purpose of refreshing an already 837existing `LANG.po' file, by comparing it with a newer `PACKAGE.pot' 838template file, extracted by `xgettext' out of recent C sources. The 839refreshing operation adjusts all references to C source locations for 840strings, since these strings move as programs are modified. Also, 841`msgmerge' comments out as obsolete, in `LANG.po', those already 842translated entries which are no longer used in the program sources 843(*note Obsolete Entries::). It finally discovers new strings and 844inserts them in the resulting PO file as untranslated entries (*note 845Untranslated Entries::). *Note msgmerge Invocation::, for more 846information about what `msgmerge' really does. 847 848 Whatever route or means taken, the goal is to obtain an updated 849`LANG.po' file offering translations for all strings. 850 851 The temporal mobility, or fluidity of PO files, is an integral part 852of the translation game, and should be well understood, and accepted. 853People resisting it will have a hard time participating in the 854Translation Project, or will give a hard time to other participants! In 855particular, maintainers should relax and include all available official 856PO files in their distributions, even if these have not recently been 857updated, without exerting pressure on the translator teams to get the 858job done. The pressure should rather come from the community of users 859speaking a particular language, and maintainers should consider 860themselves fairly relieved of any concern about the adequacy of 861translation files. On the other hand, translators should reasonably 862try updating the PO files they are responsible for, while the package 863is undergoing pretest, prior to an official distribution. 864 865 Once the PO file is complete and dependable, the `msgfmt' program is 866used for turning the PO file into a machine-oriented format, which may 867yield efficient retrieval of translations by the programs of the 868package, whenever needed at runtime (*note MO Files::). *Note msgfmt 869Invocation::, for more information about all modes of execution for the 870`msgfmt' program. 871 872 Finally, the modified and marked C sources are compiled and linked 873with the GNU `gettext' library, usually through the operation of 874`make', given a suitable `Makefile' exists for the project, and the 875resulting executable is installed somewhere users will find it. The MO 876files themselves should also be properly installed. Given the 877appropriate environment variables are set (*note End Users::), the 878program should localize itself automatically, whenever it executes. 879 880 The remainder of this manual has the purpose of explaining in depth 881the various steps outlined above. 882 883 884File: gettext.info, Node: Users, Next: PO Files, Prev: Introduction, Up: Top 885 8862 The User's View 887***************** 888 889When GNU `gettext' will truly have reached its goal, average users 890should feel some kind of astonished pleasure, seeing the effect of that 891strange kind of magic that just makes their own native language appear 892everywhere on their screens. As for naive users, they would ideally 893have no special pleasure about it, merely taking their own language for 894_granted_, and becoming rather unhappy otherwise. 895 896 So, let's try to describe here how we would like the magic to 897operate, as we want the users' view to be the simplest, among all ways 898one could look at GNU `gettext'. All other software engineers: 899programmers, translators, maintainers, should work together in such a 900way that the magic becomes possible. This is a long and progressive 901undertaking, and information is available about the progress of the 902Translation Project. 903 904 When a package is distributed, there are two kinds of users: 905"installers" who fetch the distribution, unpack it, configure it, 906compile it and install it for themselves or others to use; and "end 907users" that call programs of the package, once these have been 908installed at their site. GNU `gettext' is offering magic for both 909installers and end users. 910 911* Menu: 912 913* Matrix:: The Current `ABOUT-NLS' Matrix 914* End Users:: Magic for End Users 915 916 917File: gettext.info, Node: Matrix, Next: End Users, Prev: Users, Up: Users 918 9192.1 The Current `ABOUT-NLS' Matrix 920================================== 921 922Languages are not equally supported in all packages using GNU 923`gettext'. To know if some package uses GNU `gettext', one may check 924the distribution for the `ABOUT-NLS' information file, for some `LL.po' 925files, often kept together into some `po/' directory, or for an `intl/' 926directory. Internationalized packages have usually many `LL.po' files, 927where LL represents the language. *Note End Users:: for a complete 928description of the format for LL. 929 930 More generally, a matrix is available for showing the current state 931of the Translation Project, listing which packages are prepared for 932multi-lingual messages, and which languages are supported by each. 933Because this information changes often, this matrix is not kept within 934this GNU `gettext' manual. This information is often found in file 935`ABOUT-NLS' from various distributions, but is also as old as the 936distribution itself. A recent copy of this `ABOUT-NLS' file, 937containing up-to-date information, should generally be found on the 938Translation Project sites, and also on most GNU archive sites. 939 940 941File: gettext.info, Node: End Users, Prev: Matrix, Up: Users 942 9432.2 Magic for End Users 944======================= 945 946We consider here those packages using GNU `gettext' internally, and for 947which the installers did not disable translation at _configure_ time. 948Then, users only have to set the `LANG' environment variable to the 949appropriate `LL_CC' combination prior to using the programs in the 950package. *Note Matrix::. For example, let's presume a German site. 951At the shell prompt, users merely have to execute `setenv LANG de_DE' 952(in `csh') or `export LANG; LANG=de_DE' (in `sh'). They could even do 953this from their `.login' or `.profile' file. 954 955 956File: gettext.info, Node: PO Files, Next: Sources, Prev: Users, Up: Top 957 9583 The Format of PO Files 959************************ 960 961The GNU `gettext' toolset helps programmers and translators at 962producing, updating and using translation files, mainly those PO files 963which are textual, editable files. This chapter explains the format of 964PO files. 965 966 A PO file is made up of many entries, each entry holding the relation 967between an original untranslated string and its corresponding 968translation. All entries in a given PO file usually pertain to a 969single project, and all translations are expressed in a single target 970language. One PO file "entry" has the following schematic structure: 971 972 WHITE-SPACE 973 # TRANSLATOR-COMMENTS 974 #. EXTRACTED-COMMENTS 975 #: REFERENCE... 976 #, FLAG... 977 #| msgid PREVIOUS-UNTRANSLATED-STRING 978 msgid UNTRANSLATED-STRING 979 msgstr TRANSLATED-STRING 980 981 The general structure of a PO file should be well understood by the 982translator. When using PO mode, very little has to be known about the 983format details, as PO mode takes care of them for her. 984 985 A simple entry can look like this: 986 987 #: lib/error.c:116 988 msgid "Unknown system error" 989 msgstr "Error desconegut del sistema" 990 991 Entries begin with some optional white space. Usually, when 992generated through GNU `gettext' tools, there is exactly one blank line 993between entries. Then comments follow, on lines all starting with the 994character `#'. There are two kinds of comments: those which have some 995white space immediately following the `#' - the TRANSLATOR COMMENTS -, 996which comments are created and maintained exclusively by the 997translator, and those which have some non-white character just after the 998`#' - the AUTOMATIC COMMENTS -, which comments are created and 999maintained automatically by GNU `gettext' tools. Comment lines 1000starting with `#.' contain comments given by the programmer, directed 1001at the translator; these comments are called EXTRACTED COMMENTS because 1002the `xgettext' program extracts them from the program's source code. 1003Comment lines starting with `#:' contain references to the program's 1004source code. Comment lines starting with `#,' contain flags; more 1005about these below. Comment lines starting with `#|' contain the 1006previous untranslated string for which the translator gave a 1007translation. 1008 1009 All comments, of either kind, are optional. 1010 1011 After white space and comments, entries show two strings, namely 1012first the untranslated string as it appears in the original program 1013sources, and then, the translation of this string. The original string 1014is introduced by the keyword `msgid', and the translation, by `msgstr'. 1015The two strings, untranslated and translated, are quoted in various 1016ways in the PO file, using `"' delimiters and `\' escapes, but the 1017translator does not really have to pay attention to the precise quoting 1018format, as PO mode fully takes care of quoting for her. 1019 1020 The `msgid' strings, as well as automatic comments, are produced and 1021managed by other GNU `gettext' tools, and PO mode does not provide 1022means for the translator to alter these. The most she can do is merely 1023deleting them, and only by deleting the whole entry. On the other 1024hand, the `msgstr' string, as well as translator comments, are really 1025meant for the translator, and PO mode gives her the full control she 1026needs. 1027 1028 The comment lines beginning with `#,' are special because they are 1029not completely ignored by the programs as comments generally are. The 1030comma separated list of FLAGs is used by the `msgfmt' program to give 1031the user some better diagnostic messages. Currently there are two 1032forms of flags defined: 1033 1034`fuzzy' 1035 This flag can be generated by the `msgmerge' program or it can be 1036 inserted by the translator herself. It shows that the `msgstr' 1037 string might not be a correct translation (anymore). Only the 1038 translator can judge if the translation requires further 1039 modification, or is acceptable as is. Once satisfied with the 1040 translation, she then removes this `fuzzy' attribute. The 1041 `msgmerge' program inserts this when it combined the `msgid' and 1042 `msgstr' entries after fuzzy search only. *Note Fuzzy Entries::. 1043 1044`c-format' 1045`no-c-format' 1046 These flags should not be added by a human. Instead only the 1047 `xgettext' program adds them. In an automated PO file processing 1048 system as proposed here the user changes would be thrown away 1049 again as soon as the `xgettext' program generates a new template 1050 file. 1051 1052 The `c-format' flag tells that the untranslated string and the 1053 translation are supposed to be C format strings. The `no-c-format' 1054 flag tells that they are not C format strings, even though the 1055 untranslated string happens to look like a C format string (with 1056 `%' directives). 1057 1058 In case the `c-format' flag is given for a string the `msgfmt' 1059 does some more tests to check to validity of the translation. 1060 *Note msgfmt Invocation::, *Note c-format Flag:: and *Note 1061 c-format::. 1062 1063`objc-format' 1064`no-objc-format' 1065 Likewise for Objective C, see *Note objc-format::. 1066 1067`sh-format' 1068`no-sh-format' 1069 Likewise for Shell, see *Note sh-format::. 1070 1071`python-format' 1072`no-python-format' 1073 Likewise for Python, see *Note python-format::. 1074 1075`lisp-format' 1076`no-lisp-format' 1077 Likewise for Lisp, see *Note lisp-format::. 1078 1079`elisp-format' 1080`no-elisp-format' 1081 Likewise for Emacs Lisp, see *Note elisp-format::. 1082 1083`librep-format' 1084`no-librep-format' 1085 Likewise for librep, see *Note librep-format::. 1086 1087`scheme-format' 1088`no-scheme-format' 1089 Likewise for Scheme, see *Note scheme-format::. 1090 1091`smalltalk-format' 1092`no-smalltalk-format' 1093 Likewise for Smalltalk, see *Note smalltalk-format::. 1094 1095`java-format' 1096`no-java-format' 1097 Likewise for Java, see *Note java-format::. 1098 1099`csharp-format' 1100`no-csharp-format' 1101 Likewise for C#, see *Note csharp-format::. 1102 1103`awk-format' 1104`no-awk-format' 1105 Likewise for awk, see *Note awk-format::. 1106 1107`object-pascal-format' 1108`no-object-pascal-format' 1109 Likewise for Object Pascal, see *Note object-pascal-format::. 1110 1111`ycp-format' 1112`no-ycp-format' 1113 Likewise for YCP, see *Note ycp-format::. 1114 1115`tcl-format' 1116`no-tcl-format' 1117 Likewise for Tcl, see *Note tcl-format::. 1118 1119`perl-format' 1120`no-perl-format' 1121 Likewise for Perl, see *Note perl-format::. 1122 1123`perl-brace-format' 1124`no-perl-brace-format' 1125 Likewise for Perl brace, see *Note perl-format::. 1126 1127`php-format' 1128`no-php-format' 1129 Likewise for PHP, see *Note php-format::. 1130 1131`gcc-internal-format' 1132`no-gcc-internal-format' 1133 Likewise for the GCC sources, see *Note gcc-internal-format::. 1134 1135`qt-format' 1136`no-qt-format' 1137 Likewise for Qt, see *Note qt-format::. 1138 1139`boost-format' 1140`no-boost-format' 1141 Likewise for Boost, see *Note boost-format::. 1142 1143 1144 It is also possible to have entries with a context specifier. They 1145look like this: 1146 1147 WHITE-SPACE 1148 # TRANSLATOR-COMMENTS 1149 #. EXTRACTED-COMMENTS 1150 #: REFERENCE... 1151 #, FLAG... 1152 #| msgctxt PREVIOUS-CONTEXT 1153 #| msgid PREVIOUS-UNTRANSLATED-STRING 1154 msgctxt CONTEXT 1155 msgid UNTRANSLATED-STRING 1156 msgstr TRANSLATED-STRING 1157 1158 The context serves to disambiguate messages with the same 1159UNTRANSLATED-STRING. It is possible to have several entries with the 1160same UNTRANSLATED-STRING in a PO file, provided that they each have a 1161different CONTEXT. Note that an empty CONTEXT string and an absent 1162`msgctxt' line do not mean the same thing. 1163 1164 A different kind of entries is used for translations which involve 1165plural forms. 1166 1167 WHITE-SPACE 1168 # TRANSLATOR-COMMENTS 1169 #. EXTRACTED-COMMENTS 1170 #: REFERENCE... 1171 #, FLAG... 1172 #| msgid PREVIOUS-UNTRANSLATED-STRING-SINGULAR 1173 #| msgid_plural PREVIOUS-UNTRANSLATED-STRING-PLURAL 1174 msgid UNTRANSLATED-STRING-SINGULAR 1175 msgid_plural UNTRANSLATED-STRING-PLURAL 1176 msgstr[0] TRANSLATED-STRING-CASE-0 1177 ... 1178 msgstr[N] TRANSLATED-STRING-CASE-N 1179 1180 Such an entry can look like this: 1181 1182 #: src/msgcmp.c:338 src/po-lex.c:699 1183 #, c-format 1184 msgid "found %d fatal error" 1185 msgid_plural "found %d fatal errors" 1186 msgstr[0] "s'ha trobat %d error fatal" 1187 msgstr[1] "s'han trobat %d errors fatals" 1188 1189 Here also, a `msgctxt' context can be specified before `msgid', like 1190above. 1191 1192 The PREVIOUS-UNTRANSLATED-STRING is optionally inserted by the 1193`msgmerge' program, at the same time when it marks a message fuzzy. It 1194helps the translator to see which changes were done by the developers 1195on the UNTRANSLATED-STRING. 1196 1197 It happens that some lines, usually whitespace or comments, follow 1198the very last entry of a PO file. Such lines are not part of any entry, 1199and will be dropped when the PO file is processed by the tools, or may 1200disturb some PO file editors. 1201 1202 The remainder of this section may be safely skipped by those using a 1203PO file editor, yet it may be interesting for everybody to have a better 1204idea of the precise format of a PO file. On the other hand, those 1205wishing to modify PO files by hand should carefully continue reading on. 1206 1207 Each of UNTRANSLATED-STRING and TRANSLATED-STRING respects the C 1208syntax for a character string, including the surrounding quotes and 1209embedded backslashed escape sequences. When the time comes to write 1210multi-line strings, one should not use escaped newlines. Instead, a 1211closing quote should follow the last character on the line to be 1212continued, and an opening quote should resume the string at the 1213beginning of the following PO file line. For example: 1214 1215 msgid "" 1216 "Here is an example of how one might continue a very long string\n" 1217 "for the common case the string represents multi-line output.\n" 1218 1219In this example, the empty string is used on the first line, to allow 1220better alignment of the `H' from the word `Here' over the `f' from the 1221word `for'. In this example, the `msgid' keyword is followed by three 1222strings, which are meant to be concatenated. Concatenating the empty 1223string does not change the resulting overall string, but it is a way 1224for us to comply with the necessity of `msgid' to be followed by a 1225string on the same line, while keeping the multi-line presentation 1226left-justified, as we find this to be a cleaner disposition. The empty 1227string could have been omitted, but only if the string starting with 1228`Here' was promoted on the first line, right after `msgid'.(1) It was 1229not really necessary either to switch between the two last quoted 1230strings immediately after the newline `\n', the switch could have 1231occurred after _any_ other character, we just did it this way because 1232it is neater. 1233 1234 One should carefully distinguish between end of lines marked as `\n' 1235_inside_ quotes, which are part of the represented string, and end of 1236lines in the PO file itself, outside string quotes, which have no 1237incidence on the represented string. 1238 1239 Outside strings, white lines and comments may be used freely. 1240Comments start at the beginning of a line with `#' and extend until the 1241end of the PO file line. Comments written by translators should have 1242the initial `#' immediately followed by some white space. If the `#' 1243is not immediately followed by white space, this comment is most likely 1244generated and managed by specialized GNU tools, and might disappear or 1245be replaced unexpectedly when the PO file is given to `msgmerge'. 1246 1247 ---------- Footnotes ---------- 1248 1249 (1) This limitation is not imposed by GNU `gettext', but is for 1250compatibility with the `msgfmt' implementation on Solaris. 1251 1252 1253File: gettext.info, Node: Sources, Next: Template, Prev: PO Files, Up: Top 1254 12554 Preparing Program Sources 1256*************************** 1257 1258For the programmer, changes to the C source code fall into three 1259categories. First, you have to make the localization functions known 1260to all modules needing message translation. Second, you should 1261properly trigger the operation of GNU `gettext' when the program 1262initializes, usually from the `main' function. Last, you should 1263identify, adjust and mark all constant strings in your program needing 1264translation. 1265 1266* Menu: 1267 1268* Importing:: Importing the `gettext' declaration 1269* Triggering:: Triggering `gettext' Operations 1270* Preparing Strings:: Preparing Translatable Strings 1271* Mark Keywords:: How Marks Appear in Sources 1272* Marking:: Marking Translatable Strings 1273* c-format Flag:: Telling something about the following string 1274* Special cases:: Special Cases of Translatable Strings 1275* Names:: Marking Proper Names for Translation 1276* Libraries:: Preparing Library Sources 1277 1278 1279File: gettext.info, Node: Importing, Next: Triggering, Prev: Sources, Up: Sources 1280 12814.1 Importing the `gettext' declaration 1282======================================= 1283 1284Presuming that your set of programs, or package, has been adjusted so 1285all needed GNU `gettext' files are available, and your `Makefile' files 1286are adjusted (*note Maintainers::), each C module having translated C 1287strings should contain the line: 1288 1289 #include <libintl.h> 1290 1291 Similarly, each C module containing `printf()'/`fprintf()'/... 1292calls with a format string that could be a translated C string (even if 1293the C string comes from a different C module) should contain the line: 1294 1295 #include <libintl.h> 1296 1297 1298File: gettext.info, Node: Triggering, Next: Preparing Strings, Prev: Importing, Up: Sources 1299 13004.2 Triggering `gettext' Operations 1301=================================== 1302 1303The initialization of locale data should be done with more or less the 1304same code in every program, as demonstrated below: 1305 1306 int 1307 main (int argc, char *argv[]) 1308 { 1309 ... 1310 setlocale (LC_ALL, ""); 1311 bindtextdomain (PACKAGE, LOCALEDIR); 1312 textdomain (PACKAGE); 1313 ... 1314 } 1315 1316 PACKAGE and LOCALEDIR should be provided either by `config.h' or by 1317the Makefile. For now consult the `gettext' or `hello' sources for 1318more information. 1319 1320 The use of `LC_ALL' might not be appropriate for you. `LC_ALL' 1321includes all locale categories and especially `LC_CTYPE'. This later 1322category is responsible for determining character classes with the 1323`isalnum' etc. functions from `ctype.h' which could especially for 1324programs, which process some kind of input language, be wrong. For 1325example this would mean that a source code using the c, (c-cedilla 1326character) is runnable in France but not in the U.S. 1327 1328 Some systems also have problems with parsing numbers using the 1329`scanf' functions if an other but the `LC_ALL' locale is used. The 1330standards say that additional formats but the one known in the `"C"' 1331locale might be recognized. But some systems seem to reject numbers in 1332the `"C"' locale format. In some situation, it might also be a problem 1333with the notation itself which makes it impossible to recognize whether 1334the number is in the `"C"' locale or the local format. This can happen 1335if thousands separator characters are used. Some locales define this 1336character according to the national conventions to `'.'' which is the 1337same character used in the `"C"' locale to denote the decimal point. 1338 1339 So it is sometimes necessary to replace the `LC_ALL' line in the 1340code above by a sequence of `setlocale' lines 1341 1342 { 1343 ... 1344 setlocale (LC_CTYPE, ""); 1345 setlocale (LC_MESSAGES, ""); 1346 ... 1347 } 1348 1349On all POSIX conformant systems the locale categories `LC_CTYPE', 1350`LC_MESSAGES', `LC_COLLATE', `LC_MONETARY', `LC_NUMERIC', and `LC_TIME' 1351are available. On some systems which are only ISO C compliant, 1352`LC_MESSAGES' is missing, but a substitute for it is defined in GNU 1353gettext's `<libintl.h>'. 1354 1355 Note that changing the `LC_CTYPE' also affects the functions 1356declared in the `<ctype.h>' standard header. If this is not desirable 1357in your application (for example in a compiler's parser), you can use a 1358set of substitute functions which hardwire the C locale, such as found 1359in the `<c-ctype.h>' and `<c-ctype.c>' files in the gettext source 1360distribution. 1361 1362 It is also possible to switch the locale forth and back between the 1363environment dependent locale and the C locale, but this approach is 1364normally avoided because a `setlocale' call is expensive, because it is 1365tedious to determine the places where a locale switch is needed in a 1366large program's source, and because switching a locale is not 1367multithread-safe. 1368 1369 1370File: gettext.info, Node: Preparing Strings, Next: Mark Keywords, Prev: Triggering, Up: Sources 1371 13724.3 Preparing Translatable Strings 1373================================== 1374 1375Before strings can be marked for translations, they sometimes need to 1376be adjusted. Usually preparing a string for translation is done right 1377before marking it, during the marking phase which is described in the 1378next sections. What you have to keep in mind while doing that is the 1379following. 1380 1381 * Decent English style. 1382 1383 * Entire sentences. 1384 1385 * Split at paragraphs. 1386 1387 * Use format strings instead of string concatenation. 1388 1389 * Avoid unusual markup and unusual control characters. 1390 1391Let's look at some examples of these guidelines. 1392 1393 Translatable strings should be in good English style. If slang 1394language with abbreviations and shortcuts is used, often translators 1395will not understand the message and will produce very inappropriate 1396translations. 1397 1398 "%s: is parameter\n" 1399 1400This is nearly untranslatable: Is the displayed item _a_ parameter or 1401_the_ parameter? 1402 1403 "No match" 1404 1405The ambiguity in this message makes it unintelligible: Is the program 1406attempting to set something on fire? Does it mean "The given object does 1407not match the template"? Does it mean "The template does not fit for any 1408of the objects"? 1409 1410 In both cases, adding more words to the message will help both the 1411translator and the English speaking user. 1412 1413 Translatable strings should be entire sentences. It is often not 1414possible to translate single verbs or adjectives in a substitutable way. 1415 1416 printf ("File %s is %s protected", filename, rw ? "write" : "read"); 1417 1418Most translators will not look at the source and will thus only see the 1419string `"File %s is %s protected"', which is unintelligible. Change 1420this to 1421 1422 printf (rw ? "File %s is write protected" : "File %s is read protected", 1423 filename); 1424 1425This way the translator will not only understand the message, she will 1426also be able to find the appropriate grammatical construction. A French 1427translator for example translates "write protected" like "protected 1428against writing". 1429 1430 Entire sentences are also important because in many languages, the 1431declination of some word in a sentence depends on the gender or the 1432number (singular/plural) of another part of the sentence. There are 1433usually more interdependencies between words than in English. The 1434consequence is that asking a translator to translate two half-sentences 1435and then combining these two half-sentences through dumb string 1436concatenation will not work, for many languages, even though it would 1437work for English. That's why translators need to handle entire 1438sentences. 1439 1440 Often sentences don't fit into a single line. If a sentence is 1441output using two subsequent `printf' statements, like this 1442 1443 printf ("Locale charset \"%s\" is different from\n", lcharset); 1444 printf ("input file charset \"%s\".\n", fcharset); 1445 1446the translator would have to translate two half sentences, but nothing 1447in the POT file would tell her that the two half sentences belong 1448together. It is necessary to merge the two `printf' statements so that 1449the translator can handle the entire sentence at once and decide at 1450which place to insert a line break in the translation (if at all): 1451 1452 printf ("Locale charset \"%s\" is different from\n\ 1453 input file charset \"%s\".\n", lcharset, fcharset); 1454 1455 You may now ask: how about two or more adjacent sentences? Like in 1456this case: 1457 1458 puts ("Apollo 13 scenario: Stack overflow handling failed."); 1459 puts ("On the next stack overflow we will crash!!!"); 1460 1461Should these two statements merged into a single one? I would recommend 1462to merge them if the two sentences are related to each other, because 1463then it makes it easier for the translator to understand and translate 1464both. On the other hand, if one of the two messages is a stereotypic 1465one, occurring in other places as well, you will do a favour to the 1466translator by not merging the two. (Identical messages occurring in 1467several places are combined by xgettext, so the translator has to 1468handle them once only.) 1469 1470 Translatable strings should be limited to one paragraph; don't let a 1471single message be longer than ten lines. The reason is that when the 1472translatable string changes, the translator is faced with the task of 1473updating the entire translated string. Maybe only a single word will 1474have changed in the English string, but the translator doesn't see that 1475(with the current translation tools), therefore she has to proofread 1476the entire message. 1477 1478 Many GNU programs have a `--help' output that extends over several 1479screen pages. It is a courtesy towards the translators to split such a 1480message into several ones of five to ten lines each. While doing that, 1481you can also attempt to split the documented options into groups, such 1482as the input options, the output options, and the informative output 1483options. This will help every user to find the option he is looking 1484for. 1485 1486 Hardcoded string concatenation is sometimes used to construct English 1487strings: 1488 1489 strcpy (s, "Replace "); 1490 strcat (s, object1); 1491 strcat (s, " with "); 1492 strcat (s, object2); 1493 strcat (s, "?"); 1494 1495In order to present to the translator only entire sentences, and also 1496because in some languages the translator might want to swap the order 1497of `object1' and `object2', it is necessary to change this to use a 1498format string: 1499 1500 sprintf (s, "Replace %s with %s?", object1, object2); 1501 1502 A similar case is compile time concatenation of strings. The ISO C 150399 include file `<inttypes.h>' contains a macro `PRId64' that can be 1504used as a formatting directive for outputting an `int64_t' integer 1505through `printf'. It expands to a constant string, usually "d" or "ld" 1506or "lld" or something like this, depending on the platform. Assume you 1507have code like 1508 1509 printf ("The amount is %0" PRId64 "\n", number); 1510 1511The `gettext' tools and library have special support for these 1512`<inttypes.h>' macros. You can therefore simply write 1513 1514 printf (gettext ("The amount is %0" PRId64 "\n"), number); 1515 1516The PO file will contain the string "The amount is %0<PRId64>\n". The 1517translators will provide a translation containing "%0<PRId64>" as well, 1518and at runtime the `gettext' function's result will contain the 1519appropriate constant string, "d" or "ld" or "lld". 1520 1521 This works only for the predefined `<inttypes.h>' macros. If you 1522have defined your own similar macros, let's say `MYPRId64', that are 1523not known to `xgettext', the solution for this problem is to change the 1524code like this: 1525 1526 char buf1[100]; 1527 sprintf (buf1, "%0" MYPRId64, number); 1528 printf (gettext ("The amount is %s\n"), buf1); 1529 1530 This means, you put the platform dependent code in one statement, 1531and the internationalization code in a different statement. Note that 1532a buffer length of 100 is safe, because all available hardware integer 1533types are limited to 128 bits, and to print a 128 bit integer one needs 1534at most 54 characters, regardless whether in decimal, octal or 1535hexadecimal. 1536 1537 All this applies to other programming languages as well. For 1538example, in Java and C#, string concatenation is very frequently used, 1539because it is a compiler built-in operator. Like in C, in Java, you 1540would change 1541 1542 System.out.println("Replace "+object1+" with "+object2+"?"); 1543 1544into a statement involving a format string: 1545 1546 System.out.println( 1547 MessageFormat.format("Replace {0} with {1}?", 1548 new Object[] { object1, object2 })); 1549 1550Similarly, in C#, you would change 1551 1552 Console.WriteLine("Replace "+object1+" with "+object2+"?"); 1553 1554into a statement involving a format string: 1555 1556 Console.WriteLine( 1557 String.Format("Replace {0} with {1}?", object1, object2)); 1558 1559 Unusual markup or control characters should not be used in 1560translatable strings. Translators will likely not understand the 1561particular meaning of the markup or control characters. 1562 1563 For example, if you have a convention that `|' delimits the 1564left-hand and right-hand part of some GUI elements, translators will 1565often not understand it without specific comments. It might be better 1566to have the translator translate the left-hand and right-hand part 1567separately. 1568 1569 Another example is the `argp' convention to use a single `\v' 1570(vertical tab) control character to delimit two sections inside a 1571string. This is flawed. Some translators may convert it to a simple 1572newline, some to blank lines. With some PO file editors it may not be 1573easy to even enter a vertical tab control character. So, you cannot be 1574sure that the translation will contain a `\v' character, at the 1575corresponding position. The solution is, again, to let the translator 1576translate two separate strings and combine at run-time the two 1577translated strings with the `\v' required by the convention. 1578 1579 HTML markup, however, is common enough that it's probably ok to use 1580in translatable strings. But please bear in mind that the GNU gettext 1581tools don't verify that the translations are well-formed HTML. 1582 1583 1584File: gettext.info, Node: Mark Keywords, Next: Marking, Prev: Preparing Strings, Up: Sources 1585 15864.4 How Marks Appear in Sources 1587=============================== 1588 1589All strings requiring translation should be marked in the C sources. 1590Marking is done in such a way that each translatable string appears to 1591be the sole argument of some function or preprocessor macro. There are 1592only a few such possible functions or macros meant for translation, and 1593their names are said to be marking keywords. The marking is attached 1594to strings themselves, rather than to what we do with them. This 1595approach has more uses. A blatant example is an error message produced 1596by formatting. The format string needs translation, as well as some 1597strings inserted through some `%s' specification in the format, while 1598the result from `sprintf' may have so many different instances that it 1599is impractical to list them all in some `error_string_out()' routine, 1600say. 1601 1602 This marking operation has two goals. The first goal of marking is 1603for triggering the retrieval of the translation, at run time. The 1604keyword is possibly resolved into a routine able to dynamically return 1605the proper translation, as far as possible or wanted, for the argument 1606string. Most localizable strings are found in executable positions, 1607that is, attached to variables or given as parameters to functions. 1608But this is not universal usage, and some translatable strings appear 1609in structured initializations. *Note Special cases::. 1610 1611 The second goal of the marking operation is to help `xgettext' at 1612properly extracting all translatable strings when it scans a set of 1613program sources and produces PO file templates. 1614 1615 The canonical keyword for marking translatable strings is `gettext', 1616it gave its name to the whole GNU `gettext' package. For packages 1617making only light use of the `gettext' keyword, macro or function, it 1618is easily used _as is_. However, for packages using the `gettext' 1619interface more heavily, it is usually more convenient to give the main 1620keyword a shorter, less obtrusive name. Indeed, the keyword might 1621appear on a lot of strings all over the package, and programmers 1622usually do not want nor need their program sources to remind them 1623forcefully, all the time, that they are internationalized. Further, a 1624long keyword has the disadvantage of using more horizontal space, 1625forcing more indentation work on sources for those trying to keep them 1626within 79 or 80 columns. 1627 1628 Many packages use `_' (a simple underline) as a keyword, and write 1629`_("Translatable string")' instead of `gettext ("Translatable 1630string")'. Further, the coding rule, from GNU standards, wanting that 1631there is a space between the keyword and the opening parenthesis is 1632relaxed, in practice, for this particular usage. So, the textual 1633overhead per translatable string is reduced to only three characters: 1634the underline and the two parentheses. However, even if GNU `gettext' 1635uses this convention internally, it does not offer it officially. The 1636real, genuine keyword is truly `gettext' indeed. It is fairly easy for 1637those wanting to use `_' instead of `gettext' to declare: 1638 1639 #include <libintl.h> 1640 #define _(String) gettext (String) 1641 1642instead of merely using `#include <libintl.h>'. 1643 1644 The marking keywords `gettext' and `_' take the translatable string 1645as sole argument. It is also possible to define marking functions that 1646take it at another argument position. It is even possible to make the 1647marked argument position depend on the total number of arguments of the 1648function call; this is useful in C++. All this is achieved using 1649`xgettext''s `--keyword' option. 1650 1651 Note also that long strings can be split across lines, into multiple 1652adjacent string tokens. Automatic string concatenation is performed at 1653compile time according to ISO C and ISO C++; `xgettext' also supports 1654this syntax. 1655 1656 Later on, the maintenance is relatively easy. If, as a programmer, 1657you add or modify a string, you will have to ask yourself if the new or 1658altered string requires translation, and include it within `_()' if you 1659think it should be translated. For example, `"%s"' is an example of 1660string _not_ requiring translation. But `"%s: %d"' _does_ require 1661translation, because in French, unlike in English, it's customary to 1662put a space before a colon. 1663 1664 1665File: gettext.info, Node: Marking, Next: c-format Flag, Prev: Mark Keywords, Up: Sources 1666 16674.5 Marking Translatable Strings 1668================================ 1669 1670In PO mode, one set of features is meant more for the programmer than 1671for the translator, and allows him to interactively mark which strings, 1672in a set of program sources, are translatable, and which are not. Even 1673if it is a fairly easy job for a programmer to find and mark such 1674strings by other means, using any editor of his choice, PO mode makes 1675this work more comfortable. Further, this gives translators who feel a 1676little like programmers, or programmers who feel a little like 1677translators, a tool letting them work at marking translatable strings 1678in the program sources, while simultaneously producing a set of 1679translation in some language, for the package being internationalized. 1680 1681 The set of program sources, targeted by the PO mode commands describe 1682here, should have an Emacs tags table constructed for your project, 1683prior to using these PO file commands. This is easy to do. In any 1684shell window, change the directory to the root of your project, then 1685execute a command resembling: 1686 1687 etags src/*.[hc] lib/*.[hc] 1688 1689presuming here you want to process all `.h' and `.c' files from the 1690`src/' and `lib/' directories. This command will explore all said 1691files and create a `TAGS' file in your root directory, somewhat 1692summarizing the contents using a special file format Emacs can 1693understand. 1694 1695 For packages following the GNU coding standards, there is a make 1696goal `tags' or `TAGS' which constructs the tag files in all directories 1697and for all files containing source code. 1698 1699 Once your `TAGS' file is ready, the following commands assist the 1700programmer at marking translatable strings in his set of sources. But 1701these commands are necessarily driven from within a PO file window, and 1702it is likely that you do not even have such a PO file yet. This is not 1703a problem at all, as you may safely open a new, empty PO file, mainly 1704for using these commands. This empty PO file will slowly fill in while 1705you mark strings as translatable in your program sources. 1706 1707`,' 1708 Search through program sources for a string which looks like a 1709 candidate for translation (`po-tags-search'). 1710 1711`M-,' 1712 Mark the last string found with `_()' (`po-mark-translatable'). 1713 1714`M-.' 1715 Mark the last string found with a keyword taken from a set of 1716 possible keywords. This command with a prefix allows some 1717 management of these keywords (`po-select-mark-and-mark'). 1718 1719 1720 The `,' (`po-tags-search') command searches for the next occurrence 1721of a string which looks like a possible candidate for translation, and 1722displays the program source in another Emacs window, positioned in such 1723a way that the string is near the top of this other window. If the 1724string is too big to fit whole in this window, it is positioned so only 1725its end is shown. In any case, the cursor is left in the PO file 1726window. If the shown string would be better presented differently in 1727different native languages, you may mark it using `M-,' or `M-.'. 1728Otherwise, you might rather ignore it and skip to the next string by 1729merely repeating the `,' command. 1730 1731 A string is a good candidate for translation if it contains a 1732sequence of three or more letters. A string containing at most two 1733letters in a row will be considered as a candidate if it has more 1734letters than non-letters. The command disregards strings containing no 1735letters, or isolated letters only. It also disregards strings within 1736comments, or strings already marked with some keyword PO mode knows 1737(see below). 1738 1739 If you have never told Emacs about some `TAGS' file to use, the 1740command will request that you specify one from the minibuffer, the 1741first time you use the command. You may later change your `TAGS' file 1742by using the regular Emacs command `M-x visit-tags-table', which will 1743ask you to name the precise `TAGS' file you want to use. *Note Tag 1744Tables: (emacs)Tags. 1745 1746 Each time you use the `,' command, the search resumes from where it 1747was left by the previous search, and goes through all program sources, 1748obeying the `TAGS' file, until all sources have been processed. 1749However, by giving a prefix argument to the command (`C-u ,'), you may 1750request that the search be restarted all over again from the first 1751program source; but in this case, strings that you recently marked as 1752translatable will be automatically skipped. 1753 1754 Using this `,' command does not prevent using of other regular Emacs 1755tags commands. For example, regular `tags-search' or 1756`tags-query-replace' commands may be used without disrupting the 1757independent `,' search sequence. However, as implemented, the 1758_initial_ `,' command (or the `,' command is used with a prefix) might 1759also reinitialize the regular Emacs tags searching to the first tags 1760file, this reinitialization might be considered spurious. 1761 1762 The `M-,' (`po-mark-translatable') command will mark the recently 1763found string with the `_' keyword. The `M-.' 1764(`po-select-mark-and-mark') command will request that you type one 1765keyword from the minibuffer and use that keyword for marking the 1766string. Both commands will automatically create a new PO file 1767untranslated entry for the string being marked, and make it the current 1768entry (making it easy for you to immediately proceed to its 1769translation, if you feel like doing it right away). It is possible 1770that the modifications made to the program source by `M-,' or `M-.' 1771render some source line longer than 80 columns, forcing you to break 1772and re-indent this line differently. You may use the `O' command from 1773PO mode, or any other window changing command from Emacs, to break out 1774into the program source window, and do any needed adjustments. You 1775will have to use some regular Emacs command to return the cursor to the 1776PO file window, if you want command `,' for the next string, say. 1777 1778 The `M-.' command has a few built-in speedups, so you do not have to 1779explicitly type all keywords all the time. The first such speedup is 1780that you are presented with a _preferred_ keyword, which you may accept 1781by merely typing `<RET>' at the prompt. The second speedup is that you 1782may type any non-ambiguous prefix of the keyword you really mean, and 1783the command will complete it automatically for you. This also means 1784that PO mode has to _know_ all your possible keywords, and that it will 1785not accept mistyped keywords. 1786 1787 If you reply `?' to the keyword request, the command gives a list of 1788all known keywords, from which you may choose. When the command is 1789prefixed by an argument (`C-u M-.'), it inhibits updating any program 1790source or PO file buffer, and does some simple keyword management 1791instead. In this case, the command asks for a keyword, written in 1792full, which becomes a new allowed keyword for later `M-.' commands. 1793Moreover, this new keyword automatically becomes the _preferred_ 1794keyword for later commands. By typing an already known keyword in 1795response to `C-u M-.', one merely changes the _preferred_ keyword and 1796does nothing more. 1797 1798 All keywords known for `M-.' are recognized by the `,' command when 1799scanning for strings, and strings already marked by any of those known 1800keywords are automatically skipped. If many PO files are opened 1801simultaneously, each one has its own independent set of known keywords. 1802There is no provision in PO mode, currently, for deleting a known 1803keyword, you have to quit the file (maybe using `q') and reopen it 1804afresh. When a PO file is newly brought up in an Emacs window, only 1805`gettext' and `_' are known as keywords, and `gettext' is preferred for 1806the `M-.' command. In fact, this is not useful to prefer `_', as this 1807one is already built in the `M-,' command. 1808 1809 1810File: gettext.info, Node: c-format Flag, Next: Special cases, Prev: Marking, Up: Sources 1811 18124.6 Special Comments preceding Keywords 1813======================================= 1814 1815In C programs strings are often used within calls of functions from the 1816`printf' family. The special thing about these format strings is that 1817they can contain format specifiers introduced with `%'. Assume we have 1818the code 1819 1820 printf (gettext ("String `%s' has %d characters\n"), s, strlen (s)); 1821 1822A possible German translation for the above string might be: 1823 1824 "%d Zeichen lang ist die Zeichenkette `%s'" 1825 1826 A C programmer, even if he cannot speak German, will recognize that 1827there is something wrong here. The order of the two format specifiers 1828is changed but of course the arguments in the `printf' don't have. 1829This will most probably lead to problems because now the length of the 1830string is regarded as the address. 1831 1832 To prevent errors at runtime caused by translations the `msgfmt' 1833tool can check statically whether the arguments in the original and the 1834translation string match in type and number. If this is not the case 1835and the `-c' option has been passed to `msgfmt', `msgfmt' will give an 1836error and refuse to produce a MO file. Thus consequent use of `msgfmt 1837-c' will catch the error, so that it cannot cause cause problems at 1838runtime. 1839 1840If the word order in the above German translation would be correct one 1841would have to write 1842 1843 "%2$d Zeichen lang ist die Zeichenkette `%1$s'" 1844 1845The routines in `msgfmt' know about this special notation. 1846 1847 Because not all strings in a program must be format strings it is not 1848useful for `msgfmt' to test all the strings in the `.po' file. This 1849might cause problems because the string might contain what looks like a 1850format specifier, but the string is not used in `printf'. 1851 1852 Therefore the `xgettext' adds a special tag to those messages it 1853thinks might be a format string. There is no absolute rule for this, 1854only a heuristic. In the `.po' file the entry is marked using the 1855`c-format' flag in the `#,' comment line (*note PO Files::). 1856 1857 The careful reader now might say that this again can cause problems. 1858The heuristic might guess it wrong. This is true and therefore 1859`xgettext' knows about a special kind of comment which lets the 1860programmer take over the decision. If in the same line as or the 1861immediately preceding line to the `gettext' keyword the `xgettext' 1862program finds a comment containing the words `xgettext:c-format', it 1863will mark the string in any case with the `c-format' flag. This kind 1864of comment should be used when `xgettext' does not recognize the string 1865as a format string but it really is one and it should be tested. 1866Please note that when the comment is in the same line as the `gettext' 1867keyword, it must be before the string to be translated. 1868 1869 This situation happens quite often. The `printf' function is often 1870called with strings which do not contain a format specifier. Of course 1871one would normally use `fputs' but it does happen. In this case 1872`xgettext' does not recognize this as a format string but what happens 1873if the translation introduces a valid format specifier? The `printf' 1874function will try to access one of the parameters but none exists 1875because the original code does not pass any parameters. 1876 1877 `xgettext' of course could make a wrong decision the other way 1878round, i.e. a string marked as a format string actually is not a format 1879string. In this case the `msgfmt' might give too many warnings and 1880would prevent translating the `.po' file. The method to prevent this 1881wrong decision is similar to the one used above, only the comment to 1882use must contain the string `xgettext:no-c-format'. 1883 1884 If a string is marked with `c-format' and this is not correct the 1885user can find out who is responsible for the decision. See *Note 1886xgettext Invocation:: to see how the `--debug' option can be used for 1887solving this problem. 1888 1889 1890File: gettext.info, Node: Special cases, Next: Names, Prev: c-format Flag, Up: Sources 1891 18924.7 Special Cases of Translatable Strings 1893========================================= 1894 1895The attentive reader might now point out that it is not always possible 1896to mark translatable string with `gettext' or something like this. 1897Consider the following case: 1898 1899 { 1900 static const char *messages[] = { 1901 "some very meaningful message", 1902 "and another one" 1903 }; 1904 const char *string; 1905 ... 1906 string 1907 = index > 1 ? "a default message" : messages[index]; 1908 1909 fputs (string); 1910 ... 1911 } 1912 1913 While it is no problem to mark the string `"a default message"' it 1914is not possible to mark the string initializers for `messages'. What 1915is to be done? We have to fulfill two tasks. First we have to mark the 1916strings so that the `xgettext' program (*note xgettext Invocation::) 1917can find them, and second we have to translate the string at runtime 1918before printing them. 1919 1920 The first task can be fulfilled by creating a new keyword, which 1921names a no-op. For the second we have to mark all access points to a 1922string from the array. So one solution can look like this: 1923 1924 #define gettext_noop(String) String 1925 1926 { 1927 static const char *messages[] = { 1928 gettext_noop ("some very meaningful message"), 1929 gettext_noop ("and another one") 1930 }; 1931 const char *string; 1932 ... 1933 string 1934 = index > 1 ? gettext ("a default message") : gettext (messages[index]); 1935 1936 fputs (string); 1937 ... 1938 } 1939 1940 Please convince yourself that the string which is written by `fputs' 1941is translated in any case. How to get `xgettext' know the additional 1942keyword `gettext_noop' is explained in *Note xgettext Invocation::. 1943 1944 The above is of course not the only solution. You could also come 1945along with the following one: 1946 1947 #define gettext_noop(String) String 1948 1949 { 1950 static const char *messages[] = { 1951 gettext_noop ("some very meaningful message", 1952 gettext_noop ("and another one") 1953 }; 1954 const char *string; 1955 ... 1956 string 1957 = index > 1 ? gettext_noop ("a default message") : messages[index]; 1958 1959 fputs (gettext (string)); 1960 ... 1961 } 1962 1963 But this has a drawback. The programmer has to take care that he 1964uses `gettext_noop' for the string `"a default message"'. A use of 1965`gettext' could have in rare cases unpredictable results. 1966 1967 One advantage is that you need not make control flow analysis to make 1968sure the output is really translated in any case. But this analysis is 1969generally not very difficult. If it should be in any situation you can 1970use this second method in this situation. 1971 1972 1973File: gettext.info, Node: Names, Next: Libraries, Prev: Special cases, Up: Sources 1974 19754.8 Marking Proper Names for Translation 1976======================================== 1977 1978Should names of persons, cities, locations etc. be marked for 1979translation or not? People who only know languages that can be written 1980with Latin letters (English, Spanish, French, German, etc.) are tempted 1981to say "no", because names usually do not change when transported 1982between these languages. However, in general when translating from one 1983script to another, names are translated too, usually phonetically or by 1984transliteration. For example, Russian or Greek names are converted to 1985the Latin alphabet when being translated to English, and English or 1986French names are converted to the Katakana script when being translated 1987to Japanese. This is necessary because the speakers of the target 1988language in general cannot read the script the name is originally 1989written in. 1990 1991 As a programmer, you should therefore make sure that names are marked 1992for translation, with a special comment telling the translators that it 1993is a proper name and how to pronounce it. Like this: 1994 1995 printf (_("Written by %s.\n"), 1996 /* TRANSLATORS: This is a proper name. See the gettext 1997 manual, section Names. Note this is actually a non-ASCII 1998 name: The first name is (with Unicode escapes) 1999 "Fran\u00e7ois" or (with HTML entities) "François". 2000 Pronunciation is like "fraa-swa pee-nar". */ 2001 _("Francois Pinard")); 2002 2003 As a translator, you should use some care when translating names, 2004because it is frustrating if people see their names mutilated or 2005distorted. If your language uses the Latin script, all you need to do 2006is to reproduce the name as perfectly as you can within the usual 2007character set of your language. In this particular case, this means to 2008provide a translation containing the c-cedilla character. If your 2009language uses a different script and the people speaking it don't 2010usually read Latin words, it means transliteration; but you should 2011still give, in parentheses, the original writing of the name - for the 2012sake of the people that do read the Latin script. Here is an example, 2013using Greek as the target script: 2014 2015 #. This is a proper name. See the gettext 2016 #. manual, section Names. Note this is actually a non-ASCII 2017 #. name: The first name is (with Unicode escapes) 2018 #. "Fran\u00e7ois" or (with HTML entities) "François". 2019 #. Pronunciation is like "fraa-swa pee-nar". 2020 msgid "Francois Pinard" 2021 msgstr "\phi\rho\alpha\sigma\omicron\alpha \pi\iota\nu\alpha\rho" 2022 " (Francois Pinard)" 2023 2024 Because translation of names is such a sensitive domain, it is a good 2025idea to test your translation before submitting it. 2026 2027 The translation project `http://sourceforge.net/projects/translation' 2028has set up a POT file and translation domain consisting of program 2029author names, with better facilities for the translator than those 2030presented here. Namely, there the original name is written directly in 2031Unicode (rather than with Unicode escapes or HTML entities), and the 2032pronunciation is denoted using the International Phonetic Alphabet (see 2033`http://www.wikipedia.org/wiki/International_Phonetic_Alphabet'). 2034 2035 However, we don't recommend this approach for all POT files in all 2036packages, because this would force translators to use PO files in UTF-8 2037encoding, which is - in the current state of software (as of 2003) - a 2038major hassle for translators using GNU Emacs or XEmacs with po-mode. 2039 2040 2041File: gettext.info, Node: Libraries, Prev: Names, Up: Sources 2042 20434.9 Preparing Library Sources 2044============================= 2045 2046When you are preparing a library, not a program, for the use of 2047`gettext', only a few details are different. Here we assume that the 2048library has a translation domain and a POT file of its own. (If it 2049uses the translation domain and POT file of the main program, then the 2050previous sections apply without changes.) 2051 2052 1. The library code doesn't call `setlocale (LC_ALL, "")'. It's the 2053 responsibility of the main program to set the locale. The 2054 library's documentation should mention this fact, so that 2055 developers of programs using the library are aware of it. 2056 2057 2. The library code doesn't call `textdomain (PACKAGE)', because it 2058 would interfere with the text domain set by the main program. 2059 2060 3. The initialization code for a program was 2061 2062 setlocale (LC_ALL, ""); 2063 bindtextdomain (PACKAGE, LOCALEDIR); 2064 textdomain (PACKAGE); 2065 2066 For a library it is reduced to 2067 2068 bindtextdomain (PACKAGE, LOCALEDIR); 2069 2070 If your library's API doesn't already have an initialization 2071 function, you need to create one, containing at least the 2072 `bindtextdomain' invocation. However, you usually don't need to 2073 export and document this initialization function: It is sufficient 2074 that all entry points of the library call the initialization 2075 function if it hasn't been called before. The typical idiom used 2076 to achieve this is a static boolean variable that indicates 2077 whether the initialization function has been called. Like this: 2078 2079 static bool libfoo_initialized; 2080 2081 static void 2082 libfoo_initialize (void) 2083 { 2084 bindtextdomain (PACKAGE, LOCALEDIR); 2085 libfoo_initialized = true; 2086 } 2087 2088 /* This function is part of the exported API. */ 2089 struct foo * 2090 create_foo (...) 2091 { 2092 /* Must ensure the initialization is performed. */ 2093 if (!libfoo_initialized) 2094 libfoo_initialize (); 2095 ... 2096 } 2097 2098 /* This function is part of the exported API. The argument must be 2099 non-NULL and have been created through create_foo(). */ 2100 int 2101 foo_refcount (struct foo *argument) 2102 { 2103 /* No need to invoke the initialization function here, because 2104 create_foo() must already have been called before. */ 2105 ... 2106 } 2107 2108 4. The usual declaration of the `_' macro in each source file was 2109 2110 #include <libintl.h> 2111 #define _(String) gettext (String) 2112 2113 for a program. For a library, which has its own translation 2114 domain, it reads like this: 2115 2116 #include <libintl.h> 2117 #define _(String) dgettext (PACKAGE, String) 2118 2119 In other words, `dgettext' is used instead of `gettext'. 2120 Similarly, the `dngettext' function should be used in place of the 2121 `ngettext' function. 2122 2123 2124File: gettext.info, Node: Template, Next: Creating, Prev: Sources, Up: Top 2125 21265 Making the PO Template File 2127***************************** 2128 2129After preparing the sources, the programmer creates a PO template file. 2130This section explains how to use `xgettext' for this purpose. 2131 2132 `xgettext' creates a file named `DOMAINNAME.po'. You should then 2133rename it to `DOMAINNAME.pot'. (Why doesn't `xgettext' create it under 2134the name `DOMAINNAME.pot' right away? The answer is: for historical 2135reasons. When `xgettext' was specified, the distinction between a PO 2136file and PO file template was fuzzy, and the suffix `.pot' wasn't in 2137use at that time.) 2138 2139* Menu: 2140 2141* xgettext Invocation:: Invoking the `xgettext' Program 2142 2143 2144File: gettext.info, Node: xgettext Invocation, Prev: Template, Up: Template 2145 21465.1 Invoking the `xgettext' Program 2147=================================== 2148 2149 xgettext [OPTION] [INPUTFILE] ... 2150 2151 The `xgettext' program extracts translatable strings from given 2152input files. 2153 21545.1.1 Input file location 2155------------------------- 2156 2157`INPUTFILE ...' 2158 Input files. 2159 2160`-f FILE' 2161`--files-from=FILE' 2162 Read the names of the input files from FILE instead of getting 2163 them from the command line. 2164 2165`-D DIRECTORY' 2166`--directory=DIRECTORY' 2167 Add DIRECTORY to the list of directories. Source files are 2168 searched relative to this list of directories. The resulting `.po' 2169 file will be written relative to the current directory, though. 2170 2171 2172 If INPUTFILE is `-', standard input is read. 2173 21745.1.2 Output file location 2175-------------------------- 2176 2177`-d NAME' 2178`--default-domain=NAME' 2179 Use `NAME.po' for output (instead of `messages.po'). 2180 2181`-o FILE' 2182`--output=FILE' 2183 Write output to specified file (instead of `NAME.po' or 2184 `messages.po'). 2185 2186`-p DIR' 2187`--output-dir=DIR' 2188 Output files will be placed in directory DIR. 2189 2190 2191 If the output FILE is `-' or `/dev/stdout', the output is written to 2192standard output. 2193 21945.1.3 Choice of input file language 2195----------------------------------- 2196 2197`-L NAME' 2198`--language=NAME' 2199 Specifies the language of the input files. The supported languages 2200 are `C', `C++', `ObjectiveC', `PO', `Python', `Lisp', `EmacsLisp', 2201 `librep', `Scheme', `Smalltalk', `Java', `JavaProperties', `C#', 2202 `awk', `YCP', `Tcl', `Perl', `PHP', `GCC-source', `NXStringTable', 2203 `RST', `Glade'. 2204 2205`-C' 2206`--c++' 2207 This is a shorthand for `--language=C++'. 2208 2209 2210 By default the language is guessed depending on the input file name 2211extension. 2212 22135.1.4 Input file interpretation 2214------------------------------- 2215 2216`--from-code=NAME' 2217 Specifies the encoding of the input files. This option is needed 2218 only if some untranslated message strings or their corresponding 2219 comments contain non-ASCII characters. Note that Tcl and Glade 2220 input files are always assumed to be in UTF-8, regardless of this 2221 option. 2222 2223 2224 By default the input files are assumed to be in ASCII. 2225 22265.1.5 Operation mode 2227-------------------- 2228 2229`-j' 2230`--join-existing' 2231 Join messages with existing file. 2232 2233`-x FILE' 2234`--exclude-file=FILE' 2235 Entries from FILE are not extracted. FILE should be a PO or POT 2236 file. 2237 2238`-c [TAG]' 2239`--add-comments[=TAG]' 2240 Place comment block with TAG (or those preceding keyword lines) in 2241 output file. 2242 2243 22445.1.6 Language specific options 2245------------------------------- 2246 2247`-a' 2248`--extract-all' 2249 Extract all strings. 2250 2251 This option has an effect with most languages, namely C, C++, 2252 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, 2253 Tcl, Perl, PHP, GCC-source, Glade. 2254 2255`-k KEYWORDSPEC' 2256`--keyword[=KEYWORDSPEC]' 2257 Additional keyword to be looked for (without KEYWORDSPEC means not 2258 to use default keywords). 2259 2260 If KEYWORDSPEC is a C identifier ID, `xgettext' looks for strings 2261 in the first argument of each call to the function or macro ID. 2262 If KEYWORDSPEC is of the form `ID:ARGNUM', `xgettext' looks for 2263 strings in the ARGNUMth argument of the call. If KEYWORDSPEC is 2264 of the form `ID:ARGNUM1,ARGNUM2', `xgettext' looks for strings in 2265 the ARGNUM1st argument and in the ARGNUM2nd argument of the call, 2266 and treats them as singular/plural variants for a message with 2267 plural handling. Also, if KEYWORDSPEC is of the form 2268 `ID:CONTEXTARGNUMc,ARGNUM' or `ID:ARGNUM,CONTEXTARGNUMc', 2269 `xgettext' treats strings in the CONTEXTARGNUMth argument as a 2270 context specifier. And, as a special-purpose support for GNOME, 2271 if KEYWORDSPEC is of the form `ID:ARGNUMg', `xgettext' recognizes 2272 the ARGNUMth argument as a string with context, using the GNOME 2273 `glib' syntax `"msgctxt|msgid"'. 2274 Furthermore, if KEYWORDSPEC is of the form `ID:...,TOTALNUMARGSt', 2275 `xgettext' recognizes this argument specification only if the 2276 number of actual arguments is equal to TOTALNUMARGS. This is 2277 useful for disambiguating overloaded function calls in C++. 2278 Finally, if KEYWORDSPEC is of the form `ID:ARGNUM...,"XCOMMENT"', 2279 `xgettext', when extracting a message from the specified argument 2280 strings, adds an extracted comment XCOMMENT to the message. Note 2281 that when used through a normal shell command line, the 2282 double-quotes around the XCOMMENT need to be escaped. 2283 2284 This option has an effect with most languages, namely C, C++, 2285 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, 2286 Tcl, Perl, PHP, GCC-source, Glade. 2287 2288 The default keyword specifications, which are always looked for if 2289 not explicitly disabled, are language dependent. They are: 2290 2291 * For C, C++, and GCC-source: `gettext', `dgettext:2', 2292 `dcgettext:2', `ngettext:1,2', `dngettext:2,3', 2293 `dcngettext:2,3', `gettext_noop', and `pgettext:1c,2', 2294 `dpgettext:2c,3', `dcpgettext:2c,3', `npgettext:1c,2,3', 2295 `dnpgettext:2c,3,4', `dcnpgettext:2c,3,4'. 2296 2297 * For Objective C: Like for C, and also `NSLocalizedString', 2298 `_', `NSLocalizedStaticString', `__'. 2299 2300 * For Shell scripts: `gettext', `ngettext:1,2', `eval_gettext', 2301 `eval_ngettext:1,2'. 2302 2303 * For Python: `gettext', `ugettext', `dgettext:2', 2304 `ngettext:1,2', `ungettext:1,2', `dngettext:2,3', `_'. 2305 2306 * For Lisp: `gettext', `ngettext:1,2', `gettext-noop'. 2307 2308 * For EmacsLisp: `_'. 2309 2310 * For librep: `_'. 2311 2312 * For Scheme: `gettext', `ngettext:1,2', `gettext-noop'. 2313 2314 * For Java: `GettextResource.gettext:2', 2315 `GettextResource.ngettext:2,3', `gettext', `ngettext:1,2', 2316 `getString'. 2317 2318 * For C#: `GetString', `GetPluralString:1,2'. 2319 2320 * For awk: `dcgettext', `dcngettext:1,2'. 2321 2322 * For Tcl: `::msgcat::mc'. 2323 2324 * For Perl: `gettext', `%gettext', `$gettext', `dgettext:2', 2325 `dcgettext:2', `ngettext:1,2', `dngettext:2,3', 2326 `dcngettext:2,3', `gettext_noop'. 2327 2328 * For PHP: `_', `gettext', `dgettext:2', `dcgettext:2', 2329 `ngettext:1,2', `dngettext:2,3', `dcngettext:2,3'. 2330 2331 * For Glade 1: `label', `title', `text', `format', `copyright', 2332 `comments', `preview_text', `tooltip'. 2333 2334 To disable the default keyword specifications, the option `-k' or 2335 `--keyword' or `--keyword=', without a KEYWORDSPEC, can be used. 2336 2337`--flag=WORD:ARG:FLAG' 2338 Specifies additional flags for strings occurring as part of the 2339 ARGth argument of the function WORD. The possible flags are the 2340 possible format string indicators, such as `c-format', and their 2341 negations, such as `no-c-format', possibly prefixed with `pass-'. 2342 The meaning of `--flag=FUNCTION:ARG:LANG-format' is that in 2343 language LANG, the specified FUNCTION expects as ARGth argument a 2344 format string. (For those of you familiar with GCC function 2345 attributes, `--flag=FUNCTION:ARG:c-format' is roughly equivalent 2346 to the declaration `__attribute__ ((__format__ (__printf__, ARG, 2347 ...)))' attached to FUNCTION in a C source file.) For example, if 2348 you use the `error' function from GNU libc, you can specify its 2349 behaviour through `--flag=error:3:c-format'. The effect of this 2350 specification is that `xgettext' will mark as format strings all 2351 `gettext' invocations that occur as ARGth argument of FUNCTION. 2352 This is useful when such strings contain no format string 2353 directives: together with the checks done by `msgfmt -c' it will 2354 ensure that translators cannot accidentally use format string 2355 directives that would lead to a crash at runtime. 2356 The meaning of `--flag=FUNCTION:ARG:pass-LANG-format' is that in 2357 language LANG, if the FUNCTION call occurs in a position that must 2358 yield a format string, then its ARGth argument must yield a format 2359 string of the same type as well. (If you know GCC function 2360 attributes, the `--flag=FUNCTION:ARG:pass-c-format' option is 2361 roughly equivalent to the declaration `__attribute__ 2362 ((__format_arg__ (ARG)))' attached to FUNCTION in a C source file.) 2363 For example, if you use the `_' shortcut for the `gettext' 2364 function, you should use `--flag=_:1:pass-c-format'. The effect 2365 of this specification is that `xgettext' will propagate a format 2366 string requirement for a `_("string")' call to its first argument, 2367 the literal `"string"', and thus mark it as a format string. This 2368 is useful when such strings contain no format string directives: 2369 together with the checks done by `msgfmt -c' it will ensure that 2370 translators cannot accidentally use format string directives that 2371 would lead to a crash at runtime. 2372 This option has an effect with most languages, namely C, C++, 2373 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java, 2374 C#, awk, YCP, Tcl, Perl, PHP, GCC-source. 2375 2376`-T' 2377`--trigraphs' 2378 Understand ANSI C trigraphs for input. 2379 This option has an effect only with the languages C, C++, 2380 ObjectiveC. 2381 2382`--qt' 2383 Recognize Qt format strings. 2384 This option has an effect only with the language C++. 2385 2386`--boost' 2387 Recognize Boost format strings. 2388 This option has an effect only with the language C++. 2389 2390`--debug' 2391 Use the flags `c-format' and `possible-c-format' to show who was 2392 responsible for marking a message as a format string. The latter 2393 form is used if the `xgettext' program decided, the format form is 2394 used if the programmer prescribed it. 2395 2396 By default only the `c-format' form is used. The translator should 2397 not have to care about these details. 2398 2399 2400 This implementation of `xgettext' is able to process a few awkward 2401cases, like strings in preprocessor macros, ANSI concatenation of 2402adjacent strings, and escaped end of lines for continued strings. 2403 24045.1.7 Output details 2405-------------------- 2406 2407`--force-po' 2408 Always write an output file even if no message is defined. 2409 2410`-i' 2411`--indent' 2412 Write the .po file using indented style. 2413 2414`--no-location' 2415 Do not write `#: FILENAME:LINE' lines. 2416 2417`-n' 2418`--add-location' 2419 Generate `#: FILENAME:LINE' lines (default). 2420 2421`--strict' 2422 Write out a strict Uniforum conforming PO file. Note that this 2423 Uniforum format should be avoided because it doesn't support the 2424 GNU extensions. 2425 2426`--properties-output' 2427 Write out a Java ResourceBundle in Java `.properties' syntax. Note 2428 that this file format doesn't support plural forms and silently 2429 drops obsolete messages. 2430 2431`--stringtable-output' 2432 Write out a NeXTstep/GNUstep localized resource file in `.strings' 2433 syntax. Note that this file format doesn't support plural forms. 2434 2435`-w NUMBER' 2436`--width=NUMBER' 2437 Set the output page width. Long strings in the output files will 2438 be split across multiple lines in order to ensure that each line's 2439 width (= number of screen columns) is less or equal to the given 2440 NUMBER. 2441 2442`--no-wrap' 2443 Do not break long message lines. Message lines whose width 2444 exceeds the output page width will not be split into several 2445 lines. Only file reference lines which are wider than the output 2446 page width will be split. 2447 2448`-s' 2449`--sort-output' 2450 Generate sorted output. Note that using this option makes it much 2451 harder for the translator to understand each message's context. 2452 2453`-F' 2454`--sort-by-file' 2455 Sort output by file location. 2456 2457`--omit-header' 2458 Don't write header with `msgid ""' entry. 2459 2460 This is useful for testing purposes because it eliminates a source 2461 of variance for generated `.gmo' files. With `--omit-header', two 2462 invocations of `xgettext' on the same files with the same options 2463 at different times are guaranteed to produce the same results. 2464 2465`--copyright-holder=STRING' 2466 Set the copyright holder in the output. STRING should be the 2467 copyright holder of the surrounding package. (Note that the msgstr 2468 strings, extracted from the package's sources, belong to the 2469 copyright holder of the package.) Translators are expected to 2470 transfer or disclaim the copyright for their translations, so that 2471 package maintainers can distribute them without legal risk. If 2472 STRING is empty, the output files are marked as being in the 2473 public domain; in this case, the translators are expected to 2474 disclaim their copyright, again so that package maintainers can 2475 distribute them without legal risk. 2476 2477 The default value for STRING is the Free Software Foundation, Inc., 2478 simply because `xgettext' was first used in the GNU project. 2479 2480`--foreign-user' 2481 Omit FSF copyright in output. This option is equivalent to 2482 `--copyright-holder='''. It can be useful for packages outside 2483 the GNU project that want their translations to be in the public 2484 domain. 2485 2486`--msgid-bugs-address=EMAIL@ADDRESS' 2487 Set the reporting address for msgid bugs. This is the email 2488 address or URL to which the translators shall report bugs in the 2489 untranslated strings: 2490 2491 - Strings which are not entire sentences, see the maintainer 2492 guidelines in *Note Preparing Strings::. 2493 2494 - Strings which use unclear terms or require additional context 2495 to be understood. 2496 2497 - Strings which make invalid assumptions about notation of 2498 date, time or money. 2499 2500 - Pluralisation problems. 2501 2502 - Incorrect English spelling. 2503 2504 - Incorrect formatting. 2505 2506 It can be your email address, or a mailing list address where 2507 translators can write to without being subscribed, or the URL of a 2508 web page through which the translators can contact you. 2509 2510 The default value is empty, which means that translators will be 2511 clueless! Don't forget to specify this option. 2512 2513`-m [STRING]' 2514`--msgstr-prefix[=STRING]' 2515 Use STRING (or "" if not specified) as prefix for msgstr entries. 2516 2517`-M [STRING]' 2518`--msgstr-suffix[=STRING]' 2519 Use STRING (or "" if not specified) as suffix for msgstr entries. 2520 2521 25225.1.8 Informative output 2523------------------------ 2524 2525`-h' 2526`--help' 2527 Display this help and exit. 2528 2529`-V' 2530`--version' 2531 Output version information and exit. 2532 2533 2534 2535File: gettext.info, Node: Creating, Next: Updating, Prev: Template, Up: Top 2536 25376 Creating a New PO File 2538************************ 2539 2540When starting a new translation, the translator creates a file called 2541`LANG.po', as a copy of the `PACKAGE.pot' template file with 2542modifications in the initial comments (at the beginning of the file) 2543and in the header entry (the first entry, near the beginning of the 2544file). 2545 2546 The easiest way to do so is by use of the `msginit' program. For 2547example: 2548 2549 $ cd PACKAGE-VERSION 2550 $ cd po 2551 $ msginit 2552 2553 The alternative way is to do the copy and modifications by hand. To 2554do so, the translator copies `PACKAGE.pot' to `LANG.po'. Then she 2555modifies the initial comments and the header entry of this file. 2556 2557* Menu: 2558 2559* msginit Invocation:: Invoking the `msginit' Program 2560* Header Entry:: Filling in the Header Entry 2561 2562 2563File: gettext.info, Node: msginit Invocation, Next: Header Entry, Prev: Creating, Up: Creating 2564 25656.1 Invoking the `msginit' Program 2566================================== 2567 2568 msginit [OPTION] 2569 2570 The `msginit' program creates a new PO file, initializing the meta 2571information with values from the user's environment. 2572 25736.1.1 Input file location 2574------------------------- 2575 2576`-i INPUTFILE' 2577`--input=INPUTFILE' 2578 Input POT file. 2579 2580 2581 If no INPUTFILE is given, the current directory is searched for the 2582POT file. If it is `-', standard input is read. 2583 25846.1.2 Output file location 2585-------------------------- 2586 2587`-o FILE' 2588`--output-file=FILE' 2589 Write output to specified PO file. 2590 2591 2592 If no output file is given, it depends on the `--locale' option or 2593the user's locale setting. If it is `-', the results are written to 2594standard output. 2595 25966.1.3 Input file syntax 2597----------------------- 2598 2599`-P' 2600`--properties-input' 2601 Assume the input file is a Java ResourceBundle in Java 2602 `.properties' syntax, not in PO file syntax. 2603 2604`--stringtable-input' 2605 Assume the input file is a NeXTstep/GNUstep localized resource 2606 file in `.strings' syntax, not in PO file syntax. 2607 2608 26096.1.4 Output details 2610-------------------- 2611 2612`-l LL_CC' 2613`--locale=LL_CC' 2614 Set target locale. LL should be a language code, and CC should be 2615 a country code. The command `locale -a' can be used to output a 2616 list of all installed locales. The default is the user's locale 2617 setting. 2618 2619`--no-translator' 2620 Declares that the PO file will not have a human translator and is 2621 instead automatically generated. 2622 2623`-p' 2624`--properties-output' 2625 Write out a Java ResourceBundle in Java `.properties' syntax. Note 2626 that this file format doesn't support plural forms and silently 2627 drops obsolete messages. 2628 2629`--stringtable-output' 2630 Write out a NeXTstep/GNUstep localized resource file in `.strings' 2631 syntax. Note that this file format doesn't support plural forms. 2632 2633`-w NUMBER' 2634`--width=NUMBER' 2635 Set the output page width. Long strings in the output files will 2636 be split across multiple lines in order to ensure that each line's 2637 width (= number of screen columns) is less or equal to the given 2638 NUMBER. 2639 2640`--no-wrap' 2641 Do not break long message lines. Message lines whose width 2642 exceeds the output page width will not be split into several 2643 lines. Only file reference lines which are wider than the output 2644 page width will be split. 2645 2646 26476.1.5 Informative output 2648------------------------ 2649 2650`-h' 2651`--help' 2652 Display this help and exit. 2653 2654`-V' 2655`--version' 2656 Output version information and exit. 2657 2658 2659 2660File: gettext.info, Node: Header Entry, Prev: msginit Invocation, Up: Creating 2661 26626.2 Filling in the Header Entry 2663=============================== 2664 2665The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and "FIRST AUTHOR 2666<EMAIL@ADDRESS>, YEAR" ought to be replaced by sensible information. 2667This can be done in any text editor; if Emacs is used and it switched 2668to PO mode automatically (because it has recognized the file's suffix), 2669you can disable it by typing `M-x fundamental-mode'. 2670 2671 Modifying the header entry can already be done using PO mode: in 2672Emacs, type `M-x po-mode RET' and then `RET' again to start editing the 2673entry. You should fill in the following fields. 2674 2675Project-Id-Version 2676 This is the name and version of the package. 2677 2678Report-Msgid-Bugs-To 2679 This has already been filled in by `xgettext'. It contains an 2680 email address or URL where you can report bugs in the untranslated 2681 strings: 2682 2683 - Strings which are not entire sentences, see the maintainer 2684 guidelines in *Note Preparing Strings::. 2685 2686 - Strings which use unclear terms or require additional context 2687 to be understood. 2688 2689 - Strings which make invalid assumptions about notation of 2690 date, time or money. 2691 2692 - Pluralisation problems. 2693 2694 - Incorrect English spelling. 2695 2696 - Incorrect formatting. 2697 2698POT-Creation-Date 2699 This has already been filled in by `xgettext'. 2700 2701PO-Revision-Date 2702 You don't need to fill this in. It will be filled by the PO file 2703 editor when you save the file. 2704 2705Last-Translator 2706 Fill in your name and email address (without double quotes). 2707 2708Language-Team 2709 Fill in the English name of the language, and the email address or 2710 homepage URL of the language team you are part of. 2711 2712 Before starting a translation, it is a good idea to get in touch 2713 with your translation team, not only to make sure you don't do 2714 duplicated work, but also to coordinate difficult linguistic 2715 issues. 2716 2717 In the Free Translation Project, each translation team has its own 2718 mailing list. The up-to-date list of teams can be found at the 2719 Free Translation Project's homepage, 2720 `http://www.iro.umontreal.ca/contrib/po/HTML/', in the "National 2721 teams" area. 2722 2723Content-Type 2724 Replace `CHARSET' with the character encoding used for your 2725 language, in your locale, or UTF-8. This field is needed for 2726 correct operation of the `msgmerge' and `msgfmt' programs, as well 2727 as for users whose locale's character encoding differs from yours 2728 (see *Note Charset conversion::). 2729 2730 You get the character encoding of your locale by running the shell 2731 command `locale charmap'. If the result is `C' or 2732 `ANSI_X3.4-1968', which is equivalent to `ASCII' (= `US-ASCII'), 2733 it means that your locale is not correctly configured. In this 2734 case, ask your translation team which charset to use. `ASCII' is 2735 not usable for any language except Latin. 2736 2737 Because the PO files must be portable to operating systems with 2738 less advanced internationalization facilities, the character 2739 encodings that can be used are limited to those supported by both 2740 GNU `libc' and GNU `libiconv'. These are: `ASCII', `ISO-8859-1', 2741 `ISO-8859-2', `ISO-8859-3', `ISO-8859-4', `ISO-8859-5', 2742 `ISO-8859-6', `ISO-8859-7', `ISO-8859-8', `ISO-8859-9', 2743 `ISO-8859-13', `ISO-8859-14', `ISO-8859-15', `KOI8-R', `KOI8-U', 2744 `KOI8-T', `CP850', `CP866', `CP874', `CP932', `CP949', `CP950', 2745 `CP1250', `CP1251', `CP1252', `CP1253', `CP1254', `CP1255', 2746 `CP1256', `CP1257', `GB2312', `EUC-JP', `EUC-KR', `EUC-TW', 2747 `BIG5', `BIG5-HKSCS', `GBK', `GB18030', `SHIFT_JIS', `JOHAB', 2748 `TIS-620', `VISCII', `GEORGIAN-PS', `UTF-8'. 2749 2750 In the GNU system, the following encodings are frequently used for 2751 the corresponding languages. 2752 2753 * `ISO-8859-1' for Afrikaans, Albanian, Basque, Breton, 2754 Catalan, Cornish, Danish, Dutch, English, Estonian, Faroese, 2755 Finnish, French, Galician, German, Greenlandic, Icelandic, 2756 Indonesian, Irish, Italian, Malay, Manx, Norwegian, Occitan, 2757 Portuguese, Spanish, Swedish, Tagalog, Uzbek, Walloon, 2758 2759 * `ISO-8859-2' for Bosnian, Croatian, Czech, Hungarian, Polish, 2760 Romanian, Serbian, Slovak, Slovenian, 2761 2762 * `ISO-8859-3' for Maltese, 2763 2764 * `ISO-8859-5' for Macedonian, Serbian, 2765 2766 * `ISO-8859-6' for Arabic, 2767 2768 * `ISO-8859-7' for Greek, 2769 2770 * `ISO-8859-8' for Hebrew, 2771 2772 * `ISO-8859-9' for Turkish, 2773 2774 * `ISO-8859-13' for Latvian, Lithuanian, Maori, 2775 2776 * `ISO-8859-14' for Welsh, 2777 2778 * `ISO-8859-15' for Basque, Catalan, Dutch, English, Finnish, 2779 French, Galician, German, Irish, Italian, Portuguese, 2780 Spanish, Swedish, Walloon, 2781 2782 * `KOI8-R' for Russian, 2783 2784 * `KOI8-U' for Ukrainian, 2785 2786 * `KOI8-T' for Tajik, 2787 2788 * `CP1251' for Bulgarian, Byelorussian, 2789 2790 * `GB2312', `GBK', `GB18030' for simplified writing of Chinese, 2791 2792 * `BIG5', `BIG5-HKSCS' for traditional writing of Chinese, 2793 2794 * `EUC-JP' for Japanese, 2795 2796 * `EUC-KR' for Korean, 2797 2798 * `TIS-620' for Thai, 2799 2800 * `GEORGIAN-PS' for Georgian, 2801 2802 * `UTF-8' for any language, including those listed above. 2803 2804 When single quote characters or double quote characters are used in 2805 translations for your language, and your locale's encoding is one 2806 of the ISO-8859-* charsets, it is best if you create your PO files 2807 in UTF-8 encoding, instead of your locale's encoding. This is 2808 because in UTF-8 the real quote characters can be represented 2809 (single quote characters: U+2018, U+2019, double quote characters: 2810 U+201C, U+201D), whereas none of ISO-8859-* charsets has them all. 2811 Users in UTF-8 locales will see the real quote characters, 2812 whereas users in ISO-8859-* locales will see the vertical 2813 apostrophe and the vertical double quote instead (because that's 2814 what the character set conversion will transliterate them to). 2815 2816 To enter such quote characters under X11, you can change your 2817 keyboard mapping using the `xmodmap' program. The X11 names of 2818 the quote characters are "leftsinglequotemark", 2819 "rightsinglequotemark", "leftdoublequotemark", 2820 "rightdoublequotemark", "singlelowquotemark", "doublelowquotemark". 2821 2822 Note that only recent versions of GNU Emacs support the UTF-8 2823 encoding: Emacs 20 with Mule-UCS, and Emacs 21. As of January 2824 2001, XEmacs doesn't support the UTF-8 encoding. 2825 2826 The character encoding name can be written in either upper or 2827 lower case. Usually upper case is preferred. 2828 2829Content-Transfer-Encoding 2830 Set this to `8bit'. 2831 2832Plural-Forms 2833 This field is optional. It is only needed if the PO file has 2834 plural forms. You can find them by searching for the 2835 `msgid_plural' keyword. The format of the plural forms field is 2836 described in *Note Plural forms::. 2837 2838 2839File: gettext.info, Node: Updating, Next: Editing, Prev: Creating, Up: Top 2840 28417 Updating Existing PO Files 2842**************************** 2843 2844* Menu: 2845 2846* msgmerge Invocation:: Invoking the `msgmerge' Program 2847 2848 2849File: gettext.info, Node: msgmerge Invocation, Prev: Updating, Up: Updating 2850 28517.1 Invoking the `msgmerge' Program 2852=================================== 2853 2854 msgmerge [OPTION] DEF.po REF.pot 2855 2856 The `msgmerge' program merges two Uniforum style .po files together. 2857The DEF.po file is an existing PO file with translations which will be 2858taken over to the newly created file as long as they still match; 2859comments will be preserved, but extracted comments and file positions 2860will be discarded. The REF.pot file is the last created PO file with 2861up-to-date source references but old translations, or a PO Template file 2862(generally created by `xgettext'); any translations or comments in the 2863file will be discarded, however dot comments and file positions will be 2864preserved. Where an exact match cannot be found, fuzzy matching is 2865used to produce better results. 2866 28677.1.1 Input file location 2868------------------------- 2869 2870`DEF.po' 2871 Translations referring to old sources. 2872 2873`REF.pot' 2874 References to the new sources. 2875 2876`-D DIRECTORY' 2877`--directory=DIRECTORY' 2878 Add DIRECTORY to the list of directories. Source files are 2879 searched relative to this list of directories. The resulting `.po' 2880 file will be written relative to the current directory, though. 2881 2882`-C FILE' 2883`--compendium=FILE' 2884 Specify an additional library of message translations. *Note 2885 Compendium::. This option may be specified more than once. 2886 2887 28887.1.2 Operation mode 2889-------------------- 2890 2891`-U' 2892`--update' 2893 Update DEF.po. Do nothing if DEF.po is already up to date. 2894 2895 28967.1.3 Output file location 2897-------------------------- 2898 2899`-o FILE' 2900`--output-file=FILE' 2901 Write output to specified file. 2902 2903 2904 The results are written to standard output if no output file is 2905specified or if it is `-'. 2906 29077.1.4 Output file location in update mode 2908----------------------------------------- 2909 2910The result is written back to DEF.po. 2911 2912`--backup=CONTROL' 2913 Make a backup of DEF.po 2914 2915`--suffix=SUFFIX' 2916 Override the usual backup suffix. 2917 2918 2919 The version control method may be selected via the `--backup' option 2920or through the `VERSION_CONTROL' environment variable. Here are the 2921values: 2922 2923`none' 2924`off' 2925 Never make backups (even if `--backup' is given). 2926 2927`numbered' 2928`t' 2929 Make numbered backups. 2930 2931`existing' 2932`nil' 2933 Make numbered backups if numbered backups for this file already 2934 exist, otherwise make simple backups. 2935 2936`simple' 2937`never' 2938 Always make simple backups. 2939 2940 2941 The backup suffix is `~', unless set with `--suffix' or the 2942`SIMPLE_BACKUP_SUFFIX' environment variable. 2943 29447.1.5 Operation modifiers 2945------------------------- 2946 2947`-m' 2948`--multi-domain' 2949 Apply REF.pot to each of the domains in DEF.po. 2950 2951`-N' 2952`--no-fuzzy-matching' 2953 Do not use fuzzy matching when an exact match is not found. This 2954 may speed up the operation considerably. 2955 2956`--previous' 2957 Keep the previous msgids of translated messages, marked with `#|', 2958 when adding the fuzzy marker to such messages. 2959 29607.1.6 Input file syntax 2961----------------------- 2962 2963`-P' 2964`--properties-input' 2965 Assume the input files are Java ResourceBundles in Java 2966 `.properties' syntax, not in PO file syntax. 2967 2968`--stringtable-input' 2969 Assume the input files are NeXTstep/GNUstep localized resource 2970 files in `.strings' syntax, not in PO file syntax. 2971 2972 29737.1.7 Output details 2974-------------------- 2975 2976`--force-po' 2977 Always write an output file even if it contains no message. 2978 2979`-i' 2980`--indent' 2981 Write the .po file using indented style. 2982 2983`--no-location' 2984 Do not write `#: FILENAME:LINE' lines. 2985 2986`--add-location' 2987 Generate `#: FILENAME:LINE' lines (default). 2988 2989`--strict' 2990 Write out a strict Uniforum conforming PO file. Note that this 2991 Uniforum format should be avoided because it doesn't support the 2992 GNU extensions. 2993 2994`-p' 2995`--properties-output' 2996 Write out a Java ResourceBundle in Java `.properties' syntax. Note 2997 that this file format doesn't support plural forms and silently 2998 drops obsolete messages. 2999 3000`--stringtable-output' 3001 Write out a NeXTstep/GNUstep localized resource file in `.strings' 3002 syntax. Note that this file format doesn't support plural forms. 3003 3004`-w NUMBER' 3005`--width=NUMBER' 3006 Set the output page width. Long strings in the output files will 3007 be split across multiple lines in order to ensure that each line's 3008 width (= number of screen columns) is less or equal to the given 3009 NUMBER. 3010 3011`--no-wrap' 3012 Do not break long message lines. Message lines whose width 3013 exceeds the output page width will not be split into several 3014 lines. Only file reference lines which are wider than the output 3015 page width will be split. 3016 3017`-s' 3018`--sort-output' 3019 Generate sorted output. Note that using this option makes it much 3020 harder for the translator to understand each message's context. 3021 3022`-F' 3023`--sort-by-file' 3024 Sort output by file location. 3025 3026 30277.1.8 Informative output 3028------------------------ 3029 3030`-h' 3031`--help' 3032 Display this help and exit. 3033 3034`-V' 3035`--version' 3036 Output version information and exit. 3037 3038`-v' 3039`--verbose' 3040 Increase verbosity level. 3041 3042`-q' 3043`--quiet' 3044`--silent' 3045 Suppress progress indicators. 3046 3047 3048 3049File: gettext.info, Node: Editing, Next: Manipulating, Prev: Updating, Up: Top 3050 30518 Editing PO Files 3052****************** 3053 3054* Menu: 3055 3056* KBabel:: KDE's PO File Editor 3057* Gtranslator:: GNOME's PO File Editor 3058* PO Mode:: Emacs's PO File Editor 3059 3060 3061File: gettext.info, Node: KBabel, Next: Gtranslator, Prev: Editing, Up: Editing 3062 30638.1 KDE's PO File Editor 3064======================== 3065 3066 3067File: gettext.info, Node: Gtranslator, Next: PO Mode, Prev: KBabel, Up: Editing 3068 30698.2 GNOME's PO File Editor 3070========================== 3071 3072 3073File: gettext.info, Node: PO Mode, Prev: Gtranslator, Up: Editing 3074 30758.3 Emacs's PO File Editor 3076========================== 3077 3078For those of you being the lucky users of Emacs, PO mode has been 3079specifically created for providing a cozy environment for editing or 3080modifying PO files. While editing a PO file, PO mode allows for the 3081easy browsing of auxiliary and compendium PO files, as well as for 3082following references into the set of C program sources from which PO 3083files have been derived. It has a few special features, among which 3084are the interactive marking of program strings as translatable, and the 3085validation of PO files with easy repositioning to PO file lines showing 3086errors. 3087 3088 For the beginning, besides main PO mode commands (*note Main PO 3089Commands::), you should know how to move between entries (*note Entry 3090Positioning::), and how to handle untranslated entries (*note 3091Untranslated Entries::). 3092 3093* Menu: 3094 3095* Installation:: Completing GNU `gettext' Installation 3096* Main PO Commands:: Main Commands 3097* Entry Positioning:: Entry Positioning 3098* Normalizing:: Normalizing Strings in Entries 3099* Translated Entries:: Translated Entries 3100* Fuzzy Entries:: Fuzzy Entries 3101* Untranslated Entries:: Untranslated Entries 3102* Obsolete Entries:: Obsolete Entries 3103* Modifying Translations:: Modifying Translations 3104* Modifying Comments:: Modifying Comments 3105* Subedit:: Mode for Editing Translations 3106* C Sources Context:: C Sources Context 3107* Auxiliary:: Consulting Auxiliary PO Files 3108* Compendium:: Using Translation Compendia 3109 3110 3111File: gettext.info, Node: Installation, Next: Main PO Commands, Prev: PO Mode, Up: PO Mode 3112 31138.3.1 Completing GNU `gettext' Installation 3114------------------------------------------- 3115 3116Once you have received, unpacked, configured and compiled the GNU 3117`gettext' distribution, the `make install' command puts in place the 3118programs `xgettext', `msgfmt', `gettext', and `msgmerge', as well as 3119their available message catalogs. To top off a comfortable 3120installation, you might also want to make the PO mode available to your 3121Emacs users. 3122 3123 During the installation of the PO mode, you might want to modify your 3124file `.emacs', once and for all, so it contains a few lines looking 3125like: 3126 3127 (setq auto-mode-alist 3128 (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist)) 3129 (autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t) 3130 3131 Later, whenever you edit some `.po' file, or any file having the 3132string `.po.' within its name, Emacs loads `po-mode.elc' (or 3133`po-mode.el') as needed, and automatically activates PO mode commands 3134for the associated buffer. The string _PO_ appears in the mode line 3135for any buffer for which PO mode is active. Many PO files may be 3136active at once in a single Emacs session. 3137 3138 If you are using Emacs version 20 or newer, and have already 3139installed the appropriate international fonts on your system, you may 3140also tell Emacs how to determine automatically the coding system of 3141every PO file. This will often (but not always) cause the necessary 3142fonts to be loaded and used for displaying the translations on your 3143Emacs screen. For this to happen, add the lines: 3144 3145 (modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\." 3146 'po-find-file-coding-system) 3147 (autoload 'po-find-file-coding-system "po-mode") 3148 3149to your `.emacs' file. If, with this, you still see boxes instead of 3150international characters, try a different font set (via Shift Mouse 3151button 1). 3152 3153 3154File: gettext.info, Node: Main PO Commands, Next: Entry Positioning, Prev: Installation, Up: PO Mode 3155 31568.3.2 Main PO mode Commands 3157--------------------------- 3158 3159After setting up Emacs with something similar to the lines in *Note 3160Installation::, PO mode is activated for a window when Emacs finds a PO 3161file in that window. This puts the window read-only and establishes a 3162po-mode-map, which is a genuine Emacs mode, in a way that is not derived 3163from text mode in any way. Functions found on `po-mode-hook', if any, 3164will be executed. 3165 3166 When PO mode is active in a window, the letters `PO' appear in the 3167mode line for that window. The mode line also displays how many 3168entries of each kind are held in the PO file. For example, the string 3169`132t+3f+10u+2o' would tell the translator that the PO mode contains 3170132 translated entries (*note Translated Entries::, 3 fuzzy entries 3171(*note Fuzzy Entries::), 10 untranslated entries (*note Untranslated 3172Entries::) and 2 obsolete entries (*note Obsolete Entries::). 3173Zero-coefficients items are not shown. So, in this example, if the 3174fuzzy entries were unfuzzied, the untranslated entries were translated 3175and the obsolete entries were deleted, the mode line would merely 3176display `145t' for the counters. 3177 3178 The main PO commands are those which do not fit into the other 3179categories of subsequent sections. These allow for quitting PO mode or 3180for managing windows in special ways. 3181 3182`_' 3183 Undo last modification to the PO file (`po-undo'). 3184 3185`Q' 3186 Quit processing and save the PO file (`po-quit'). 3187 3188`q' 3189 Quit processing, possibly after confirmation 3190 (`po-confirm-and-quit'). 3191 3192`0' 3193 Temporary leave the PO file window (`po-other-window'). 3194 3195`?' 3196`h' 3197 Show help about PO mode (`po-help'). 3198 3199`=' 3200 Give some PO file statistics (`po-statistics'). 3201 3202`V' 3203 Batch validate the format of the whole PO file (`po-validate'). 3204 3205 3206 The command `_' (`po-undo') interfaces to the Emacs _undo_ facility. 3207*Note Undoing Changes: (emacs)Undo. Each time `U' is typed, 3208modifications which the translator did to the PO file are undone a 3209little more. For the purpose of undoing, each PO mode command is 3210atomic. This is especially true for the `<RET>' command: the whole 3211edition made by using a single use of this command is undone at once, 3212even if the edition itself implied several actions. However, while in 3213the editing window, one can undo the edition work quite parsimoniously. 3214 3215 The commands `Q' (`po-quit') and `q' (`po-confirm-and-quit') are 3216used when the translator is done with the PO file. The former is a bit 3217less verbose than the latter. If the file has been modified, it is 3218saved to disk first. In both cases, and prior to all this, the 3219commands check if any untranslated messages remain in the PO file and, 3220if so, the translator is asked if she really wants to leave off working 3221with this PO file. This is the preferred way of getting rid of an 3222Emacs PO file buffer. Merely killing it through the usual command 3223`C-x k' (`kill-buffer') is not the tidiest way to proceed. 3224 3225 The command `0' (`po-other-window') is another, softer way, to leave 3226PO mode, temporarily. It just moves the cursor to some other Emacs 3227window, and pops one if necessary. For example, if the translator just 3228got PO mode to show some source context in some other, she might 3229discover some apparent bug in the program source that needs correction. 3230This command allows the translator to change sex, become a programmer, 3231and have the cursor right into the window containing the program she 3232(or rather _he_) wants to modify. By later getting the cursor back in 3233the PO file window, or by asking Emacs to edit this file once again, PO 3234mode is then recovered. 3235 3236 The command `h' (`po-help') displays a summary of all available PO 3237mode commands. The translator should then type any character to resume 3238normal PO mode operations. The command `?' has the same effect as `h'. 3239 3240 The command `=' (`po-statistics') computes the total number of 3241entries in the PO file, the ordinal of the current entry (counted from 32421), the number of untranslated entries, the number of obsolete entries, 3243and displays all these numbers. 3244 3245 The command `V' (`po-validate') launches `msgfmt' in checking and 3246verbose mode over the current PO file. This command first offers to 3247save the current PO file on disk. The `msgfmt' tool, from GNU 3248`gettext', has the purpose of creating a MO file out of a PO file, and 3249PO mode uses the features of this program for checking the overall 3250format of a PO file, as well as all individual entries. 3251 3252 The program `msgfmt' runs asynchronously with Emacs, so the 3253translator regains control immediately while her PO file is being 3254studied. Error output is collected in the Emacs `*compilation*' buffer, 3255displayed in another window. The regular Emacs command `C-x`' 3256(`next-error'), as well as other usual compile commands, allow the 3257translator to reposition quickly to the offending parts of the PO file. 3258Once the cursor is on the line in error, the translator may decide on 3259any PO mode action which would help correcting the error. 3260 3261 3262File: gettext.info, Node: Entry Positioning, Next: Normalizing, Prev: Main PO Commands, Up: PO Mode 3263 32648.3.3 Entry Positioning 3265----------------------- 3266 3267The cursor in a PO file window is almost always part of an entry. The 3268only exceptions are the special case when the cursor is after the last 3269entry in the file, or when the PO file is empty. The entry where the 3270cursor is found to be is said to be the current entry. Many PO mode 3271commands operate on the current entry, so moving the cursor does more 3272than allowing the translator to browse the PO file, this also selects 3273on which entry commands operate. 3274 3275 Some PO mode commands alter the position of the cursor in a 3276specialized way. A few of those special purpose positioning are 3277described here, the others are described in following sections (for a 3278complete list try `C-h m'): 3279 3280`.' 3281 Redisplay the current entry (`po-current-entry'). 3282 3283`n' 3284 Select the entry after the current one (`po-next-entry'). 3285 3286`p' 3287 Select the entry before the current one (`po-previous-entry'). 3288 3289`<' 3290 Select the first entry in the PO file (`po-first-entry'). 3291 3292`>' 3293 Select the last entry in the PO file (`po-last-entry'). 3294 3295`m' 3296 Record the location of the current entry for later use 3297 (`po-push-location'). 3298 3299`r' 3300 Return to a previously saved entry location (`po-pop-location'). 3301 3302`x' 3303 Exchange the current entry location with the previously saved one 3304 (`po-exchange-location'). 3305 3306 3307 Any Emacs command able to reposition the cursor may be used to 3308select the current entry in PO mode, including commands which move by 3309characters, lines, paragraphs, screens or pages, and search commands. 3310However, there is a kind of standard way to display the current entry 3311in PO mode, which usual Emacs commands moving the cursor do not 3312especially try to enforce. The command `.' (`po-current-entry') has 3313the sole purpose of redisplaying the current entry properly, after the 3314current entry has been changed by means external to PO mode, or the 3315Emacs screen otherwise altered. 3316 3317 It is yet to be decided if PO mode helps the translator, or otherwise 3318irritates her, by forcing a rigid window disposition while she is doing 3319her work. We originally had quite precise ideas about how windows 3320should behave, but on the other hand, anyone used to Emacs is often 3321happy to keep full control. Maybe a fixed window disposition might be 3322offered as a PO mode option that the translator might activate or 3323deactivate at will, so it could be offered on an experimental basis. 3324If nobody feels a real need for using it, or a compulsion for writing 3325it, we should drop this whole idea. The incentive for doing it should 3326come from translators rather than programmers, as opinions from an 3327experienced translator are surely more worth to me than opinions from 3328programmers _thinking_ about how _others_ should do translation. 3329 3330 The commands `n' (`po-next-entry') and `p' (`po-previous-entry') 3331move the cursor the entry following, or preceding, the current one. If 3332`n' is given while the cursor is on the last entry of the PO file, or 3333if `p' is given while the cursor is on the first entry, no move is done. 3334 3335 The commands `<' (`po-first-entry') and `>' (`po-last-entry') move 3336the cursor to the first entry, or last entry, of the PO file. When the 3337cursor is located past the last entry in a PO file, most PO mode 3338commands will return an error saying `After last entry'. Moreover, the 3339commands `<' and `>' have the special property of being able to work 3340even when the cursor is not into some PO file entry, and one may use 3341them for nicely correcting this situation. But even these commands 3342will fail on a truly empty PO file. There are development plans for 3343the PO mode for it to interactively fill an empty PO file from sources. 3344*Note Marking::. 3345 3346 The translator may decide, before working at the translation of a 3347particular entry, that she needs to browse the remainder of the PO 3348file, maybe for finding the terminology or phraseology used in related 3349entries. She can of course use the standard Emacs idioms for saving 3350the current cursor location in some register, and use that register for 3351getting back, or else, use the location ring. 3352 3353 PO mode offers another approach, by which cursor locations may be 3354saved onto a special stack. The command `m' (`po-push-location') 3355merely adds the location of current entry to the stack, pushing the 3356already saved locations under the new one. The command `r' 3357(`po-pop-location') consumes the top stack element and repositions the 3358cursor to the entry associated with that top element. This position is 3359then lost, for the next `r' will move the cursor to the previously 3360saved location, and so on until no locations remain on the stack. 3361 3362 If the translator wants the position to be kept on the location 3363stack, maybe for taking a look at the entry associated with the top 3364element, then go elsewhere with the intent of getting back later, she 3365ought to use `m' immediately after `r'. 3366 3367 The command `x' (`po-exchange-location') simultaneously repositions 3368the cursor to the entry associated with the top element of the stack of 3369saved locations, and replaces that top element with the location of the 3370current entry before the move. Consequently, repeating the `x' command 3371toggles alternatively between two entries. For achieving this, the 3372translator will position the cursor on the first entry, use `m', then 3373position to the second entry, and merely use `x' for making the switch. 3374 3375 3376File: gettext.info, Node: Normalizing, Next: Translated Entries, Prev: Entry Positioning, Up: PO Mode 3377 33788.3.4 Normalizing Strings in Entries 3379------------------------------------ 3380 3381There are many different ways for encoding a particular string into a 3382PO file entry, because there are so many different ways to split and 3383quote multi-line strings, and even, to represent special characters by 3384backslashed escaped sequences. Some features of PO mode rely on the 3385ability for PO mode to scan an already existing PO file for a 3386particular string encoded into the `msgid' field of some entry. Even 3387if PO mode has internally all the built-in machinery for implementing 3388this recognition easily, doing it fast is technically difficult. To 3389facilitate a solution to this efficiency problem, we decided on a 3390canonical representation for strings. 3391 3392 A conventional representation of strings in a PO file is currently 3393under discussion, and PO mode experiments with a canonical 3394representation. Having both `xgettext' and PO mode converging towards 3395a uniform way of representing equivalent strings would be useful, as 3396the internal normalization needed by PO mode could be automatically 3397satisfied when using `xgettext' from GNU `gettext'. An explicit PO 3398mode normalization should then be only necessary for PO files imported 3399from elsewhere, or for when the convention itself evolves. 3400 3401 So, for achieving normalization of at least the strings of a given 3402PO file needing a canonical representation, the following PO mode 3403command is available: 3404 3405`M-x po-normalize' 3406 Tidy the whole PO file by making entries more uniform. 3407 3408 3409 The special command `M-x po-normalize', which has no associated 3410keys, revises all entries, ensuring that strings of both original and 3411translated entries use uniform internal quoting in the PO file. It 3412also removes any crumb after the last entry. This command may be 3413useful for PO files freshly imported from elsewhere, or if we ever 3414improve on the canonical quoting format we use. This canonical format 3415is not only meant for getting cleaner PO files, but also for greatly 3416speeding up `msgid' string lookup for some other PO mode commands. 3417 3418 `M-x po-normalize' presently makes three passes over the entries. 3419The first implements heuristics for converting PO files for GNU 3420`gettext' 0.6 and earlier, in which `msgid' and `msgstr' fields were 3421using K&R style C string syntax for multi-line strings. These 3422heuristics may fail for comments not related to obsolete entries and 3423ending with a backslash; they also depend on subsequent passes for 3424finalizing the proper commenting of continued lines for obsolete 3425entries. This first pass might disappear once all oldish PO files 3426would have been adjusted. The second and third pass normalize all 3427`msgid' and `msgstr' strings respectively. They also clean out those 3428trailing backslashes used by XView's `msgfmt' for continued lines. 3429 3430 Having such an explicit normalizing command allows for importing PO 3431files from other sources, but also eases the evolution of the current 3432convention, evolution driven mostly by aesthetic concerns, as of now. 3433It is easy to make suggested adjustments at a later time, as the 3434normalizing command and eventually, other GNU `gettext' tools should 3435greatly automate conformance. A description of the canonical string 3436format is given below, for the particular benefit of those not having 3437Emacs handy, and who would nevertheless want to handcraft their PO 3438files in nice ways. 3439 3440 Right now, in PO mode, strings are single line or multi-line. A 3441string goes multi-line if and only if it has _embedded_ newlines, that 3442is, if it matches `[^\n]\n+[^\n]'. So, we would have: 3443 3444 msgstr "\n\nHello, world!\n\n\n" 3445 3446 but, replacing the space by a newline, this becomes: 3447 3448 msgstr "" 3449 "\n" 3450 "\n" 3451 "Hello,\n" 3452 "world!\n" 3453 "\n" 3454 "\n" 3455 3456 We are deliberately using a caricatural example, here, to make the 3457point clearer. Usually, multi-lines are not that bad looking. It is 3458probable that we will implement the following suggestion. We might 3459lump together all initial newlines into the empty string, and also all 3460newlines introducing empty lines (that is, for N > 1, the N-1'th last 3461newlines would go together on a separate string), so making the 3462previous example appear: 3463 3464 msgstr "\n\n" 3465 "Hello,\n" 3466 "world!\n" 3467 "\n\n" 3468 3469 There are a few yet undecided little points about string 3470normalization, to be documented in this manual, once these questions 3471settle. 3472 3473 3474File: gettext.info, Node: Translated Entries, Next: Fuzzy Entries, Prev: Normalizing, Up: PO Mode 3475 34768.3.5 Translated Entries 3477------------------------ 3478 3479Each PO file entry for which the `msgstr' field has been filled with a 3480translation, and which is not marked as fuzzy (*note Fuzzy Entries::), 3481is said to be a "translated" entry. Only translated entries will later 3482be compiled by GNU `msgfmt' and become usable in programs. Other entry 3483types will be excluded; translation will not occur for them. 3484 3485 Some commands are more specifically related to translated entry 3486processing. 3487 3488`t' 3489 Find the next translated entry (`po-next-translated-entry'). 3490 3491`T' 3492 Find the previous translated entry 3493 (`po-previous-translated-entry'). 3494 3495 3496 The commands `t' (`po-next-translated-entry') and `T' 3497(`po-previous-translated-entry') move forwards or backwards, chasing 3498for an translated entry. If none is found, the search is extended and 3499wraps around in the PO file buffer. 3500 3501 Translated entries usually result from the translator having edited 3502in a translation for them, *Note Modifying Translations::. However, if 3503the variable `po-auto-fuzzy-on-edit' is not `nil', the entry having 3504received a new translation first becomes a fuzzy entry, which ought to 3505be later unfuzzied before becoming an official, genuine translated 3506entry. *Note Fuzzy Entries::. 3507 3508 3509File: gettext.info, Node: Fuzzy Entries, Next: Untranslated Entries, Prev: Translated Entries, Up: PO Mode 3510 35118.3.6 Fuzzy Entries 3512------------------- 3513 3514Each PO file entry may have a set of "attributes", which are qualities 3515given a name and explicitly associated with the translation, using a 3516special system comment. One of these attributes has the name `fuzzy', 3517and entries having this attribute are said to have a fuzzy translation. 3518They are called fuzzy entries, for short. 3519 3520 Fuzzy entries, even if they account for translated entries for most 3521other purposes, usually call for revision by the translator. Those may 3522be produced by applying the program `msgmerge' to update an older 3523translated PO files according to a new PO template file, when this tool 3524hypothesises that some new `msgid' has been modified only slightly out 3525of an older one, and chooses to pair what it thinks to be the old 3526translation for the new modified entry. The slight alteration in the 3527original string (the `msgid' string) should often be reflected in the 3528translated string, and this requires the intervention of the 3529translator. For this reason, `msgmerge' might mark some entries as 3530being fuzzy. 3531 3532 Also, the translator may decide herself to mark an entry as fuzzy 3533for her own convenience, when she wants to remember that the entry has 3534to be later revisited. So, some commands are more specifically related 3535to fuzzy entry processing. 3536 3537`z' 3538 Find the next fuzzy entry (`po-next-fuzzy-entry'). 3539 3540`Z' 3541 Find the previous fuzzy entry (`po-previous-fuzzy-entry'). 3542 3543`<TAB>' 3544 Remove the fuzzy attribute of the current entry (`po-unfuzzy'). 3545 3546 3547 The commands `z' (`po-next-fuzzy-entry') and `Z' 3548(`po-previous-fuzzy-entry') move forwards or backwards, chasing for a 3549fuzzy entry. If none is found, the search is extended and wraps around 3550in the PO file buffer. 3551 3552 The command `<TAB>' (`po-unfuzzy') removes the fuzzy attribute 3553associated with an entry, usually leaving it translated. Further, if 3554the variable `po-auto-select-on-unfuzzy' has not the `nil' value, the 3555`<TAB>' command will automatically chase for another interesting entry 3556to work on. The initial value of `po-auto-select-on-unfuzzy' is `nil'. 3557 3558 The initial value of `po-auto-fuzzy-on-edit' is `nil'. However, if 3559the variable `po-auto-fuzzy-on-edit' is set to `t', any entry edited 3560through the `<RET>' command is marked fuzzy, as a way to ensure some 3561kind of double check, later. In this case, the usual paradigm is that 3562an entry becomes fuzzy (if not already) whenever the translator 3563modifies it. If she is satisfied with the translation, she then uses 3564`<TAB>' to pick another entry to work on, clearing the fuzzy attribute 3565on the same blow. If she is not satisfied yet, she merely uses `<SPC>' 3566to chase another entry, leaving the entry fuzzy. 3567 3568 The translator may also use the `<DEL>' command 3569(`po-fade-out-entry') over any translated entry to mark it as being 3570fuzzy, when she wants to easily leave a trace she wants to later return 3571working at this entry. 3572 3573 Also, when time comes to quit working on a PO file buffer with the 3574`q' command, the translator is asked for confirmation, if fuzzy string 3575still exists. 3576 3577 3578File: gettext.info, Node: Untranslated Entries, Next: Obsolete Entries, Prev: Fuzzy Entries, Up: PO Mode 3579 35808.3.7 Untranslated Entries 3581-------------------------- 3582 3583When `xgettext' originally creates a PO file, unless told otherwise, it 3584initializes the `msgid' field with the untranslated string, and leaves 3585the `msgstr' string to be empty. Such entries, having an empty 3586translation, are said to be "untranslated" entries. Later, when the 3587programmer slightly modifies some string right in the program, this 3588change is later reflected in the PO file by the appearance of a new 3589untranslated entry for the modified string. 3590 3591 The usual commands moving from entry to entry consider untranslated 3592entries on the same level as active entries. Untranslated entries are 3593easily recognizable by the fact they end with `msgstr ""'. 3594 3595 The work of the translator might be (quite naively) seen as the 3596process of seeking for an untranslated entry, editing a translation for 3597it, and repeating these actions until no untranslated entries remain. 3598Some commands are more specifically related to untranslated entry 3599processing. 3600 3601`u' 3602 Find the next untranslated entry (`po-next-untranslated-entry'). 3603 3604`U' 3605 Find the previous untranslated entry 3606 (`po-previous-untransted-entry'). 3607 3608`k' 3609 Turn the current entry into an untranslated one (`po-kill-msgstr'). 3610 3611 3612 The commands `u' (`po-next-untranslated-entry') and `U' 3613(`po-previous-untransted-entry') move forwards or backwards, chasing 3614for an untranslated entry. If none is found, the search is extended 3615and wraps around in the PO file buffer. 3616 3617 An entry can be turned back into an untranslated entry by merely 3618emptying its translation, using the command `k' (`po-kill-msgstr'). 3619*Note Modifying Translations::. 3620 3621 Also, when time comes to quit working on a PO file buffer with the 3622`q' command, the translator is asked for confirmation, if some 3623untranslated string still exists. 3624 3625 3626File: gettext.info, Node: Obsolete Entries, Next: Modifying Translations, Prev: Untranslated Entries, Up: PO Mode 3627 36288.3.8 Obsolete Entries 3629---------------------- 3630 3631By "obsolete" PO file entries, we mean those entries which are 3632commented out, usually by `msgmerge' when it found that the translation 3633is not needed anymore by the package being localized. 3634 3635 The usual commands moving from entry to entry consider obsolete 3636entries on the same level as active entries. Obsolete entries are 3637easily recognizable by the fact that all their lines start with `#', 3638even those lines containing `msgid' or `msgstr'. 3639 3640 Commands exist for emptying the translation or reinitializing it to 3641the original untranslated string. Commands interfacing with the kill 3642ring may force some previously saved text into the translation. The 3643user may interactively edit the translation. All these commands may 3644apply to obsolete entries, carefully leaving the entry obsolete after 3645the fact. 3646 3647 Moreover, some commands are more specifically related to obsolete 3648entry processing. 3649 3650`o' 3651 Find the next obsolete entry (`po-next-obsolete-entry'). 3652 3653`O' 3654 Find the previous obsolete entry (`po-previous-obsolete-entry'). 3655 3656`<DEL>' 3657 Make an active entry obsolete, or zap out an obsolete entry 3658 (`po-fade-out-entry'). 3659 3660 3661 The commands `o' (`po-next-obsolete-entry') and `O' 3662(`po-previous-obsolete-entry') move forwards or backwards, chasing for 3663an obsolete entry. If none is found, the search is extended and wraps 3664around in the PO file buffer. 3665 3666 PO mode does not provide ways for un-commenting an obsolete entry 3667and making it active, because this would reintroduce an original 3668untranslated string which does not correspond to any marked string in 3669the program sources. This goes with the philosophy of never 3670introducing useless `msgid' values. 3671 3672 However, it is possible to comment out an active entry, so making it 3673obsolete. GNU `gettext' utilities will later react to the 3674disappearance of a translation by using the untranslated string. The 3675command `<DEL>' (`po-fade-out-entry') pushes the current entry a little 3676further towards annihilation. If the entry is active (it is a 3677translated entry), then it is first made fuzzy. If it is already fuzzy, 3678then the entry is merely commented out, with confirmation. If the entry 3679is already obsolete, then it is completely deleted from the PO file. 3680It is easy to recycle the translation so deleted into some other PO file 3681entry, usually one which is untranslated. *Note Modifying 3682Translations::. 3683 3684 Here is a quite interesting problem to solve for later development of 3685PO mode, for those nights you are not sleepy. The idea would be that 3686PO mode might become bright enough, one of these days, to make good 3687guesses at retrieving the most probable candidate, among all obsolete 3688entries, for initializing the translation of a newly appeared string. 3689I think it might be a quite hard problem to do this algorithmically, as 3690we have to develop good and efficient measures of string similarity. 3691Right now, PO mode completely lets the decision to the translator, when 3692the time comes to find the adequate obsolete translation, it merely 3693tries to provide handy tools for helping her to do so. 3694 3695 3696File: gettext.info, Node: Modifying Translations, Next: Modifying Comments, Prev: Obsolete Entries, Up: PO Mode 3697 36988.3.9 Modifying Translations 3699---------------------------- 3700 3701PO mode prevents direct modification of the PO file, by the usual means 3702Emacs gives for altering a buffer's contents. By doing so, it pretends 3703helping the translator to avoid little clerical errors about the 3704overall file format, or the proper quoting of strings, as those errors 3705would be easily made. Other kinds of errors are still possible, but 3706some may be caught and diagnosed by the batch validation process, which 3707the translator may always trigger by the `V' command. For all other 3708errors, the translator has to rely on her own judgment, and also on the 3709linguistic reports submitted to her by the users of the translated 3710package, having the same mother tongue. 3711 3712 When the time comes to create a translation, correct an error 3713diagnosed mechanically or reported by a user, the translators have to 3714resort to using the following commands for modifying the translations. 3715 3716`<RET>' 3717 Interactively edit the translation (`po-edit-msgstr'). 3718 3719`<LFD>' 3720`C-j' 3721 Reinitialize the translation with the original, untranslated string 3722 (`po-msgid-to-msgstr'). 3723 3724`k' 3725 Save the translation on the kill ring, and delete it 3726 (`po-kill-msgstr'). 3727 3728`w' 3729 Save the translation on the kill ring, without deleting it 3730 (`po-kill-ring-save-msgstr'). 3731 3732`y' 3733 Replace the translation, taking the new from the kill ring 3734 (`po-yank-msgstr'). 3735 3736 3737 The command `<RET>' (`po-edit-msgstr') opens a new Emacs window 3738meant to edit in a new translation, or to modify an already existing 3739translation. The new window contains a copy of the translation taken 3740from the current PO file entry, all ready for edition, expunged of all 3741quoting marks, fully modifiable and with the complete extent of Emacs 3742modifying commands. When the translator is done with her 3743modifications, she may use `C-c C-c' to close the subedit window with 3744the automatically requoted results, or `C-c C-k' to abort her 3745modifications. *Note Subedit::, for more information. 3746 3747 The command `<LFD>' (`po-msgid-to-msgstr') initializes, or 3748reinitializes the translation with the original string. This command is 3749normally used when the translator wants to redo a fresh translation of 3750the original string, disregarding any previous work. 3751 3752 It is possible to arrange so, whenever editing an untranslated 3753entry, the `<LFD>' command be automatically executed. If you set 3754`po-auto-edit-with-msgid' to `t', the translation gets initialised with 3755the original string, in case none exists already. The default value 3756for `po-auto-edit-with-msgid' is `nil'. 3757 3758 In fact, whether it is best to start a translation with an empty 3759string, or rather with a copy of the original string, is a matter of 3760taste or habit. Sometimes, the source language and the target language 3761are so different that is simply best to start writing on an empty page. 3762At other times, the source and target languages are so close that it 3763would be a waste to retype a number of words already being written in 3764the original string. A translator may also like having the original 3765string right under her eyes, as she will progressively overwrite the 3766original text with the translation, even if this requires some extra 3767editing work to get rid of the original. 3768 3769 The command `k' (`po-kill-msgstr') merely empties the translation 3770string, so turning the entry into an untranslated one. But while doing 3771so, its previous contents is put apart in a special place, known as the 3772kill ring. The command `w' (`po-kill-ring-save-msgstr') has also the 3773effect of taking a copy of the translation onto the kill ring, but it 3774otherwise leaves the entry alone, and does _not_ remove the translation 3775from the entry. Both commands use exactly the Emacs kill ring, which 3776is shared between buffers, and which is well known already to Emacs 3777lovers. 3778 3779 The translator may use `k' or `w' many times in the course of her 3780work, as the kill ring may hold several saved translations. From the 3781kill ring, strings may later be reinserted in various Emacs buffers. 3782In particular, the kill ring may be used for moving translation strings 3783between different entries of a single PO file buffer, or if the 3784translator is handling many such buffers at once, even between PO files. 3785 3786 To facilitate exchanges with buffers which are not in PO mode, the 3787translation string put on the kill ring by the `k' command is fully 3788unquoted before being saved: external quotes are removed, multi-line 3789strings are concatenated, and backslash escaped sequences are turned 3790into their corresponding characters. In the special case of obsolete 3791entries, the translation is also uncommented prior to saving. 3792 3793 The command `y' (`po-yank-msgstr') completely replaces the 3794translation of the current entry by a string taken from the kill ring. 3795Following Emacs terminology, we then say that the replacement string is 3796"yanked" into the PO file buffer. *Note Yanking: (emacs)Yanking. The 3797first time `y' is used, the translation receives the value of the most 3798recent addition to the kill ring. If `y' is typed once again, 3799immediately, without intervening keystrokes, the translation just 3800inserted is taken away and replaced by the second most recent addition 3801to the kill ring. By repeating `y' many times in a row, the translator 3802may travel along the kill ring for saved strings, until she finds the 3803string she really wanted. 3804 3805 When a string is yanked into a PO file entry, it is fully and 3806automatically requoted for complying with the format PO files should 3807have. Further, if the entry is obsolete, PO mode then appropriately 3808push the inserted string inside comments. Once again, translators 3809should not burden themselves with quoting considerations besides, of 3810course, the necessity of the translated string itself respective to the 3811program using it. 3812 3813 Note that `k' or `w' are not the only commands pushing strings on 3814the kill ring, as almost any PO mode command replacing translation 3815strings (or the translator comments) automatically saves the old string 3816on the kill ring. The main exceptions to this general rule are the 3817yanking commands themselves. 3818 3819 To better illustrate the operation of killing and yanking, let's use 3820an actual example, taken from a common situation. When the programmer 3821slightly modifies some string right in the program, his change is later 3822reflected in the PO file by the appearance of a new untranslated entry 3823for the modified string, and the fact that the entry translating the 3824original or unmodified string becomes obsolete. In many cases, the 3825translator might spare herself some work by retrieving the unmodified 3826translation from the obsolete entry, then initializing the untranslated 3827entry `msgstr' field with this retrieved translation. Once this done, 3828the obsolete entry is not wanted anymore, and may be safely deleted. 3829 3830 When the translator finds an untranslated entry and suspects that a 3831slight variant of the translation exists, she immediately uses `m' to 3832mark the current entry location, then starts chasing obsolete entries 3833with `o', hoping to find some translation corresponding to the 3834unmodified string. Once found, she uses the `<DEL>' command for 3835deleting the obsolete entry, knowing that `<DEL>' also _kills_ the 3836translation, that is, pushes the translation on the kill ring. Then, 3837`r' returns to the initial untranslated entry, and `y' then _yanks_ the 3838saved translation right into the `msgstr' field. The translator is 3839then free to use `<RET>' for fine tuning the translation contents, and 3840maybe to later use `u', then `m' again, for going on with the next 3841untranslated string. 3842 3843 When some sequence of keys has to be typed over and over again, the 3844translator may find it useful to become better acquainted with the Emacs 3845capability of learning these sequences and playing them back under 3846request. *Note Keyboard Macros: (emacs)Keyboard Macros. 3847 3848 3849File: gettext.info, Node: Modifying Comments, Next: Subedit, Prev: Modifying Translations, Up: PO Mode 3850 38518.3.10 Modifying Comments 3852------------------------- 3853 3854Any translation work done seriously will raise many linguistic 3855difficulties, for which decisions have to be made, and the choices 3856further documented. These documents may be saved within the PO file in 3857form of translator comments, which the translator is free to create, 3858delete, or modify at will. These comments may be useful to herself 3859when she returns to this PO file after a while. 3860 3861 Comments not having whitespace after the initial `#', for example, 3862those beginning with `#.' or `#:', are _not_ translator comments, they 3863are exclusively created by other `gettext' tools. So, the commands 3864below will never alter such system added comments, they are not meant 3865for the translator to modify. *Note PO Files::. 3866 3867 The following commands are somewhat similar to those modifying 3868translations, so the general indications given for those apply here. 3869*Note Modifying Translations::. 3870 3871`#' 3872 Interactively edit the translator comments (`po-edit-comment'). 3873 3874`K' 3875 Save the translator comments on the kill ring, and delete it 3876 (`po-kill-comment'). 3877 3878`W' 3879 Save the translator comments on the kill ring, without deleting it 3880 (`po-kill-ring-save-comment'). 3881 3882`Y' 3883 Replace the translator comments, taking the new from the kill ring 3884 (`po-yank-comment'). 3885 3886 3887 These commands parallel PO mode commands for modifying the 3888translation strings, and behave much the same way as they do, except 3889that they handle this part of PO file comments meant for translator 3890usage, rather than the translation strings. So, if the descriptions 3891given below are slightly succinct, it is because the full details have 3892already been given. *Note Modifying Translations::. 3893 3894 The command `#' (`po-edit-comment') opens a new Emacs window 3895containing a copy of the translator comments on the current PO file 3896entry. If there are no such comments, PO mode understands that the 3897translator wants to add a comment to the entry, and she is presented 3898with an empty screen. Comment marks (`#') and the space following them 3899are automatically removed before edition, and reinstated after. For 3900translator comments pertaining to obsolete entries, the uncommenting 3901and recommenting operations are done twice. Once in the editing 3902window, the keys `C-c C-c' allow the translator to tell she is finished 3903with editing the comment. *Note Subedit::, for further details. 3904 3905 Functions found on `po-subedit-mode-hook', if any, are executed after 3906the string has been inserted in the edit buffer. 3907 3908 The command `K' (`po-kill-comment') gets rid of all translator 3909comments, while saving those comments on the kill ring. The command 3910`W' (`po-kill-ring-save-comment') takes a copy of the translator 3911comments on the kill ring, but leaves them undisturbed in the current 3912entry. The command `Y' (`po-yank-comment') completely replaces the 3913translator comments by a string taken at the front of the kill ring. 3914When this command is immediately repeated, the comments just inserted 3915are withdrawn, and replaced by other strings taken along the kill ring. 3916 3917 On the kill ring, all strings have the same nature. There is no 3918distinction between _translation_ strings and _translator comments_ 3919strings. So, for example, let's presume the translator has just 3920finished editing a translation, and wants to create a new translator 3921comment to document why the previous translation was not good, just to 3922remember what was the problem. Foreseeing that she will do that in her 3923documentation, the translator may want to quote the previous 3924translation in her translator comments. To do so, she may initialize 3925the translator comments with the previous translation, still at the 3926head of the kill ring. Because editing already pushed the previous 3927translation on the kill ring, she merely has to type `M-w' prior to 3928`#', and the previous translation will be right there, all ready for 3929being introduced by some explanatory text. 3930 3931 On the other hand, presume there are some translator comments already 3932and that the translator wants to add to those comments, instead of 3933wholly replacing them. Then, she should edit the comment right away 3934with `#'. Once inside the editing window, she can use the regular 3935Emacs commands `C-y' (`yank') and `M-y' (`yank-pop') to get the 3936previous translation where she likes. 3937 3938 3939File: gettext.info, Node: Subedit, Next: C Sources Context, Prev: Modifying Comments, Up: PO Mode 3940 39418.3.11 Details of Sub Edition 3942----------------------------- 3943 3944The PO subedit minor mode has a few peculiarities worth being described 3945in fuller detail. It installs a few commands over the usual editing set 3946of Emacs, which are described below. 3947 3948`C-c C-c' 3949 Complete edition (`po-subedit-exit'). 3950 3951`C-c C-k' 3952 Abort edition (`po-subedit-abort'). 3953 3954`C-c C-a' 3955 Consult auxiliary PO files (`po-subedit-cycle-auxiliary'). 3956 3957 3958 The window's contents represents a translation for a given message, 3959or a translator comment. The translator may modify this window to her 3960heart's content. Once this is done, the command `C-c C-c' 3961(`po-subedit-exit') may be used to return the edited translation into 3962the PO file, replacing the original translation, even if it moved out of 3963sight or if buffers were switched. 3964 3965 If the translator becomes unsatisfied with her translation or 3966comment, to the extent she prefers keeping what was existent prior to 3967the `<RET>' or `#' command, she may use the command `C-c C-k' 3968(`po-subedit-abort') to merely get rid of edition, while preserving the 3969original translation or comment. Another way would be for her to exit 3970normally with `C-c C-c', then type `U' once for undoing the whole 3971effect of last edition. 3972 3973 The command `C-c C-a' (`po-subedit-cycle-auxiliary') allows for 3974glancing through translations already achieved in other languages, 3975directly while editing the current translation. This may be quite 3976convenient when the translator is fluent at many languages, but of 3977course, only makes sense when such completed auxiliary PO files are 3978already available to her (*note Auxiliary::). 3979 3980 Functions found on `po-subedit-mode-hook', if any, are executed after 3981the string has been inserted in the edit buffer. 3982 3983 While editing her translation, the translator should pay attention 3984to not inserting unwanted `<RET>' (newline) characters at the end of 3985the translated string if those are not meant to be there, or to removing 3986such characters when they are required. Since these characters are not 3987visible in the editing buffer, they are easily introduced by mistake. 3988To help her, `<RET>' automatically puts the character `<' at the end of 3989the string being edited, but this `<' is not really part of the string. 3990On exiting the editing window with `C-c C-c', PO mode automatically 3991removes such `<' and all whitespace added after it. If the translator 3992adds characters after the terminating `<', it looses its delimiting 3993property and integrally becomes part of the string. If she removes the 3994delimiting `<', then the edited string is taken _as is_, with all 3995trailing newlines, even if invisible. Also, if the translated string 3996ought to end itself with a genuine `<', then the delimiting `<' may not 3997be removed; so the string should appear, in the editing window, as 3998ending with two `<' in a row. 3999 4000 When a translation (or a comment) is being edited, the translator 4001may move the cursor back into the PO file buffer and freely move to 4002other entries, browsing at will. If, with an edition pending, the 4003translator wanders in the PO file buffer, she may decide to start 4004modifying another entry. Each entry being edited has its own subedit 4005buffer. It is possible to simultaneously edit the translation _and_ 4006the comment of a single entry, or to edit entries in different PO 4007files, all at once. Typing `<RET>' on a field already being edited 4008merely resumes that particular edit. Yet, the translator should better 4009be comfortable at handling many Emacs windows! 4010 4011 Pending subedits may be completed or aborted in any order, regardless 4012of how or when they were started. When many subedits are pending and 4013the translator asks for quitting the PO file (with the `q' command), 4014subedits are automatically resumed one at a time, so she may decide for 4015each of them. 4016 4017 4018File: gettext.info, Node: C Sources Context, Next: Auxiliary, Prev: Subedit, Up: PO Mode 4019 40208.3.12 C Sources Context 4021------------------------ 4022 4023PO mode is particularly powerful when used with PO files created 4024through GNU `gettext' utilities, as those utilities insert special 4025comments in the PO files they generate. Some of these special comments 4026relate the PO file entry to exactly where the untranslated string 4027appears in the program sources. 4028 4029 When the translator gets to an untranslated entry, she is fairly 4030often faced with an original string which is not as informative as it 4031normally should be, being succinct, cryptic, or otherwise ambiguous. 4032Before choosing how to translate the string, she needs to understand 4033better what the string really means and how tight the translation has 4034to be. Most of the time, when problems arise, the only way left to make 4035her judgment is looking at the true program sources from where this 4036string originated, searching for surrounding comments the programmer 4037might have put in there, and looking around for helping clues of _any_ 4038kind. 4039 4040 Surely, when looking at program sources, the translator will receive 4041more help if she is a fluent programmer. However, even if she is not 4042versed in programming and feels a little lost in C code, the translator 4043should not be shy at taking a look, once in a while. It is most 4044probable that she will still be able to find some of the hints she 4045needs. She will learn quickly to not feel uncomfortable in program 4046code, paying more attention to programmer's comments, variable and 4047function names (if he dared choosing them well), and overall 4048organization, than to the program code itself. 4049 4050 The following commands are meant to help the translator at getting 4051program source context for a PO file entry. 4052 4053`s' 4054 Resume the display of a program source context, or cycle through 4055 them (`po-cycle-source-reference'). 4056 4057`M-s' 4058 Display of a program source context selected by menu 4059 (`po-select-source-reference'). 4060 4061`S' 4062 Add a directory to the search path for source files 4063 (`po-consider-source-path'). 4064 4065`M-S' 4066 Delete a directory from the search path for source files 4067 (`po-ignore-source-path'). 4068 4069 4070 The commands `s' (`po-cycle-source-reference') and `M-s' 4071(`po-select-source-reference') both open another window displaying some 4072source program file, and already positioned in such a way that it shows 4073an actual use of the string to be translated. By doing so, the command 4074gives source program context for the string. But if the entry has no 4075source context references, or if all references are unresolved along 4076the search path for program sources, then the command diagnoses this as 4077an error. 4078 4079 Even if `s' (or `M-s') opens a new window, the cursor stays in the 4080PO file window. If the translator really wants to get into the program 4081source window, she ought to do it explicitly, maybe by using command 4082`O'. 4083 4084 When `s' is typed for the first time, or for a PO file entry which 4085is different of the last one used for getting source context, then the 4086command reacts by giving the first context available for this entry, if 4087any. If some context has already been recently displayed for the 4088current PO file entry, and the translator wandered off to do other 4089things, typing `s' again will merely resume, in another window, the 4090context last displayed. In particular, if the translator moved the 4091cursor away from the context in the source file, the command will bring 4092the cursor back to the context. By using `s' many times in a row, with 4093no other commands intervening, PO mode will cycle to the next available 4094contexts for this particular entry, getting back to the first context 4095once the last has been shown. 4096 4097 The command `M-s' behaves differently. Instead of cycling through 4098references, it lets the translator choose a particular reference among 4099many, and displays that reference. It is best used with completion, if 4100the translator types `<TAB>' immediately after `M-s', in response to 4101the question, she will be offered a menu of all possible references, as 4102a reminder of which are the acceptable answers. This command is useful 4103only where there are really many contexts available for a single string 4104to translate. 4105 4106 Program source files are usually found relative to where the PO file 4107stands. As a special provision, when this fails, the file is also 4108looked for, but relative to the directory immediately above it. Those 4109two cases take proper care of most PO files. However, it might happen 4110that a PO file has been moved, or is edited in a different place than 4111its normal location. When this happens, the translator should tell PO 4112mode in which directory normally sits the genuine PO file. Many such 4113directories may be specified, and all together, they constitute what is 4114called the "search path" for program sources. The command `S' 4115(`po-consider-source-path') is used to interactively enter a new 4116directory at the front of the search path, and the command `M-S' 4117(`po-ignore-source-path') is used to select, with completion, one of 4118the directories she does not want anymore on the search path. 4119 4120 4121File: gettext.info, Node: Auxiliary, Next: Compendium, Prev: C Sources Context, Up: PO Mode 4122 41238.3.13 Consulting Auxiliary PO Files 4124------------------------------------ 4125 4126PO mode is able to help the knowledgeable translator, being fluent in 4127many languages, at taking advantage of translations already achieved in 4128other languages she just happens to know. It provides these other 4129language translations as additional context for her own work. Moreover, 4130it has features to ease the production of translations for many 4131languages at once, for translators preferring to work in this way. 4132 4133 An "auxiliary" PO file is an existing PO file meant for the same 4134package the translator is working on, but targeted to a different mother 4135tongue language. Commands exist for declaring and handling auxiliary 4136PO files, and also for showing contexts for the entry under work. 4137 4138 Here are the auxiliary file commands available in PO mode. 4139 4140`a' 4141 Seek auxiliary files for another translation for the same entry 4142 (`po-cycle-auxiliary'). 4143 4144`C-c C-a' 4145 Switch to a particular auxiliary file (`po-select-auxiliary'). 4146 4147`A' 4148 Declare this PO file as an auxiliary file 4149 (`po-consider-as-auxiliary'). 4150 4151`M-A' 4152 Remove this PO file from the list of auxiliary files 4153 (`po-ignore-as-auxiliary'). 4154 4155 4156 Command `A' (`po-consider-as-auxiliary') adds the current PO file to 4157the list of auxiliary files, while command `M-A' 4158(`po-ignore-as-auxiliary' just removes it. 4159 4160 The command `a' (`po-cycle-auxiliary') seeks all auxiliary PO files, 4161round-robin, searching for a translated entry in some other language 4162having an `msgid' field identical as the one for the current entry. 4163The found PO file, if any, takes the place of the current PO file in 4164the display (its window gets on top). Before doing so, the current PO 4165file is also made into an auxiliary file, if not already. So, `a' in 4166this newly displayed PO file will seek another PO file, and so on, so 4167repeating `a' will eventually yield back the original PO file. 4168 4169 The command `C-c C-a' (`po-select-auxiliary') asks the translator 4170for her choice of a particular auxiliary file, with completion, and 4171then switches to that selected PO file. The command also checks if the 4172selected file has an `msgid' field identical as the one for the current 4173entry, and if yes, this entry becomes current. Otherwise, the cursor 4174of the selected file is left undisturbed. 4175 4176 For all this to work fully, auxiliary PO files will have to be 4177normalized, in that way that `msgid' fields should be written _exactly_ 4178the same way. It is possible to write `msgid' fields in various ways 4179for representing the same string, different writing would break the 4180proper behaviour of the auxiliary file commands of PO mode. This is not 4181expected to be much a problem in practice, as most existing PO files 4182have their `msgid' entries written by the same GNU `gettext' tools. 4183 4184 However, PO files initially created by PO mode itself, while marking 4185strings in source files, are normalised differently. So are PO files 4186resulting of the `M-x normalize' command. Until these discrepancies 4187between PO mode and other GNU `gettext' tools get fully resolved, the 4188translator should stay aware of normalisation issues. 4189 4190 4191File: gettext.info, Node: Compendium, Prev: Auxiliary, Up: PO Mode 4192 41938.3.14 Using Translation Compendia 4194---------------------------------- 4195 4196A "compendium" is a special PO file containing a set of translations 4197recurring in many different packages. The translator can use gettext 4198tools to build a new compendium, to add entries to her compendium, and 4199to initialize untranslated entries, or to update already translated 4200entries, from translations kept in the compendium. 4201 4202* Menu: 4203 4204* Creating Compendia:: Merging translations for later use 4205* Using Compendia:: Using older translations if they fit 4206 4207 4208File: gettext.info, Node: Creating Compendia, Next: Using Compendia, Prev: Compendium, Up: Compendium 4209 42108.3.14.1 Creating Compendia 4211........................... 4212 4213Basically every PO file consisting of translated entries only can be 4214declared as a valid compendium. Often the translator wants to have 4215special compendia; let's consider two cases: `concatenating PO files' 4216and `extracting a message subset from a PO file'. 4217 42188.3.14.2 Concatenate PO Files 4219............................. 4220 4221To concatenate several valid PO files into one compendium file you can 4222use `msgcomm' or `msgcat' (the latter preferred): 4223 4224 msgcat -o compendium.po file1.po file2.po 4225 4226 By default, `msgcat' will accumulate divergent translations for the 4227same string. Those occurrences will be marked as `fuzzy' and highly 4228visible decorated; calling `msgcat' on `file1.po': 4229 4230 #: src/hello.c:200 4231 #, c-format 4232 msgid "Report bugs to <%s>.\n" 4233 msgstr "Comunicar `bugs' a <%s>.\n" 4234 4235and `file2.po': 4236 4237 #: src/bye.c:100 4238 #, c-format 4239 msgid "Report bugs to <%s>.\n" 4240 msgstr "Comunicar \"bugs\" a <%s>.\n" 4241 4242will result in: 4243 4244 #: src/hello.c:200 src/bye.c:100 4245 #, fuzzy, c-format 4246 msgid "Report bugs to <%s>.\n" 4247 msgstr "" 4248 "#-#-#-#-# file1.po #-#-#-#-#\n" 4249 "Comunicar `bugs' a <%s>.\n" 4250 "#-#-#-#-# file2.po #-#-#-#-#\n" 4251 "Comunicar \"bugs\" a <%s>.\n" 4252 4253The translator will have to resolve this "conflict" manually; she has 4254to decide whether the first or the second version is appropriate (or 4255provide a new translation), to delete the "marker lines", and finally 4256to remove the `fuzzy' mark. 4257 4258 If the translator knows in advance the first found translation of a 4259message is always the best translation she can make use to the 4260`--use-first' switch: 4261 4262 msgcat --use-first -o compendium.po file1.po file2.po 4263 4264 A good compendium file must not contain `fuzzy' or untranslated 4265entries. If input files are "dirty" you must preprocess the input 4266files or postprocess the result using `msgattrib --translated 4267--no-fuzzy'. 4268 42698.3.14.3 Extract a Message Subset from a PO File 4270................................................ 4271 4272Nobody wants to translate the same messages again and again; thus you 4273may wish to have a compendium file containing `getopt.c' messages. 4274 4275 To extract a message subset (e.g., all `getopt.c' messages) from an 4276existing PO file into one compendium file you can use `msggrep': 4277 4278 msggrep --location src/getopt.c -o compendium.po file.po 4279 4280 4281File: gettext.info, Node: Using Compendia, Prev: Creating Compendia, Up: Compendium 4282 42838.3.14.4 Using Compendia 4284........................ 4285 4286You can use a compendium file to initialize a translation from scratch 4287or to update an already existing translation. 4288 42898.3.14.5 Initialize a New Translation File 4290.......................................... 4291 4292Since a PO file with translations does not exist the translator can 4293merely use `/dev/null' to fake the "old" translation file. 4294 4295 msgmerge --compendium compendium.po -o file.po /dev/null file.pot 4296 42978.3.14.6 Update an Existing Translation File 4298............................................ 4299 4300Concatenate the compendium file(s) and the existing PO, merge the 4301result with the POT file and remove the obsolete entries (optional, 4302here done using `sed'): 4303 4304 msgcat --use-first -o update.po compendium1.po compendium2.po file.po 4305 msgmerge update.po file.pot | sed -e '/^#~/d' > file.po 4306 4307 4308File: gettext.info, Node: Manipulating, Next: Binaries, Prev: Editing, Up: Top 4309 43109 Manipulating PO Files 4311*********************** 4312 4313Sometimes it is necessary to manipulate PO files in a way that is better 4314performed automatically than by hand. GNU `gettext' includes a 4315complete set of tools for this purpose. 4316 4317 When merging two packages into a single package, the resulting POT 4318file will be the concatenation of the two packages' POT files. Thus the 4319maintainer must concatenate the two existing package translations into 4320a single translation catalog, for each language. This is best performed 4321using `msgcat'. It is then the translators' duty to deal with any 4322possible conflicts that arose during the merge. 4323 4324 When a translator takes over the translation job from another 4325translator, but she uses a different character encoding in her locale, 4326she will convert the catalog to her character encoding. This is best 4327done through the `msgconv' program. 4328 4329 When a maintainer takes a source file with tagged messages from 4330another package, he should also take the existing translations for this 4331source file (and not let the translators do the same job twice). One 4332way to do this is through `msggrep', another is to create a POT file for 4333that source file and use `msgmerge'. 4334 4335 When a translator wants to adjust some translation catalog for a 4336special dialect or orthography -- for example, German as written in 4337Switzerland versus German as written in Germany -- she needs to apply 4338some text processing to every message in the catalog. The tool for 4339doing this is `msgfilter'. 4340 4341 Another use of `msgfilter' is to produce approximately the POT file 4342for which a given PO file was made. This can be done through a filter 4343command like `msgfilter sed -e d | sed -e '/^# /d''. Note that the 4344original POT file may have had different comments and different plural 4345message counts, that's why it's better to use the original POT file if 4346available. 4347 4348 When a translator wants to check her translations, for example 4349according to orthography rules or using a non-interactive spell 4350checker, she can do so using the `msgexec' program. 4351 4352 When third party tools create PO or POT files, sometimes duplicates 4353cannot be avoided. But the GNU `gettext' tools give an error when they 4354encounter duplicate msgids in the same file and in the same domain. To 4355merge duplicates, the `msguniq' program can be used. 4356 4357 `msgcomm' is a more general tool for keeping or throwing away 4358duplicates, occurring in different files. 4359 4360 `msgcmp' can be used to check whether a translation catalog is 4361completely translated. 4362 4363 `msgattrib' can be used to select and extract only the fuzzy or 4364untranslated messages of a translation catalog. 4365 4366 `msgen' is useful as a first step for preparing English translation 4367catalogs. It copies each message's msgid to its msgstr. 4368 4369 Finally, for those applications where all these various programs are 4370not sufficient, a library `libgettextpo' is provided that can be used to 4371write other specialized programs that process PO files. 4372 4373* Menu: 4374 4375* msgcat Invocation:: Invoking the `msgcat' Program 4376* msgconv Invocation:: Invoking the `msgconv' Program 4377* msggrep Invocation:: Invoking the `msggrep' Program 4378* msgfilter Invocation:: Invoking the `msgfilter' Program 4379* msguniq Invocation:: Invoking the `msguniq' Program 4380* msgcomm Invocation:: Invoking the `msgcomm' Program 4381* msgcmp Invocation:: Invoking the `msgcmp' Program 4382* msgattrib Invocation:: Invoking the `msgattrib' Program 4383* msgen Invocation:: Invoking the `msgen' Program 4384* msgexec Invocation:: Invoking the `msgexec' Program 4385* libgettextpo:: Writing your own programs that process PO files 4386 4387 4388File: gettext.info, Node: msgcat Invocation, Next: msgconv Invocation, Prev: Manipulating, Up: Manipulating 4389 43909.1 Invoking the `msgcat' Program 4391================================= 4392 4393 msgcat [OPTION] [INPUTFILE]... 4394 4395 The `msgcat' program concatenates and merges the specified PO files. 4396It finds messages which are common to two or more of the specified PO 4397files. By using the `--more-than' option, greater commonality may be 4398requested before messages are printed. Conversely, the `--less-than' 4399option may be used to specify less commonality before messages are 4400printed (i.e. `--less-than=2' will only print the unique messages). 4401Translations, comments and extract comments will be cumulated, except 4402that if `--use-first' is specified, they will be taken from the first 4403PO file to define them. File positions from all PO files will be 4404cumulated. 4405 44069.1.1 Input file location 4407------------------------- 4408 4409`INPUTFILE ...' 4410 Input files. 4411 4412`-f FILE' 4413`--files-from=FILE' 4414 Read the names of the input files from FILE instead of getting 4415 them from the command line. 4416 4417`-D DIRECTORY' 4418`--directory=DIRECTORY' 4419 Add DIRECTORY to the list of directories. Source files are 4420 searched relative to this list of directories. The resulting `.po' 4421 file will be written relative to the current directory, though. 4422 4423 4424 If INPUTFILE is `-', standard input is read. 4425 44269.1.2 Output file location 4427-------------------------- 4428 4429`-o FILE' 4430`--output-file=FILE' 4431 Write output to specified file. 4432 4433 4434 The results are written to standard output if no output file is 4435specified or if it is `-'. 4436 44379.1.3 Message selection 4438----------------------- 4439 4440`-< NUMBER' 4441`--less-than=NUMBER' 4442 Print messages with less than NUMBER definitions, defaults to 4443 infinite if not set. 4444 4445`-> NUMBER' 4446`--more-than=NUMBER' 4447 Print messages with more than NUMBER definitions, defaults to 0 if 4448 not set. 4449 4450`-u' 4451`--unique' 4452 Shorthand for `--less-than=2'. Requests that only unique messages 4453 be printed. 4454 4455 44569.1.4 Input file syntax 4457----------------------- 4458 4459`-P' 4460`--properties-input' 4461 Assume the input files are Java ResourceBundles in Java 4462 `.properties' syntax, not in PO file syntax. 4463 4464`--stringtable-input' 4465 Assume the input files are NeXTstep/GNUstep localized resource 4466 files in `.strings' syntax, not in PO file syntax. 4467 4468 44699.1.5 Output details 4470-------------------- 4471 4472`-t' 4473`--to-code=NAME' 4474 Specify encoding for output. 4475 4476`--use-first' 4477 Use first available translation for each message. Don't merge 4478 several translations into one. 4479 4480`--force-po' 4481 Always write an output file even if it contains no message. 4482 4483`-i' 4484`--indent' 4485 Write the .po file using indented style. 4486 4487`--no-location' 4488 Do not write `#: FILENAME:LINE' lines. 4489 4490`-n' 4491`--add-location' 4492 Generate `#: FILENAME:LINE' lines (default). 4493 4494`--strict' 4495 Write out a strict Uniforum conforming PO file. Note that this 4496 Uniforum format should be avoided because it doesn't support the 4497 GNU extensions. 4498 4499`-p' 4500`--properties-output' 4501 Write out a Java ResourceBundle in Java `.properties' syntax. Note 4502 that this file format doesn't support plural forms and silently 4503 drops obsolete messages. 4504 4505`--stringtable-output' 4506 Write out a NeXTstep/GNUstep localized resource file in `.strings' 4507 syntax. Note that this file format doesn't support plural forms. 4508 4509`-w NUMBER' 4510`--width=NUMBER' 4511 Set the output page width. Long strings in the output files will 4512 be split across multiple lines in order to ensure that each line's 4513 width (= number of screen columns) is less or equal to the given 4514 NUMBER. 4515 4516`--no-wrap' 4517 Do not break long message lines. Message lines whose width 4518 exceeds the output page width will not be split into several 4519 lines. Only file reference lines which are wider than the output 4520 page width will be split. 4521 4522`-s' 4523`--sort-output' 4524 Generate sorted output. Note that using this option makes it much 4525 harder for the translator to understand each message's context. 4526 4527`-F' 4528`--sort-by-file' 4529 Sort output by file location. 4530 4531 45329.1.6 Informative output 4533------------------------ 4534 4535`-h' 4536`--help' 4537 Display this help and exit. 4538 4539`-V' 4540`--version' 4541 Output version information and exit. 4542 4543 4544 4545File: gettext.info, Node: msgconv Invocation, Next: msggrep Invocation, Prev: msgcat Invocation, Up: Manipulating 4546 45479.2 Invoking the `msgconv' Program 4548================================== 4549 4550 msgconv [OPTION] [INPUTFILE] 4551 4552 The `msgconv' program converts a translation catalog to a different 4553character encoding. 4554 45559.2.1 Input file location 4556------------------------- 4557 4558`INPUTFILE' 4559 Input PO file. 4560 4561`-D DIRECTORY' 4562`--directory=DIRECTORY' 4563 Add DIRECTORY to the list of directories. Source files are 4564 searched relative to this list of directories. The resulting `.po' 4565 file will be written relative to the current directory, though. 4566 4567 4568 If no INPUTFILE is given or if it is `-', standard input is read. 4569 45709.2.2 Output file location 4571-------------------------- 4572 4573`-o FILE' 4574`--output-file=FILE' 4575 Write output to specified file. 4576 4577 4578 The results are written to standard output if no output file is 4579specified or if it is `-'. 4580 45819.2.3 Conversion target 4582----------------------- 4583 4584`-t' 4585`--to-code=NAME' 4586 Specify encoding for output. 4587 4588 4589 The default encoding is the current locale's encoding. 4590 45919.2.4 Input file syntax 4592----------------------- 4593 4594`-P' 4595`--properties-input' 4596 Assume the input file is a Java ResourceBundle in Java 4597 `.properties' syntax, not in PO file syntax. 4598 4599`--stringtable-input' 4600 Assume the input file is a NeXTstep/GNUstep localized resource 4601 file in `.strings' syntax, not in PO file syntax. 4602 4603 46049.2.5 Output details 4605-------------------- 4606 4607`--force-po' 4608 Always write an output file even if it contains no message. 4609 4610`-i' 4611`--indent' 4612 Write the .po file using indented style. 4613 4614`--no-location' 4615 Do not write `#: FILENAME:LINE' lines. 4616 4617`--add-location' 4618 Generate `#: FILENAME:LINE' lines (default). 4619 4620`--strict' 4621 Write out a strict Uniforum conforming PO file. Note that this 4622 Uniforum format should be avoided because it doesn't support the 4623 GNU extensions. 4624 4625`-p' 4626`--properties-output' 4627 Write out a Java ResourceBundle in Java `.properties' syntax. Note 4628 that this file format doesn't support plural forms and silently 4629 drops obsolete messages. 4630 4631`--stringtable-output' 4632 Write out a NeXTstep/GNUstep localized resource file in `.strings' 4633 syntax. Note that this file format doesn't support plural forms. 4634 4635`-w NUMBER' 4636`--width=NUMBER' 4637 Set the output page width. Long strings in the output files will 4638 be split across multiple lines in order to ensure that each line's 4639 width (= number of screen columns) is less or equal to the given 4640 NUMBER. 4641 4642`--no-wrap' 4643 Do not break long message lines. Message lines whose width 4644 exceeds the output page width will not be split into several 4645 lines. Only file reference lines which are wider than the output 4646 page width will be split. 4647 4648`-s' 4649`--sort-output' 4650 Generate sorted output. Note that using this option makes it much 4651 harder for the translator to understand each message's context. 4652 4653`-F' 4654`--sort-by-file' 4655 Sort output by file location. 4656 4657 46589.2.6 Informative output 4659------------------------ 4660 4661`-h' 4662`--help' 4663 Display this help and exit. 4664 4665`-V' 4666`--version' 4667 Output version information and exit. 4668 4669 4670 4671File: gettext.info, Node: msggrep Invocation, Next: msgfilter Invocation, Prev: msgconv Invocation, Up: Manipulating 4672 46739.3 Invoking the `msggrep' Program 4674================================== 4675 4676 msggrep [OPTION] [INPUTFILE] 4677 4678 The `msggrep' program extracts all messages of a translation catalog 4679that match a given pattern or belong to some given source files. 4680 46819.3.1 Input file location 4682------------------------- 4683 4684`INPUTFILE' 4685 Input PO file. 4686 4687`-D DIRECTORY' 4688`--directory=DIRECTORY' 4689 Add DIRECTORY to the list of directories. Source files are 4690 searched relative to this list of directories. The resulting `.po' 4691 file will be written relative to the current directory, though. 4692 4693 4694 If no INPUTFILE is given or if it is `-', standard input is read. 4695 46969.3.2 Output file location 4697-------------------------- 4698 4699`-o FILE' 4700`--output-file=FILE' 4701 Write output to specified file. 4702 4703 4704 The results are written to standard output if no output file is 4705specified or if it is `-'. 4706 47079.3.3 Message selection 4708----------------------- 4709 4710 [-N SOURCEFILE]... [-M DOMAINNAME]... 4711 [-J MSGCTXT-PATTERN [-K MSGID-PATTERN] [-T MSGSTR-PATTERN] 4712 [-C COMMENT-PATTERN] 4713 4714 A message is selected if 4715 * it comes from one of the specified source files, 4716 4717 * or if it comes from one of the specified domains, 4718 4719 * or if `-J' is given and its context (msgctxt) matches 4720 MSGCTXT-PATTERN, 4721 4722 * or if `-K' is given and its key (msgid or msgid_plural) matches 4723 MSGID-PATTERN, 4724 4725 * or if `-T' is given and its translation (msgstr) matches 4726 MSGSTR-PATTERN, 4727 4728 * or if `-C' is given and the translator's comment matches 4729 COMMENT-PATTERN. 4730 4731 When more than one selection criterion is specified, the set of 4732selected messages is the union of the selected messages of each 4733criterion. 4734 4735 MSGID-PATTERN or MSGSTR-PATTERN syntax: 4736 [-E | -F] [-e PATTERN | -f FILE]... 4737 PATTERNs are basic regular expressions by default, or extended 4738regular expressions if -E is given, or fixed strings if -F is given. 4739 4740`-N SOURCEFILE' 4741`--location=SOURCEFILE' 4742 Select messages extracted from SOURCEFILE. SOURCEFILE can be 4743 either a literal file name or a wildcard pattern. 4744 4745`-M DOMAINNAME' 4746`--domain=DOMAINNAME' 4747 Select messages belonging to domain DOMAINNAME. 4748 4749`-J' 4750`--msgctxt' 4751 Start of patterns for the msgctxt. 4752 4753`-K' 4754`--msgid' 4755 Start of patterns for the msgid. 4756 4757`-T' 4758`--msgstr' 4759 Start of patterns for the msgstr. 4760 4761`-C' 4762`--comment' 4763 Start of patterns for the translator's comment. 4764 4765`-X' 4766`--extracted-comment' 4767 Start of patterns for the extracted comments. 4768 4769`-E' 4770`--extended-regexp' 4771 Specify that PATTERN is an extended regular expression. 4772 4773`-F' 4774`--fixed-strings' 4775 Specify that PATTERN is a set of newline-separated strings. 4776 4777`-e PATTERN' 4778`--regexp=PATTERN' 4779 Use PATTERN as a regular expression. 4780 4781`-f FILE' 4782`--file=FILE' 4783 Obtain PATTERN from FILE. 4784 4785`-i' 4786`--ignore-case' 4787 Ignore case distinctions. 4788 4789`-v' 4790`--invert-match' 4791 Output only the messages that do not match any selection 4792 criterion, instead of the messages that match a selection 4793 criterion. 4794 4795 47969.3.4 Input file syntax 4797----------------------- 4798 4799`-P' 4800`--properties-input' 4801 Assume the input file is a Java ResourceBundle in Java 4802 `.properties' syntax, not in PO file syntax. 4803 4804`--stringtable-input' 4805 Assume the input file is a NeXTstep/GNUstep localized resource 4806 file in `.strings' syntax, not in PO file syntax. 4807 4808 48099.3.5 Output details 4810-------------------- 4811 4812`--force-po' 4813 Always write an output file even if it contains no message. 4814 4815`--indent' 4816 Write the .po file using indented style. 4817 4818`--no-location' 4819 Do not write `#: FILENAME:LINE' lines. 4820 4821`--add-location' 4822 Generate `#: FILENAME:LINE' lines (default). 4823 4824`--strict' 4825 Write out a strict Uniforum conforming PO file. Note that this 4826 Uniforum format should be avoided because it doesn't support the 4827 GNU extensions. 4828 4829`-p' 4830`--properties-output' 4831 Write out a Java ResourceBundle in Java `.properties' syntax. Note 4832 that this file format doesn't support plural forms and silently 4833 drops obsolete messages. 4834 4835`--stringtable-output' 4836 Write out a NeXTstep/GNUstep localized resource file in `.strings' 4837 syntax. Note that this file format doesn't support plural forms. 4838 4839`-w NUMBER' 4840`--width=NUMBER' 4841 Set the output page width. Long strings in the output files will 4842 be split across multiple lines in order to ensure that each line's 4843 width (= number of screen columns) is less or equal to the given 4844 NUMBER. 4845 4846`--no-wrap' 4847 Do not break long message lines. Message lines whose width 4848 exceeds the output page width will not be split into several 4849 lines. Only file reference lines which are wider than the output 4850 page width will be split. 4851 4852`--sort-output' 4853 Generate sorted output. Note that using this option makes it much 4854 harder for the translator to understand each message's context. 4855 4856`--sort-by-file' 4857 Sort output by file location. 4858 4859 48609.3.6 Informative output 4861------------------------ 4862 4863`-h' 4864`--help' 4865 Display this help and exit. 4866 4867`-V' 4868`--version' 4869 Output version information and exit. 4870 4871 4872 4873File: gettext.info, Node: msgfilter Invocation, Next: msguniq Invocation, Prev: msggrep Invocation, Up: Manipulating 4874 48759.4 Invoking the `msgfilter' Program 4876==================================== 4877 4878 msgfilter [OPTION] FILTER [FILTER-OPTION] 4879 4880 The `msgfilter' program applies a filter to all translations of a 4881translation catalog. 4882 48839.4.1 Input file location 4884------------------------- 4885 4886`-i INPUTFILE' 4887`--input=INPUTFILE' 4888 Input PO file. 4889 4890`-D DIRECTORY' 4891`--directory=DIRECTORY' 4892 Add DIRECTORY to the list of directories. Source files are 4893 searched relative to this list of directories. The resulting `.po' 4894 file will be written relative to the current directory, though. 4895 4896 4897 If no INPUTFILE is given or if it is `-', standard input is read. 4898 48999.4.2 Output file location 4900-------------------------- 4901 4902`-o FILE' 4903`--output-file=FILE' 4904 Write output to specified file. 4905 4906 4907 The results are written to standard output if no output file is 4908specified or if it is `-'. 4909 49109.4.3 The filter 4911---------------- 4912 4913The FILTER can be any program that reads a translation from standard 4914input and writes a modified translation to standard output. A 4915frequently used filter is `sed'. A few particular built-in filters are 4916also recognized. 4917 4918 Note: If the filter is not a built-in filter, you have to care about 4919encodings: It is your responsibility to ensure that the FILTER can cope 4920with input encoded in the translation catalog's encoding. If the 4921FILTER wants input in a particular encoding, you can in a first step 4922convert the translation catalog to that encoding using the `msgconv' 4923program, before invoking `msgfilter'. If the FILTER wants input in the 4924locale's encoding, but you want to avoid the locale's encoding, then 4925you can first convert the translation catalog to UTF-8 using the 4926`msgconv' program and then make `msgfilter' work in an UTF-8 locale, by 4927using the `LC_ALL' environment variable. 4928 4929 Note: Most translations in a translation catalog don't end with a 4930newline character. For this reason, it is important that the FILTER 4931recognizes its last input line even if it ends without a newline, and 4932that it doesn't add an undesired trailing newline at the end. The `sed' 4933program on some platforms is known to ignore the last line of input if 4934it is not terminated with a newline. You can use GNU `sed' instead; it 4935does not have this limitation. 4936 49379.4.4 Useful FILTER-OPTIONs when the FILTER is `sed' 4938---------------------------------------------------- 4939 4940`-e SCRIPT' 4941`--expression=SCRIPT' 4942 Add SCRIPT to the commands to be executed. 4943 4944`-f SCRIPTFILE' 4945`--file=SCRIPTFILE' 4946 Add the contents of SCRIPTFILE to the commands to be executed. 4947 4948`-n' 4949`--quiet' 4950`--silent' 4951 Suppress automatic printing of pattern space. 4952 4953 49549.4.5 Built-in FILTERs 4955---------------------- 4956 4957The filter `recode-sr-latin' is recognized as a built-in filter. The 4958command `recode-sr-latin' converts Serbian text, written in the 4959Cyrillic script, to the Latin script. The command `msgfilter 4960recode-sr-latin' applies this conversion to the translations of a PO 4961file. Thus, it can be used to convert an `sr.po' file to an 4962`sr@latin.po' file. 4963 4964 The use of built-in filters is not sensitive to the current locale's 4965encoding. Moreover, when used with a built-in filter, `msgfilter' can 4966automatically convert the message catalog to the UTF-8 encoding when 4967needed. 4968 49699.4.6 Input file syntax 4970----------------------- 4971 4972`-P' 4973`--properties-input' 4974 Assume the input file is a Java ResourceBundle in Java 4975 `.properties' syntax, not in PO file syntax. 4976 4977`--stringtable-input' 4978 Assume the input file is a NeXTstep/GNUstep localized resource 4979 file in `.strings' syntax, not in PO file syntax. 4980 4981 49829.4.7 Output details 4983-------------------- 4984 4985`--force-po' 4986 Always write an output file even if it contains no message. 4987 4988`--indent' 4989 Write the .po file using indented style. 4990 4991`--keep-header' 4992 Keep the header entry, i.e. the message with `msgid ""', 4993 unmodified, instead of filtering it. By default, the header entry 4994 is subject to filtering like any other message. 4995 4996`--no-location' 4997 Do not write `#: FILENAME:LINE' lines. 4998 4999`--add-location' 5000 Generate `#: FILENAME:LINE' lines (default). 5001 5002`--strict' 5003 Write out a strict Uniforum conforming PO file. Note that this 5004 Uniforum format should be avoided because it doesn't support the 5005 GNU extensions. 5006 5007`-p' 5008`--properties-output' 5009 Write out a Java ResourceBundle in Java `.properties' syntax. Note 5010 that this file format doesn't support plural forms and silently 5011 drops obsolete messages. 5012 5013`--stringtable-output' 5014 Write out a NeXTstep/GNUstep localized resource file in `.strings' 5015 syntax. Note that this file format doesn't support plural forms. 5016 5017`-w NUMBER' 5018`--width=NUMBER' 5019 Set the output page width. Long strings in the output files will 5020 be split across multiple lines in order to ensure that each line's 5021 width (= number of screen columns) is less or equal to the given 5022 NUMBER. 5023 5024`--no-wrap' 5025 Do not break long message lines. Message lines whose width 5026 exceeds the output page width will not be split into several 5027 lines. Only file reference lines which are wider than the output 5028 page width will be split. 5029 5030`-s' 5031`--sort-output' 5032 Generate sorted output. Note that using this option makes it much 5033 harder for the translator to understand each message's context. 5034 5035`-F' 5036`--sort-by-file' 5037 Sort output by file location. 5038 5039 50409.4.8 Informative output 5041------------------------ 5042 5043`-h' 5044`--help' 5045 Display this help and exit. 5046 5047`-V' 5048`--version' 5049 Output version information and exit. 5050 5051 5052 5053File: gettext.info, Node: msguniq Invocation, Next: msgcomm Invocation, Prev: msgfilter Invocation, Up: Manipulating 5054 50559.5 Invoking the `msguniq' Program 5056================================== 5057 5058 msguniq [OPTION] [INPUTFILE] 5059 5060 The `msguniq' program unifies duplicate translations in a translation 5061catalog. It finds duplicate translations of the same message ID. Such 5062duplicates are invalid input for other programs like `msgfmt', 5063`msgmerge' or `msgcat'. By default, duplicates are merged together. 5064When using the `--repeated' option, only duplicates are output, and all 5065other messages are discarded. Comments and extracted comments will be 5066cumulated, except that if `--use-first' is specified, they will be 5067taken from the first translation. File positions will be cumulated. 5068When using the `--unique' option, duplicates are discarded. 5069 50709.5.1 Input file location 5071------------------------- 5072 5073`INPUTFILE' 5074 Input PO file. 5075 5076`-D DIRECTORY' 5077`--directory=DIRECTORY' 5078 Add DIRECTORY to the list of directories. Source files are 5079 searched relative to this list of directories. The resulting `.po' 5080 file will be written relative to the current directory, though. 5081 5082 5083 If no INPUTFILE is given or if it is `-', standard input is read. 5084 50859.5.2 Output file location 5086-------------------------- 5087 5088`-o FILE' 5089`--output-file=FILE' 5090 Write output to specified file. 5091 5092 5093 The results are written to standard output if no output file is 5094specified or if it is `-'. 5095 50969.5.3 Message selection 5097----------------------- 5098 5099`-d' 5100`--repeated' 5101 Print only duplicates. 5102 5103`-u' 5104`--unique' 5105 Print only unique messages, discard duplicates. 5106 5107 51089.5.4 Input file syntax 5109----------------------- 5110 5111`-P' 5112`--properties-input' 5113 Assume the input file is a Java ResourceBundle in Java 5114 `.properties' syntax, not in PO file syntax. 5115 5116`--stringtable-input' 5117 Assume the input file is a NeXTstep/GNUstep localized resource 5118 file in `.strings' syntax, not in PO file syntax. 5119 5120 51219.5.5 Output details 5122-------------------- 5123 5124`-t' 5125`--to-code=NAME' 5126 Specify encoding for output. 5127 5128`--use-first' 5129 Use first available translation for each message. Don't merge 5130 several translations into one. 5131 5132`--force-po' 5133 Always write an output file even if it contains no message. 5134 5135`-i' 5136`--indent' 5137 Write the .po file using indented style. 5138 5139`--no-location' 5140 Do not write `#: FILENAME:LINE' lines. 5141 5142`-n' 5143`--add-location' 5144 Generate `#: FILENAME:LINE' lines (default). 5145 5146`--strict' 5147 Write out a strict Uniforum conforming PO file. Note that this 5148 Uniforum format should be avoided because it doesn't support the 5149 GNU extensions. 5150 5151`-p' 5152`--properties-output' 5153 Write out a Java ResourceBundle in Java `.properties' syntax. Note 5154 that this file format doesn't support plural forms and silently 5155 drops obsolete messages. 5156 5157`--stringtable-output' 5158 Write out a NeXTstep/GNUstep localized resource file in `.strings' 5159 syntax. Note that this file format doesn't support plural forms. 5160 5161`-w NUMBER' 5162`--width=NUMBER' 5163 Set the output page width. Long strings in the output files will 5164 be split across multiple lines in order to ensure that each line's 5165 width (= number of screen columns) is less or equal to the given 5166 NUMBER. 5167 5168`--no-wrap' 5169 Do not break long message lines. Message lines whose width 5170 exceeds the output page width will not be split into several 5171 lines. Only file reference lines which are wider than the output 5172 page width will be split. 5173 5174`-s' 5175`--sort-output' 5176 Generate sorted output. Note that using this option makes it much 5177 harder for the translator to understand each message's context. 5178 5179`-F' 5180`--sort-by-file' 5181 Sort output by file location. 5182 5183 51849.5.6 Informative output 5185------------------------ 5186 5187`-h' 5188`--help' 5189 Display this help and exit. 5190 5191`-V' 5192`--version' 5193 Output version information and exit. 5194 5195 5196 5197File: gettext.info, Node: msgcomm Invocation, Next: msgcmp Invocation, Prev: msguniq Invocation, Up: Manipulating 5198 51999.6 Invoking the `msgcomm' Program 5200================================== 5201 5202 msgcomm [OPTION] [INPUTFILE]... 5203 5204 The `msgcomm' program finds messages which are common to two or more 5205of the specified PO files. By using the `--more-than' option, greater 5206commonality may be requested before messages are printed. Conversely, 5207the `--less-than' option may be used to specify less commonality before 5208messages are printed (i.e. `--less-than=2' will only print the unique 5209messages). Translations, comments and extract comments will be 5210preserved, but only from the first PO file to define them. File 5211positions from all PO files will be cumulated. 5212 52139.6.1 Input file location 5214------------------------- 5215 5216`INPUTFILE ...' 5217 Input files. 5218 5219`-f FILE' 5220`--files-from=FILE' 5221 Read the names of the input files from FILE instead of getting 5222 them from the command line. 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 INPUTFILE is `-', standard input is read. 5232 52339.6.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.6.3 Message selection 5245----------------------- 5246 5247`-< NUMBER' 5248`--less-than=NUMBER' 5249 Print messages with less than NUMBER definitions, defaults to 5250 infinite if not set. 5251 5252`-> NUMBER' 5253`--more-than=NUMBER' 5254 Print messages with more than NUMBER definitions, defaults to 1 if 5255 not set. 5256 5257`-u' 5258`--unique' 5259 Shorthand for `--less-than=2'. Requests that only unique messages 5260 be printed. 5261 5262 52639.6.4 Input file syntax 5264----------------------- 5265 5266`-P' 5267`--properties-input' 5268 Assume the input files are Java ResourceBundles in Java 5269 `.properties' syntax, not in PO file syntax. 5270 5271`--stringtable-input' 5272 Assume the input files are NeXTstep/GNUstep localized resource 5273 files in `.strings' syntax, not in PO file syntax. 5274 5275 52769.6.5 Output details 5277-------------------- 5278 5279`--force-po' 5280 Always write an output file even if it contains no message. 5281 5282`-i' 5283`--indent' 5284 Write the .po file using indented style. 5285 5286`--no-location' 5287 Do not write `#: FILENAME:LINE' lines. 5288 5289`-n' 5290`--add-location' 5291 Generate `#: FILENAME:LINE' lines (default). 5292 5293`--strict' 5294 Write out a strict Uniforum conforming PO file. Note that this 5295 Uniforum format should be avoided because it doesn't support the 5296 GNU extensions. 5297 5298`-p' 5299`--properties-output' 5300 Write out a Java ResourceBundle in Java `.properties' syntax. Note 5301 that this file format doesn't support plural forms and silently 5302 drops obsolete messages. 5303 5304`--stringtable-output' 5305 Write out a NeXTstep/GNUstep localized resource file in `.strings' 5306 syntax. Note that this file format doesn't support plural forms. 5307 5308`-w NUMBER' 5309`--width=NUMBER' 5310 Set the output page width. Long strings in the output files will 5311 be split across multiple lines in order to ensure that each line's 5312 width (= number of screen columns) is less or equal to the given 5313 NUMBER. 5314 5315`--no-wrap' 5316 Do not break long message lines. Message lines whose width 5317 exceeds the output page width will not be split into several 5318 lines. Only file reference lines which are wider than the output 5319 page width will be split. 5320 5321`-s' 5322`--sort-output' 5323 Generate sorted output. Note that using this option makes it much 5324 harder for the translator to understand each message's context. 5325 5326`-F' 5327`--sort-by-file' 5328 Sort output by file location. 5329 5330`--omit-header' 5331 Don't write header with `msgid ""' entry. 5332 5333 53349.6.6 Informative output 5335------------------------ 5336 5337`-h' 5338`--help' 5339 Display this help and exit. 5340 5341`-V' 5342`--version' 5343 Output version information and exit. 5344 5345 5346 5347File: gettext.info, Node: msgcmp Invocation, Next: msgattrib Invocation, Prev: msgcomm Invocation, Up: Manipulating 5348 53499.7 Invoking the `msgcmp' Program 5350================================= 5351 5352 msgcmp [OPTION] DEF.po REF.pot 5353 5354 The `msgcmp' program compares two Uniforum style .po files to check 5355that both contain the same set of msgid strings. The DEF.po file is an 5356existing PO file with the translations. The REF.pot file is the last 5357created PO file, or a PO Template file (generally created by 5358`xgettext'). This is useful for checking that you have translated each 5359and every message in your program. Where an exact match cannot be 5360found, fuzzy matching is used to produce better diagnostics. 5361 53629.7.1 Input file location 5363------------------------- 5364 5365`DEF.po' 5366 Translations. 5367 5368`REF.pot' 5369 References to the sources. 5370 5371`-D DIRECTORY' 5372`--directory=DIRECTORY' 5373 Add DIRECTORY to the list of directories. Source files are 5374 searched relative to this list of directories. 5375 5376 53779.7.2 Operation modifiers 5378------------------------- 5379 5380`-m' 5381`--multi-domain' 5382 Apply REF.pot to each of the domains in DEF.po. 5383 5384`--use-fuzzy' 5385 Consider fuzzy messages in the DEF.po file like translated 5386 messages. Note that using this option is usually wrong, because 5387 fuzzy messages are exactly those which have not been validated by 5388 a human translator. 5389 5390`--use-untranslated' 5391 Consider untranslated messages in the DEF.po file like translated 5392 messages. Note that using this option is usually wrong. 5393 5394 53959.7.3 Input file syntax 5396----------------------- 5397 5398`-P' 5399`--properties-input' 5400 Assume the input files are Java ResourceBundles in Java 5401 `.properties' syntax, not in PO file syntax. 5402 5403`--stringtable-input' 5404 Assume the input files are NeXTstep/GNUstep localized resource 5405 files in `.strings' syntax, not in PO file syntax. 5406 5407 54089.7.4 Informative output 5409------------------------ 5410 5411`-h' 5412`--help' 5413 Display this help and exit. 5414 5415`-V' 5416`--version' 5417 Output version information and exit. 5418 5419 5420 5421File: gettext.info, Node: msgattrib Invocation, Next: msgen Invocation, Prev: msgcmp Invocation, Up: Manipulating 5422 54239.8 Invoking the `msgattrib' Program 5424==================================== 5425 5426 msgattrib [OPTION] [INPUTFILE] 5427 5428 The `msgattrib' program filters the messages of a translation catalog 5429according to their attributes, and manipulates the attributes. 5430 54319.8.1 Input file location 5432------------------------- 5433 5434`INPUTFILE' 5435 Input PO file. 5436 5437`-D DIRECTORY' 5438`--directory=DIRECTORY' 5439 Add DIRECTORY to the list of directories. Source files are 5440 searched relative to this list of directories. The resulting `.po' 5441 file will be written relative to the current directory, though. 5442 5443 5444 If no INPUTFILE is given or if it is `-', standard input is read. 5445 54469.8.2 Output file location 5447-------------------------- 5448 5449`-o FILE' 5450`--output-file=FILE' 5451 Write output to specified file. 5452 5453 5454 The results are written to standard output if no output file is 5455specified or if it is `-'. 5456 54579.8.3 Message selection 5458----------------------- 5459 5460`--translated' 5461 Keep translated messages, remove untranslated messages. 5462 5463`--untranslated' 5464 Keep untranslated messages, remove translated messages. 5465 5466`--no-fuzzy' 5467 Remove `fuzzy' marked messages. 5468 5469`--only-fuzzy' 5470 Keep `fuzzy' marked messages, remove all other messages. 5471 5472`--no-obsolete' 5473 Remove obsolete #~ messages. 5474 5475`--only-obsolete' 5476 Keep obsolete #~ messages, remove all other messages. 5477 5478 54799.8.4 Attribute manipulation 5480---------------------------- 5481 5482Attributes are modified after the message selection/removal has been 5483performed. If the `--only-file' or `--ignore-file' option is 5484specified, the attribute modification is applied only to those messages 5485that are listed in the ONLY-FILE and not listed in the IGNORE-FILE. 5486 5487`--set-fuzzy' 5488 Set all messages `fuzzy'. 5489 5490`--clear-fuzzy' 5491 Set all messages non-`fuzzy'. 5492 5493`--set-obsolete' 5494 Set all messages obsolete. 5495 5496`--clear-obsolete' 5497 Set all messages non-obsolete. 5498 5499`--clear-previous' 5500 Remove the "previous msgid" (`#|') comments from all messages. 5501 5502`--only-file=FILE' 5503 Limit the attribute changes to entries that are listed in FILE. 5504 FILE should be a PO or POT file. 5505 5506`--ignore-file=FILE' 5507 Limit the attribute changes to entries that are not listed in FILE. 5508 FILE should be a PO or POT file. 5509 5510`--fuzzy' 5511 Synonym for `--only-fuzzy --clear-fuzzy': It keeps only the fuzzy 5512 messages and removes their `fuzzy' mark. 5513 5514`--obsolete' 5515 Synonym for `--only-obsolete --clear-obsolete': It keeps only the 5516 obsolete messages and makes them non-obsolete. 5517 5518 55199.8.5 Input file syntax 5520----------------------- 5521 5522`-P' 5523`--properties-input' 5524 Assume the input file is a Java ResourceBundle in Java 5525 `.properties' syntax, not in PO file syntax. 5526 5527`--stringtable-input' 5528 Assume the input file is a NeXTstep/GNUstep localized resource 5529 file in `.strings' syntax, not in PO file syntax. 5530 5531 55329.8.6 Output details 5533-------------------- 5534 5535`--force-po' 5536 Always write an output file even if it contains no message. 5537 5538`-i' 5539`--indent' 5540 Write the .po file using indented style. 5541 5542`--no-location' 5543 Do not write `#: FILENAME:LINE' lines. 5544 5545`-n' 5546`--add-location' 5547 Generate `#: FILENAME:LINE' lines (default). 5548 5549`--strict' 5550 Write out a strict Uniforum conforming PO file. Note that this 5551 Uniforum format should be avoided because it doesn't support the 5552 GNU extensions. 5553 5554`-p' 5555`--properties-output' 5556 Write out a Java ResourceBundle in Java `.properties' syntax. Note 5557 that this file format doesn't support plural forms and silently 5558 drops obsolete messages. 5559 5560`--stringtable-output' 5561 Write out a NeXTstep/GNUstep localized resource file in `.strings' 5562 syntax. Note that this file format doesn't support plural forms. 5563 5564`-w NUMBER' 5565`--width=NUMBER' 5566 Set the output page width. Long strings in the output files will 5567 be split across multiple lines in order to ensure that each line's 5568 width (= number of screen columns) is less or equal to the given 5569 NUMBER. 5570 5571`--no-wrap' 5572 Do not break long message lines. Message lines whose width 5573 exceeds the output page width will not be split into several 5574 lines. Only file reference lines which are wider than the output 5575 page width will be split. 5576 5577`-s' 5578`--sort-output' 5579 Generate sorted output. Note that using this option makes it much 5580 harder for the translator to understand each message's context. 5581 5582`-F' 5583`--sort-by-file' 5584 Sort output by file location. 5585 5586 55879.8.7 Informative output 5588------------------------ 5589 5590`-h' 5591`--help' 5592 Display this help and exit. 5593 5594`-V' 5595`--version' 5596 Output version information and exit. 5597 5598 5599 5600File: gettext.info, Node: msgen Invocation, Next: msgexec Invocation, Prev: msgattrib Invocation, Up: Manipulating 5601 56029.9 Invoking the `msgen' Program 5603================================ 5604 5605 msgen [OPTION] INPUTFILE 5606 5607 The `msgen' program creates an English translation catalog. The 5608input file is the last created English PO file, or a PO Template file 5609(generally created by xgettext). Untranslated entries are assigned a 5610translation that is identical to the msgid. 5611 5612 Note: `msginit --no-translator --locale=en' performs a very similar 5613task. The main difference is that `msginit' cares specially about the 5614header entry, whereas `msgen' doesn't. 5615 56169.9.1 Input file location 5617------------------------- 5618 5619`INPUTFILE' 5620 Input PO or POT file. 5621 5622`-D DIRECTORY' 5623`--directory=DIRECTORY' 5624 Add DIRECTORY to the list of directories. Source files are 5625 searched relative to this list of directories. The resulting `.po' 5626 file will be written relative to the current directory, though. 5627 5628 5629 If INPUTFILE is `-', standard input is read. 5630 56319.9.2 Output file location 5632-------------------------- 5633 5634`-o FILE' 5635`--output-file=FILE' 5636 Write output to specified file. 5637 5638 5639 The results are written to standard output if no output file is 5640specified or if it is `-'. 5641 56429.9.3 Input file syntax 5643----------------------- 5644 5645`-P' 5646`--properties-input' 5647 Assume the input file is a Java ResourceBundle in Java 5648 `.properties' syntax, not in PO file syntax. 5649 5650`--stringtable-input' 5651 Assume the input file is a NeXTstep/GNUstep localized resource 5652 file in `.strings' syntax, not in PO file syntax. 5653 5654 56559.9.4 Output details 5656-------------------- 5657 5658`--force-po' 5659 Always write an output file even if it contains no message. 5660 5661`-i' 5662`--indent' 5663 Write the .po file using indented style. 5664 5665`--no-location' 5666 Do not write `#: FILENAME:LINE' lines. 5667 5668`--add-location' 5669 Generate `#: FILENAME:LINE' lines (default). 5670 5671`--strict' 5672 Write out a strict Uniforum conforming PO file. Note that this 5673 Uniforum format should be avoided because it doesn't support the 5674 GNU extensions. 5675 5676`-p' 5677`--properties-output' 5678 Write out a Java ResourceBundle in Java `.properties' syntax. Note 5679 that this file format doesn't support plural forms and silently 5680 drops obsolete messages. 5681 5682`--stringtable-output' 5683 Write out a NeXTstep/GNUstep localized resource file in `.strings' 5684 syntax. Note that this file format doesn't support plural forms. 5685 5686`-w NUMBER' 5687`--width=NUMBER' 5688 Set the output page width. Long strings in the output files will 5689 be split across multiple lines in order to ensure that each line's 5690 width (= number of screen columns) is less or equal to the given 5691 NUMBER. 5692 5693`--no-wrap' 5694 Do not break long message lines. Message lines whose width 5695 exceeds the output page width will not be split into several 5696 lines. Only file reference lines which are wider than the output 5697 page width will be split. 5698 5699`-s' 5700`--sort-output' 5701 Generate sorted output. Note that using this option makes it much 5702 harder for the translator to understand each message's context. 5703 5704`-F' 5705`--sort-by-file' 5706 Sort output by file location. 5707 5708 57099.9.5 Informative output 5710------------------------ 5711 5712`-h' 5713`--help' 5714 Display this help and exit. 5715 5716`-V' 5717`--version' 5718 Output version information and exit. 5719 5720 5721 5722File: gettext.info, Node: msgexec Invocation, Next: libgettextpo, Prev: msgen Invocation, Up: Manipulating 5723 57249.10 Invoking the `msgexec' Program 5725=================================== 5726 5727 msgexec [OPTION] COMMAND [COMMAND-OPTION] 5728 5729 The `msgexec' program applies a command to all translations of a 5730translation catalog. The COMMAND can be any program that reads a 5731translation from standard input. It is invoked once for each 5732translation. Its output becomes msgexec's output. `msgexec''s return 5733code is the maximum return code across all invocations. 5734 5735 A special builtin command called `0' outputs the translation, 5736followed by a null byte. The output of `msgexec 0' is suitable as 5737input for `xargs -0'. 5738 5739 During each COMMAND invocation, the environment variable 5740`MSGEXEC_MSGID' is bound to the message's msgid, and the environment 5741variable `MSGEXEC_LOCATION' is bound to the location in the PO file of 5742the message. If the message has a context, the environment variable 5743`MSGEXEC_MSGCTXT' is bound to the message's msgctxt, otherwise it is 5744unbound. 5745 5746 Note: It is your responsibility to ensure that the COMMAND can cope 5747with input encoded in the translation catalog's encoding. If the 5748COMMAND wants input in a particular encoding, you can in a first step 5749convert the translation catalog to that encoding using the `msgconv' 5750program, before invoking `msgexec'. If the COMMAND wants input in the 5751locale's encoding, but you want to avoid the locale's encoding, then 5752you can first convert the translation catalog to UTF-8 using the 5753`msgconv' program and then make `msgexec' work in an UTF-8 locale, by 5754using the `LC_ALL' environment variable. 5755 57569.10.1 Input file location 5757-------------------------- 5758 5759`-i INPUTFILE' 5760`--input=INPUTFILE' 5761 Input PO file. 5762 5763`-D DIRECTORY' 5764`--directory=DIRECTORY' 5765 Add DIRECTORY to the list of directories. Source files are 5766 searched relative to this list of directories. The resulting `.po' 5767 file will be written relative to the current directory, though. 5768 5769 5770 If no INPUTFILE is given or if it is `-', standard input is read. 5771 57729.10.2 Input file syntax 5773------------------------ 5774 5775`-P' 5776`--properties-input' 5777 Assume the input file is a Java ResourceBundle in Java 5778 `.properties' syntax, not in PO file syntax. 5779 5780`--stringtable-input' 5781 Assume the input file is a NeXTstep/GNUstep localized resource 5782 file in `.strings' syntax, not in PO file syntax. 5783 5784 57859.10.3 Informative output 5786------------------------- 5787 5788`-h' 5789`--help' 5790 Display this help and exit. 5791 5792`-V' 5793`--version' 5794 Output version information and exit. 5795 5796 5797 5798File: gettext.info, Node: libgettextpo, Prev: msgexec Invocation, Up: Manipulating 5799 58009.11 Writing your own programs that process PO files 5801==================================================== 5802 5803For the tasks for which a combination of `msgattrib', `msgcat' etc. is 5804not sufficient, a set of C functions is provided in a library, to make 5805it possible to process PO files in your own programs. When you use 5806this library, you don't need to write routines to parse the PO file; 5807instead, you retrieve a pointer in memory to each of messages contained 5808in the PO file. Functions for writing PO files are not provided at 5809this time. 5810 5811 The functions are declared in the header file `<gettext-po.h>', and 5812are defined in a library called `libgettextpo'. 5813 5814 -- Data Type: po_file_t 5815 This is a pointer type that refers to the contents of a PO file, 5816 after it has been read into memory. 5817 5818 -- Data Type: po_message_iterator_t 5819 This is a pointer type that refers to an iterator that produces a 5820 sequence of messages. 5821 5822 -- Data Type: po_message_t 5823 This is a pointer type that refers to a message of a PO file, 5824 including its translation. 5825 5826 -- Function: po_file_t po_file_read (const char *FILENAME) 5827 The `po_file_read' function reads a PO file into memory. The file 5828 name is given as argument. The return value is a handle to the PO 5829 file's contents, valid until `po_file_free' is called on it. In 5830 case of error, the return value is `NULL', and `errno' is set. 5831 5832 -- Function: void po_file_free (po_file_t FILE) 5833 The `po_file_free' function frees a PO file's contents from memory, 5834 including all messages that are only implicitly accessible through 5835 iterators. 5836 5837 -- Function: const char * const * po_file_domains (po_file_t FILE) 5838 The `po_file_domains' function returns the domains for which the 5839 given PO file has messages. The return value is a `NULL' 5840 terminated array which is valid as long as the FILE handle is 5841 valid. For PO files which contain no `domain' directive, the 5842 return value contains only one domain, namely the default domain 5843 `"messages"'. 5844 5845 -- Function: po_message_iterator_t po_message_iterator (po_file_t 5846 FILE, const char *DOMAIN) 5847 The `po_message_iterator' returns an iterator that will produce the 5848 messages of FILE that belong to the given DOMAIN. If DOMAIN is 5849 `NULL', the default domain is used instead. To list the messages, 5850 use the function `po_next_message' repeatedly. 5851 5852 -- Function: void po_message_iterator_free (po_message_iterator_t 5853 ITERATOR) 5854 The `po_message_iterator_free' function frees an iterator 5855 previously allocated through the `po_message_iterator' function. 5856 5857 -- Function: po_message_t po_next_message (po_message_iterator_t 5858 ITERATOR) 5859 The `po_next_message' function returns the next message from 5860 ITERATOR and advances the iterator. It returns `NULL' when the 5861 iterator has reached the end of its message list. 5862 5863 The following functions returns details of a `po_message_t'. Recall 5864that the results are valid as long as the FILE handle is valid. 5865 5866 -- Function: const char * po_message_msgid (po_message_t MESSAGE) 5867 The `po_message_msgid' function returns the `msgid' (untranslated 5868 English string) of a message. This is guaranteed to be non-`NULL'. 5869 5870 -- Function: const char * po_message_msgid_plural (po_message_t 5871 MESSAGE) 5872 The `po_message_msgid_plural' function returns the `msgid_plural' 5873 (untranslated English plural string) of a message with plurals, or 5874 `NULL' for a message without plural. 5875 5876 -- Function: const char * po_message_msgstr (po_message_t MESSAGE) 5877 The `po_message_msgstr' function returns the `msgstr' (translation) 5878 of a message. For an untranslated message, the return value is an 5879 empty string. 5880 5881 -- Function: const char * po_message_msgstr_plural (po_message_t 5882 MESSAGE, int INDEX) 5883 The `po_message_msgstr_plural' function returns the 5884 `msgstr[INDEX]' of a message with plurals, or `NULL' when the 5885 INDEX is out of range or for a message without plural. 5886 5887 Here is an example code how these functions can be used. 5888 5889 const char *filename = ...; 5890 po_file_t file = po_file_read (filename); 5891 5892 if (file == NULL) 5893 error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename); 5894 { 5895 const char * const *domains = po_file_domains (file); 5896 const char * const *domainp; 5897 5898 for (domainp = domains; *domainp; domainp++) 5899 { 5900 const char *domain = *domainp; 5901 po_message_iterator_t iterator = po_message_iterator (file, domain); 5902 5903 for (;;) 5904 { 5905 po_message_t *message = po_next_message (iterator); 5906 5907 if (message == NULL) 5908 break; 5909 { 5910 const char *msgid = po_message_msgid (message); 5911 const char *msgstr = po_message_msgstr (message); 5912 5913 ... 5914 } 5915 } 5916 po_message_iterator_free (iterator); 5917 } 5918 } 5919 po_file_free (file); 5920 5921 5922File: gettext.info, Node: Binaries, Next: Programmers, Prev: Manipulating, Up: Top 5923 592410 Producing Binary MO Files 5925**************************** 5926 5927* Menu: 5928 5929* msgfmt Invocation:: Invoking the `msgfmt' Program 5930* msgunfmt Invocation:: Invoking the `msgunfmt' Program 5931* MO Files:: The Format of GNU MO Files 5932 5933 5934File: gettext.info, Node: msgfmt Invocation, Next: msgunfmt Invocation, Prev: Binaries, Up: Binaries 5935 593610.1 Invoking the `msgfmt' Program 5937================================== 5938 5939 msgfmt [OPTION] FILENAME.po ... 5940 5941 The `msgfmt' programs generates a binary message catalog from a 5942textual translation description. 5943 594410.1.1 Input file location 5945-------------------------- 5946 5947`FILENAME.po ...' 5948 5949`-D DIRECTORY' 5950`--directory=DIRECTORY' 5951 Add DIRECTORY to the list of directories. Source files are 5952 searched relative to this list of directories. The resulting `.po' 5953 file will be written relative to the current directory, though. 5954 5955 5956 If an input file is `-', standard input is read. 5957 595810.1.2 Operation mode 5959--------------------- 5960 5961`-j' 5962`--java' 5963 Java mode: generate a Java `ResourceBundle' class. 5964 5965`--java2' 5966 Like -java, and assume Java2 (JDK 1.2 or higher). 5967 5968`--csharp' 5969 C# mode: generate a .NET .dll file containing a subclass of 5970 `GettextResourceSet'. 5971 5972`--csharp-resources' 5973 C# resources mode: generate a .NET `.resources' file. 5974 5975`--tcl' 5976 Tcl mode: generate a tcl/msgcat `.msg' file. 5977 5978`--qt' 5979 Qt mode: generate a Qt `.qm' file. 5980 5981 598210.1.3 Output file location 5983--------------------------- 5984 5985`-o FILE' 5986`--output-file=FILE' 5987 Write output to specified file. 5988 5989`--strict' 5990 Direct the program to work strictly following the Uniforum/Sun 5991 implementation. Currently this only affects the naming of the 5992 output file. If this option is not given the name of the output 5993 file is the same as the domain name. If the strict Uniforum mode 5994 is enabled the suffix `.mo' is added to the file name if it is not 5995 already present. 5996 5997 We find this behaviour of Sun's implementation rather silly and so 5998 by default this mode is _not_ selected. 5999 6000 6001 If the output FILE is `-', output is written to standard output. 6002 600310.1.4 Output file location in Java mode 6004---------------------------------------- 6005 6006`-r RESOURCE' 6007`--resource=RESOURCE' 6008 Specify the resource name. 6009 6010`-l LOCALE' 6011`--locale=LOCALE' 6012 Specify the locale name, either a language specification of the 6013 form LL or a combined language and country specification of the 6014 form LL_CC. 6015 6016`-d DIRECTORY' 6017 Specify the base directory of classes directory hierarchy. 6018 6019 6020 The class name is determined by appending the locale name to the 6021resource name, separated with an underscore. The `-d' option is 6022mandatory. The class is written under the specified directory. 6023 602410.1.5 Output file location in C# mode 6025-------------------------------------- 6026 6027`-r RESOURCE' 6028`--resource=RESOURCE' 6029 Specify the resource name. 6030 6031`-l LOCALE' 6032`--locale=LOCALE' 6033 Specify the locale name, either a language specification of the 6034 form LL or a combined language and country specification of the 6035 form LL_CC. 6036 6037`-d DIRECTORY' 6038 Specify the base directory for locale dependent `.dll' files. 6039 6040 6041 The `-l' and `-d' options are mandatory. The `.dll' file is written 6042in a subdirectory of the specified directory whose name depends on the 6043locale. 6044 604510.1.6 Output file location in Tcl mode 6046--------------------------------------- 6047 6048`-l LOCALE' 6049`--locale=LOCALE' 6050 Specify the locale name, either a language specification of the 6051 form LL or a combined language and country specification of the 6052 form LL_CC. 6053 6054`-d DIRECTORY' 6055 Specify the base directory of `.msg' message catalogs. 6056 6057 6058 The `-l' and `-d' options are mandatory. The `.msg' file is written 6059in the specified directory. 6060 606110.1.7 Input file syntax 6062------------------------ 6063 6064`-P' 6065`--properties-input' 6066 Assume the input files are Java ResourceBundles in Java 6067 `.properties' syntax, not in PO file syntax. 6068 6069`--stringtable-input' 6070 Assume the input files are NeXTstep/GNUstep localized resource 6071 files in `.strings' syntax, not in PO file syntax. 6072 6073 607410.1.8 Input file interpretation 6075-------------------------------- 6076 6077`-c' 6078`--check' 6079 Perform all the checks implied by `--check-format', 6080 `--check-header', `--check-domain'. 6081 6082`--check-format' 6083 Check language dependent format strings. 6084 6085 If the string represents a format string used in a `printf'-like 6086 function both strings should have the same number of `%' format 6087 specifiers, with matching types. If the flag `c-format' or 6088 `possible-c-format' appears in the special comment <#,> for this 6089 entry a check is performed. For example, the check will diagnose 6090 using `%.*s' against `%s', or `%d' against `%s', or `%d' against 6091 `%x'. It can even handle positional parameters. 6092 6093 Normally the `xgettext' program automatically decides whether a 6094 string is a format string or not. This algorithm is not perfect, 6095 though. It might regard a string as a format string though it is 6096 not used in a `printf'-like function and so `msgfmt' might report 6097 errors where there are none. 6098 6099 To solve this problem the programmer can dictate the decision to 6100 the `xgettext' program (*note c-format::). The translator should 6101 not consider removing the flag from the <#,> line. This "fix" 6102 would be reversed again as soon as `msgmerge' is called the next 6103 time. 6104 6105`--check-header' 6106 Verify presence and contents of the header entry. *Note Header 6107 Entry::, for a description of the various fields in the header 6108 entry. 6109 6110`--check-domain' 6111 Check for conflicts between domain directives and the 6112 `--output-file' option 6113 6114`-C' 6115`--check-compatibility' 6116 Check that GNU msgfmt behaves like X/Open msgfmt. This will give 6117 an error when attempting to use the GNU extensions. 6118 6119`--check-accelerators[=CHAR]' 6120 Check presence of keyboard accelerators for menu items. This is 6121 based on the convention used in some GUIs that a keyboard 6122 accelerator in a menu item string is designated by an immediately 6123 preceding `&' character. Sometimes a keyboard accelerator is also 6124 called "keyboard mnemonic". This check verifies that if the 6125 untranslated string has exactly one `&' character, the translated 6126 string has exactly one `&' as well. If this option is given with 6127 a CHAR argument, this CHAR should be a non-alphanumeric character 6128 and is used as keyboard accelerator mark instead of `&'. 6129 6130`-f' 6131`--use-fuzzy' 6132 Use fuzzy entries in output. Note that using this option is 6133 usually wrong, because fuzzy messages are exactly those which have 6134 not been validated by a human translator. 6135 6136 613710.1.9 Output details 6138--------------------- 6139 6140`-a NUMBER' 6141`--alignment=NUMBER' 6142 Align strings to NUMBER bytes (default: 1). 6143 6144`--no-hash' 6145 Don't include a hash table in the binary file. Lookup will be 6146 more expensive at run time (binary search instead of hash table 6147 lookup). 6148 6149 615010.1.10 Informative output 6151-------------------------- 6152 6153`-h' 6154`--help' 6155 Display this help and exit. 6156 6157`-V' 6158`--version' 6159 Output version information and exit. 6160 6161`--statistics' 6162 Print statistics about translations. 6163 6164`-v' 6165`--verbose' 6166 Increase verbosity level. 6167 6168 6169 6170File: gettext.info, Node: msgunfmt Invocation, Next: MO Files, Prev: msgfmt Invocation, Up: Binaries 6171 617210.2 Invoking the `msgunfmt' Program 6173==================================== 6174 6175 msgunfmt [OPTION] [FILE]... 6176 6177 The `msgunfmt' program converts a binary message catalog to a 6178Uniforum style .po file. 6179 618010.2.1 Operation mode 6181--------------------- 6182 6183`-j' 6184`--java' 6185 Java mode: input is a Java `ResourceBundle' class. 6186 6187`--csharp' 6188 C# mode: input is a .NET .dll file containing a subclass of 6189 `GettextResourceSet'. 6190 6191`--csharp-resources' 6192 C# resources mode: input is a .NET `.resources' file. 6193 6194`--tcl' 6195 Tcl mode: input is a tcl/msgcat `.msg' file. 6196 6197 619810.2.2 Input file location 6199-------------------------- 6200 6201`FILE ...' 6202 Input .mo files. 6203 6204 6205 If no input FILE is given or if it is `-', standard input is read. 6206 620710.2.3 Input file location in Java mode 6208--------------------------------------- 6209 6210`-r RESOURCE' 6211`--resource=RESOURCE' 6212 Specify the resource name. 6213 6214`-l LOCALE' 6215`--locale=LOCALE' 6216 Specify the locale name, either a language specification of the 6217 form LL or a combined language and country specification of the 6218 form LL_CC. 6219 6220 6221 The class name is determined by appending the locale name to the 6222resource name, separated with an underscore. The class is located 6223using the `CLASSPATH'. 6224 622510.2.4 Input file location in C# mode 6226------------------------------------- 6227 6228`-r RESOURCE' 6229`--resource=RESOURCE' 6230 Specify the resource name. 6231 6232`-l LOCALE' 6233`--locale=LOCALE' 6234 Specify the locale name, either a language specification of the 6235 form LL or a combined language and country specification of the 6236 form LL_CC. 6237 6238`-d DIRECTORY' 6239 Specify the base directory for locale dependent `.dll' files. 6240 6241 6242 The `-l' and `-d' options are mandatory. The `.msg' file is located 6243in a subdirectory of the specified directory whose name depends on the 6244locale. 6245 624610.2.5 Input file location in Tcl mode 6247-------------------------------------- 6248 6249`-l LOCALE' 6250`--locale=LOCALE' 6251 Specify the locale name, either a language specification of the 6252 form LL or a combined language and country specification of the 6253 form LL_CC. 6254 6255`-d DIRECTORY' 6256 Specify the base directory of `.msg' message catalogs. 6257 6258 6259 The `-l' and `-d' options are mandatory. The `.msg' file is located 6260in the specified directory. 6261 626210.2.6 Output file location 6263--------------------------- 6264 6265`-o FILE' 6266`--output-file=FILE' 6267 Write output to specified file. 6268 6269 6270 The results are written to standard output if no output file is 6271specified or if it is `-'. 6272 627310.2.7 Output details 6274--------------------- 6275 6276`--force-po' 6277 Always write an output file even if it contains no message. 6278 6279`-i' 6280`--indent' 6281 Write the .po file using indented style. 6282 6283`--strict' 6284 Write out a strict Uniforum conforming PO file. Note that this 6285 Uniforum format should be avoided because it doesn't support the 6286 GNU extensions. 6287 6288`-p' 6289`--properties-output' 6290 Write out a Java ResourceBundle in Java `.properties' syntax. Note 6291 that this file format doesn't support plural forms and silently 6292 drops obsolete messages. 6293 6294`--stringtable-output' 6295 Write out a NeXTstep/GNUstep localized resource file in `.strings' 6296 syntax. Note that this file format doesn't support plural forms. 6297 6298`-w NUMBER' 6299`--width=NUMBER' 6300 Set the output page width. Long strings in the output files will 6301 be split across multiple lines in order to ensure that each line's 6302 width (= number of screen columns) is less or equal to the given 6303 NUMBER. 6304 6305`--no-wrap' 6306 Do not break long message lines. Message lines whose width 6307 exceeds the output page width will not be split into several 6308 lines. Only file reference lines which are wider than the output 6309 page width will be split. 6310 6311`-s' 6312`--sort-output' 6313 Generate sorted output. Note that using this option makes it much 6314 harder for the translator to understand each message's context. 6315 6316 631710.2.8 Informative output 6318------------------------- 6319 6320`-h' 6321`--help' 6322 Display this help and exit. 6323 6324`-V' 6325`--version' 6326 Output version information and exit. 6327 6328`-v' 6329`--verbose' 6330 Increase verbosity level. 6331 6332 6333 6334File: gettext.info, Node: MO Files, Prev: msgunfmt Invocation, Up: Binaries 6335 633610.3 The Format of GNU MO Files 6337=============================== 6338 6339The format of the generated MO files is best described by a picture, 6340which appears below. 6341 6342 The first two words serve the identification of the file. The magic 6343number will always signal GNU MO files. The number is stored in the 6344byte order of the generating machine, so the magic number really is two 6345numbers: `0x950412de' and `0xde120495'. The second word describes the 6346current revision of the file format. For now the revision is 0. This 6347might change in future versions, and ensures that the readers of MO 6348files can distinguish new formats from old ones, so that both can be 6349handled correctly. The version is kept separate from the magic number, 6350instead of using different magic numbers for different formats, mainly 6351because `/etc/magic' is not updated often. It might be better to have 6352magic separated from internal format version identification. 6353 6354 Follow a number of pointers to later tables in the file, allowing 6355for the extension of the prefix part of MO files without having to 6356recompile programs reading them. This might become useful for later 6357inserting a few flag bits, indication about the charset used, new 6358tables, or other things. 6359 6360 Then, at offset O and offset T in the picture, two tables of string 6361descriptors can be found. In both tables, each string descriptor uses 6362two 32 bits integers, one for the string length, another for the offset 6363of the string in the MO file, counting in bytes from the start of the 6364file. The first table contains descriptors for the original strings, 6365and is sorted so the original strings are in increasing lexicographical 6366order. The second table contains descriptors for the translated 6367strings, and is parallel to the first table: to find the corresponding 6368translation one has to access the array slot in the second array with 6369the same index. 6370 6371 Having the original strings sorted enables the use of simple binary 6372search, for when the MO file does not contain an hashing table, or for 6373when it is not practical to use the hashing table provided in the MO 6374file. This also has another advantage, as the empty string in a PO 6375file GNU `gettext' is usually _translated_ into some system information 6376attached to that particular MO file, and the empty string necessarily 6377becomes the first in both the original and translated tables, making 6378the system information very easy to find. 6379 6380 The size S of the hash table can be zero. In this case, the hash 6381table itself is not contained in the MO file. Some people might prefer 6382this because a precomputed hashing table takes disk space, and does not 6383win _that_ much speed. The hash table contains indices to the sorted 6384array of strings in the MO file. Conflict resolution is done by double 6385hashing. The precise hashing algorithm used is fairly dependent on GNU 6386`gettext' code, and is not documented here. 6387 6388 As for the strings themselves, they follow the hash file, and each 6389is terminated with a <NUL>, and this <NUL> is not counted in the length 6390which appears in the string descriptor. The `msgfmt' program has an 6391option selecting the alignment for MO file strings. With this option, 6392each string is separately aligned so it starts at an offset which is a 6393multiple of the alignment value. On some RISC machines, a correct 6394alignment will speed things up. 6395 6396 Contexts are stored by storing the concatenation of the context, a 6397<EOT> byte, and the original string, instead of the original string. 6398 6399 Plural forms are stored by letting the plural of the original string 6400follow the singular of the original string, separated through a <NUL> 6401byte. The length which appears in the string descriptor includes both. 6402However, only the singular of the original string takes part in the 6403hash table lookup. The plural variants of the translation are all 6404stored consecutively, separated through a <NUL> byte. Here also, the 6405length in the string descriptor includes all of them. 6406 6407 Nothing prevents a MO file from having embedded <NUL>s in strings. 6408However, the program interface currently used already presumes that 6409strings are <NUL> terminated, so embedded <NUL>s are somewhat useless. 6410But the MO file format is general enough so other interfaces would be 6411later possible, if for example, we ever want to implement wide 6412characters right in MO files, where <NUL> bytes may accidentally 6413appear. (No, we don't want to have wide characters in MO files. They 6414would make the file unnecessarily large, and the `wchar_t' type being 6415platform dependent, MO files would be platform dependent as well.) 6416 6417 This particular issue has been strongly debated in the GNU `gettext' 6418development forum, and it is expectable that MO file format will evolve 6419or change over time. It is even possible that many formats may later 6420be supported concurrently. But surely, we have to start somewhere, and 6421the MO file format described here is a good start. Nothing is cast in 6422concrete, and the format may later evolve fairly easily, so we should 6423feel comfortable with the current approach. 6424 6425 byte 6426 +------------------------------------------+ 6427 0 | magic number = 0x950412de | 6428 | | 6429 4 | file format revision = 0 | 6430 | | 6431 8 | number of strings | == N 6432 | | 6433 12 | offset of table with original strings | == O 6434 | | 6435 16 | offset of table with translation strings | == T 6436 | | 6437 20 | size of hashing table | == S 6438 | | 6439 24 | offset of hashing table | == H 6440 | | 6441 . . 6442 . (possibly more entries later) . 6443 . . 6444 | | 6445 O | length & offset 0th string ----------------. 6446 O + 8 | length & offset 1st string ------------------. 6447 ... ... | | 6448 O + ((N-1)*8)| length & offset (N-1)th string | | | 6449 | | | | 6450 T | length & offset 0th translation ---------------. 6451 T + 8 | length & offset 1st translation -----------------. 6452 ... ... | | | | 6453 T + ((N-1)*8)| length & offset (N-1)th translation | | | | | 6454 | | | | | | 6455 H | start hash table | | | | | 6456 ... ... | | | | 6457 H + S * 4 | end hash table | | | | | 6458 | | | | | | 6459 | NUL terminated 0th string <----------------' | | | 6460 | | | | | 6461 | NUL terminated 1st string <------------------' | | 6462 | | | | 6463 ... ... | | 6464 | | | | 6465 | NUL terminated 0th translation <---------------' | 6466 | | | 6467 | NUL terminated 1st translation <-----------------' 6468 | | 6469 ... ... 6470 | | 6471 +------------------------------------------+ 6472 6473 6474File: gettext.info, Node: Programmers, Next: Translators, Prev: Binaries, Up: Top 6475 647611 The Programmer's View 6477************************ 6478 6479One aim of the current message catalog implementation provided by GNU 6480`gettext' was to use the system's message catalog handling, if the 6481installer wishes to do so. So we perhaps should first take a look at 6482the solutions we know about. The people in the POSIX committee did not 6483manage to agree on one of the semi-official standards which we'll 6484describe below. In fact they couldn't agree on anything, so they 6485decided only to include an example of an interface. The major Unix 6486vendors are split in the usage of the two most important 6487specifications: X/Open's catgets vs. Uniforum's gettext interface. 6488We'll describe them both and later explain our solution of this dilemma. 6489 6490* Menu: 6491 6492* catgets:: About `catgets' 6493* gettext:: About `gettext' 6494* Comparison:: Comparing the two interfaces 6495* Using libintl.a:: Using libintl.a in own programs 6496* gettext grok:: Being a `gettext' grok 6497* Temp Programmers:: Temporary Notes for the Programmers Chapter 6498 6499 6500File: gettext.info, Node: catgets, Next: gettext, Prev: Programmers, Up: Programmers 6501 650211.1 About `catgets' 6503==================== 6504 6505The `catgets' implementation is defined in the X/Open Portability 6506Guide, Volume 3, XSI Supplementary Definitions, Chapter 5. But the 6507process of creating this standard seemed to be too slow for some of the 6508Unix vendors so they created their implementations on preliminary 6509versions of the standard. Of course this leads again to problems while 6510writing platform independent programs: even the usage of `catgets' does 6511not guarantee a unique interface. 6512 6513 Another, personal comment on this that only a bunch of committee 6514members could have made this interface. They never really tried to 6515program using this interface. It is a fast, memory-saving 6516implementation, an user can happily live with it. But programmers hate 6517it (at least I and some others do...) 6518 6519 But we must not forget one point: after all the trouble with 6520transferring the rights on Unix(tm) they at last came to X/Open, the 6521very same who published this specification. This leads me to making 6522the prediction that this interface will be in future Unix standards 6523(e.g. Spec1170) and therefore part of all Unix implementation 6524(implementations, which are _allowed_ to wear this name). 6525 6526* Menu: 6527 6528* Interface to catgets:: The interface 6529* Problems with catgets:: Problems with the `catgets' interface?! 6530 6531 6532File: gettext.info, Node: Interface to catgets, Next: Problems with catgets, Prev: catgets, Up: catgets 6533 653411.1.1 The Interface 6535-------------------- 6536 6537The interface to the `catgets' implementation consists of three 6538functions which correspond to those used in file access: `catopen' to 6539open the catalog for using, `catgets' for accessing the message tables, 6540and `catclose' for closing after work is done. Prototypes for the 6541functions and the needed definitions are in the `<nl_types.h>' header 6542file. 6543 6544 `catopen' is used like in this: 6545 6546 nl_catd catd = catopen ("catalog_name", 0); 6547 6548 The function takes as the argument the name of the catalog. This 6549usual refers to the name of the program or the package. The second 6550parameter is not further specified in the standard. I don't even know 6551whether it is implemented consistently among various systems. So the 6552common advice is to use `0' as the value. The return value is a handle 6553to the message catalog, equivalent to handles to file returned by 6554`open'. 6555 6556 This handle is of course used in the `catgets' function which can be 6557used like this: 6558 6559 char *translation = catgets (catd, set_no, msg_id, "original string"); 6560 6561 The first parameter is this catalog descriptor. The second parameter 6562specifies the set of messages in this catalog, in which the message 6563described by `msg_id' is obtained. `catgets' therefore uses a 6564three-stage addressing: 6565 6566 catalog name => set number => message ID => translation 6567 6568 The fourth argument is not used to address the translation. It is 6569given as a default value in case when one of the addressing stages 6570fail. One important thing to remember is that although the return type 6571of catgets is `char *' the resulting string _must not_ be changed. It 6572should better be `const char *', but the standard is published in 1988, 6573one year before ANSI C. 6574 6575The last of these functions is used and behaves as expected: 6576 6577 catclose (catd); 6578 6579 After this no `catgets' call using the descriptor is legal anymore. 6580 6581 6582File: gettext.info, Node: Problems with catgets, Prev: Interface to catgets, Up: catgets 6583 658411.1.2 Problems with the `catgets' Interface?! 6585---------------------------------------------- 6586 6587Now that this description seemed to be really easy -- where are the 6588problems we speak of? In fact the interface could be used in a 6589reasonable way, but constructing the message catalogs is a pain. The 6590reason for this lies in the third argument of `catgets': the unique 6591message ID. This has to be a numeric value for all messages in a single 6592set. Perhaps you could imagine the problems keeping such a list while 6593changing the source code. Add a new message here, remove one there. Of 6594course there have been developed a lot of tools helping to organize this 6595chaos but one as the other fails in one aspect or the other. We don't 6596want to say that the other approach has no problems but they are far 6597more easy to manage. 6598 6599 6600File: gettext.info, Node: gettext, Next: Comparison, Prev: catgets, Up: Programmers 6601 660211.2 About `gettext' 6603==================== 6604 6605The definition of the `gettext' interface comes from a Uniforum 6606proposal. It was submitted there by Sun, who had implemented the 6607`gettext' function in SunOS 4, around 1990. Nowadays, the `gettext' 6608interface is specified by the OpenI18N standard. 6609 6610 The main point about this solution is that it does not follow the 6611method of normal file handling (open-use-close) and that it does not 6612burden the programmer with so many tasks, especially the unique key 6613handling. Of course here also a unique key is needed, but this key is 6614the message itself (how long or short it is). See *Note Comparison:: 6615for a more detailed comparison of the two methods. 6616 6617 The following section contains a rather detailed description of the 6618interface. We make it that detailed because this is the interface we 6619chose for the GNU `gettext' Library. Programmers interested in using 6620this library will be interested in this description. 6621 6622* Menu: 6623 6624* Interface to gettext:: The interface 6625* Ambiguities:: Solving ambiguities 6626* Locating Catalogs:: Locating message catalog files 6627* Charset conversion:: How to request conversion to Unicode 6628* Contexts:: Solving ambiguities in GUI programs 6629* Plural forms:: Additional functions for handling plurals 6630* Optimized gettext:: Optimization of the *gettext functions 6631 6632 6633File: gettext.info, Node: Interface to gettext, Next: Ambiguities, Prev: gettext, Up: gettext 6634 663511.2.1 The Interface 6636-------------------- 6637 6638The minimal functionality an interface must have is a) to select a 6639domain the strings are coming from (a single domain for all programs is 6640not reasonable because its construction and maintenance is difficult, 6641perhaps impossible) and b) to access a string in a selected domain. 6642 6643 This is principally the description of the `gettext' interface. It 6644has a global domain which unqualified usages reference. Of course this 6645domain is selectable by the user. 6646 6647 char *textdomain (const char *domain_name); 6648 6649 This provides the possibility to change or query the current status 6650of the current global domain of the `LC_MESSAGE' category. The 6651argument is a null-terminated string, whose characters must be legal in 6652the use in filenames. If the DOMAIN_NAME argument is `NULL', the 6653function returns the current value. If no value has been set before, 6654the name of the default domain is returned: _messages_. Please note 6655that although the return value of `textdomain' is of type `char *' no 6656changing is allowed. It is also important to know that no checks of 6657the availability are made. If the name is not available you will see 6658this by the fact that no translations are provided. 6659 6660To use a domain set by `textdomain' the function 6661 6662 char *gettext (const char *msgid); 6663 6664is to be used. This is the simplest reasonable form one can imagine. 6665The translation of the string MSGID is returned if it is available in 6666the current domain. If it is not available, the argument itself is 6667returned. If the argument is `NULL' the result is undefined. 6668 6669 One thing which should come into mind is that no explicit dependency 6670to the used domain is given. The current value of the domain for the 6671`LC_MESSAGES' locale is used. If this changes between two executions 6672of the same `gettext' call in the program, both calls reference a 6673different message catalog. 6674 6675 For the easiest case, which is normally used in internationalized 6676packages, once at the beginning of execution a call to `textdomain' is 6677issued, setting the domain to a unique name, normally the package name. 6678In the following code all strings which have to be translated are 6679filtered through the gettext function. That's all, the package speaks 6680your language. 6681 6682 6683File: gettext.info, Node: Ambiguities, Next: Locating Catalogs, Prev: Interface to gettext, Up: gettext 6684 668511.2.2 Solving Ambiguities 6686-------------------------- 6687 6688While this single name domain works well for most applications there 6689might be the need to get translations from more than one domain. Of 6690course one could switch between different domains with calls to 6691`textdomain', but this is really not convenient nor is it fast. A 6692possible situation could be one case subject to discussion during this 6693writing: all error messages of functions in the set of common used 6694functions should go into a separate domain `error'. By this mean we 6695would only need to translate them once. Another case are messages from 6696a library, as these _have_ to be independent of the current domain set 6697by the application. 6698 6699For this reasons there are two more functions to retrieve strings: 6700 6701 char *dgettext (const char *domain_name, const char *msgid); 6702 char *dcgettext (const char *domain_name, const char *msgid, 6703 int category); 6704 6705 Both take an additional argument at the first place, which 6706corresponds to the argument of `textdomain'. The third argument of 6707`dcgettext' allows to use another locale but `LC_MESSAGES'. But I 6708really don't know where this can be useful. If the DOMAIN_NAME is 6709`NULL' or CATEGORY has an value beside the known ones, the result is 6710undefined. It should also be noted that this function is not part of 6711the second known implementation of this function family, the one found 6712in Solaris. 6713 6714 A second ambiguity can arise by the fact, that perhaps more than one 6715domain has the same name. This can be solved by specifying where the 6716needed message catalog files can be found. 6717 6718 char *bindtextdomain (const char *domain_name, 6719 const char *dir_name); 6720 6721 Calling this function binds the given domain to a file in the 6722specified directory (how this file is determined follows below). 6723Especially a file in the systems default place is not favored against 6724the specified file anymore (as it would be by solely using 6725`textdomain'). A `NULL' pointer for the DIR_NAME parameter returns the 6726binding associated with DOMAIN_NAME. If DOMAIN_NAME itself is `NULL' 6727nothing happens and a `NULL' pointer is returned. Here again as for 6728all the other functions is true that none of the return value must be 6729changed! 6730 6731 It is important to remember that relative path names for the 6732DIR_NAME parameter can be trouble. Since the path is always computed 6733relative to the current directory different results will be achieved 6734when the program executes a `chdir' command. Relative paths should 6735always be avoided to avoid dependencies and unreliabilities. 6736 6737 6738File: gettext.info, Node: Locating Catalogs, Next: Charset conversion, Prev: Ambiguities, Up: gettext 6739 674011.2.3 Locating Message Catalog Files 6741------------------------------------- 6742 6743Because many different languages for many different packages have to be 6744stored we need some way to add these information to file message catalog 6745files. The way usually used in Unix environments is have this encoding 6746in the file name. This is also done here. The directory name given in 6747`bindtextdomain's second argument (or the default directory), followed 6748by the value and name of the locale and the domain name are 6749concatenated: 6750 6751 DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo 6752 6753 The default value for DIR_NAME is system specific. For the GNU 6754library, and for packages adhering to its conventions, it's: 6755 /usr/local/share/locale 6756 6757LOCALE is the value of the locale whose name is this `LC_CATEGORY'. 6758For `gettext' and `dgettext' this `LC_CATEGORY' is always 6759`LC_MESSAGES'.(1) The value of the locale is determined through 6760`setlocale (LC_CATEGORY, NULL)'. (2) `dcgettext' specifies the locale 6761category by the third argument. 6762 6763 ---------- Footnotes ---------- 6764 6765 (1) Some system, eg Ultrix, don't have `LC_MESSAGES'. Here we use a 6766more or less arbitrary value for it, namely 1729, the smallest positive 6767integer which can be represented in two different ways as the sum of 6768two cubes. 6769 6770 (2) When the system does not support `setlocale' its behavior in 6771setting the locale values is simulated by looking at the environment 6772variables. 6773 6774 6775File: gettext.info, Node: Charset conversion, Next: Contexts, Prev: Locating Catalogs, Up: gettext 6776 677711.2.4 How to specify the output character set `gettext' uses 6778------------------------------------------------------------- 6779 6780`gettext' not only looks up a translation in a message catalog. It 6781also converts the translation on the fly to the desired output character 6782set. This is useful if the user is working in a different character set 6783than the translator who created the message catalog, because it avoids 6784distributing variants of message catalogs which differ only in the 6785character set. 6786 6787 The output character set is, by default, the value of `nl_langinfo 6788(CODESET)', which depends on the `LC_CTYPE' part of the current locale. 6789But programs which store strings in a locale independent way (e.g. 6790UTF-8) can request that `gettext' and related functions return the 6791translations in that encoding, by use of the `bind_textdomain_codeset' 6792function. 6793 6794 Note that the MSGID argument to `gettext' is not subject to 6795character set conversion. Also, when `gettext' does not find a 6796translation for MSGID, it returns MSGID unchanged - independently of 6797the current output character set. It is therefore recommended that all 6798MSGIDs be US-ASCII strings. 6799 6800 -- Function: char * bind_textdomain_codeset (const char *DOMAINNAME, 6801 const char *CODESET) 6802 The `bind_textdomain_codeset' function can be used to specify the 6803 output character set for message catalogs for domain DOMAINNAME. 6804 The CODESET argument must be a valid codeset name which can be used 6805 for the `iconv_open' function, or a null pointer. 6806 6807 If the CODESET parameter is the null pointer, 6808 `bind_textdomain_codeset' returns the currently selected codeset 6809 for the domain with the name DOMAINNAME. It returns `NULL' if no 6810 codeset has yet been selected. 6811 6812 The `bind_textdomain_codeset' function can be used several times. 6813 If used multiple times with the same DOMAINNAME argument, the 6814 later call overrides the settings made by the earlier one. 6815 6816 The `bind_textdomain_codeset' function returns a pointer to a 6817 string containing the name of the selected codeset. The string is 6818 allocated internally in the function and must not be changed by the 6819 user. If the system went out of core during the execution of 6820 `bind_textdomain_codeset', the return value is `NULL' and the 6821 global variable ERRNO is set accordingly. 6822 6823 6824File: gettext.info, Node: Contexts, Next: Plural forms, Prev: Charset conversion, Up: gettext 6825 682611.2.5 Using contexts for solving ambiguities 6827--------------------------------------------- 6828 6829One place where the `gettext' functions, if used normally, have big 6830problems is within programs with graphical user interfaces (GUIs). The 6831problem is that many of the strings which have to be translated are very 6832short. They have to appear in pull-down menus which restricts the 6833length. But strings which are not containing entire sentences or at 6834least large fragments of a sentence may appear in more than one 6835situation in the program but might have different translations. This is 6836especially true for the one-word strings which are frequently used in 6837GUI programs. 6838 6839 As a consequence many people say that the `gettext' approach is 6840wrong and instead `catgets' should be used which indeed does not have 6841this problem. But there is a very simple and powerful method to handle 6842this kind of problems with the `gettext' functions. 6843 6844 Contexts can be added to strings to be translated. A context 6845dependent translation lookup is when a translation for a given string 6846is searched, that is limited to a given context. The translation for 6847the same string in a different context can be different. The different 6848translations of the same string in different contexts can be stored in 6849the in the same MO file, and can be edited by the translator in the 6850same PO file. 6851 6852 The `gettext.h' include file contains the lookup macros for strings 6853with contexts. They are implemented as thin macros and inline functions 6854over the functions from `<libintl.h>'. 6855 6856 const char *pgettext (const char *msgctxt, const char *msgid); 6857 6858 In a call of this macro, MSGCTXT and MSGID must be string literals. 6859The macro returns the translation of MSGID, restricted to the context 6860given by MSGCTXT. 6861 6862 The MSGCTXT string is visible in the PO file to the translator. You 6863should try to make it somehow canonical and never changing. Because 6864every time you change an MSGCTXT, the translator will have to review 6865the translation of MSGID. 6866 6867 Finding a canonical MSGCTXT string that doesn't change over time can 6868be hard. But you shouldn't use the file name or class name containing 6869the `pgettext' call - because it is a common development task to rename 6870a file or a class, and it shouldn't cause translator work. Also you 6871shouldn't use a comment in the form of a complete English sentence as 6872MSGCTXT - because orthography or grammar changes are often applied to 6873such sentences, and again, it shouldn't force the translator to do a 6874review. 6875 6876 The `p' in `pgettext' stands for "particular": `pgettext' fetches a 6877particular translation of the MSGID. 6878 6879 const char *dpgettext (const char *domain_name, 6880 const char *msgctxt, const char *msgid); 6881 const char *dcpgettext (const char *domain_name, 6882 const char *msgctxt, const char *msgid, 6883 int category); 6884 6885 These are generalizations of `pgettext'. They behave similarly to 6886`dgettext' and `dcgettext', respectively. The DOMAIN_NAME argument 6887defines the translation domain. The CATEGORY argument allows to use 6888another locale facet than `LC_MESSAGES'. 6889 6890 As as example consider the following fictional situation. A GUI 6891program has a menu bar with the following entries: 6892 6893 +------------+------------+--------------------------------------+ 6894 | File | Printer | | 6895 +------------+------------+--------------------------------------+ 6896 | Open | | Select | 6897 | New | | Open | 6898 +----------+ | Connect | 6899 +----------+ 6900 6901 To have the strings `File', `Printer', `Open', `New', `Select', and 6902`Connect' translated there has to be at some point in the code a call 6903to a function of the `gettext' family. But in two places the string 6904passed into the function would be `Open'. The translations might not 6905be the same and therefore we are in the dilemma described above. 6906 6907 What distinguishes the two places is the menu path from the menu 6908root to the particular menu entries: 6909 6910 Menu|File 6911 Menu|Printer 6912 Menu|File|Open 6913 Menu|File|New 6914 Menu|Printer|Select 6915 Menu|Printer|Open 6916 Menu|Printer|Connect 6917 6918 The context is thus the menu path without its last part. So, the 6919calls look like this: 6920 6921 pgettext ("Menu|", "File") 6922 pgettext ("Menu|", "Printer") 6923 pgettext ("Menu|File|", "Open") 6924 pgettext ("Menu|File|", "New") 6925 pgettext ("Menu|Printer|", "Select") 6926 pgettext ("Menu|Printer|", "Open") 6927 pgettext ("Menu|Printer|", "Connect") 6928 6929 Whether or not to use the `|' character at the end of the context is 6930a matter of style. 6931 6932 For more complex cases, where the MSGCTXT or MSGID are not string 6933literals, more general macros are available: 6934 6935 const char *pgettext_expr (const char *msgctxt, const char *msgid); 6936 const char *dpgettext_expr (const char *domain_name, 6937 const char *msgctxt, const char *msgid); 6938 const char *dcpgettext_expr (const char *domain_name, 6939 const char *msgctxt, const char *msgid, 6940 int category); 6941 6942 Here MSGCTXT and MSGID can be arbitrary string-valued expressions. 6943These macros are more general. But in the case that both argument 6944expressions are string literals, the macros without the `_expr' suffix 6945are more efficient. 6946 6947 6948File: gettext.info, Node: Plural forms, Next: Optimized gettext, Prev: Contexts, Up: gettext 6949 695011.2.6 Additional functions for plural forms 6951-------------------------------------------- 6952 6953The functions of the `gettext' family described so far (and all the 6954`catgets' functions as well) have one problem in the real world which 6955have been neglected completely in all existing approaches. What is 6956meant here is the handling of plural forms. 6957 6958 Looking through Unix source code before the time anybody thought 6959about internationalization (and, sadly, even afterwards) one can often 6960find code similar to the following: 6961 6962 printf ("%d file%s deleted", n, n == 1 ? "" : "s"); 6963 6964After the first complaints from people internationalizing the code 6965people either completely avoided formulations like this or used strings 6966like `"file(s)"'. Both look unnatural and should be avoided. First 6967tries to solve the problem correctly looked like this: 6968 6969 if (n == 1) 6970 printf ("%d file deleted", n); 6971 else 6972 printf ("%d files deleted", n); 6973 6974 But this does not solve the problem. It helps languages where the 6975plural form of a noun is not simply constructed by adding an `s' but 6976that is all. Once again people fell into the trap of believing the 6977rules their language is using are universal. But the handling of plural 6978forms differs widely between the language families. For example, Rafal 6979Maszkowski `<rzm@mat.uni.torun.pl>' reports: 6980 6981 In Polish we use e.g. plik (file) this way: 6982 1 plik 6983 2,3,4 pliki 6984 5-21 pliko'w 6985 22-24 pliki 6986 25-31 pliko'w 6987 and so on (o' means 8859-2 oacute which should be rather okreska, 6988 similar to aogonek). 6989 6990 There are two things which can differ between languages (and even 6991inside language families); 6992 6993 * The form how plural forms are built differs. This is a problem 6994 with languages which have many irregularities. German, for 6995 instance, is a drastic case. Though English and German are part 6996 of the same language family (Germanic), the almost regular forming 6997 of plural noun forms (appending an `s') is hardly found in German. 6998 6999 * The number of plural forms differ. This is somewhat surprising for 7000 those who only have experiences with Romanic and Germanic languages 7001 since here the number is the same (there are two). 7002 7003 But other language families have only one form or many forms. More 7004 information on this in an extra section. 7005 7006 The consequence of this is that application writers should not try to 7007solve the problem in their code. This would be localization since it is 7008only usable for certain, hardcoded language environments. Instead the 7009extended `gettext' interface should be used. 7010 7011 These extra functions are taking instead of the one key string two 7012strings and a numerical argument. The idea behind this is that using 7013the numerical argument and the first string as a key, the implementation 7014can select using rules specified by the translator the right plural 7015form. The two string arguments then will be used to provide a return 7016value in case no message catalog is found (similar to the normal 7017`gettext' behavior). In this case the rules for Germanic language is 7018used and it is assumed that the first string argument is the singular 7019form, the second the plural form. 7020 7021 This has the consequence that programs without language catalogs can 7022display the correct strings only if the program itself is written using 7023a Germanic language. This is a limitation but since the GNU C library 7024(as well as the GNU `gettext' package) are written as part of the GNU 7025package and the coding standards for the GNU project require program 7026being written in English, this solution nevertheless fulfills its 7027purpose. 7028 7029 -- Function: char * ngettext (const char *MSGID1, const char *MSGID2, 7030 unsigned long int N) 7031 The `ngettext' function is similar to the `gettext' function as it 7032 finds the message catalogs in the same way. But it takes two 7033 extra arguments. The MSGID1 parameter must contain the singular 7034 form of the string to be converted. It is also used as the key 7035 for the search in the catalog. The MSGID2 parameter is the plural 7036 form. The parameter N is used to determine the plural form. If no 7037 message catalog is found MSGID1 is returned if `n == 1', otherwise 7038 `msgid2'. 7039 7040 An example for the use of this function is: 7041 7042 printf (ngettext ("%d file removed", "%d files removed", n), n); 7043 7044 Please note that the numeric value N has to be passed to the 7045 `printf' function as well. It is not sufficient to pass it only to 7046 `ngettext'. 7047 7048 In the English singular case, the number - always 1 - can be 7049 replaced with "one": 7050 7051 printf (ngettext ("One file removed", "%d files removed", n), n); 7052 7053 This works because the `printf' function discards excess arguments 7054 that are not consumed by the format string. 7055 7056 It is also possible to use this function when the strings don't 7057 contain a cardinal number: 7058 7059 puts (ngettext ("Delete the selected file?", 7060 "Delete the selected files?", 7061 n)); 7062 7063 In this case the number N is only used to choose the plural form. 7064 7065 -- Function: char * dngettext (const char *DOMAIN, const char *MSGID1, 7066 const char *MSGID2, unsigned long int N) 7067 The `dngettext' is similar to the `dgettext' function in the way 7068 the message catalog is selected. The difference is that it takes 7069 two extra parameter to provide the correct plural form. These two 7070 parameters are handled in the same way `ngettext' handles them. 7071 7072 -- Function: char * dcngettext (const char *DOMAIN, const char 7073 *MSGID1, const char *MSGID2, unsigned long int N, int 7074 CATEGORY) 7075 The `dcngettext' is similar to the `dcgettext' function in the way 7076 the message catalog is selected. The difference is that it takes 7077 two extra parameter to provide the correct plural form. These two 7078 parameters are handled in the same way `ngettext' handles them. 7079 7080 Now, how do these functions solve the problem of the plural forms? 7081Without the input of linguists (which was not available) it was not 7082possible to determine whether there are only a few different forms in 7083which plural forms are formed or whether the number can increase with 7084every new supported language. 7085 7086 Therefore the solution implemented is to allow the translator to 7087specify the rules of how to select the plural form. Since the formula 7088varies with every language this is the only viable solution except for 7089hardcoding the information in the code (which still would require the 7090possibility of extensions to not prevent the use of new languages). 7091 7092 The information about the plural form selection has to be stored in 7093the header entry of the PO file (the one with the empty `msgid' string). 7094The plural form information looks like this: 7095 7096 Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1; 7097 7098 The `nplurals' value must be a decimal number which specifies how 7099many different plural forms exist for this language. The string 7100following `plural' is an expression which is using the C language 7101syntax. Exceptions are that no negative numbers are allowed, numbers 7102must be decimal, and the only variable allowed is `n'. Spaces are 7103allowed in the expression, but backslash-newlines are not; in the 7104examples below the backslash-newlines are present for formatting 7105purposes only. This expression will be evaluated whenever one of the 7106functions `ngettext', `dngettext', or `dcngettext' is called. The 7107numeric value passed to these functions is then substituted for all uses 7108of the variable `n' in the expression. The resulting value then must 7109be greater or equal to zero and smaller than the value given as the 7110value of `nplurals'. 7111 7112The following rules are known at this point. The language with families 7113are listed. But this does not necessarily mean the information can be 7114generalized for the whole family (as can be easily seen in the table 7115below).(1) 7116 7117Only one form: 7118 Some languages only require one single form. There is no 7119 distinction between the singular and plural form. An appropriate 7120 header entry would look like this: 7121 7122 Plural-Forms: nplurals=1; plural=0; 7123 7124 Languages with this property include: 7125 7126 Asian family 7127 Japanese, Korean, Vietnamese 7128 7129 Turkic/Altaic family 7130 Turkish 7131 7132Two forms, singular used for one only 7133 This is the form used in most existing programs since it is what 7134 English is using. A header entry would look like this: 7135 7136 Plural-Forms: nplurals=2; plural=n != 1; 7137 7138 (Note: this uses the feature of C expressions that boolean 7139 expressions have to value zero or one.) 7140 7141 Languages with this property include: 7142 7143 Germanic family 7144 Danish, Dutch, English, Faroese, German, Norwegian, Swedish 7145 7146 Finno-Ugric family 7147 Estonian, Finnish 7148 7149 Latin/Greek family 7150 Greek 7151 7152 Semitic family 7153 Hebrew 7154 7155 Romanic family 7156 Italian, Portuguese, Spanish 7157 7158 Artificial 7159 Esperanto 7160 7161 Another language using the same header entry is: 7162 7163 Finno-Ugric family 7164 Hungarian 7165 7166 Hungarian does not appear to have a plural if you look at 7167 sentences involving cardinal numbers. For example, "1 apple" is 7168 "1 alma", and "123 apples" is "123 alma". But when the number is 7169 not explicit, the distinction between singular and plural exists: 7170 "the apple" is "az alma", and "the apples" is "az alma'k". Since 7171 `ngettext' has to support both types of sentences, it is 7172 classified here, under "two forms". 7173 7174Two forms, singular used for zero and one 7175 Exceptional case in the language family. The header entry would 7176 be: 7177 7178 Plural-Forms: nplurals=2; plural=n>1; 7179 7180 Languages with this property include: 7181 7182 Romanic family 7183 French, Brazilian Portuguese 7184 7185Three forms, special case for zero 7186 The header entry would be: 7187 7188 Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2; 7189 7190 Languages with this property include: 7191 7192 Baltic family 7193 Latvian 7194 7195Three forms, special cases for one and two 7196 The header entry would be: 7197 7198 Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2; 7199 7200 Languages with this property include: 7201 7202 Celtic 7203 Gaeilge (Irish) 7204 7205Three forms, special case for numbers ending in 00 or [2-9][0-9] 7206 The header entry would be: 7207 7208 Plural-Forms: nplurals=3; \ 7209 plural=n==1 ? 0 : (n==0 || (n%100 > 0 && n%100 < 20)) ? 1 : 2; 7210 7211 Languages with this property include: 7212 7213 Romanic family 7214 Romanian 7215 7216Three forms, special case for numbers ending in 1[2-9] 7217 The header entry would look like this: 7218 7219 Plural-Forms: nplurals=3; \ 7220 plural=n%10==1 && n%100!=11 ? 0 : \ 7221 n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2; 7222 7223 Languages with this property include: 7224 7225 Baltic family 7226 Lithuanian 7227 7228Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4] 7229 The header entry would look like this: 7230 7231 Plural-Forms: nplurals=3; \ 7232 plural=n%10==1 && n%100!=11 ? 0 : \ 7233 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2; 7234 7235 Languages with this property include: 7236 7237 Slavic family 7238 Croatian, Serbian, Russian, Ukrainian 7239 7240Three forms, special cases for 1 and 2, 3, 4 7241 The header entry would look like this: 7242 7243 Plural-Forms: nplurals=3; \ 7244 plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2; 7245 7246 Languages with this property include: 7247 7248 Slavic family 7249 Slovak, Czech 7250 7251Three forms, special case for one and some numbers ending in 2, 3, or 4 7252 The header entry would look like this: 7253 7254 Plural-Forms: nplurals=3; \ 7255 plural=n==1 ? 0 : \ 7256 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2; 7257 7258 Languages with this property include: 7259 7260 Slavic family 7261 Polish 7262 7263Four forms, special case for one and all numbers ending in 02, 03, or 04 7264 The header entry would look like this: 7265 7266 Plural-Forms: nplurals=4; \ 7267 plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3; 7268 7269 Languages with this property include: 7270 7271 Slavic family 7272 Slovenian 7273 7274 You might now ask, `ngettext' handles only numbers N of type 7275`unsigned long'. What about larger integer types? What about negative 7276numbers? What about floating-point numbers? 7277 7278 About larger integer types, such as `uintmax_t' or `unsigned long 7279long': they can be handled by reducing the value to a range that fits 7280in an `unsigned long'. Simply casting the value to `unsigned long' 7281would not do the right thing, since it would treat `ULONG_MAX + 1' like 7282zero, `ULONG_MAX + 2' like singular, and the like. Here you can 7283exploit the fact that all mentioned plural form formulas eventually 7284become periodic, with a period that is a divisor of 100 (or 1000 or 72851000000). So, when you reduce a large value to another one in the 7286range [1000000, 1999999] that ends in the same 6 decimal digits, you 7287can assume that it will lead to the same plural form selection. This 7288code does this: 7289 7290 #include <inttypes.h> 7291 uintmax_t nbytes = ...; 7292 printf (ngettext ("The file has %"PRIuMAX" byte.", 7293 "The file has %"PRIuMAX" bytes.", 7294 (nbytes > ULONG_MAX 7295 ? (nbytes % 1000000) + 1000000 7296 : nbytes)), 7297 nbytes); 7298 7299 Negative and floating-point values usually represent physical 7300entities for which singular and plural don't clearly apply. In such 7301cases, there is no need to use `ngettext'; a simple `gettext' call with 7302a form suitable for all values will do. For example: 7303 7304 printf (gettext ("Time elapsed: %.3f seconds"), 7305 num_milliseconds * 0.001); 7306 7307Even if NUM_MILLISECONDS happens to be a multiple of 1000, the output 7308 Time elapsed: 1.000 seconds 7309 is acceptable in English, and similarly for other languages. 7310 7311 ---------- Footnotes ---------- 7312 7313 (1) Additions are welcome. Send appropriate information to 7314<bug-gnu-gettext@gnu.org> and <bug-glibc-manual@gnu.org>. 7315 7316 7317File: gettext.info, Node: Optimized gettext, Prev: Plural forms, Up: gettext 7318 731911.2.7 Optimization of the *gettext functions 7320--------------------------------------------- 7321 7322At this point of the discussion we should talk about an advantage of the 7323GNU `gettext' implementation. Some readers might have pointed out that 7324an internationalized program might have a poor performance if some 7325string has to be translated in an inner loop. While this is unavoidable 7326when the string varies from one run of the loop to the other it is 7327simply a waste of time when the string is always the same. Take the 7328following example: 7329 7330 { 7331 while (...) 7332 { 7333 puts (gettext ("Hello world")); 7334 } 7335 } 7336 7337When the locale selection does not change between two runs the resulting 7338string is always the same. One way to use this is: 7339 7340 { 7341 str = gettext ("Hello world"); 7342 while (...) 7343 { 7344 puts (str); 7345 } 7346 } 7347 7348But this solution is not usable in all situation (e.g. when the locale 7349selection changes) nor does it lead to legible code. 7350 7351 For this reason, GNU `gettext' caches previous translation results. 7352When the same translation is requested twice, with no new message 7353catalogs being loaded in between, `gettext' will, the second time, find 7354the result through a single cache lookup. 7355 7356 7357File: gettext.info, Node: Comparison, Next: Using libintl.a, Prev: gettext, Up: Programmers 7358 735911.3 Comparing the Two Interfaces 7360================================= 7361 7362The following discussion is perhaps a little bit colored. As said 7363above we implemented GNU `gettext' following the Uniforum proposal and 7364this surely has its reasons. But it should show how we came to this 7365decision. 7366 7367 First we take a look at the developing process. When we write an 7368application using NLS provided by `gettext' we proceed as always. Only 7369when we come to a string which might be seen by the users and thus has 7370to be translated we use `gettext("...")' instead of `"..."'. At the 7371beginning of each source file (or in a central header file) we define 7372 7373 #define gettext(String) (String) 7374 7375 Even this definition can be avoided when the system supports the 7376`gettext' function in its C library. When we compile this code the 7377result is the same as if no NLS code is used. When you take a look at 7378the GNU `gettext' code you will see that we use `_("...")' instead of 7379`gettext("...")'. This reduces the number of additional characters per 7380translatable string to _3_ (in words: three). 7381 7382 When now a production version of the program is needed we simply 7383replace the definition 7384 7385 #define _(String) (String) 7386 7387by 7388 7389 #include <libintl.h> 7390 #define _(String) gettext (String) 7391 7392Additionally we run the program `xgettext' on all source code file 7393which contain translatable strings and that's it: we have a running 7394program which does not depend on translations to be available, but which 7395can use any that becomes available. 7396 7397 The same procedure can be done for the `gettext_noop' invocations 7398(*note Special cases::). One usually defines `gettext_noop' as a no-op 7399macro. So you should consider the following code for your project: 7400 7401 #define gettext_noop(String) String 7402 #define N_(String) gettext_noop (String) 7403 7404 `N_' is a short form similar to `_'. The `Makefile' in the `po/' 7405directory of GNU `gettext' knows by default both of the mentioned short 7406forms so you are invited to follow this proposal for your own ease. 7407 7408 Now to `catgets'. The main problem is the work for the programmer. 7409Every time he comes to a translatable string he has to define a number 7410(or a symbolic constant) which has also be defined in the message 7411catalog file. He also has to take care for duplicate entries, 7412duplicate message IDs etc. If he wants to have the same quality in the 7413message catalog as the GNU `gettext' program provides he also has to 7414put the descriptive comments for the strings and the location in all 7415source code files in the message catalog. This is nearly a Mission: 7416Impossible. 7417 7418 But there are also some points people might call advantages speaking 7419for `catgets'. If you have a single word in a string and this string 7420is used in different contexts it is likely that in one or the other 7421language the word has different translations. Example: 7422 7423 printf ("%s: %d", gettext ("number"), number_of_errors) 7424 7425 printf ("you should see %d %s", number_count, 7426 number_count == 1 ? gettext ("number") : gettext ("numbers")) 7427 7428 Here we have to translate two times the string `"number"'. Even if 7429you do not speak a language beside English it might be possible to 7430recognize that the two words have a different meaning. In German the 7431first appearance has to be translated to `"Anzahl"' and the second to 7432`"Zahl"'. 7433 7434 Now you can say that this example is really esoteric. And you are 7435right! This is exactly how we felt about this problem and decide that 7436it does not weight that much. The solution for the above problem could 7437be very easy: 7438 7439 printf ("%s %d", gettext ("number:"), number_of_errors) 7440 7441 printf (number_count == 1 ? gettext ("you should see %d number") 7442 : gettext ("you should see %d numbers"), 7443 number_count) 7444 7445 We believe that we can solve all conflicts with this method. If it 7446is difficult one can also consider changing one of the conflicting 7447string a little bit. But it is not impossible to overcome. 7448 7449 `catgets' allows same original entry to have different translations, 7450but `gettext' has another, scalable approach for solving ambiguities of 7451this kind: *Note Ambiguities::. 7452 7453 7454File: gettext.info, Node: Using libintl.a, Next: gettext grok, Prev: Comparison, Up: Programmers 7455 745611.4 Using libintl.a in own programs 7457==================================== 7458 7459Starting with version 0.9.4 the library `libintl.h' should be 7460self-contained. I.e., you can use it in your own programs without 7461providing additional functions. The `Makefile' will put the header and 7462the library in directories selected using the `$(prefix)'. 7463 7464 7465File: gettext.info, Node: gettext grok, Next: Temp Programmers, Prev: Using libintl.a, Up: Programmers 7466 746711.5 Being a `gettext' grok 7468=========================== 7469 7470* NOTE: * This documentation section is outdated and needs to be 7471revised. 7472 7473 To fully exploit the functionality of the GNU `gettext' library it 7474is surely helpful to read the source code. But for those who don't want 7475to spend that much time in reading the (sometimes complicated) code here 7476is a list comments: 7477 7478 * Changing the language at runtime 7479 7480 For interactive programs it might be useful to offer a selection 7481 of the used language at runtime. To understand how to do this one 7482 need to know how the used language is determined while executing 7483 the `gettext' function. The method which is presented here only 7484 works correctly with the GNU implementation of the `gettext' 7485 functions. 7486 7487 In the function `dcgettext' at every call the current setting of 7488 the highest priority environment variable is determined and used. 7489 Highest priority means here the following list with decreasing 7490 priority: 7491 7492 1. `LANGUAGE' 7493 7494 2. `LC_ALL' 7495 7496 3. `LC_xxx', according to selected locale 7497 7498 4. `LANG' 7499 7500 Afterwards the path is constructed using the found value and the 7501 translation file is loaded if available. 7502 7503 What happens now when the value for, say, `LANGUAGE' changes? 7504 According to the process explained above the new value of this 7505 variable is found as soon as the `dcgettext' function is called. 7506 But this also means the (perhaps) different message catalog file 7507 is loaded. In other words: the used language is changed. 7508 7509 But there is one little hook. The code for gcc-2.7.0 and up 7510 provides some optimization. This optimization normally prevents 7511 the calling of the `dcgettext' function as long as no new catalog 7512 is loaded. But if `dcgettext' is not called the program also 7513 cannot find the `LANGUAGE' variable be changed (*note Optimized 7514 gettext::). A solution for this is very easy. Include the 7515 following code in the language switching function. 7516 7517 /* Change language. */ 7518 setenv ("LANGUAGE", "fr", 1); 7519 7520 /* Make change known. */ 7521 { 7522 extern int _nl_msg_cat_cntr; 7523 ++_nl_msg_cat_cntr; 7524 } 7525 7526 The variable `_nl_msg_cat_cntr' is defined in `loadmsgcat.c'. You 7527 don't need to know what this is for. But it can be used to detect 7528 whether a `gettext' implementation is GNU gettext and not non-GNU 7529 system's native gettext implementation. 7530 7531 7532 7533File: gettext.info, Node: Temp Programmers, Prev: gettext grok, Up: Programmers 7534 753511.6 Temporary Notes for the Programmers Chapter 7536================================================ 7537 7538* NOTE: * This documentation section is outdated and needs to be 7539revised. 7540 7541* Menu: 7542 7543* Temp Implementations:: Temporary - Two Possible Implementations 7544* Temp catgets:: Temporary - About `catgets' 7545* Temp WSI:: Temporary - Why a single implementation 7546* Temp Notes:: Temporary - Notes 7547 7548 7549File: gettext.info, Node: Temp Implementations, Next: Temp catgets, Prev: Temp Programmers, Up: Temp Programmers 7550 755111.6.1 Temporary - Two Possible Implementations 7552----------------------------------------------- 7553 7554There are two competing methods for language independent messages: the 7555X/Open `catgets' method, and the Uniforum `gettext' method. The 7556`catgets' method indexes messages by integers; the `gettext' method 7557indexes them by their English translations. The `catgets' method has 7558been around longer and is supported by more vendors. The `gettext' 7559method is supported by Sun, and it has been heard that the COSE 7560multi-vendor initiative is supporting it. Neither method is a POSIX 7561standard; the POSIX.1 committee had a lot of disagreement in this area. 7562 7563 Neither one is in the POSIX standard. There was much disagreement 7564in the POSIX.1 committee about using the `gettext' routines vs. 7565`catgets' (XPG). In the end the committee couldn't agree on anything, 7566so no messaging system was included as part of the standard. I believe 7567the informative annex of the standard includes the XPG3 messaging 7568interfaces, "...as an example of a messaging system that has been 7569implemented..." 7570 7571 They were very careful not to say anywhere that you should use one 7572set of interfaces over the other. For more on this topic please see 7573the Programming for Internationalization FAQ. 7574 7575 7576File: gettext.info, Node: Temp catgets, Next: Temp WSI, Prev: Temp Implementations, Up: Temp Programmers 7577 757811.6.2 Temporary - About `catgets' 7579---------------------------------- 7580 7581There have been a few discussions of late on the use of `catgets' as a 7582base. I think it important to present both sides of the argument and 7583hence am opting to play devil's advocate for a little bit. 7584 7585 I'll not deny the fact that `catgets' could have been designed a lot 7586better. It currently has quite a number of limitations and these have 7587already been pointed out. 7588 7589 However there is a great deal to be said for consistency and 7590standardization. A common recurring problem when writing Unix software 7591is the myriad portability problems across Unix platforms. It seems as 7592if every Unix vendor had a look at the operating system and found parts 7593they could improve upon. Undoubtedly, these modifications are probably 7594innovative and solve real problems. However, software developers have 7595a hard time keeping up with all these changes across so many platforms. 7596 7597 And this has prompted the Unix vendors to begin to standardize their 7598systems. Hence the impetus for Spec1170. Every major Unix vendor has 7599committed to supporting this standard and every Unix software developer 7600waits with glee the day they can write software to this standard and 7601simply recompile (without having to use autoconf) across different 7602platforms. 7603 7604 As I understand it, Spec1170 is roughly based upon version 4 of the 7605X/Open Portability Guidelines (XPG4). Because `catgets' and friends 7606are defined in XPG4, I'm led to believe that `catgets' is a part of 7607Spec1170 and hence will become a standardized component of all Unix 7608systems. 7609 7610 7611File: gettext.info, Node: Temp WSI, Next: Temp Notes, Prev: Temp catgets, Up: Temp Programmers 7612 761311.6.3 Temporary - Why a single implementation 7614---------------------------------------------- 7615 7616Now it seems kind of wasteful to me to have two different systems 7617installed for accessing message catalogs. If we do want to remedy 7618`catgets' deficiencies why don't we try to expand `catgets' (in a 7619compatible manner) rather than implement an entirely new system. 7620Otherwise, we'll end up with two message catalog access systems 7621installed with an operating system - one set of routines for packages 7622using GNU `gettext' for their internationalization, and another set of 7623routines (catgets) for all other software. Bloated? 7624 7625 Supposing another catalog access system is implemented. Which do we 7626recommend? At least for Linux, we need to attract as many software 7627developers as possible. Hence we need to make it as easy for them to 7628port their software as possible. Which means supporting `catgets'. We 7629will be implementing the `libintl' code within our `libc', but does 7630this mean we also have to incorporate another message catalog access 7631scheme within our `libc' as well? And what about people who are going 7632to be using the `libintl' + non-`catgets' routines. When they port 7633their software to other platforms, they're now going to have to include 7634the front-end (`libintl') code plus the back-end code (the non-`catgets' 7635access routines) with their software instead of just including the 7636`libintl' code with their software. 7637 7638 Message catalog support is however only the tip of the iceberg. 7639What about the data for the other locale categories. They also have a 7640number of deficiencies. Are we going to abandon them as well and 7641develop another duplicate set of routines (should `libintl' expand 7642beyond message catalog support)? 7643 7644 Like many parts of Unix that can be improved upon, we're stuck with 7645balancing compatibility with the past with useful improvements and 7646innovations for the future. 7647 7648 7649File: gettext.info, Node: Temp Notes, Prev: Temp WSI, Up: Temp Programmers 7650 765111.6.4 Temporary - Notes 7652------------------------ 7653 7654X/Open agreed very late on the standard form so that many 7655implementations differ from the final form. Both of my system (old 7656Linux catgets and Ultrix-4) have a strange variation. 7657 7658 OK. After incorporating the last changes I have to spend some time 7659on making the GNU/Linux `libc' `gettext' functions. So in future 7660Solaris is not the only system having `gettext'. 7661 7662 7663File: gettext.info, Node: Translators, Next: Maintainers, Prev: Programmers, Up: Top 7664 766512 The Translator's View 7666************************ 7667 7668* Menu: 7669 7670* Trans Intro 0:: Introduction 0 7671* Trans Intro 1:: Introduction 1 7672* Discussions:: Discussions 7673* Organization:: Organization 7674* Information Flow:: Information Flow 7675* Prioritizing messages:: How to find which messages to translate first 7676 7677 7678File: gettext.info, Node: Trans Intro 0, Next: Trans Intro 1, Prev: Translators, Up: Translators 7679 768012.1 Introduction 0 7681=================== 7682 7683* NOTE: * This documentation section is outdated and needs to be 7684revised. 7685 7686 Free software is going international! The Translation Project is a 7687way to get maintainers, translators and users all together, so free 7688software will gradually become able to speak many native languages. 7689 7690 The GNU `gettext' tool set contains _everything_ maintainers need 7691for internationalizing their packages for messages. It also contains 7692quite useful tools for helping translators at localizing messages to 7693their native language, once a package has already been 7694internationalized. 7695 7696 To achieve the Translation Project, we need many interested people 7697who like their own language and write it well, and who are also able to 7698synergize with other translators speaking the same language. If you'd 7699like to volunteer to _work_ at translating messages, please send mail 7700to your translating team. 7701 7702 Each team has its own mailing list, courtesy of Linux International. 7703You may reach your translating team at the address `LL@li.org', 7704replacing LL by the two-letter ISO 639 code for your language. 7705Language codes are _not_ the same as country codes given in ISO 3166. 7706The following translating teams exist: 7707 7708 Chinese `zh', Czech `cs', Danish `da', Dutch `nl', Esperanto `eo', 7709 Finnish `fi', French `fr', Irish `ga', German `de', Greek `el', 7710 Italian `it', Japanese `ja', Indonesian `in', Norwegian `no', 7711 Polish `pl', Portuguese `pt', Russian `ru', Spanish `es', Swedish 7712 `sv' and Turkish `tr'. 7713 7714For example, you may reach the Chinese translating team by writing to 7715`zh@li.org'. When you become a member of the translating team for your 7716own language, you may subscribe to its list. For example, Swedish 7717people can send a message to `sv-request@li.org', having this message 7718body: 7719 7720 subscribe 7721 7722 Keep in mind that team members should be interested in _working_ at 7723translations, or at solving translational difficulties, rather than 7724merely lurking around. If your team does not exist yet and you want to 7725start one, please write to `translation@iro.umontreal.ca'; you will 7726then reach the coordinator for all translator teams. 7727 7728 A handful of GNU packages have already been adapted and provided 7729with message translations for several languages. Translation teams 7730have begun to organize, using these packages as a starting point. But 7731there are many more packages and many languages for which we have no 7732volunteer translators. If you would like to volunteer to work at 7733translating messages, please send mail to 7734`translation@iro.umontreal.ca' indicating what language(s) you can work 7735on. 7736 7737 7738File: gettext.info, Node: Trans Intro 1, Next: Discussions, Prev: Trans Intro 0, Up: Translators 7739 774012.2 Introduction 1 7741=================== 7742 7743* NOTE: * This documentation section is outdated and needs to be 7744revised. 7745 7746 This is now official, GNU is going international! Here is the 7747announcement submitted for the January 1995 GNU Bulletin: 7748 7749 A handful of GNU packages have already been adapted and provided 7750 with message translations for several languages. Translation 7751 teams have begun to organize, using these packages as a starting 7752 point. But there are many more packages and many languages for 7753 which we have no volunteer translators. If you'd like to 7754 volunteer to work at translating messages, please send mail to 7755 `translation@iro.umontreal.ca' indicating what language(s) you can 7756 work on. 7757 7758 This document should answer many questions for those who are curious 7759about the process or would like to contribute. Please at least skim 7760over it, hoping to cut down a little of the high volume of e-mail 7761generated by this collective effort towards internationalization of 7762free software. 7763 7764 Most free programming which is widely shared is done in English, and 7765currently, English is used as the main communicating language between 7766national communities collaborating to free software. This very document 7767is written in English. This will not change in the foreseeable future. 7768 7769 However, there is a strong appetite from national communities for 7770having more software able to write using national language and habits, 7771and there is an on-going effort to modify free software in such a way 7772that it becomes able to do so. The experiments driven so far raised an 7773enthusiastic response from pretesters, so we believe that 7774internationalization of free software is dedicated to succeed. 7775 7776 For suggestion clarifications, additions or corrections to this 7777document, please e-mail to `translation@iro.umontreal.ca'. 7778 7779 7780File: gettext.info, Node: Discussions, Next: Organization, Prev: Trans Intro 1, Up: Translators 7781 778212.3 Discussions 7783================ 7784 7785* NOTE: * This documentation section is outdated and needs to be 7786revised. 7787 7788 Facing this internationalization effort, a few users expressed their 7789concerns. Some of these doubts are presented and discussed, here. 7790 7791 * Smaller groups 7792 7793 Some languages are not spoken by a very large number of people, so 7794 people speaking them sometimes consider that there may not be all 7795 that much demand such versions of free software packages. 7796 Moreover, many people being _into computers_, in some countries, 7797 generally seem to prefer English versions of their software. 7798 7799 On the other end, people might enjoy their own language a lot, and 7800 be very motivated at providing to themselves the pleasure of 7801 having their beloved free software speaking their mother tongue. 7802 They do themselves a personal favor, and do not pay that much 7803 attention to the number of people benefiting of their work. 7804 7805 * Misinterpretation 7806 7807 Other users are shy to push forward their own language, seeing in 7808 this some kind of misplaced propaganda. Someone thought there 7809 must be some users of the language over the networks pestering 7810 other people with it. 7811 7812 But any spoken language is worth localization, because there are 7813 people behind the language for whom the language is important and 7814 dear to their hearts. 7815 7816 * Odd translations 7817 7818 The biggest problem is to find the right translations so that 7819 everybody can understand the messages. Translations are usually a 7820 little odd. Some people get used to English, to the extent they 7821 may find translations into their own language "rather pushy, 7822 obnoxious and sometimes even hilarious." As a French speaking 7823 man, I have the experience of those instruction manuals for goods, 7824 so poorly translated in French in Korea or Taiwan... 7825 7826 The fact is that we sometimes have to create a kind of national 7827 computer culture, and this is not easy without the collaboration of 7828 many people liking their mother tongue. This is why translations 7829 are better achieved by people knowing and loving their own 7830 language, and ready to work together at improving the results they 7831 obtain. 7832 7833 * Dependencies over the GPL or LGPL 7834 7835 Some people wonder if using GNU `gettext' necessarily brings their 7836 package under the protective wing of the GNU General Public 7837 License or the GNU Library General Public License, when they do 7838 not want to make their program free, or want other kinds of 7839 freedom. The simplest answer is "normally not". 7840 7841 The `gettext-runtime' part of GNU `gettext', i.e. the contents of 7842 `libintl', is covered by the GNU Library General Public License. 7843 The `gettext-tools' part of GNU `gettext', i.e. the rest of the 7844 GNU `gettext' package, is covered by the GNU General Public 7845 License. 7846 7847 The mere marking of localizable strings in a package, or 7848 conditional inclusion of a few lines for initialization, is not 7849 really including GPL'ed or LGPL'ed code. However, since the 7850 localization routines in `libintl' are under the LGPL, the LGPL 7851 needs to be considered. It gives the right to distribute the 7852 complete unmodified source of `libintl' even with non-free 7853 programs. It also gives the right to use `libintl' as a shared 7854 library, even for non-free programs. But it gives the right to 7855 use `libintl' as a static library or to incorporate `libintl' into 7856 another library only to free software. 7857 7858 7859 7860File: gettext.info, Node: Organization, Next: Information Flow, Prev: Discussions, Up: Translators 7861 786212.4 Organization 7863================= 7864 7865* NOTE: * This documentation section is outdated and needs to be 7866revised. 7867 7868 On a larger scale, the true solution would be to organize some kind 7869of fairly precise set up in which volunteers could participate. I gave 7870some thought to this idea lately, and realize there will be some touchy 7871points. I thought of writing to Richard Stallman to launch such a 7872project, but feel it might be good to shake out the ideas between 7873ourselves first. Most probably that Linux International has some 7874experience in the field already, or would like to orchestrate the 7875volunteer work, maybe. Food for thought, in any case! 7876 7877 I guess we have to setup something early, somehow, that will help 7878many possible contributors of the same language to interlock and avoid 7879work duplication, and further be put in contact for solving together 7880problems particular to their tongue (in most languages, there are many 7881difficulties peculiar to translating technical English). My Swedish 7882contributor acknowledged these difficulties, and I'm well aware of them 7883for French. 7884 7885 This is surely not a technical issue, but we should manage so the 7886effort of locale contributors be maximally useful, despite the national 7887team layer interface between contributors and maintainers. 7888 7889 The Translation Project needs some setup for coordinating language 7890coordinators. Localizing evolving programs will surely become a 7891permanent and continuous activity in the free software community, once 7892well started. The setup should be minimally completed and tested 7893before GNU `gettext' becomes an official reality. The e-mail address 7894`translation@iro.umontreal.ca' has been setup for receiving offers from 7895volunteers and general e-mail on these topics. This address reaches 7896the Translation Project coordinator. 7897 7898* Menu: 7899 7900* Central Coordination:: Central Coordination 7901* National Teams:: National Teams 7902* Mailing Lists:: Mailing Lists 7903 7904 7905File: gettext.info, Node: Central Coordination, Next: National Teams, Prev: Organization, Up: Organization 7906 790712.4.1 Central Coordination 7908--------------------------- 7909 7910I also think GNU will need sooner than it thinks, that someone setup a 7911way to organize and coordinate these groups. Some kind of group of 7912groups. My opinion is that it would be good that GNU delegates this 7913task to a small group of collaborating volunteers, shortly. Perhaps in 7914`gnu.announce' a list of this national committee's can be published. 7915 7916 My role as coordinator would simply be to refer to Ulrich any German 7917speaking volunteer interested to localization of free software 7918packages, and maybe helping national groups to initially organize, 7919while maintaining national registries for until national groups are 7920ready to take over. In fact, the coordinator should ease volunteers to 7921get in contact with one another for creating national teams, which 7922should then select one coordinator per language, or country 7923(regionalized language). If well done, the coordination should be 7924useful without being an overwhelming task, the time to put delegations 7925in place. 7926 7927 7928File: gettext.info, Node: National Teams, Next: Mailing Lists, Prev: Central Coordination, Up: Organization 7929 793012.4.2 National Teams 7931--------------------- 7932 7933I suggest we look for volunteer coordinators/editors for individual 7934languages. These people will scan contributions of translation files 7935for various programs, for their own languages, and will ensure high and 7936uniform standards of diction. 7937 7938 From my current experience with other people in these days, those who 7939provide localizations are very enthusiastic about the process, and are 7940more interested in the localization process than in the program they 7941localize, and want to do many programs, not just one. This seems to 7942confirm that having a coordinator/editor for each language is a good 7943idea. 7944 7945 We need to choose someone who is good at writing clear and concise 7946prose in the language in question. That is hard--we can't check it 7947ourselves. So we need to ask a few people to judge each others' 7948writing and select the one who is best. 7949 7950 I announce my prerelease to a few dozen people, and you would not 7951believe all the discussions it generated already. I shudder to think 7952what will happen when this will be launched, for true, officially, 7953world wide. Who am I to arbitrate between two Czekolsovak users 7954contradicting each other, for example? 7955 7956 I assume that your German is not much better than my French so that 7957I would not be able to judge about these formulations. What I would 7958suggest is that for each language there is a group for people who 7959maintain the PO files and judge about changes. I suspect there will be 7960cultural differences between how such groups of people will behave. 7961Some will have relaxed ways, reach consensus easily, and have anyone of 7962the group relate to the maintainers, while others will fight to death, 7963organize heavy administrations up to national standards, and use strict 7964channels. 7965 7966 The German team is putting out a good example. Right now, they are 7967maybe half a dozen people revising translations of each other and 7968discussing the linguistic issues. I do not even have all the names. 7969Ulrich Drepper is taking care of coordinating the German team. He 7970subscribed to all my pretest lists, so I do not even have to warn him 7971specifically of incoming releases. 7972 7973 I'm sure, that is a good idea to get teams for each language working 7974on translations. That will make the translations better and more 7975consistent. 7976 7977* Menu: 7978 7979* Sub-Cultures:: Sub-Cultures 7980* Organizational Ideas:: Organizational Ideas 7981 7982 7983File: gettext.info, Node: Sub-Cultures, Next: Organizational Ideas, Prev: National Teams, Up: National Teams 7984 798512.4.2.1 Sub-Cultures 7986..................... 7987 7988Taking French for example, there are a few sub-cultures around computers 7989which developed diverging vocabularies. Picking volunteers here and 7990there without addressing this problem in an organized way, soon in the 7991project, might produce a distasteful mix of internationalized programs, 7992and possibly trigger endless quarrels among those who really care. 7993 7994 Keeping some kind of unity in the way French localization of 7995internationalized programs is achieved is a difficult (and delicate) 7996job. Knowing the latin character of French people (:-), if we take this 7997the wrong way, we could end up nowhere, or spoil a lot of energies. 7998Maybe we should begin to address this problem seriously _before_ GNU 7999`gettext' become officially published. And I suspect that this means 8000soon! 8001 8002 8003File: gettext.info, Node: Organizational Ideas, Prev: Sub-Cultures, Up: National Teams 8004 800512.4.2.2 Organizational Ideas 8006............................. 8007 8008I expect the next big changes after the official release. Please note 8009that I use the German translation of the short GPL message. We need to 8010set a few good examples before the localization goes out for true in 8011the free software community. Here are a few points to discuss: 8012 8013 * Each group should have one FTP server (at least one master). 8014 8015 * The files on the server should reflect the latest version (of 8016 course!) and it should also contain a RCS directory with the 8017 corresponding archives (I don't have this now). 8018 8019 * There should also be a ChangeLog file (this is more useful than the 8020 RCS archive but can be generated automatically from the later by 8021 Emacs). 8022 8023 * A "core group" should judge about questionable changes (for now 8024 this group consists solely by me but I ask some others 8025 occasionally; this also seems to work). 8026 8027 8028 8029File: gettext.info, Node: Mailing Lists, Prev: National Teams, Up: Organization 8030 803112.4.3 Mailing Lists 8032-------------------- 8033 8034If we get any inquiries about GNU `gettext', send them on to: 8035 8036 `translation@iro.umontreal.ca' 8037 8038 The `*-pretest' lists are quite useful to me, maybe the idea could 8039be generalized to many GNU, and non-GNU packages. But each maintainer 8040his/her way! 8041 8042 Franc,ois, we have a mechanism in place here at `gnu.ai.mit.edu' to 8043track teams, support mailing lists for them and log members. We have a 8044slight preference that you use it. If this is OK with you, I can get 8045you clued in. 8046 8047 Things are changing! A few years ago, when Daniel Fekete and I 8048asked for a mailing list for GNU localization, nested at the FSF, we 8049were politely invited to organize it anywhere else, and so did we. For 8050communicating with my pretesters, I later made a handful of mailing 8051lists located at iro.umontreal.ca and administrated by `majordomo'. 8052These lists have been _very_ dependable so far... 8053 8054 I suspect that the German team will organize itself a mailing list 8055located in Germany, and so forth for other countries. But before they 8056organize for true, it could surely be useful to offer mailing lists 8057located at the FSF to each national team. So yes, please explain me 8058how I should proceed to create and handle them. 8059 8060 We should create temporary mailing lists, one per country, to help 8061people organize. Temporary, because once regrouped and structured, it 8062would be fair the volunteers from country bring back _their_ list in 8063there and manage it as they want. My feeling is that, in the long run, 8064each team should run its own list, from within their country. There 8065also should be some central list to which all teams could subscribe as 8066they see fit, as long as each team is represented in it. 8067 8068 8069File: gettext.info, Node: Information Flow, Next: Prioritizing messages, Prev: Organization, Up: Translators 8070 807112.5 Information Flow 8072===================== 8073 8074* NOTE: * This documentation section is outdated and needs to be 8075revised. 8076 8077 There will surely be some discussion about this messages after the 8078packages are finally released. If people now send you some proposals 8079for better messages, how do you proceed? Jim, please note that right 8080now, as I put forward nearly a dozen of localizable programs, I receive 8081both the translations and the coordination concerns about them. 8082 8083 If I put one of my things to pretest, Ulrich receives the 8084announcement and passes it on to the German team, who make last minute 8085revisions. Then he submits the translation files to me _as the 8086maintainer_. For free packages I do not maintain, I would not even 8087hear about it. This scheme could be made to work for the whole 8088Translation Project, I think. For security reasons, maybe Ulrich 8089(national coordinators, in fact) should update central registry kept at 8090the Translation Project (Jim, me, or Len's recruits) once in a while. 8091 8092 In December/January, I was aggressively ready to internationalize 8093all of GNU, giving myself the duty of one small GNU package per week or 8094so, taking many weeks or months for bigger packages. But it does not 8095work this way. I first did all the things I'm responsible for. I've 8096nothing against some missionary work on other maintainers, but I'm also 8097loosing a lot of energy over it--same debates over again. 8098 8099 And when the first localized packages are released we'll get a lot of 8100responses about ugly translations :-). Surely, and we need to have 8101beforehand a fairly good idea about how to handle the information flow 8102between the national teams and the package maintainers. 8103 8104 Please start saving somewhere a quick history of each PO file. I 8105know for sure that the file format will change, allowing for comments. 8106It would be nice that each file has a kind of log, and references for 8107those who want to submit comments or gripes, or otherwise contribute. 8108I sent a proposal for a fast and flexible format, but it is not 8109receiving acceptance yet by the GNU deciders. I'll tell you when I 8110have more information about this. 8111 8112 8113File: gettext.info, Node: Prioritizing messages, Prev: Information Flow, Up: Translators 8114 811512.6 Prioritizing messages: How to determine which messages to translate first 8116============================================================================== 8117 8118A translator sometimes has only a limited amount of time per week to 8119spend on a package, and some packages have quite large message catalogs 8120(over 1000 messages). Therefore she wishes to translate the messages 8121first that are the most visible to the user, or that occur most 8122frequently. This section describes how to determine these "most 8123urgent" messages. It also applies to determine the "next most urgent" 8124messages after the message catalog has already been partially 8125translated. 8126 8127 In a first step, she uses the programs like a user would do. While 8128she does this, the GNU `gettext' library logs into a file the not yet 8129translated messages for which a translation was requested from the 8130program. 8131 8132 In a second step, she uses the PO mode to translate precisely this 8133set of messages. 8134 8135 Here a more details. The GNU `libintl' library (but not the 8136corresponding functions in GNU `libc') supports an environment variable 8137`GETTEXT_LOG_UNTRANSLATED'. The GNU `libintl' library will log into 8138this file the messages for which `gettext()' and related functions 8139couldn't find the translation. If the file doesn't exist, it will be 8140created as needed. On systems with GNU `libc' a shared library 8141`preloadable_libintl.so' is provided that can be used with the ELF 8142`LD_PRELOAD' mechanism. 8143 8144 So, in the first step, the translator uses these commands on systems 8145with GNU `libc': 8146 8147 $ LD_PRELOAD=/usr/local/lib/preloadable_libintl.so 8148 $ export LD_PRELOAD 8149 $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused 8150 $ export GETTEXT_LOG_UNTRANSLATED 8151 8152and these commands on other systems: 8153 8154 $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused 8155 $ export GETTEXT_LOG_UNTRANSLATED 8156 8157 Then she uses and peruses the programs. (It is a good and 8158recommended practice to use the programs for which you provide 8159translations: it gives you the needed context.) When done, she removes 8160the environment variables: 8161 8162 $ unset LD_PRELOAD 8163 $ unset GETTEXT_LOG_UNTRANSLATED 8164 8165 The second step starts with removing duplicates: 8166 8167 $ msguniq $HOME/gettextlogused > missing.po 8168 8169 The result is a PO file, but needs some preprocessing before a PO 8170file editor can be used with it. First, it is a multi-domain PO file, 8171containing messages from many translation domains. Second, it lacks 8172all translator comments and source references. Here is how to get a 8173list of the affected translation domains: 8174 8175 $ sed -n -e 's,^domain "\(.*\)"$,\1,p' < missing.po | sort | uniq 8176 8177 Then the translator can handle the domains one by one. For 8178simplicity, let's use environment variables to denote the language, 8179domain and source package. 8180 8181 $ lang=nl # your language 8182 $ domain=coreutils # the name of the domain to be handled 8183 $ package=/usr/src/gnu/coreutils-4.5.4 # the package where it comes from 8184 8185 She takes the latest copy of `$lang.po' from the Translation Project, 8186or from the package (in most cases, `$package/po/$lang.po'), or creates 8187a fresh one if she's the first translator (see *Note Creating::). She 8188then uses the following commands to mark the not urgent messages as 8189"obsolete". (This doesn't mean that these messages - translated and 8190untranslated ones - will go away. It simply means that the PO file 8191editor will ignore them in the following editing session.) 8192 8193 $ msggrep --domain=$domain missing.po | grep -v '^domain' \ 8194 > $domain-missing.po 8195 $ msgattrib --set-obsolete --ignore-file $domain-missing.po $domain.$lang.po \ 8196 > $domain.$lang-urgent.po 8197 8198 The she translates `$domain.$lang-urgent.po' by use of a PO file 8199editor (*note Editing::). (FIXME: I don't know whether `KBabel' and 8200`gtranslator' also preserve obsolete messages, as they should.) 8201Finally she restores the not urgent messages (with their earlier 8202translations, for those which were already translated) through this 8203command: 8204 8205 $ msgmerge --no-fuzzy-matching $domain.$lang-urgent.po $package/po/$domain.pot \ 8206 > $domain.$lang.po 8207 8208 Then she can submit `$domain.$lang.po' and proceed to the next 8209domain. 8210 8211 8212File: gettext.info, Node: Maintainers, Next: Installers, Prev: Translators, Up: Top 8213 821413 The Maintainer's View 8215************************ 8216 8217The maintainer of a package has many responsibilities. One of them is 8218ensuring that the package will install easily on many platforms, and 8219that the magic we described earlier (*note Users::) will work for 8220installers and end users. 8221 8222 Of course, there are many possible ways by which GNU `gettext' might 8223be integrated in a distribution, and this chapter does not cover them 8224in all generality. Instead, it details one possible approach which is 8225especially adequate for many free software distributions following GNU 8226standards, or even better, Gnits standards, because GNU `gettext' is 8227purposely for helping the internationalization of the whole GNU 8228project, and as many other good free packages as possible. So, the 8229maintainer's view presented here presumes that the package already has 8230a `configure.in' file and uses GNU Autoconf. 8231 8232 Nevertheless, GNU `gettext' may surely be useful for free packages 8233not following GNU standards and conventions, but the maintainers of such 8234packages might have to show imagination and initiative in organizing 8235their distributions so `gettext' work for them in all situations. 8236There are surely many, out there. 8237 8238 Even if `gettext' methods are now stabilizing, slight adjustments 8239might be needed between successive `gettext' versions, so you should 8240ideally revise this chapter in subsequent releases, looking for changes. 8241 8242* Menu: 8243 8244* Flat and Non-Flat:: Flat or Non-Flat Directory Structures 8245* Prerequisites:: Prerequisite Works 8246* gettextize Invocation:: Invoking the `gettextize' Program 8247* Adjusting Files:: Files You Must Create or Alter 8248* autoconf macros:: Autoconf macros for use in `configure.in' 8249* CVS Issues:: Integrating with CVS 8250* Release Management:: Creating a Distribution Tarball 8251 8252 8253File: gettext.info, Node: Flat and Non-Flat, Next: Prerequisites, Prev: Maintainers, Up: Maintainers 8254 825513.1 Flat or Non-Flat Directory Structures 8256========================================== 8257 8258Some free software packages are distributed as `tar' files which unpack 8259in a single directory, these are said to be "flat" distributions. 8260Other free software packages have a one level hierarchy of 8261subdirectories, using for example a subdirectory named `doc/' for the 8262Texinfo manual and man pages, another called `lib/' for holding 8263functions meant to replace or complement C libraries, and a 8264subdirectory `src/' for holding the proper sources for the package. 8265These other distributions are said to be "non-flat". 8266 8267 We cannot say much about flat distributions. A flat directory 8268structure has the disadvantage of increasing the difficulty of updating 8269to a new version of GNU `gettext'. Also, if you have many PO files, 8270this could somewhat pollute your single directory. Also, GNU 8271`gettext''s libintl sources consist of C sources, shell scripts, `sed' 8272scripts and complicated Makefile rules, which don't fit well into an 8273existing flat structure. For these reasons, we recommend to use 8274non-flat approach in this case as well. 8275 8276 Maybe because GNU `gettext' itself has a non-flat structure, we have 8277more experience with this approach, and this is what will be described 8278in the remaining of this chapter. Some maintainers might use this as 8279an opportunity to unflatten their package structure. 8280 8281 8282File: gettext.info, Node: Prerequisites, Next: gettextize Invocation, Prev: Flat and Non-Flat, Up: Maintainers 8283 828413.2 Prerequisite Works 8285======================= 8286 8287There are some works which are required for using GNU `gettext' in one 8288of your package. These works have some kind of generality that escape 8289the point by point descriptions used in the remainder of this chapter. 8290So, we describe them here. 8291 8292 * Before attempting to use `gettextize' you should install some 8293 other packages first. Ensure that recent versions of GNU `m4', 8294 GNU Autoconf and GNU `gettext' are already installed at your site, 8295 and if not, proceed to do this first. If you get to install these 8296 things, beware that GNU `m4' must be fully installed before GNU 8297 Autoconf is even _configured_. 8298 8299 To further ease the task of a package maintainer the `automake' 8300 package was designed and implemented. GNU `gettext' now uses this 8301 tool and the `Makefile's in the `intl/' and `po/' therefore know 8302 about all the goals necessary for using `automake' and `libintl' 8303 in one project. 8304 8305 Those four packages are only needed by you, as a maintainer; the 8306 installers of your own package and end users do not really need 8307 any of GNU `m4', GNU Autoconf, GNU `gettext', or GNU `automake' 8308 for successfully installing and running your package, with messages 8309 properly translated. But this is not completely true if you 8310 provide internationalized shell scripts within your own package: 8311 GNU `gettext' shall then be installed at the user site if the end 8312 users want to see the translation of shell script messages. 8313 8314 * Your package should use Autoconf and have a `configure.in' or 8315 `configure.ac' file. If it does not, you have to learn how. The 8316 Autoconf documentation is quite well written, it is a good idea 8317 that you print it and get familiar with it. 8318 8319 * Your C sources should have already been modified according to 8320 instructions given earlier in this manual. *Note Sources::. 8321 8322 * Your `po/' directory should receive all PO files submitted to you 8323 by the translator teams, each having `LL.po' as a name. This is 8324 not usually easy to get translation work done before your package 8325 gets internationalized and available! Since the cycle has to 8326 start somewhere, the easiest for the maintainer is to start with 8327 absolutely no PO files, and wait until various translator teams 8328 get interested in your package, and submit PO files. 8329 8330 8331 It is worth adding here a few words about how the maintainer should 8332ideally behave with PO files submissions. As a maintainer, your role is 8333to authenticate the origin of the submission as being the representative 8334of the appropriate translating teams of the Translation Project (forward 8335the submission to `translation@iro.umontreal.ca' in case of doubt), to 8336ensure that the PO file format is not severely broken and does not 8337prevent successful installation, and for the rest, to merely put these 8338PO files in `po/' for distribution. 8339 8340 As a maintainer, you do not have to take on your shoulders the 8341responsibility of checking if the translations are adequate or 8342complete, and should avoid diving into linguistic matters. Translation 8343teams drive themselves and are fully responsible of their linguistic 8344choices for the Translation Project. Keep in mind that translator 8345teams are _not_ driven by maintainers. You can help by carefully 8346redirecting all communications and reports from users about linguistic 8347matters to the appropriate translation team, or explain users how to 8348reach or join their team. The simplest might be to send them the 8349`ABOUT-NLS' file. 8350 8351 Maintainers should _never ever_ apply PO file bug reports 8352themselves, short-cutting translation teams. If some translator has 8353difficulty to get some of her points through her team, it should not be 8354an option for her to directly negotiate translations with maintainers. 8355Teams ought to settle their problems themselves, if any. If you, as a 8356maintainer, ever think there is a real problem with a team, please 8357never try to _solve_ a team's problem on your own. 8358 8359 8360File: gettext.info, Node: gettextize Invocation, Next: Adjusting Files, Prev: Prerequisites, Up: Maintainers 8361 836213.3 Invoking the `gettextize' Program 8363====================================== 8364 8365The `gettextize' program is an interactive tool that helps the 8366maintainer of a package internationalized through GNU `gettext'. It is 8367used for two purposes: 8368 8369 * As a wizard, when a package is modified to use GNU `gettext' for 8370 the first time. 8371 8372 * As a migration tool, for upgrading the GNU `gettext' support in a 8373 package from a previous to a newer version of GNU `gettext'. 8374 8375 This program performs the following tasks: 8376 8377 * It copies into the package some files that are consistently and 8378 identically needed in every package internationalized through GNU 8379 `gettext'. 8380 8381 * It performs as many of the tasks mentioned in the next section 8382 *Note Adjusting Files:: as can be performed automatically. 8383 8384 * It removes obsolete files and idioms used for previous GNU 8385 `gettext' versions to the form recommended for the current GNU 8386 `gettext' version. 8387 8388 * It prints a summary of the tasks that ought to be done manually 8389 and could not be done automatically by `gettextize'. 8390 8391 It can be invoked as follows: 8392 8393 gettextize [ OPTION... ] [ DIRECTORY ] 8394 8395and accepts the following options: 8396 8397`-f' 8398`--force' 8399 Force replacement of files which already exist. 8400 8401`--intl' 8402 Install the libintl sources in a subdirectory named `intl/'. This 8403 libintl will be used to provide internationalization on systems 8404 that don't have GNU libintl installed. If this option is omitted, 8405 the call to `AM_GNU_GETTEXT' in `configure.in' should read: 8406 `AM_GNU_GETTEXT([external])', and internationalization will not be 8407 enabled on systems lacking GNU gettext. 8408 8409`--no-changelog' 8410 Don't update or create ChangeLog files. By default, `gettextize' 8411 logs all changes (file additions, modifications and removals) in a 8412 file called `ChangeLog' in each affected directory. 8413 8414`--symlink' 8415 Make symbolic links instead of copying the needed files. This can 8416 be useful to save a few kilobytes of disk space, but it requires 8417 extra effort to create self-contained tarballs, it may disturb 8418 some mechanism the maintainer applies to the sources, and it is 8419 likely to introduce bugs when a newer version of `gettext' is 8420 installed on the system. 8421 8422`-n' 8423`--dry-run' 8424 Print modifications but don't perform them. All actions that 8425 `gettextize' would normally execute are inhibited and instead only 8426 listed on standard output. 8427 8428`--help' 8429 Display this help and exit. 8430 8431`--version' 8432 Output version information and exit. 8433 8434 8435 If DIRECTORY is given, this is the top level directory of a package 8436to prepare for using GNU `gettext'. If not given, it is assumed that 8437the current directory is the top level directory of such a package. 8438 8439 The program `gettextize' provides the following files. However, no 8440existing file will be replaced unless the option `--force' (`-f') is 8441specified. 8442 8443 1. The `ABOUT-NLS' file is copied in the main directory of your 8444 package, the one being at the top level. This file gives the main 8445 indications about how to install and use the Native Language 8446 Support features of your program. You might elect to use a more 8447 recent copy of this `ABOUT-NLS' file than the one provided through 8448 `gettextize', if you have one handy. You may also fetch a more 8449 recent copy of file `ABOUT-NLS' from Translation Project sites, 8450 and from most GNU archive sites. 8451 8452 2. A `po/' directory is created for eventually holding all 8453 translation files, but initially only containing the file 8454 `po/Makefile.in.in' from the GNU `gettext' distribution (beware 8455 the double `.in' in the file name) and a few auxiliary files. If 8456 the `po/' directory already exists, it will be preserved along 8457 with the files it contains, and only `Makefile.in.in' and the 8458 auxiliary files will be overwritten. 8459 8460 3. Only if `--intl' has been specified: A `intl/' directory is 8461 created and filled with most of the files originally in the 8462 `intl/' directory of the GNU `gettext' distribution. Also, if 8463 option `--force' (`-f') is given, the `intl/' directory is emptied 8464 first. 8465 8466 4. The file `config.rpath' is copied into the directory containing 8467 configuration support files. It is needed by the `AM_GNU_GETTEXT' 8468 autoconf macro. 8469 8470 5. Only if the project is using GNU `automake': A set of `autoconf' 8471 macro files is copied into the package's `autoconf' macro 8472 repository, usually in a directory called `m4/'. 8473 8474 If your site support symbolic links, `gettextize' will not actually 8475copy the files into your package, but establish symbolic links instead. 8476This avoids duplicating the disk space needed in all packages. Merely 8477using the `-h' option while creating the `tar' archive of your 8478distribution will resolve each link by an actual copy in the 8479distribution archive. So, to insist, you really should use `-h' option 8480with `tar' within your `dist' goal of your main `Makefile.in'. 8481 8482 Furthermore, `gettextize' will update all `Makefile.am' files in 8483each affected directory, as well as the top level `configure.in' or 8484`configure.ac' file. 8485 8486 It is interesting to understand that most new files for supporting 8487GNU `gettext' facilities in one package go in `intl/', `po/' and `m4/' 8488subdirectories. One distinction between `intl/' and the two other 8489directories is that `intl/' is meant to be completely identical in all 8490packages using GNU `gettext', while the other directories will mostly 8491contain package dependent files. 8492 8493 The `gettextize' program makes backup files for all files it 8494replaces or changes, and also write ChangeLog entries about these 8495changes. This way, the careful maintainer can check after running 8496`gettextize' whether its changes are acceptable to him, and possibly 8497adjust them. An exception to this rule is the `intl/' directory, which 8498is added or replaced or removed as a whole. 8499 8500 It is important to understand that `gettextize' can not do the 8501entire job of adapting a package for using GNU `gettext'. The amount 8502of remaining work depends on whether the package uses GNU `automake' or 8503not. But in any case, the maintainer should still read the section 8504*Note Adjusting Files:: after invoking `gettextize'. 8505 8506 In particular, if after using `gettexize', you get an error 8507`AC_COMPILE_IFELSE was called before AC_GNU_SOURCE' or `AC_RUN_IFELSE 8508was called before AC_GNU_SOURCE', you can fix it by modifying 8509`configure.ac', as described in *Note configure.in::. 8510 8511 It is also important to understand that `gettextize' is not part of 8512the GNU build system, in the sense that it should not be invoked 8513automatically, and not be invoked by someone who doesn't assume the 8514responsibilities of a package maintainer. For the latter purpose, a 8515separate tool is provided, see *Note autopoint Invocation::. 8516 8517 8518File: gettext.info, Node: Adjusting Files, Next: autoconf macros, Prev: gettextize Invocation, Up: Maintainers 8519 852013.4 Files You Must Create or Alter 8521=================================== 8522 8523Besides files which are automatically added through `gettextize', there 8524are many files needing revision for properly interacting with GNU 8525`gettext'. If you are closely following GNU standards for Makefile 8526engineering and auto-configuration, the adaptations should be easier to 8527achieve. Here is a point by point description of the changes needed in 8528each. 8529 8530 So, here comes a list of files, each one followed by a description of 8531all alterations it needs. Many examples are taken out from the GNU 8532`gettext' 0.16.1 distribution itself, or from the GNU `hello' 8533distribution (`http://www.franken.de/users/gnu/ke/hello' or 8534`http://www.gnu.franken.de/ke/hello/') You may indeed refer to the 8535source code of the GNU `gettext' and GNU `hello' packages, as they are 8536intended to be good examples for using GNU gettext functionality. 8537 8538* Menu: 8539 8540* po/POTFILES.in:: `POTFILES.in' in `po/' 8541* po/LINGUAS:: `LINGUAS' in `po/' 8542* po/Makevars:: `Makevars' in `po/' 8543* po/Rules-*:: Extending `Makefile' in `po/' 8544* configure.in:: `configure.in' at top level 8545* config.guess:: `config.guess', `config.sub' at top level 8546* mkinstalldirs:: `mkinstalldirs' at top level 8547* aclocal:: `aclocal.m4' at top level 8548* acconfig:: `acconfig.h' at top level 8549* config.h.in:: `config.h.in' at top level 8550* Makefile:: `Makefile.in' at top level 8551* src/Makefile:: `Makefile.in' in `src/' 8552* lib/gettext.h:: `gettext.h' in `lib/' 8553 8554 8555File: gettext.info, Node: po/POTFILES.in, Next: po/LINGUAS, Prev: Adjusting Files, Up: Adjusting Files 8556 855713.4.1 `POTFILES.in' in `po/' 8558----------------------------- 8559 8560The `po/' directory should receive a file named `POTFILES.in'. This 8561file tells which files, among all program sources, have marked strings 8562needing translation. Here is an example of such a file: 8563 8564 # List of source files containing translatable strings. 8565 # Copyright (C) 1995 Free Software Foundation, Inc. 8566 8567 # Common library files 8568 lib/error.c 8569 lib/getopt.c 8570 lib/xmalloc.c 8571 8572 # Package source files 8573 src/gettext.c 8574 src/msgfmt.c 8575 src/xgettext.c 8576 8577Hash-marked comments and white lines are ignored. All other lines list 8578those source files containing strings marked for translation (*note 8579Mark Keywords::), in a notation relative to the top level of your whole 8580distribution, rather than the location of the `POTFILES.in' file itself. 8581 8582 When a C file is automatically generated by a tool, like `flex' or 8583`bison', that doesn't introduce translatable strings by itself, it is 8584recommended to list in `po/POTFILES.in' the real source file (ending in 8585`.l' in the case of `flex', or in `.y' in the case of `bison'), not the 8586generated C file. 8587 8588 8589File: gettext.info, Node: po/LINGUAS, Next: po/Makevars, Prev: po/POTFILES.in, Up: Adjusting Files 8590 859113.4.2 `LINGUAS' in `po/' 8592------------------------- 8593 8594The `po/' directory should also receive a file named `LINGUAS'. This 8595file contains the list of available translations. It is a whitespace 8596separated list. Hash-marked comments and white lines are ignored. 8597Here is an example file: 8598 8599 # Set of available languages. 8600 de fr 8601 8602This example means that German and French PO files are available, so 8603that these languages are currently supported by your package. If you 8604want to further restrict, at installation time, the set of installed 8605languages, this should not be done by modifying the `LINGUAS' file, but 8606rather by using the `LINGUAS' environment variable (*note Installers::). 8607 8608 It is recommended that you add the "languages" `en@quot' and 8609`en@boldquot' to the `LINGUAS' file. `en@quot' is a variant of English 8610message catalogs (`en') which uses real quotation marks instead of the 8611ugly looking asymmetric ASCII substitutes ``' and `''. `en@boldquot' 8612is a variant of `en@quot' that additionally outputs quoted pieces of 8613text in a bold font, when used in a terminal emulator which supports 8614the VT100 escape sequences (such as `xterm' or the Linux console, but 8615not Emacs in `M-x shell' mode). 8616 8617 These extra message catalogs `en@quot' and `en@boldquot' are 8618constructed automatically, not by translators; to support them, you 8619need the files `Rules-quot', `quot.sed', `boldquot.sed', 8620`en@quot.header', `en@boldquot.header', `insert-header.sin' in the 8621`po/' directory. You can copy them from GNU gettext's `po/' directory; 8622they are also installed by running `gettextize'. 8623 8624 8625File: gettext.info, Node: po/Makevars, Next: po/Rules-*, Prev: po/LINGUAS, Up: Adjusting Files 8626 862713.4.3 `Makevars' in `po/' 8628-------------------------- 8629 8630The `po/' directory also has a file named `Makevars'. It contains 8631variables that are specific to your project. `po/Makevars' gets 8632inserted into the `po/Makefile' when the latter is created. The 8633variables thus take effect when the POT file is created or updated, and 8634when the message catalogs get installed. 8635 8636 The first three variables can be left unmodified if your package has 8637a single message domain and, accordingly, a single `po/' directory. 8638Only packages which have multiple `po/' directories at different 8639locations need to adjust the three first variables defined in 8640`Makevars'. 8641 8642 8643File: gettext.info, Node: po/Rules-*, Next: configure.in, Prev: po/Makevars, Up: Adjusting Files 8644 864513.4.4 Extending `Makefile' in `po/' 8646------------------------------------ 8647 8648All files called `Rules-*' in the `po/' directory get appended to the 8649`po/Makefile' when it is created. They present an opportunity to add 8650rules for special PO files to the Makefile, without needing to mess 8651with `po/Makefile.in.in'. 8652 8653 GNU gettext comes with a `Rules-quot' file, containing rules for 8654building catalogs `en@quot.po' and `en@boldquot.po'. The effect of 8655`en@quot.po' is that people who set their `LANGUAGE' environment 8656variable to `en@quot' will get messages with proper looking symmetric 8657Unicode quotation marks instead of abusing the ASCII grave accent and 8658the ASCII apostrophe for indicating quotations. To enable this 8659catalog, simply add `en@quot' to the `po/LINGUAS' file. The effect of 8660`en@boldquot.po' is that people who set `LANGUAGE' to `en@boldquot' 8661will get not only proper quotation marks, but also the quoted text will 8662be shown in a bold font on terminals and consoles. This catalog is 8663useful only for command-line programs, not GUI programs. To enable it, 8664similarly add `en@boldquot' to the `po/LINGUAS' file. 8665 8666 Similarly, you can create rules for building message catalogs for the 8667`sr@latin' locale - Serbian written with the Latin alphabet - from 8668those for the `sr' locale - Serbian written with Cyrillic letters. See 8669*Note msgfilter Invocation::. 8670 8671 8672File: gettext.info, Node: configure.in, Next: config.guess, Prev: po/Rules-*, Up: Adjusting Files 8673 867413.4.5 `configure.in' at top level 8675---------------------------------- 8676 8677`configure.in' or `configure.ac' - this is the source from which 8678`autoconf' generates the `configure' script. 8679 8680 1. Declare the package and version. 8681 8682 This is done by a set of lines like these: 8683 8684 PACKAGE=gettext 8685 VERSION=0.16.1 8686 AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE") 8687 AC_DEFINE_UNQUOTED(VERSION, "$VERSION") 8688 AC_SUBST(PACKAGE) 8689 AC_SUBST(VERSION) 8690 8691 or, if you are using GNU `automake', by a line like this: 8692 8693 AM_INIT_AUTOMAKE(gettext, 0.16.1) 8694 8695 Of course, you replace `gettext' with the name of your package, 8696 and `0.16.1' by its version numbers, exactly as they should appear 8697 in the packaged `tar' file name of your distribution 8698 (`gettext-0.16.1.tar.gz', here). 8699 8700 2. Check for internationalization support. 8701 8702 Here is the main `m4' macro for triggering internationalization 8703 support. Just add this line to `configure.in': 8704 8705 AM_GNU_GETTEXT 8706 8707 This call is purposely simple, even if it generates a lot of 8708 configure time checking and actions. 8709 8710 If you have suppressed the `intl/' subdirectory by calling 8711 `gettextize' without `--intl' option, this call should read 8712 8713 AM_GNU_GETTEXT([external]) 8714 8715 3. Have output files created. 8716 8717 The `AC_OUTPUT' directive, at the end of your `configure.in' file, 8718 needs to be modified in two ways: 8719 8720 AC_OUTPUT([EXISTING CONFIGURATION FILES intl/Makefile po/Makefile.in], 8721 [EXISTING ADDITIONAL ACTIONS]) 8722 8723 The modification to the first argument to `AC_OUTPUT' asks for 8724 substitution in the `intl/' and `po/' directories. Note the `.in' 8725 suffix used for `po/' only. This is because the distributed file 8726 is really `po/Makefile.in.in'. 8727 8728 If you have suppressed the `intl/' subdirectory by calling 8729 `gettextize' without `--intl' option, then you don't need to add 8730 `intl/Makefile' to the `AC_OUTPUT' line. 8731 8732 8733 If, after doing the recommended modifications, a command like 8734`aclocal -I m4' or `autoconf' or `autoreconf' fails with a trace 8735similar to this: 8736 8737 configure.ac:44: warning: AC_COMPILE_IFELSE was called before AC_GNU_SOURCE 8738 ../../lib/autoconf/specific.m4:335: AC_GNU_SOURCE is expanded from... 8739 m4/lock.m4:224: gl_LOCK is expanded from... 8740 m4/gettext.m4:571: gt_INTL_SUBDIR_CORE is expanded from... 8741 m4/gettext.m4:472: AM_INTL_SUBDIR is expanded from... 8742 m4/gettext.m4:347: AM_GNU_GETTEXT is expanded from... 8743 configure.ac:44: the top level 8744 configure.ac:44: warning: AC_RUN_IFELSE was called before AC_GNU_SOURCE 8745 8746you need to add an explicit invocation of `AC_GNU_SOURCE' in the 8747`configure.ac' file - after `AC_PROG_CC' but before `AM_GNU_GETTEXT', 8748most likely very close to the `AC_PROG_CC' invocation. This is 8749necessary because of ordering restrictions imposed by GNU autoconf. 8750 8751 8752File: gettext.info, Node: config.guess, Next: mkinstalldirs, Prev: configure.in, Up: Adjusting Files 8753 875413.4.6 `config.guess', `config.sub' at top level 8755------------------------------------------------ 8756 8757If you haven't suppressed the `intl/' subdirectory, you need to add the 8758GNU `config.guess' and `config.sub' files to your distribution. They 8759are needed because the `intl/' directory has platform dependent support 8760for determining the locale's character encoding and therefore needs to 8761identify the platform. 8762 8763 You can obtain the newest version of `config.guess' and `config.sub' 8764from the CVS of the `config' project at `http://savannah.gnu.org/'. The 8765commands to fetch them are 8766 $ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.guess' 8767 $ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.sub' 8768 Less recent versions are also contained in the GNU `automake' and 8769GNU `libtool' packages. 8770 8771 Normally, `config.guess' and `config.sub' are put at the top level 8772of a distribution. But it is also possible to put them in a 8773subdirectory, altogether with other configuration support files like 8774`install-sh', `ltconfig', `ltmain.sh' or `missing'. All you need to 8775do, other than moving the files, is to add the following line to your 8776`configure.in'. 8777 8778 AC_CONFIG_AUX_DIR([SUBDIR]) 8779 8780 8781File: gettext.info, Node: mkinstalldirs, Next: aclocal, Prev: config.guess, Up: Adjusting Files 8782 878313.4.7 `mkinstalldirs' at top level 8784----------------------------------- 8785 8786With earlier versions of GNU gettext, you needed to add the GNU 8787`mkinstalldirs' script to your distribution. This is not needed any 8788more. You can remove it if you not also using an automake version 8789older than automake 1.9. 8790 8791 8792File: gettext.info, Node: aclocal, Next: acconfig, Prev: mkinstalldirs, Up: Adjusting Files 8793 879413.4.8 `aclocal.m4' at top level 8795-------------------------------- 8796 8797If you do not have an `aclocal.m4' file in your distribution, the 8798simplest is to concatenate the files `codeset.m4', `gettext.m4', 8799`glibc2.m4', `glibc21.m4', `iconv.m4', `intdiv0.m4', `intl.m4', 8800`intldir.m4', `intmax.m4', `inttypes_h.m4', `inttypes-pri.m4', 8801`lcmessage.m4', `lib-ld.m4', `lib-link.m4', `lib-prefix.m4', `lock.m4', 8802`longdouble.m4', `longlong.m4', `nls.m4', `po.m4', `printf-posix.m4', 8803`progtest.m4', `size_max.m4', `stdint_h.m4', `uintmax_t.m4', 8804`ulonglong.m4', `visibility.m4', `wchar_t.m4', `wint_t.m4', `xsize.m4' 8805from GNU `gettext''s `m4/' directory into a single file. If you have 8806suppressed the `intl/' directory, only `gettext.m4', `iconv.m4', 8807`lib-ld.m4', `lib-link.m4', `lib-prefix.m4', `nls.m4', `po.m4', 8808`progtest.m4' need to be concatenated. 8809 8810 If you are not using GNU `automake' 1.8 or newer, you will need to 8811add a file `mkdirp.m4' from a newer automake distribution to the list 8812of files above. 8813 8814 If you already have an `aclocal.m4' file, then you will have to 8815merge the said macro files into your `aclocal.m4'. Note that if you 8816are upgrading from a previous release of GNU `gettext', you should most 8817probably _replace_ the macros (`AM_GNU_GETTEXT', etc.), as they usually 8818change a little from one release of GNU `gettext' to the next. Their 8819contents may vary as we get more experience with strange systems out 8820there. 8821 8822 If you are using GNU `automake' 1.5 or newer, it is enough to put 8823these macro files into a subdirectory named `m4/' and add the line 8824 8825 ACLOCAL_AMFLAGS = -I m4 8826 8827to your top level `Makefile.am'. 8828 8829 These macros check for the internationalization support functions 8830and related informations. Hopefully, once stabilized, these macros 8831might be integrated in the standard Autoconf set, because this piece of 8832`m4' code will be the same for all projects using GNU `gettext'. 8833 8834 8835File: gettext.info, Node: acconfig, Next: config.h.in, Prev: aclocal, Up: Adjusting Files 8836 883713.4.9 `acconfig.h' at top level 8838-------------------------------- 8839 8840Earlier GNU `gettext' releases required to put definitions for 8841`ENABLE_NLS', `HAVE_GETTEXT' and `HAVE_LC_MESSAGES', `HAVE_STPCPY', 8842`PACKAGE' and `VERSION' into an `acconfig.h' file. This is not needed 8843any more; you can remove them from your `acconfig.h' file unless your 8844package uses them independently from the `intl/' directory. 8845 8846 8847File: gettext.info, Node: config.h.in, Next: Makefile, Prev: acconfig, Up: Adjusting Files 8848 884913.4.10 `config.h.in' at top level 8850---------------------------------- 8851 8852The include file template that holds the C macros to be defined by 8853`configure' is usually called `config.h.in' and may be maintained 8854either manually or automatically. 8855 8856 If `gettextize' has created an `intl/' directory, this file must be 8857called `config.h.in' and must be at the top level. If, however, you 8858have suppressed the `intl/' directory by calling `gettextize' without 8859`--intl' option, then you can choose the name of this file and its 8860location freely. 8861 8862 If it is maintained automatically, by use of the `autoheader' 8863program, you need to do nothing about it. This is the case in 8864particular if you are using GNU `automake'. 8865 8866 If it is maintained manually, and if `gettextize' has created an 8867`intl/' directory, you should switch to using `autoheader'. The list 8868of C macros to be added for the sake of the `intl/' directory is just 8869too long to be maintained manually; it also changes between different 8870versions of GNU `gettext'. 8871 8872 If it is maintained manually, and if on the other hand you have 8873suppressed the `intl/' directory by calling `gettextize' without 8874`--intl' option, then you can get away by adding the following lines to 8875`config.h.in': 8876 8877 /* Define to 1 if translation of program messages to the user's 8878 native language is requested. */ 8879 #undef ENABLE_NLS 8880 8881 8882File: gettext.info, Node: Makefile, Next: src/Makefile, Prev: config.h.in, Up: Adjusting Files 8883 888413.4.11 `Makefile.in' at top level 8885---------------------------------- 8886 8887Here are a few modifications you need to make to your main, top-level 8888`Makefile.in' file. 8889 8890 1. Add the following lines near the beginning of your `Makefile.in', 8891 so the `dist:' goal will work properly (as explained further down): 8892 8893 PACKAGE = @PACKAGE@ 8894 VERSION = @VERSION@ 8895 8896 2. Add file `ABOUT-NLS' to the `DISTFILES' definition, so the file 8897 gets distributed. 8898 8899 3. Wherever you process subdirectories in your `Makefile.in', be sure 8900 you also process the subdirectories `intl' and `po'. Special 8901 rules in the `Makefiles' take care for the case where no 8902 internationalization is wanted. 8903 8904 If you are using Makefiles, either generated by automake, or 8905 hand-written so they carefully follow the GNU coding standards, 8906 the effected goals for which the new subdirectories must be 8907 handled include `installdirs', `install', `uninstall', `clean', 8908 `distclean'. 8909 8910 Here is an example of a canonical order of processing. In this 8911 example, we also define `SUBDIRS' in `Makefile.in' for it to be 8912 further used in the `dist:' goal. 8913 8914 SUBDIRS = doc intl lib src po 8915 8916 Note that you must arrange for `make' to descend into the `intl' 8917 directory before descending into other directories containing code 8918 which make use of the `libintl.h' header file. For this reason, 8919 here we mention `intl' before `lib' and `src'. 8920 8921 4. A delicate point is the `dist:' goal, as both `intl/Makefile' and 8922 `po/Makefile' will later assume that the proper directory has been 8923 set up from the main `Makefile'. Here is an example at what the 8924 `dist:' goal might look like: 8925 8926 distdir = $(PACKAGE)-$(VERSION) 8927 dist: Makefile 8928 rm -fr $(distdir) 8929 mkdir $(distdir) 8930 chmod 777 $(distdir) 8931 for file in $(DISTFILES); do \ 8932 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \ 8933 done 8934 for subdir in $(SUBDIRS); do \ 8935 mkdir $(distdir)/$$subdir || exit 1; \ 8936 chmod 777 $(distdir)/$$subdir; \ 8937 (cd $$subdir && $(MAKE) $@) || exit 1; \ 8938 done 8939 tar chozf $(distdir).tar.gz $(distdir) 8940 rm -fr $(distdir) 8941 8942 8943 Note that if you are using GNU `automake', `Makefile.in' is 8944automatically generated from `Makefile.am', and all needed changes to 8945`Makefile.am' are already made by running `gettextize'. 8946 8947 8948File: gettext.info, Node: src/Makefile, Next: lib/gettext.h, Prev: Makefile, Up: Adjusting Files 8949 895013.4.12 `Makefile.in' in `src/' 8951------------------------------- 8952 8953Some of the modifications made in the main `Makefile.in' will also be 8954needed in the `Makefile.in' from your package sources, which we assume 8955here to be in the `src/' subdirectory. Here are all the modifications 8956needed in `src/Makefile.in': 8957 8958 1. In view of the `dist:' goal, you should have these lines near the 8959 beginning of `src/Makefile.in': 8960 8961 PACKAGE = @PACKAGE@ 8962 VERSION = @VERSION@ 8963 8964 2. If not done already, you should guarantee that `top_srcdir' gets 8965 defined. This will serve for `cpp' include files. Just add the 8966 line: 8967 8968 top_srcdir = @top_srcdir@ 8969 8970 3. You might also want to define `subdir' as `src', later allowing 8971 for almost uniform `dist:' goals in all your `Makefile.in'. At 8972 list, the `dist:' goal below assume that you used: 8973 8974 subdir = src 8975 8976 4. The `main' function of your program will normally call 8977 `bindtextdomain' (see *note Triggering::), like this: 8978 8979 bindtextdomain (PACKAGE, LOCALEDIR); 8980 textdomain (PACKAGE); 8981 8982 To make LOCALEDIR known to the program, add the following lines to 8983 `Makefile.in': 8984 8985 datadir = @datadir@ 8986 localedir = $(datadir)/locale 8987 DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@ 8988 8989 Note that `@datadir@' defaults to `$(prefix)/share', thus 8990 `$(localedir)' defaults to `$(prefix)/share/locale'. 8991 8992 5. You should ensure that the final linking will use `@LIBINTL@' or 8993 `@LTLIBINTL@' as a library. `@LIBINTL@' is for use without 8994 `libtool', `@LTLIBINTL@' is for use with `libtool'. An easy way 8995 to achieve this is to manage that it gets into `LIBS', like this: 8996 8997 LIBS = @LIBINTL@ @LIBS@ 8998 8999 In most packages internationalized with GNU `gettext', one will 9000 find a directory `lib/' in which a library containing some helper 9001 functions will be build. (You need at least the few functions 9002 which the GNU `gettext' Library itself needs.) However some of 9003 the functions in the `lib/' also give messages to the user which 9004 of course should be translated, too. Taking care of this, the 9005 support library (say `libsupport.a') should be placed before 9006 `@LIBINTL@' and `@LIBS@' in the above example. So one has to 9007 write this: 9008 9009 LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@ 9010 9011 6. You should also ensure that directory `intl/' will be searched for 9012 C preprocessor include files in all circumstances. So, you have to 9013 manage so both `-I../intl' and `-I$(top_srcdir)/intl' will be 9014 given to the C compiler. 9015 9016 7. Your `dist:' goal has to conform with others. Here is a 9017 reasonable definition for it: 9018 9019 distdir = ../$(PACKAGE)-$(VERSION)/$(subdir) 9020 dist: Makefile $(DISTFILES) 9021 for file in $(DISTFILES); do \ 9022 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir) || exit 1; \ 9023 done 9024 9025 9026 Note that if you are using GNU `automake', `Makefile.in' is 9027automatically generated from `Makefile.am', and the first three changes 9028and the last change are not necessary. The remaining needed 9029`Makefile.am' modifications are the following: 9030 9031 1. To make LOCALEDIR known to the program, add the following to 9032 `Makefile.am': 9033 9034 <module>_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\" 9035 9036 for each specific module or compilation unit, or 9037 9038 AM_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\" 9039 9040 for all modules and compilation units together. Furthermore, add 9041 this line to define `localedir': 9042 9043 localedir = $(datadir)/locale 9044 9045 2. To ensure that the final linking will use `@LIBINTL@' or 9046 `@LTLIBINTL@' as a library, add the following to `Makefile.am': 9047 9048 <program>_LDADD = @LIBINTL@ 9049 9050 for each specific program, or 9051 9052 LDADD = @LIBINTL@ 9053 9054 for all programs together. Remember that when you use `libtool' 9055 to link a program, you need to use @LTLIBINTL@ instead of @LIBINTL@ 9056 for that program. 9057 9058 3. If you have an `intl/' directory, whose contents is created by 9059 `gettextize', then to ensure that it will be searched for C 9060 preprocessor include files in all circumstances, add something like 9061 this to `Makefile.am': 9062 9063 AM_CPPFLAGS = -I../intl -I$(top_srcdir)/intl 9064 9065 9066 9067File: gettext.info, Node: lib/gettext.h, Prev: src/Makefile, Up: Adjusting Files 9068 906913.4.13 `gettext.h' in `lib/' 9070----------------------------- 9071 9072Internationalization of packages, as provided by GNU `gettext', is 9073optional. It can be turned off in two situations: 9074 9075 * When the installer has specified `./configure --disable-nls'. This 9076 can be useful when small binaries are more important than 9077 features, for example when building utilities for boot diskettes. 9078 It can also be useful in order to get some specific C compiler 9079 warnings about code quality with some older versions of GCC (older 9080 than 3.0). 9081 9082 * When the package does not include the `intl/' subdirectory, and the 9083 libintl.h header (with its associated libintl library, if any) is 9084 not already installed on the system, it is preferable that the 9085 package builds without internationalization support, rather than 9086 to give a compilation error. 9087 9088 A C preprocessor macro can be used to detect these two cases. 9089Usually, when `libintl.h' was found and not explicitly disabled, the 9090`ENABLE_NLS' macro will be defined to 1 in the autoconf generated 9091configuration file (usually called `config.h'). In the two negative 9092situations, however, this macro will not be defined, thus it will 9093evaluate to 0 in C preprocessor expressions. 9094 9095 `gettext.h' is a convenience header file for conditional use of 9096`<libintl.h>', depending on the `ENABLE_NLS' macro. If `ENABLE_NLS' is 9097set, it includes `<libintl.h>'; otherwise it defines no-op substitutes 9098for the libintl.h functions. We recommend the use of `"gettext.h"' 9099over direct use of `<libintl.h>', so that portability to older systems 9100is guaranteed and installers can turn off internationalization if they 9101want to. In the C code, you will then write 9102 9103 #include "gettext.h" 9104 9105instead of 9106 9107 #include <libintl.h> 9108 9109 The location of `gettext.h' is usually in a directory containing 9110auxiliary include files. In many GNU packages, there is a directory 9111`lib/' containing helper functions; `gettext.h' fits there. In other 9112packages, it can go into the `src' directory. 9113 9114 Do not install the `gettext.h' file in public locations. Every 9115package that needs it should contain a copy of it on its own. 9116 9117 9118File: gettext.info, Node: autoconf macros, Next: CVS Issues, Prev: Adjusting Files, Up: Maintainers 9119 912013.5 Autoconf macros for use in `configure.in' 9121============================================== 9122 9123GNU `gettext' installs macros for use in a package's `configure.in' or 9124`configure.ac'. *Note Introduction: (autoconf)Top. The primary macro 9125is, of course, `AM_GNU_GETTEXT'. 9126 9127* Menu: 9128 9129* AM_GNU_GETTEXT:: AM_GNU_GETTEXT in `gettext.m4' 9130* AM_GNU_GETTEXT_VERSION:: AM_GNU_GETTEXT_VERSION in `gettext.m4' 9131* AM_GNU_GETTEXT_NEED:: AM_GNU_GETTEXT_NEED in `gettext.m4' 9132* AM_GNU_GETTEXT_INTL_SUBDIR:: AM_GNU_GETTEXT_INTL_SUBDIR in `intldir.m4' 9133* AM_PO_SUBDIRS:: AM_PO_SUBDIRS in `po.m4' 9134* AM_ICONV:: AM_ICONV in `iconv.m4' 9135 9136 9137File: gettext.info, Node: AM_GNU_GETTEXT, Next: AM_GNU_GETTEXT_VERSION, Prev: autoconf macros, Up: autoconf macros 9138 913913.5.1 AM_GNU_GETTEXT in `gettext.m4' 9140------------------------------------- 9141 9142The `AM_GNU_GETTEXT' macro tests for the presence of the GNU gettext 9143function family in either the C library or a separate `libintl' library 9144(shared or static libraries are both supported) or in the package's 9145`intl/' directory. It also invokes `AM_PO_SUBDIRS', thus preparing the 9146`po/' directories of the package for building. 9147 9148 `AM_GNU_GETTEXT' accepts up to three optional arguments. The general 9149syntax is 9150 9151 AM_GNU_GETTEXT([INTLSYMBOL], [NEEDSYMBOL], [INTLDIR]) 9152 9153 INTLSYMBOL can be `external' or `no-libtool'. The default (if it is 9154not specified or empty) is `no-libtool'. INTLSYMBOL should be 9155`external' for packages with no `intl/' directory. For packages with 9156an `intl/' directory, you can either use an INTLSYMBOL equal to 9157`no-libtool', or you can use `external' and override by using the macro 9158`AM_GNU_GETTEXT_INTL_SUBDIR' elsewhere. The two ways to specify the 9159existence of an `intl/' directory are equivalent. At build time, a 9160static library `$(top_builddir)/intl/libintl.a' will then be created. 9161 9162 If NEEDSYMBOL is specified and is `need-ngettext', then GNU gettext 9163implementations (in libc or libintl) without the `ngettext()' function 9164will be ignored. If NEEDSYMBOL is specified and is 9165`need-formatstring-macros', then GNU gettext implementations that don't 9166support the ISO C 99 `<inttypes.h>' formatstring macros will be ignored. 9167Only one NEEDSYMBOL can be specified. These requirements can also be 9168specified by using the macro `AM_GNU_GETTEXT_NEED' elsewhere. To 9169specify more than one requirement, just specify the strongest one among 9170them, or invoke the `AM_GNU_GETTEXT_NEED' macro several times. The 9171hierarchy among the various alternatives is as follows: 9172`need-formatstring-macros' implies `need-ngettext'. 9173 9174 INTLDIR is used to find the intl libraries. If empty, the value 9175`$(top_builddir)/intl/' is used. 9176 9177 The `AM_GNU_GETTEXT' macro determines whether GNU gettext is 9178available and should be used. If so, it sets the `USE_NLS' variable to 9179`yes'; it defines `ENABLE_NLS' to 1 in the autoconf generated 9180configuration file (usually called `config.h'); it sets the variables 9181`LIBINTL' and `LTLIBINTL' to the linker options for use in a Makefile 9182(`LIBINTL' for use without libtool, `LTLIBINTL' for use with libtool); 9183it adds an `-I' option to `CPPFLAGS' if necessary. In the negative 9184case, it sets `USE_NLS' to `no'; it sets `LIBINTL' and `LTLIBINTL' to 9185empty and doesn't change `CPPFLAGS'. 9186 9187 The complexities that `AM_GNU_GETTEXT' deals with are the following: 9188 9189 * Some operating systems have `gettext' in the C library, for example 9190 glibc. Some have it in a separate library `libintl'. GNU 9191 `libintl' might have been installed as part of the GNU `gettext' 9192 package. 9193 9194 * GNU `libintl', if installed, is not necessarily already in the 9195 search path (`CPPFLAGS' for the include file search path, 9196 `LDFLAGS' for the library search path). 9197 9198 * Except for glibc, the operating system's native `gettext' cannot 9199 exploit the GNU mo files, doesn't have the necessary locale 9200 dependency features, and cannot convert messages from the 9201 catalog's text encoding to the user's locale encoding. 9202 9203 * GNU `libintl', if installed, is not necessarily already in the run 9204 time library search path. To avoid the need for setting an 9205 environment variable like `LD_LIBRARY_PATH', the macro adds the 9206 appropriate run time search path options to the `LIBINTL' and 9207 `LTLIBINTL' variables. This works on most systems, but not on 9208 some operating systems with limited shared library support, like 9209 SCO. 9210 9211 * GNU `libintl' relies on POSIX/XSI `iconv'. The macro checks for 9212 linker options needed to use iconv and appends them to the 9213 `LIBINTL' and `LTLIBINTL' variables. 9214 9215 9216File: gettext.info, Node: AM_GNU_GETTEXT_VERSION, Next: AM_GNU_GETTEXT_NEED, Prev: AM_GNU_GETTEXT, Up: autoconf macros 9217 921813.5.2 AM_GNU_GETTEXT_VERSION in `gettext.m4' 9219--------------------------------------------- 9220 9221The `AM_GNU_GETTEXT_VERSION' macro declares the version number of the 9222GNU gettext infrastructure that is used by the package. 9223 9224 The use of this macro is optional; only the `autopoint' program makes 9225use of it (*note CVS Issues::). 9226 9227 9228File: gettext.info, Node: AM_GNU_GETTEXT_NEED, Next: AM_GNU_GETTEXT_INTL_SUBDIR, Prev: AM_GNU_GETTEXT_VERSION, Up: autoconf macros 9229 923013.5.3 AM_GNU_GETTEXT_NEED in `gettext.m4' 9231------------------------------------------ 9232 9233The `AM_GNU_GETTEXT_NEED' macro declares a constraint regarding the GNU 9234gettext implementation. The syntax is 9235 9236 AM_GNU_GETTEXT_NEED([NEEDSYMBOL]) 9237 9238 If NEEDSYMBOL is `need-ngettext', then GNU gettext implementations 9239(in libc or libintl) without the `ngettext()' function will be ignored. 9240If NEEDSYMBOL is `need-formatstring-macros', then GNU gettext 9241implementations that don't support the ISO C 99 `<inttypes.h>' 9242formatstring macros will be ignored. 9243 9244 The optional second argument of `AM_GNU_GETTEXT' is also taken into 9245account. 9246 9247 The `AM_GNU_GETTEXT_NEED' invocations can occur before or after the 9248`AM_GNU_GETTEXT' invocation; the order doesn't matter. 9249 9250 9251File: gettext.info, Node: AM_GNU_GETTEXT_INTL_SUBDIR, Next: AM_PO_SUBDIRS, Prev: AM_GNU_GETTEXT_NEED, Up: autoconf macros 9252 925313.5.4 AM_GNU_GETTEXT_INTL_SUBDIR in `intldir.m4' 9254------------------------------------------------- 9255 9256The `AM_GNU_GETTEXT_INTL_SUBDIR' macro specifies that the 9257`AM_GNU_GETTEXT' macro, although invoked with the first argument 9258`external', should also prepare for building the `intl/' subdirectory. 9259 9260 The `AM_GNU_GETTEXT_INTL_SUBDIR' invocation can occur before or after 9261the `AM_GNU_GETTEXT' invocation; the order doesn't matter. 9262 9263 The use of this macro requires GNU automake 1.10 or newer and GNU 9264autoconf 2.61 or newer. 9265 9266 9267File: gettext.info, Node: AM_PO_SUBDIRS, Next: AM_ICONV, Prev: AM_GNU_GETTEXT_INTL_SUBDIR, Up: autoconf macros 9268 926913.5.5 AM_PO_SUBDIRS in `po.m4' 9270------------------------------- 9271 9272The `AM_PO_SUBDIRS' macro prepares the `po/' directories of the package 9273for building. This macro should be used in internationalized programs 9274written in other programming languages than C, C++, Objective C, for 9275example `sh', `Python', `Lisp'. See *Note Programming Languages:: for 9276a list of programming languages that support localization through PO 9277files. 9278 9279 The `AM_PO_SUBDIRS' macro determines whether internationalization 9280should be used. If so, it sets the `USE_NLS' variable to `yes', 9281otherwise to `no'. It also determines the right values for Makefile 9282variables in each `po/' directory. 9283 9284 9285File: gettext.info, Node: AM_ICONV, Prev: AM_PO_SUBDIRS, Up: autoconf macros 9286 928713.5.6 AM_ICONV in `iconv.m4' 9288----------------------------- 9289 9290The `AM_ICONV' macro tests for the presence of the POSIX/XSI `iconv' 9291function family in either the C library or a separate `libiconv' 9292library. If found, it sets the `am_cv_func_iconv' variable to `yes'; 9293it defines `HAVE_ICONV' to 1 in the autoconf generated configuration 9294file (usually called `config.h'); it defines `ICONV_CONST' to `const' 9295or to empty, depending on whether the second argument of `iconv()' is 9296of type `const char **' or `char **'; it sets the variables `LIBICONV' 9297and `LTLIBICONV' to the linker options for use in a Makefile 9298(`LIBICONV' for use without libtool, `LTLIBICONV' for use with 9299libtool); it adds an `-I' option to `CPPFLAGS' if necessary. If not 9300found, it sets `LIBICONV' and `LTLIBICONV' to empty and doesn't change 9301`CPPFLAGS'. 9302 9303 The complexities that `AM_ICONV' deals with are the following: 9304 9305 * Some operating systems have `iconv' in the C library, for example 9306 glibc. Some have it in a separate library `libiconv', for example 9307 OSF/1 or FreeBSD. Regardless of the operating system, GNU 9308 `libiconv' might have been installed. In that case, it should be 9309 used instead of the operating system's native `iconv'. 9310 9311 * GNU `libiconv', if installed, is not necessarily already in the 9312 search path (`CPPFLAGS' for the include file search path, 9313 `LDFLAGS' for the library search path). 9314 9315 * GNU `libiconv' is binary incompatible with some operating system's 9316 native `iconv', for example on FreeBSD. Use of an `iconv.h' and 9317 `libiconv.so' that don't fit together would produce program 9318 crashes. 9319 9320 * GNU `libiconv', if installed, is not necessarily already in the 9321 run time library search path. To avoid the need for setting an 9322 environment variable like `LD_LIBRARY_PATH', the macro adds the 9323 appropriate run time search path options to the `LIBICONV' 9324 variable. This works on most systems, but not on some operating 9325 systems with limited shared library support, like SCO. 9326 9327 `iconv.m4' is distributed with the GNU gettext package because 9328`gettext.m4' relies on it. 9329 9330 9331File: gettext.info, Node: CVS Issues, Next: Release Management, Prev: autoconf macros, Up: Maintainers 9332 933313.6 Integrating with CVS 9334========================= 9335 9336Many projects use CVS for distributed development, version control and 9337source backup. This section gives some advice how to manage the uses 9338of `cvs', `gettextize', `autopoint' and `autoconf'. 9339 9340* Menu: 9341 9342* Distributed CVS:: Avoiding version mismatch in distributed development 9343* Files under CVS:: Files to put under CVS version control 9344* autopoint Invocation:: Invoking the `autopoint' Program 9345 9346 9347File: gettext.info, Node: Distributed CVS, Next: Files under CVS, Prev: CVS Issues, Up: CVS Issues 9348 934913.6.1 Avoiding version mismatch in distributed development 9350----------------------------------------------------------- 9351 9352In a project development with multiple developers, using CVS, there 9353should be a single developer who occasionally - when there is desire to 9354upgrade to a new `gettext' version - runs `gettextize' and performs the 9355changes listed in *Note Adjusting Files::, and then commits his changes 9356to the CVS. 9357 9358 It is highly recommended that all developers on a project use the 9359same version of GNU `gettext' in the package. In other words, if a 9360developer runs `gettextize', he should go the whole way, make the 9361necessary remaining changes and commit his changes to the CVS. 9362Otherwise the following damages will likely occur: 9363 9364 * Apparent version mismatch between developers. Since some `gettext' 9365 specific portions in `configure.in', `configure.ac' and 9366 `Makefile.am', `Makefile.in' files depend on the `gettext' 9367 version, the use of infrastructure files belonging to different 9368 `gettext' versions can easily lead to build errors. 9369 9370 * Hidden version mismatch. Such version mismatch can also lead to 9371 malfunctioning of the package, that may be undiscovered by the 9372 developers. The worst case of hidden version mismatch is that 9373 internationalization of the package doesn't work at all. 9374 9375 * Release risks. All developers implicitly perform constant testing 9376 on a package. This is important in the days and weeks before a 9377 release. If the guy who makes the release tar files uses a 9378 different version of GNU `gettext' than the other developers, the 9379 distribution will be less well tested than if all had been using 9380 the same `gettext' version. For example, it is possible that a 9381 platform specific bug goes undiscovered due to this constellation. 9382 9383 9384File: gettext.info, Node: Files under CVS, Next: autopoint Invocation, Prev: Distributed CVS, Up: CVS Issues 9385 938613.6.2 Files to put under CVS version control 9387--------------------------------------------- 9388 9389There are basically three ways to deal with generated files in the 9390context of a CVS repository, such as `configure' generated from 9391`configure.in', `PARSER.c' generated from `PARSER.y', or 9392`po/Makefile.in.in' autoinstalled by `gettextize' or `autopoint'. 9393 9394 1. All generated files are always committed into the repository. 9395 9396 2. All generated files are committed into the repository occasionally, 9397 for example each time a release is made. 9398 9399 3. Generated files are never committed into the repository. 9400 9401 Each of these three approaches has different advantages and 9402drawbacks. 9403 9404 1. The advantage is that anyone can check out the CVS at any moment 9405 and gets a working build. The drawbacks are: 1a. It requires 9406 some frequent "cvs commit" actions by the maintainers. 1b. The 9407 repository grows in size quite fast. 9408 9409 2. The advantage is that anyone can check out the CVS, and the usual 9410 "./configure; make" will work. The drawbacks are: 2a. The one who 9411 checks out the repository needs tools like GNU `automake', GNU 9412 `autoconf', GNU `m4' installed in his PATH; sometimes he even 9413 needs particular versions of them. 2b. When a release is made and 9414 a commit is made on the generated files, the other developers get 9415 conflicts on the generated files after doing "cvs update". 9416 Although these conflicts are easy to resolve, they are annoying. 9417 9418 3. The advantage is less work for the maintainers. The drawback is 9419 that anyone who checks out the CVS not only needs tools like GNU 9420 `automake', GNU `autoconf', GNU `m4' installed in his PATH, but 9421 also that he needs to perform a package specific pre-build step 9422 before being able to "./configure; make". 9423 9424 For the first and second approach, all files modified or brought in 9425by the occasional `gettextize' invocation and update should be 9426committed into the CVS. 9427 9428 For the third approach, the maintainer can omit from the CVS 9429repository all the files that `gettextize' mentions as "copy". 9430Instead, he adds to the `configure.in' or `configure.ac' a line of the 9431form 9432 9433 AM_GNU_GETTEXT_VERSION(0.16.1) 9434 9435and adds to the package's pre-build script an invocation of 9436`autopoint'. For everyone who checks out the CVS, this `autopoint' 9437invocation will copy into the right place the `gettext' infrastructure 9438files that have been omitted from the CVS. 9439 9440 The version number used as argument to `AM_GNU_GETTEXT_VERSION' is 9441the version of the `gettext' infrastructure that the package wants to 9442use. It is also the minimum version number of the `autopoint' program. 9443So, if you write `AM_GNU_GETTEXT_VERSION(0.11.5)' then the developers 9444can have any version >= 0.11.5 installed; the package will work with 9445the 0.11.5 infrastructure in all developers' builds. When the 9446maintainer then runs gettextize from, say, version 0.12.1 on the 9447package, the occurrence of `AM_GNU_GETTEXT_VERSION(0.11.5)' will be 9448changed into `AM_GNU_GETTEXT_VERSION(0.12.1)', and all other developers 9449that use the CVS will henceforth need to have GNU `gettext' 0.12.1 or 9450newer installed. 9451 9452 9453File: gettext.info, Node: autopoint Invocation, Prev: Files under CVS, Up: CVS Issues 9454 945513.6.3 Invoking the `autopoint' Program 9456--------------------------------------- 9457 9458 autopoint [OPTION]... 9459 9460 The `autopoint' program copies standard gettext infrastructure files 9461into a source package. It extracts from a macro call of the form 9462`AM_GNU_GETTEXT_VERSION(VERSION)', found in the package's 9463`configure.in' or `configure.ac' file, the gettext version used by the 9464package, and copies the infrastructure files belonging to this version 9465into the package. 9466 946713.6.3.1 Options 9468................ 9469 9470`-f' 9471`--force' 9472 Force overwriting of files that already exist. 9473 9474`-n' 9475`--dry-run' 9476 Print modifications but don't perform them. All file copying 9477 actions that `autopoint' would normally execute are inhibited and 9478 instead only listed on standard output. 9479 9480 948113.6.3.2 Informative output 9482........................... 9483 9484`--help' 9485 Display this help and exit. 9486 9487`--version' 9488 Output version information and exit. 9489 9490 9491 `autopoint' supports the GNU `gettext' versions from 0.10.35 to the 9492current one, 0.16.1. In order to apply `autopoint' to a package using 9493a `gettext' version newer than 0.16.1, you need to install this same 9494version of GNU `gettext' at least. 9495 9496 In packages using GNU `automake', an invocation of `autopoint' 9497should be followed by invocations of `aclocal' and then `autoconf' and 9498`autoheader'. The reason is that `autopoint' installs some autoconf 9499macro files, which are used by `aclocal' to create `aclocal.m4', and 9500the latter is used by `autoconf' to create the package's `configure' 9501script and by `autoheader' to create the package's `config.h.in' 9502include file template. 9503 9504 The name `autopoint' is an abbreviation of `auto-po-intl-m4'; the 9505tool copies or updates mostly files in the `po', `intl', `m4' 9506directories. 9507 9508 9509File: gettext.info, Node: Release Management, Prev: CVS Issues, Up: Maintainers 9510 951113.7 Creating a Distribution Tarball 9512==================================== 9513 9514In projects that use GNU `automake', the usual commands for creating a 9515distribution tarball, `make dist' or `make distcheck', automatically 9516update the PO files as needed. 9517 9518 If GNU `automake' is not used, the maintainer needs to perform this 9519update before making a release: 9520 9521 $ ./configure 9522 $ (cd po; make update-po) 9523 $ make distclean 9524 9525 9526File: gettext.info, Node: Installers, Next: Programming Languages, Prev: Maintainers, Up: Top 9527 952814 The Installer's and Distributor's View 9529***************************************** 9530 9531By default, packages fully using GNU `gettext', internally, are 9532installed in such a way that they to allow translation of messages. At 9533_configuration_ time, those packages should automatically detect 9534whether the underlying host system already provides the GNU `gettext' 9535functions. If not, the GNU `gettext' library should be automatically 9536prepared and used. Installers may use special options at configuration 9537time for changing this behavior. The command `./configure 9538--with-included-gettext' bypasses system `gettext' to use the included 9539GNU `gettext' instead, while `./configure --disable-nls' produces 9540programs totally unable to translate messages. 9541 9542 Internationalized packages have usually many `LL.po' files. Unless 9543translations are disabled, all those available are installed together 9544with the package. However, the environment variable `LINGUAS' may be 9545set, prior to configuration, to limit the installed set. `LINGUAS' 9546should then contain a space separated list of two-letter codes, stating 9547which languages are allowed. 9548 9549 9550File: gettext.info, Node: Programming Languages, Next: Conclusion, Prev: Installers, Up: Top 9551 955215 Other Programming Languages 9553****************************** 9554 9555While the presentation of `gettext' focuses mostly on C and implicitly 9556applies to C++ as well, its scope is far broader than that: Many 9557programming languages, scripting languages and other textual data like 9558GUI resources or package descriptions can make use of the gettext 9559approach. 9560 9561* Menu: 9562 9563* Language Implementors:: The Language Implementor's View 9564* Programmers for other Languages:: The Programmer's View 9565* Translators for other Languages:: The Translator's View 9566* Maintainers for other Languages:: The Maintainer's View 9567* List of Programming Languages:: Individual Programming Languages 9568* List of Data Formats:: Internationalizable Data 9569 9570 9571File: gettext.info, Node: Language Implementors, Next: Programmers for other Languages, Prev: Programming Languages, Up: Programming Languages 9572 957315.1 The Language Implementor's View 9574==================================== 9575 9576All programming and scripting languages that have the notion of strings 9577are eligible to supporting `gettext'. Supporting `gettext' means the 9578following: 9579 9580 1. You should add to the language a syntax for translatable strings. 9581 In principle, a function call of `gettext' would do, but a 9582 shorthand syntax helps keeping the legibility of internationalized 9583 programs. For example, in C we use the syntax `_("string")', and 9584 in GNU awk we use the shorthand `_"string"'. 9585 9586 2. You should arrange that evaluation of such a translatable string at 9587 runtime calls the `gettext' function, or performs equivalent 9588 processing. 9589 9590 3. Similarly, you should make the functions `ngettext', `dcgettext', 9591 `dcngettext' available from within the language. These functions 9592 are less often used, but are nevertheless necessary for particular 9593 purposes: `ngettext' for correct plural handling, and `dcgettext' 9594 and `dcngettext' for obeying other locale environment variables 9595 than `LC_MESSAGES', such as `LC_TIME' or `LC_MONETARY'. For these 9596 latter functions, you need to make the `LC_*' constants, available 9597 in the C header `<locale.h>', referenceable from within the 9598 language, usually either as enumeration values or as strings. 9599 9600 4. You should allow the programmer to designate a message domain, 9601 either by making the `textdomain' function available from within 9602 the language, or by introducing a magic variable called 9603 `TEXTDOMAIN'. Similarly, you should allow the programmer to 9604 designate where to search for message catalogs, by providing 9605 access to the `bindtextdomain' function. 9606 9607 5. You should either perform a `setlocale (LC_ALL, "")' call during 9608 the startup of your language runtime, or allow the programmer to 9609 do so. Remember that gettext will act as a no-op if the 9610 `LC_MESSAGES' and `LC_CTYPE' locale facets are not both set. 9611 9612 6. A programmer should have a way to extract translatable strings 9613 from a program into a PO file. The GNU `xgettext' program is being 9614 extended to support very different programming languages. Please 9615 contact the GNU `gettext' maintainers to help them doing this. If 9616 the string extractor is best integrated into your language's 9617 parser, GNU `xgettext' can function as a front end to your string 9618 extractor. 9619 9620 7. The language's library should have a string formatting facility 9621 where the arguments of a format string are denoted by a positional 9622 number or a name. This is needed because for some languages and 9623 some messages with more than one substitutable argument, the 9624 translation will need to output the substituted arguments in 9625 different order. *Note c-format Flag::. 9626 9627 8. If the language has more than one implementation, and not all of 9628 the implementations use `gettext', but the programs should be 9629 portable across implementations, you should provide a no-i18n 9630 emulation, that makes the other implementations accept programs 9631 written for yours, without actually translating the strings. 9632 9633 9. To help the programmer in the task of marking translatable strings, 9634 which is sometimes performed using the Emacs PO mode (*note 9635 Marking::), you are welcome to contact the GNU `gettext' 9636 maintainers, so they can add support for your language to 9637 `po-mode.el'. 9638 9639 On the implementation side, three approaches are possible, with 9640different effects on portability and copyright: 9641 9642 * You may integrate the GNU `gettext''s `intl/' directory in your 9643 package, as described in *Note Maintainers::. This allows you to 9644 have internationalization on all kinds of platforms. Note that 9645 when you then distribute your package, it legally falls under the 9646 GNU General Public License, and the GNU project will be glad about 9647 your contribution to the Free Software pool. 9648 9649 * You may link against GNU `gettext' functions if they are found in 9650 the C library. For example, an autoconf test for `gettext()' and 9651 `ngettext()' will detect this situation. For the moment, this test 9652 will succeed on GNU systems and not on other platforms. No severe 9653 copyright restrictions apply. 9654 9655 * You may emulate or reimplement the GNU `gettext' functionality. 9656 This has the advantage of full portability and no copyright 9657 restrictions, but also the drawback that you have to reimplement 9658 the GNU `gettext' features (such as the `LANGUAGE' environment 9659 variable, the locale aliases database, the automatic charset 9660 conversion, and plural handling). 9661 9662 9663File: gettext.info, Node: Programmers for other Languages, Next: Translators for other Languages, Prev: Language Implementors, Up: Programming Languages 9664 966515.2 The Programmer's View 9666========================== 9667 9668For the programmer, the general procedure is the same as for the C 9669language. The Emacs PO mode marking supports other languages, and the 9670GNU `xgettext' string extractor recognizes other languages based on the 9671file extension or a command-line option. In some languages, 9672`setlocale' is not needed because it is already performed by the 9673underlying language runtime. 9674 9675 9676File: gettext.info, Node: Translators for other Languages, Next: Maintainers for other Languages, Prev: Programmers for other Languages, Up: Programming Languages 9677 967815.3 The Translator's View 9679========================== 9680 9681The translator works exactly as in the C language case. The only 9682difference is that when translating format strings, she has to be aware 9683of the language's particular syntax for positional arguments in format 9684strings. 9685 9686* Menu: 9687 9688* c-format:: C Format Strings 9689* objc-format:: Objective C Format Strings 9690* sh-format:: Shell Format Strings 9691* python-format:: Python Format Strings 9692* lisp-format:: Lisp Format Strings 9693* elisp-format:: Emacs Lisp Format Strings 9694* librep-format:: librep Format Strings 9695* scheme-format:: Scheme Format Strings 9696* smalltalk-format:: Smalltalk Format Strings 9697* java-format:: Java Format Strings 9698* csharp-format:: C# Format Strings 9699* awk-format:: awk Format Strings 9700* object-pascal-format:: Object Pascal Format Strings 9701* ycp-format:: YCP Format Strings 9702* tcl-format:: Tcl Format Strings 9703* perl-format:: Perl Format Strings 9704* php-format:: PHP Format Strings 9705* gcc-internal-format:: GCC internal Format Strings 9706* qt-format:: Qt Format Strings 9707* boost-format:: Boost Format Strings 9708 9709 9710File: gettext.info, Node: c-format, Next: objc-format, Prev: Translators for other Languages, Up: Translators for other Languages 9711 971215.3.1 C Format Strings 9713----------------------- 9714 9715C format strings are described in POSIX (IEEE P1003.1 2001), section 9716XSH 3 fprintf(), 9717`http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html'. 9718See also the fprintf() manual page, 9719`http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php', 9720`http://informatik.fh-wuerzburg.de/student/i510/man/printf.html'. 9721 9722 Although format strings with positions that reorder arguments, such 9723as 9724 9725 "Only %2$d bytes free on '%1$s'." 9726 9727which is semantically equivalent to 9728 9729 "'%s' has only %d bytes free." 9730 9731are a POSIX/XSI feature and not specified by ISO C 99, translators can 9732rely on this reordering ability: On the few platforms where `printf()', 9733`fprintf()' etc. don't support this feature natively, `libintl.a' or 9734`libintl.so' provides replacement functions, and GNU `<libintl.h>' 9735activates these replacement functions automatically. 9736 9737 As a special feature for Farsi (Persian) and maybe Arabic, 9738translators can insert an `I' flag into numeric format directives. For 9739example, the translation of `"%d"' can be `"%Id"'. The effect of this 9740flag, on systems with GNU `libc', is that in the output, the ASCII 9741digits are replaced with the `outdigits' defined in the `LC_CTYPE' 9742locale facet. On other systems, the `gettext' function removes this 9743flag, so that it has no effect. 9744 9745 Note that the programmer should _not_ put this flag into the 9746untranslated string. (Putting the `I' format directive flag into an 9747MSGID string would lead to undefined behaviour on platforms without 9748glibc when NLS is disabled.) 9749 9750 9751File: gettext.info, Node: objc-format, Next: sh-format, Prev: c-format, Up: Translators for other Languages 9752 975315.3.2 Objective C Format Strings 9754--------------------------------- 9755 9756Objective C format strings are like C format strings. They support an 9757additional format directive: "$@", which when executed consumes an 9758argument of type `Object *'. 9759 9760 9761File: gettext.info, Node: sh-format, Next: python-format, Prev: objc-format, Up: Translators for other Languages 9762 976315.3.3 Shell Format Strings 9764--------------------------- 9765 9766Shell format strings, as supported by GNU gettext and the `envsubst' 9767program, are strings with references to shell variables in the form 9768`$VARIABLE' or `${VARIABLE}'. References of the form 9769`${VARIABLE-DEFAULT}', `${VARIABLE:-DEFAULT}', `${VARIABLE=DEFAULT}', 9770`${VARIABLE:=DEFAULT}', `${VARIABLE+REPLACEMENT}', 9771`${VARIABLE:+REPLACEMENT}', `${VARIABLE?IGNORED}', 9772`${VARIABLE:?IGNORED}', that would be valid inside shell scripts, are 9773not supported. The VARIABLE names must consist solely of alphanumeric 9774or underscore ASCII characters, not start with a digit and be nonempty; 9775otherwise such a variable reference is ignored. 9776 9777 9778File: gettext.info, Node: python-format, Next: lisp-format, Prev: sh-format, Up: Translators for other Languages 9779 978015.3.4 Python Format Strings 9781---------------------------- 9782 9783Python format strings are described in Python Library reference / 97842. Built-in Types, Exceptions and Functions / 2.2. Built-in Types / 97852.2.6. Sequence Types / 2.2.6.2. String Formatting Operations. 9786`http://www.python.org/doc/2.2.1/lib/typesseq-strings.html'. 9787 9788 9789File: gettext.info, Node: lisp-format, Next: elisp-format, Prev: python-format, Up: Translators for other Languages 9790 979115.3.5 Lisp Format Strings 9792-------------------------- 9793 9794Lisp format strings are described in the Common Lisp HyperSpec, chapter 979522.3 Formatted Output, 9796`http://www.lisp.org/HyperSpec/Body/sec_22-3.html'. 9797 9798 9799File: gettext.info, Node: elisp-format, Next: librep-format, Prev: lisp-format, Up: Translators for other Languages 9800 980115.3.6 Emacs Lisp Format Strings 9802-------------------------------- 9803 9804Emacs Lisp format strings are documented in the Emacs Lisp reference, 9805section Formatting Strings, 9806`http://www.gnu.org/manual/elisp-manual-21-2.8/html_chapter/elisp_4.html#SEC75'. 9807Note that as of version 21, XEmacs supports numbered argument 9808specifications in format strings while FSF Emacs doesn't. 9809 9810 9811File: gettext.info, Node: librep-format, Next: scheme-format, Prev: elisp-format, Up: Translators for other Languages 9812 981315.3.7 librep Format Strings 9814---------------------------- 9815 9816librep format strings are documented in the librep manual, section 9817Formatted Output, 9818`http://librep.sourceforge.net/librep-manual.html#Formatted%20Output', 9819`http://www.gwinnup.org/research/docs/librep.html#SEC122'. 9820 9821 9822File: gettext.info, Node: scheme-format, Next: smalltalk-format, Prev: librep-format, Up: Translators for other Languages 9823 982415.3.8 Scheme Format Strings 9825---------------------------- 9826 9827Scheme format strings are documented in the SLIB manual, section 9828Format Specification. 9829 9830 9831File: gettext.info, Node: smalltalk-format, Next: java-format, Prev: scheme-format, Up: Translators for other Languages 9832 983315.3.9 Smalltalk Format Strings 9834------------------------------- 9835 9836Smalltalk format strings are described in the GNU Smalltalk 9837documentation, class `CharArray', methods `bindWith:' and 9838`bindWithArguments:'. 9839`http://www.gnu.org/software/smalltalk/gst-manual/gst_68.html#SEC238'. 9840In summary, a directive starts with `%' and is followed by `%' or a 9841nonzero digit (`1' to `9'). 9842 9843 9844File: gettext.info, Node: java-format, Next: csharp-format, Prev: smalltalk-format, Up: Translators for other Languages 9845 984615.3.10 Java Format Strings 9847--------------------------- 9848 9849Java format strings are described in the JDK documentation for class 9850`java.text.MessageFormat', 9851`http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html'. 9852See also the ICU documentation 9853`http://oss.software.ibm.com/icu/apiref/classMessageFormat.html'. 9854 9855 9856File: gettext.info, Node: csharp-format, Next: awk-format, Prev: java-format, Up: Translators for other Languages 9857 985815.3.11 C# Format Strings 9859------------------------- 9860 9861C# format strings are described in the .NET documentation for class 9862`System.String' and in 9863`http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpConFormattingOverview.asp'. 9864 9865 9866File: gettext.info, Node: awk-format, Next: object-pascal-format, Prev: csharp-format, Up: Translators for other Languages 9867 986815.3.12 awk Format Strings 9869-------------------------- 9870 9871awk format strings are described in the gawk documentation, section 9872Printf, `http://www.gnu.org/manual/gawk/html_node/Printf.html#Printf'. 9873 9874 9875File: gettext.info, Node: object-pascal-format, Next: ycp-format, Prev: awk-format, Up: Translators for other Languages 9876 987715.3.13 Object Pascal Format Strings 9878------------------------------------ 9879 9880Where is this documented? 9881 9882 9883File: gettext.info, Node: ycp-format, Next: tcl-format, Prev: object-pascal-format, Up: Translators for other Languages 9884 988515.3.14 YCP Format Strings 9886-------------------------- 9887 9888YCP sformat strings are described in the libycp documentation 9889`file:/usr/share/doc/packages/libycp/YCP-builtins.html'. In summary, a 9890directive starts with `%' and is followed by `%' or a nonzero digit 9891(`1' to `9'). 9892 9893 9894File: gettext.info, Node: tcl-format, Next: perl-format, Prev: ycp-format, Up: Translators for other Languages 9895 989615.3.15 Tcl Format Strings 9897-------------------------- 9898 9899Tcl format strings are described in the `format.n' manual page, 9900`http://www.scriptics.com/man/tcl8.3/TclCmd/format.htm'. 9901 9902 9903File: gettext.info, Node: perl-format, Next: php-format, Prev: tcl-format, Up: Translators for other Languages 9904 990515.3.16 Perl Format Strings 9906--------------------------- 9907 9908There are two kinds format strings in Perl: those acceptable to the 9909Perl built-in function `printf', labelled as `perl-format', and those 9910acceptable to the `libintl-perl' function `__x', labelled as 9911`perl-brace-format'. 9912 9913 Perl `printf' format strings are described in the `sprintf' section 9914of `man perlfunc'. 9915 9916 Perl brace format strings are described in the 9917`Locale::TextDomain(3pm)' manual page of the CPAN package libintl-perl. 9918In brief, Perl format uses placeholders put between braces (`{' and 9919`}'). The placeholder must have the syntax of simple identifiers. 9920 9921 9922File: gettext.info, Node: php-format, Next: gcc-internal-format, Prev: perl-format, Up: Translators for other Languages 9923 992415.3.17 PHP Format Strings 9925-------------------------- 9926 9927PHP format strings are described in the documentation of the PHP 9928function `sprintf', in `phpdoc/manual/function.sprintf.html' or 9929`http://www.php.net/manual/en/function.sprintf.php'. 9930 9931 9932File: gettext.info, Node: gcc-internal-format, Next: qt-format, Prev: php-format, Up: Translators for other Languages 9933 993415.3.18 GCC internal Format Strings 9935----------------------------------- 9936 9937These format strings are used inside the GCC sources. In such a format 9938string, a directive starts with `%', is optionally followed by a size 9939specifier `l', an optional flag `+', another optional flag `#', and is 9940finished by a specifier: `%' denotes a literal percent sign, `c' 9941denotes a character, `s' denotes a string, `i' and `d' denote an 9942integer, `o', `u', `x' denote an unsigned integer, `.*s' denotes a 9943string preceded by a width specification, `H' denotes a `location_t *' 9944pointer, `D' denotes a general declaration, `F' denotes a function 9945declaration, `T' denotes a type, `A' denotes a function argument, `C' 9946denotes a tree code, `E' denotes an expression, `L' denotes a 9947programming language, `O' denotes a binary operator, `P' denotes a 9948function parameter, `Q' denotes an assignment operator, `V' denotes a 9949const/volatile qualifier. 9950 9951 9952File: gettext.info, Node: qt-format, Next: boost-format, Prev: gcc-internal-format, Up: Translators for other Languages 9953 995415.3.19 Qt Format Strings 9955------------------------- 9956 9957Qt format strings are described in the documentation of the QString 9958class `file:/usr/lib/qt-3.0.5/doc/html/qstring.html'. In summary, a 9959directive consists of a `%' followed by a digit. The same directive 9960cannot occur more than once in a format string. 9961 9962 9963File: gettext.info, Node: boost-format, Prev: qt-format, Up: Translators for other Languages 9964 996515.3.20 Boost Format Strings 9966---------------------------- 9967 9968Boost format strings are described in the documentation of the 9969`boost::format' class, at 9970`http://www.boost.org/libs/format/doc/format.html'. In summary, a 9971directive has either the same syntax as in a C format string, such as 9972`%1$+5d', or may be surrounded by vertical bars, such as `%|1$+5d|' or 9973`%|1$+5|', or consists of just an argument number between percent 9974signs, such as `%1%'. 9975 9976 9977File: gettext.info, Node: Maintainers for other Languages, Next: List of Programming Languages, Prev: Translators for other Languages, Up: Programming Languages 9978 997915.4 The Maintainer's View 9980========================== 9981 9982For the maintainer, the general procedure differs from the C language 9983case in two ways. 9984 9985 * For those languages that don't use GNU gettext, the `intl/' 9986 directory is not needed and can be omitted. This means that the 9987 maintainer calls the `gettextize' program without the `--intl' 9988 option, and that he invokes the `AM_GNU_GETTEXT' autoconf macro via 9989 `AM_GNU_GETTEXT([external])'. 9990 9991 * If only a single programming language is used, the 9992 `XGETTEXT_OPTIONS' variable in `po/Makevars' (*note po/Makevars::) 9993 should be adjusted to match the `xgettext' options for that 9994 particular programming language. If the package uses more than 9995 one programming language with `gettext' support, it becomes 9996 necessary to change the POT file construction rule in 9997 `po/Makefile.in.in'. It is recommended to make one `xgettext' 9998 invocation per programming language, each with the options 9999 appropriate for that language, and to combine the resulting files 10000 using `msgcat'. 10001 10002 10003File: gettext.info, Node: List of Programming Languages, Next: List of Data Formats, Prev: Maintainers for other Languages, Up: Programming Languages 10004 1000515.5 Individual Programming Languages 10006===================================== 10007 10008* Menu: 10009 10010* C:: C, C++, Objective C 10011* sh:: sh - Shell Script 10012* bash:: bash - Bourne-Again Shell Script 10013* Python:: Python 10014* Common Lisp:: GNU clisp - Common Lisp 10015* clisp C:: GNU clisp C sources 10016* Emacs Lisp:: Emacs Lisp 10017* librep:: librep 10018* Scheme:: GNU guile - Scheme 10019* Smalltalk:: GNU Smalltalk 10020* Java:: Java 10021* C#:: C# 10022* gawk:: GNU awk 10023* Pascal:: Pascal - Free Pascal Compiler 10024* wxWidgets:: wxWidgets library 10025* YCP:: YCP - YaST2 scripting language 10026* Tcl:: Tcl - Tk's scripting language 10027* Perl:: Perl 10028* PHP:: PHP Hypertext Preprocessor 10029* Pike:: Pike 10030* GCC-source:: GNU Compiler Collection sources 10031 10032 10033File: gettext.info, Node: C, Next: sh, Prev: List of Programming Languages, Up: List of Programming Languages 10034 1003515.5.1 C, C++, Objective C 10036-------------------------- 10037 10038RPMs 10039 gcc, gpp, gobjc, glibc, gettext 10040 10041File extension 10042 For C: `c', `h'. 10043 For C++: `C', `c++', `cc', `cxx', `cpp', `hpp'. 10044 For Objective C: `m'. 10045 10046String syntax 10047 `"abc"' 10048 10049gettext shorthand 10050 `_("abc")' 10051 10052gettext/ngettext functions 10053 `gettext', `dgettext', `dcgettext', `ngettext', `dngettext', 10054 `dcngettext' 10055 10056textdomain 10057 `textdomain' function 10058 10059bindtextdomain 10060 `bindtextdomain' function 10061 10062setlocale 10063 Programmer must call `setlocale (LC_ALL, "")' 10064 10065Prerequisite 10066 `#include <libintl.h>' 10067 `#include <locale.h>' 10068 `#define _(string) gettext (string)' 10069 10070Use or emulate GNU gettext 10071 Use 10072 10073Extractor 10074 `xgettext -k_' 10075 10076Formatting with positions 10077 `fprintf "%2$d %1$d"' 10078 In C++: `autosprintf "%2$d %1$d"' (*note Introduction: 10079 (autosprintf)Top.) 10080 10081Portability 10082 autoconf (gettext.m4) and #if ENABLE_NLS 10083 10084po-mode marking 10085 yes 10086 10087 The following examples are available in the `examples' directory: 10088`hello-c', `hello-c-gnome', `hello-c++', `hello-c++-qt', 10089`hello-c++-kde', `hello-c++-gnome', `hello-c++-wxwidgets', 10090`hello-objc', `hello-objc-gnustep', `hello-objc-gnome'. 10091 10092 10093File: gettext.info, Node: sh, Next: bash, Prev: C, Up: List of Programming Languages 10094 1009515.5.2 sh - Shell Script 10096------------------------ 10097 10098RPMs 10099 bash, gettext 10100 10101File extension 10102 `sh' 10103 10104String syntax 10105 `"abc"', `'abc'', `abc' 10106 10107gettext shorthand 10108 `"`gettext \"abc\"`"' 10109 10110gettext/ngettext functions 10111 `gettext', `ngettext' programs 10112 `eval_gettext', `eval_ngettext' shell functions 10113 10114textdomain 10115 environment variable `TEXTDOMAIN' 10116 10117bindtextdomain 10118 environment variable `TEXTDOMAINDIR' 10119 10120setlocale 10121 automatic 10122 10123Prerequisite 10124 `. gettext.sh' 10125 10126Use or emulate GNU gettext 10127 use 10128 10129Extractor 10130 `xgettext' 10131 10132Formatting with positions 10133 -- 10134 10135Portability 10136 fully portable 10137 10138po-mode marking 10139 -- 10140 10141 An example is available in the `examples' directory: `hello-sh'. 10142 10143* Menu: 10144 10145* Preparing Shell Scripts:: Preparing Shell Scripts for Internationalization 10146* gettext.sh:: Contents of `gettext.sh' 10147* gettext Invocation:: Invoking the `gettext' program 10148* ngettext Invocation:: Invoking the `ngettext' program 10149* envsubst Invocation:: Invoking the `envsubst' program 10150* eval_gettext Invocation:: Invoking the `eval_gettext' function 10151* eval_ngettext Invocation:: Invoking the `eval_ngettext' function 10152 10153 10154File: gettext.info, Node: Preparing Shell Scripts, Next: gettext.sh, Prev: sh, Up: sh 10155 1015615.5.2.1 Preparing Shell Scripts for Internationalization 10157......................................................... 10158 10159Preparing a shell script for internationalization is conceptually 10160similar to the steps described in *Note Sources::. The concrete steps 10161for shell scripts are as follows. 10162 10163 1. Insert the line 10164 10165 . gettext.sh 10166 10167 near the top of the script. `gettext.sh' is a shell function 10168 library that provides the functions `eval_gettext' (see *Note 10169 eval_gettext Invocation::) and `eval_ngettext' (see *Note 10170 eval_ngettext Invocation::). You have to ensure that `gettext.sh' 10171 can be found in the `PATH'. 10172 10173 2. Set and export the `TEXTDOMAIN' and `TEXTDOMAINDIR' environment 10174 variables. Usually `TEXTDOMAIN' is the package or program name, 10175 and `TEXTDOMAINDIR' is the absolute pathname corresponding to 10176 `$prefix/share/locale', where `$prefix' is the installation 10177 location. 10178 10179 TEXTDOMAIN=@PACKAGE@ 10180 export TEXTDOMAIN 10181 TEXTDOMAINDIR=@LOCALEDIR@ 10182 export TEXTDOMAINDIR 10183 10184 3. Prepare the strings for translation, as described in *Note 10185 Preparing Strings::. 10186 10187 4. Simplify translatable strings so that they don't contain command 10188 substitution (`"`...`"' or `"$(...)"'), variable access with 10189 defaulting (like `${VARIABLE-DEFAULT}'), access to positional 10190 arguments (like `$0', `$1', ...) or highly volatile shell 10191 variables (like `$?'). This can always be done through simple 10192 local code restructuring. For example, 10193 10194 echo "Usage: $0 [OPTION] FILE..." 10195 10196 becomes 10197 10198 program_name=$0 10199 echo "Usage: $program_name [OPTION] FILE..." 10200 10201 Similarly, 10202 10203 echo "Remaining files: `ls | wc -l`" 10204 10205 becomes 10206 10207 filecount="`ls | wc -l`" 10208 echo "Remaining files: $filecount" 10209 10210 5. For each translatable string, change the output command `echo' or 10211 `$echo' to `gettext' (if the string contains no references to 10212 shell variables) or to `eval_gettext' (if it refers to shell 10213 variables), followed by a no-argument `echo' command (to account 10214 for the terminating newline). Similarly, for cases with plural 10215 handling, replace a conditional `echo' command with an invocation 10216 of `ngettext' or `eval_ngettext', followed by a no-argument `echo' 10217 command. 10218 10219 When doing this, you also need to add an extra backslash before 10220 the dollar sign in references to shell variables, so that the 10221 `eval_gettext' function receives the translatable string before 10222 the variable values are substituted into it. For example, 10223 10224 echo "Remaining files: $filecount" 10225 10226 becomes 10227 10228 eval_gettext "Remaining files: \$filecount"; echo 10229 10230 If the output command is not `echo', you can make it use `echo' 10231 nevertheless, through the use of backquotes. However, note that 10232 inside backquotes, backslashes must be doubled to be effective 10233 (because the backquoting eats one level of backslashes). For 10234 example, assuming that `error' is a shell function that signals an 10235 error, 10236 10237 error "file not found: $filename" 10238 10239 is first transformed into 10240 10241 error "`echo \"file not found: \$filename\"`" 10242 10243 which then becomes 10244 10245 error "`eval_gettext \"file not found: \\\$filename\"`" 10246 10247 10248File: gettext.info, Node: gettext.sh, Next: gettext Invocation, Prev: Preparing Shell Scripts, Up: sh 10249 1025015.5.2.2 Contents of `gettext.sh' 10251................................. 10252 10253`gettext.sh', contained in the run-time package of GNU gettext, provides 10254the following: 10255 10256 * $echo The variable `echo' is set to a command that outputs its 10257 first argument and a newline, without interpreting backslashes in 10258 the argument string. 10259 10260 * eval_gettext See *Note eval_gettext Invocation::. 10261 10262 * eval_ngettext See *Note eval_ngettext Invocation::. 10263 10264 10265File: gettext.info, Node: gettext Invocation, Next: ngettext Invocation, Prev: gettext.sh, Up: sh 10266 1026715.5.2.3 Invoking the `gettext' program 10268....................................... 10269 10270 gettext [OPTION] [[TEXTDOMAIN] MSGID] 10271 gettext [OPTION] -s [MSGID]... 10272 10273 The `gettext' program displays the native language translation of a 10274textual message. 10275 10276*Arguments* 10277 10278`-d TEXTDOMAIN' 10279`--domain=TEXTDOMAIN' 10280 Retrieve translated messages from TEXTDOMAIN. Usually a TEXTDOMAIN 10281 corresponds to a package, a program, or a module of a program. 10282 10283`-e' 10284 Enable expansion of some escape sequences. This option is for 10285 compatibility with the `echo' program or shell built-in. The 10286 escape sequences `\a', `\b', `\c', `\f', `\n', `\r', `\t', `\v', 10287 `\\', and `\' followed by one to three octal digits, are 10288 interpreted like the System V `echo' program did. 10289 10290`-E' 10291 This option is only for compatibility with the `echo' program or 10292 shell built-in. It has no effect. 10293 10294`-h' 10295`--help' 10296 Display this help and exit. 10297 10298`-n' 10299 Suppress trailing newline. By default, `gettext' adds a newline to 10300 the output. 10301 10302`-V' 10303`--version' 10304 Output version information and exit. 10305 10306`[TEXTDOMAIN] MSGID' 10307 Retrieve translated message corresponding to MSGID from TEXTDOMAIN. 10308 10309 10310 If the TEXTDOMAIN parameter is not given, the domain is determined 10311from the environment variable `TEXTDOMAIN'. If the message catalog is 10312not found in the regular directory, another location can be specified 10313with the environment variable `TEXTDOMAINDIR'. 10314 10315 When used with the `-s' option the program behaves like the `echo' 10316command. But it does not simply copy its arguments to stdout. Instead 10317those messages found in the selected catalog are translated. 10318 10319 10320File: gettext.info, Node: ngettext Invocation, Next: envsubst Invocation, Prev: gettext Invocation, Up: sh 10321 1032215.5.2.4 Invoking the `ngettext' program 10323........................................ 10324 10325 ngettext [OPTION] [TEXTDOMAIN] MSGID MSGID-PLURAL COUNT 10326 10327 The `ngettext' program displays the native language translation of a 10328textual message whose grammatical form depends on a number. 10329 10330*Arguments* 10331 10332`-d TEXTDOMAIN' 10333`--domain=TEXTDOMAIN' 10334 Retrieve translated messages from TEXTDOMAIN. Usually a TEXTDOMAIN 10335 corresponds to a package, a program, or a module of a program. 10336 10337`-e' 10338 Enable expansion of some escape sequences. This option is for 10339 compatibility with the `gettext' program. The escape sequences 10340 `\a', `\b', `\c', `\f', `\n', `\r', `\t', `\v', `\\', and `\' 10341 followed by one to three octal digits, are interpreted like the 10342 System V `echo' program did. 10343 10344`-E' 10345 This option is only for compatibility with the `gettext' program. 10346 It has no effect. 10347 10348`-h' 10349`--help' 10350 Display this help and exit. 10351 10352`-V' 10353`--version' 10354 Output version information and exit. 10355 10356`TEXTDOMAIN' 10357 Retrieve translated message from TEXTDOMAIN. 10358 10359`MSGID MSGID-PLURAL' 10360 Translate MSGID (English singular) / MSGID-PLURAL (English plural). 10361 10362`COUNT' 10363 Choose singular/plural form based on this value. 10364 10365 10366 If the TEXTDOMAIN parameter is not given, the domain is determined 10367from the environment variable `TEXTDOMAIN'. If the message catalog is 10368not found in the regular directory, another location can be specified 10369with the environment variable `TEXTDOMAINDIR'. 10370 10371 10372File: gettext.info, Node: envsubst Invocation, Next: eval_gettext Invocation, Prev: ngettext Invocation, Up: sh 10373 1037415.5.2.5 Invoking the `envsubst' program 10375........................................ 10376 10377 envsubst [OPTION] [SHELL-FORMAT] 10378 10379 The `envsubst' program substitutes the values of environment 10380variables. 10381 10382*Operation mode* 10383 10384`-v' 10385`--variables' 10386 Output the variables occurring in SHELL-FORMAT. 10387 10388 10389*Informative output* 10390 10391`-h' 10392`--help' 10393 Display this help and exit. 10394 10395`-V' 10396`--version' 10397 Output version information and exit. 10398 10399 10400 In normal operation mode, standard input is copied to standard 10401output, with references to environment variables of the form 10402`$VARIABLE' or `${VARIABLE}' being replaced with the corresponding 10403values. If a SHELL-FORMAT is given, only those environment variables 10404that are referenced in SHELL-FORMAT are substituted; otherwise all 10405environment variables references occurring in standard input are 10406substituted. 10407 10408 These substitutions are a subset of the substitutions that a shell 10409performs on unquoted and double-quoted strings. Other kinds of 10410substitutions done by a shell, such as `${VARIABLE-DEFAULT}' or 10411`$(COMMAND-LIST)' or ``COMMAND-LIST`', are not performed by the 10412`envsubst' program, due to security reasons. 10413 10414 When `--variables' is used, standard input is ignored, and the output 10415consists of the environment variables that are referenced in 10416SHELL-FORMAT, one per line. 10417 10418 10419File: gettext.info, Node: eval_gettext Invocation, Next: eval_ngettext Invocation, Prev: envsubst Invocation, Up: sh 10420 1042115.5.2.6 Invoking the `eval_gettext' function 10422............................................. 10423 10424 eval_gettext MSGID 10425 10426 This function outputs the native language translation of a textual 10427message, performing dollar-substitution on the result. Note that only 10428shell variables mentioned in MSGID will be dollar-substituted in the 10429result. 10430 10431 10432File: gettext.info, Node: eval_ngettext Invocation, Prev: eval_gettext Invocation, Up: sh 10433 1043415.5.2.7 Invoking the `eval_ngettext' function 10435.............................................. 10436 10437 eval_ngettext MSGID MSGID-PLURAL COUNT 10438 10439 This function outputs the native language translation of a textual 10440message whose grammatical form depends on a number, performing 10441dollar-substitution on the result. Note that only shell variables 10442mentioned in MSGID or MSGID-PLURAL will be dollar-substituted in the 10443result. 10444 10445 10446File: gettext.info, Node: bash, Next: Python, Prev: sh, Up: List of Programming Languages 10447 1044815.5.3 bash - Bourne-Again Shell Script 10449--------------------------------------- 10450 10451GNU `bash' 2.0 or newer has a special shorthand for translating a 10452string and substituting variable values in it: `$"msgid"'. But the use 10453of this construct is *discouraged*, due to the security holes it opens 10454and due to its portability problems. 10455 10456 The security holes of `$"..."' come from the fact that after looking 10457up the translation of the string, `bash' processes it like it processes 10458any double-quoted string: dollar and backquote processing, like `eval' 10459does. 10460 10461 1. In a locale whose encoding is one of BIG5, BIG5-HKSCS, GBK, 10462 GB18030, SHIFT_JIS, JOHAB, some double-byte characters have a 10463 second byte whose value is `0x60'. For example, the byte sequence 10464 `\xe0\x60' is a single character in these locales. Many versions 10465 of `bash' (all versions up to bash-2.05, and newer versions on 10466 platforms without `mbsrtowcs()' function) don't know about 10467 character boundaries and see a backquote character where there is 10468 only a particular Chinese character. Thus it can start executing 10469 part of the translation as a command list. This situation can 10470 occur even without the translator being aware of it: if the 10471 translator provides translations in the UTF-8 encoding, it is the 10472 `gettext()' function which will, during its conversion from the 10473 translator's encoding to the user's locale's encoding, produce the 10474 dangerous `\x60' bytes. 10475 10476 2. A translator could - voluntarily or inadvertently - use backquotes 10477 `"`...`"' or dollar-parentheses `"$(...)"' in her translations. 10478 The enclosed strings would be executed as command lists by the 10479 shell. 10480 10481 The portability problem is that `bash' must be built with 10482internationalization support; this is normally not the case on systems 10483that don't have the `gettext()' function in libc. 10484 10485 10486File: gettext.info, Node: Python, Next: Common Lisp, Prev: bash, Up: List of Programming Languages 10487 1048815.5.4 Python 10489------------- 10490 10491RPMs 10492 python 10493 10494File extension 10495 `py' 10496 10497String syntax 10498 `'abc'', `u'abc'', `r'abc'', `ur'abc'', 10499 `"abc"', `u"abc"', `r"abc"', `ur"abc"', 10500 `'''abc'''', `u'''abc'''', `r'''abc'''', `ur'''abc'''', 10501 `"""abc"""', `u"""abc"""', `r"""abc"""', `ur"""abc"""' 10502 10503gettext shorthand 10504 `_('abc')' etc. 10505 10506gettext/ngettext functions 10507 `gettext.gettext', `gettext.dgettext', `gettext.ngettext', 10508 `gettext.dngettext', also `ugettext', `ungettext' 10509 10510textdomain 10511 `gettext.textdomain' function, or `gettext.install(DOMAIN)' 10512 function 10513 10514bindtextdomain 10515 `gettext.bindtextdomain' function, or 10516 `gettext.install(DOMAIN,LOCALEDIR)' function 10517 10518setlocale 10519 not used by the gettext emulation 10520 10521Prerequisite 10522 `import gettext' 10523 10524Use or emulate GNU gettext 10525 emulate 10526 10527Extractor 10528 `xgettext' 10529 10530Formatting with positions 10531 `'...%(ident)d...' % { 'ident': value }' 10532 10533Portability 10534 fully portable 10535 10536po-mode marking 10537 -- 10538 10539 An example is available in the `examples' directory: `hello-python'. 10540 10541 10542File: gettext.info, Node: Common Lisp, Next: clisp C, Prev: Python, Up: List of Programming Languages 10543 1054415.5.5 GNU clisp - Common Lisp 10545------------------------------ 10546 10547RPMs 10548 clisp 2.28 or newer 10549 10550File extension 10551 `lisp' 10552 10553String syntax 10554 `"abc"' 10555 10556gettext shorthand 10557 `(_ "abc")', `(ENGLISH "abc")' 10558 10559gettext/ngettext functions 10560 `i18n:gettext', `i18n:ngettext' 10561 10562textdomain 10563 `i18n:textdomain' 10564 10565bindtextdomain 10566 `i18n:textdomaindir' 10567 10568setlocale 10569 automatic 10570 10571Prerequisite 10572 -- 10573 10574Use or emulate GNU gettext 10575 use 10576 10577Extractor 10578 `xgettext -k_ -kENGLISH' 10579 10580Formatting with positions 10581 `format "~1@*~D ~0@*~D"' 10582 10583Portability 10584 On platforms without gettext, no translation. 10585 10586po-mode marking 10587 -- 10588 10589 An example is available in the `examples' directory: `hello-clisp'. 10590 10591 10592File: gettext.info, Node: clisp C, Next: Emacs Lisp, Prev: Common Lisp, Up: List of Programming Languages 10593 1059415.5.6 GNU clisp C sources 10595-------------------------- 10596 10597RPMs 10598 clisp 10599 10600File extension 10601 `d' 10602 10603String syntax 10604 `"abc"' 10605 10606gettext shorthand 10607 `ENGLISH ? "abc" : ""' 10608 `GETTEXT("abc")' 10609 `GETTEXTL("abc")' 10610 10611gettext/ngettext functions 10612 `clgettext', `clgettextl' 10613 10614textdomain 10615 -- 10616 10617bindtextdomain 10618 -- 10619 10620setlocale 10621 automatic 10622 10623Prerequisite 10624 `#include "lispbibl.c"' 10625 10626Use or emulate GNU gettext 10627 use 10628 10629Extractor 10630 `clisp-xgettext' 10631 10632Formatting with positions 10633 `fprintf "%2$d %1$d"' 10634 10635Portability 10636 On platforms without gettext, no translation. 10637 10638po-mode marking 10639 -- 10640 10641 10642File: gettext.info, Node: Emacs Lisp, Next: librep, Prev: clisp C, Up: List of Programming Languages 10643 1064415.5.7 Emacs Lisp 10645----------------- 10646 10647RPMs 10648 emacs, xemacs 10649 10650File extension 10651 `el' 10652 10653String syntax 10654 `"abc"' 10655 10656gettext shorthand 10657 `(_"abc")' 10658 10659gettext/ngettext functions 10660 `gettext', `dgettext' (xemacs only) 10661 10662textdomain 10663 `domain' special form (xemacs only) 10664 10665bindtextdomain 10666 `bind-text-domain' function (xemacs only) 10667 10668setlocale 10669 automatic 10670 10671Prerequisite 10672 -- 10673 10674Use or emulate GNU gettext 10675 use 10676 10677Extractor 10678 `xgettext' 10679 10680Formatting with positions 10681 `format "%2$d %1$d"' 10682 10683Portability 10684 Only XEmacs. Without `I18N3' defined at build time, no 10685 translation. 10686 10687po-mode marking 10688 -- 10689 10690 10691File: gettext.info, Node: librep, Next: Scheme, Prev: Emacs Lisp, Up: List of Programming Languages 10692 1069315.5.8 librep 10694------------- 10695 10696RPMs 10697 librep 0.15.3 or newer 10698 10699File extension 10700 `jl' 10701 10702String syntax 10703 `"abc"' 10704 10705gettext shorthand 10706 `(_"abc")' 10707 10708gettext/ngettext functions 10709 `gettext' 10710 10711textdomain 10712 `textdomain' function 10713 10714bindtextdomain 10715 `bindtextdomain' function 10716 10717setlocale 10718 -- 10719 10720Prerequisite 10721 `(require 'rep.i18n.gettext)' 10722 10723Use or emulate GNU gettext 10724 use 10725 10726Extractor 10727 `xgettext' 10728 10729Formatting with positions 10730 `format "%2$d %1$d"' 10731 10732Portability 10733 On platforms without gettext, no translation. 10734 10735po-mode marking 10736 -- 10737 10738 An example is available in the `examples' directory: `hello-librep'. 10739 10740 10741File: gettext.info, Node: Scheme, Next: Smalltalk, Prev: librep, Up: List of Programming Languages 10742 1074315.5.9 GNU guile - Scheme 10744------------------------- 10745 10746RPMs 10747 guile 10748 10749File extension 10750 `scm' 10751 10752String syntax 10753 `"abc"' 10754 10755gettext shorthand 10756 `(_ "abc")' 10757 10758gettext/ngettext functions 10759 `gettext', `ngettext' 10760 10761textdomain 10762 `textdomain' 10763 10764bindtextdomain 10765 `bindtextdomain' 10766 10767setlocale 10768 `(catch #t (lambda () (setlocale LC_ALL "")) (lambda args #f))' 10769 10770Prerequisite 10771 `(use-modules (ice-9 format))' 10772 10773Use or emulate GNU gettext 10774 use 10775 10776Extractor 10777 `xgettext -k_' 10778 10779Formatting with positions 10780 -- 10781 10782Portability 10783 On platforms without gettext, no translation. 10784 10785po-mode marking 10786 -- 10787 10788 An example is available in the `examples' directory: `hello-guile'. 10789 10790 10791File: gettext.info, Node: Smalltalk, Next: Java, Prev: Scheme, Up: List of Programming Languages 10792 1079315.5.10 GNU Smalltalk 10794--------------------- 10795 10796RPMs 10797 smalltalk 10798 10799File extension 10800 `st' 10801 10802String syntax 10803 `'abc'' 10804 10805gettext shorthand 10806 `NLS ? 'abc'' 10807 10808gettext/ngettext functions 10809 `LcMessagesDomain>>#at:', `LcMessagesDomain>>#at:plural:with:' 10810 10811textdomain 10812 `LcMessages>>#domain:localeDirectory:' (returns a 10813 `LcMessagesDomain' object). 10814 Example: `I18N Locale default messages domain: 'gettext' 10815 localeDirectory: /usr/local/share/locale'' 10816 10817bindtextdomain 10818 `LcMessages>>#domain:localeDirectory:', see above. 10819 10820setlocale 10821 Automatic if you use `I18N Locale default'. 10822 10823Prerequisite 10824 `PackageLoader fileInPackage: 'I18N'!' 10825 10826Use or emulate GNU gettext 10827 emulate 10828 10829Extractor 10830 `xgettext' 10831 10832Formatting with positions 10833 `'%1 %2' bindWith: 'Hello' with: 'world'' 10834 10835Portability 10836 fully portable 10837 10838po-mode marking 10839 -- 10840 10841 An example is available in the `examples' directory: 10842`hello-smalltalk'. 10843 10844 10845File: gettext.info, Node: Java, Next: C#, Prev: Smalltalk, Up: List of Programming Languages 10846 1084715.5.11 Java 10848------------ 10849 10850RPMs 10851 java, java2 10852 10853File extension 10854 `java' 10855 10856String syntax 10857 "abc" 10858 10859gettext shorthand 10860 _("abc") 10861 10862gettext/ngettext functions 10863 `GettextResource.gettext', `GettextResource.ngettext' 10864 10865textdomain 10866 --, use `ResourceBundle.getResource' instead 10867 10868bindtextdomain 10869 --, use CLASSPATH instead 10870 10871setlocale 10872 automatic 10873 10874Prerequisite 10875 -- 10876 10877Use or emulate GNU gettext 10878 --, uses a Java specific message catalog format 10879 10880Extractor 10881 `xgettext -k_' 10882 10883Formatting with positions 10884 `MessageFormat.format "{1,number} {0,number}"' 10885 10886Portability 10887 fully portable 10888 10889po-mode marking 10890 -- 10891 10892 Before marking strings as internationalizable, uses of the string 10893concatenation operator need to be converted to `MessageFormat' 10894applications. For example, `"file "+filename+" not found"' becomes 10895`MessageFormat.format("file {0} not found", new Object[] { filename })'. 10896Only after this is done, can the strings be marked and extracted. 10897 10898 GNU gettext uses the native Java internationalization mechanism, 10899namely `ResourceBundle's. There are two formats of `ResourceBundle's: 10900`.properties' files and `.class' files. The `.properties' format is a 10901text file which the translators can directly edit, like PO files, but 10902which doesn't support plural forms. Whereas the `.class' format is 10903compiled from `.java' source code and can support plural forms 10904(provided it is accessed through an appropriate API, see below). 10905 10906 To convert a PO file to a `.properties' file, the `msgcat' program 10907can be used with the option `--properties-output'. To convert a 10908`.properties' file back to a PO file, the `msgcat' program can be used 10909with the option `--properties-input'. All the tools that manipulate PO 10910files can work with `.properties' files as well, if given the 10911`--properties-input' and/or `--properties-output' option. 10912 10913 To convert a PO file to a ResourceBundle class, the `msgfmt' program 10914can be used with the option `--java' or `--java2'. To convert a 10915ResourceBundle back to a PO file, the `msgunfmt' program can be used 10916with the option `--java'. 10917 10918 Two different programmatic APIs can be used to access 10919ResourceBundles. Note that both APIs work with all kinds of 10920ResourceBundles, whether GNU gettext generated classes, or other 10921`.class' or `.properties' files. 10922 10923 1. The `java.util.ResourceBundle' API. 10924 10925 In particular, its `getString' function returns a string 10926 translation. Note that a missing translation yields a 10927 `MissingResourceException'. 10928 10929 This has the advantage of being the standard API. And it does not 10930 require any additional libraries, only the `msgcat' generated 10931 `.properties' files or the `msgfmt' generated `.class' files. But 10932 it cannot do plural handling, even if the resource was generated 10933 by `msgfmt' from a PO file with plural handling. 10934 10935 2. The `gnu.gettext.GettextResource' API. 10936 10937 Reference documentation in Javadoc 1.1 style format is in the 10938 javadoc1 directory (javadoc1/tree.html) and in Javadoc 2 style 10939 format in the javadoc2 directory (javadoc2/index.html). 10940 10941 Its `gettext' function returns a string translation. Note that 10942 when a translation is missing, the MSGID argument is returned 10943 unchanged. 10944 10945 This has the advantage of having the `ngettext' function for plural 10946 handling. 10947 10948 To use this API, one needs the `libintl.jar' file which is part of 10949 the GNU gettext package and distributed under the LGPL. 10950 10951 Three examples, using the second API, are available in the `examples' 10952directory: `hello-java', `hello-java-awt', `hello-java-swing'. 10953 10954 Now, to make use of the API and define a shorthand for `getString', 10955there are three idioms that you can choose from: 10956 10957 * (This one assumes Java 1.5 or newer.) In a unique class of your 10958 project, say `Util', define a static variable holding the 10959 `ResourceBundle' instance and the shorthand: 10960 10961 private static ResourceBundle myResources = 10962 ResourceBundle.getBundle("domain-name"); 10963 public static String _(String s) { 10964 return myResources.getString(s); 10965 } 10966 10967 All classes containing internationalized strings then contain 10968 10969 import static Util._; 10970 10971 and the shorthand is used like this: 10972 10973 System.out.println(_("Operation completed.")); 10974 10975 * In a unique class of your project, say `Util', define a static 10976 variable holding the `ResourceBundle' instance: 10977 10978 public static ResourceBundle myResources = 10979 ResourceBundle.getBundle("domain-name"); 10980 10981 All classes containing internationalized strings then contain 10982 10983 private static ResourceBundle res = Util.myResources; 10984 private static String _(String s) { return res.getString(s); } 10985 10986 and the shorthand is used like this: 10987 10988 System.out.println(_("Operation completed.")); 10989 10990 * You add a class with a very short name, say `S', containing just 10991 the definition of the resource bundle and of the shorthand: 10992 10993 public class S { 10994 public static ResourceBundle myResources = 10995 ResourceBundle.getBundle("domain-name"); 10996 public static String _(String s) { 10997 return myResources.getString(s); 10998 } 10999 } 11000 11001 and the shorthand is used like this: 11002 11003 System.out.println(S._("Operation completed.")); 11004 11005 Which of the three idioms you choose, will depend on whether your 11006project requires portability to Java versions prior to Java 1.5 and, if 11007so, whether copying two lines of codes into every class is more 11008acceptable in your project than a class with a single-letter name. 11009 11010 11011File: gettext.info, Node: C#, Next: gawk, Prev: Java, Up: List of Programming Languages 11012 1101315.5.12 C# 11014---------- 11015 11016RPMs 11017 pnet, pnetlib 0.6.2 or newer, or mono 0.29 or newer 11018 11019File extension 11020 `cs' 11021 11022String syntax 11023 `"abc"', `@"abc"' 11024 11025gettext shorthand 11026 _("abc") 11027 11028gettext/ngettext functions 11029 `GettextResourceManager.GetString', 11030 `GettextResourceManager.GetPluralString' 11031 11032textdomain 11033 `new GettextResourceManager(domain)' 11034 11035bindtextdomain 11036 --, compiled message catalogs are located in subdirectories of the 11037 directory containing the executable 11038 11039setlocale 11040 automatic 11041 11042Prerequisite 11043 -- 11044 11045Use or emulate GNU gettext 11046 --, uses a C# specific message catalog format 11047 11048Extractor 11049 `xgettext -k_' 11050 11051Formatting with positions 11052 `String.Format "{1} {0}"' 11053 11054Portability 11055 fully portable 11056 11057po-mode marking 11058 -- 11059 11060 Before marking strings as internationalizable, uses of the string 11061concatenation operator need to be converted to `String.Format' 11062invocations. For example, `"file "+filename+" not found"' becomes 11063`String.Format("file {0} not found", filename)'. Only after this is 11064done, can the strings be marked and extracted. 11065 11066 GNU gettext uses the native C#/.NET internationalization mechanism, 11067namely the classes `ResourceManager' and `ResourceSet'. Applications 11068use the `ResourceManager' methods to retrieve the native language 11069translation of strings. An instance of `ResourceSet' is the in-memory 11070representation of a message catalog file. The `ResourceManager' loads 11071and accesses `ResourceSet' instances as needed to look up the 11072translations. 11073 11074 There are two formats of `ResourceSet's that can be directly loaded 11075by the C# runtime: `.resources' files and `.dll' files. 11076 11077 * The `.resources' format is a binary file usually generated through 11078 the `resgen' or `monoresgen' utility, but which doesn't support 11079 plural forms. `.resources' files can also be embedded in .NET 11080 `.exe' files. This only affects whether a file system access is 11081 performed to load the message catalog; it doesn't affect the 11082 contents of the message catalog. 11083 11084 * On the other hand, the `.dll' format is a binary file that is 11085 compiled from `.cs' source code and can support plural forms 11086 (provided it is accessed through the GNU gettext API, see below). 11087 11088 Note that these .NET `.dll' and `.exe' files are not tied to a 11089particular platform; their file format and GNU gettext for C# can be 11090used on any platform. 11091 11092 To convert a PO file to a `.resources' file, the `msgfmt' program 11093can be used with the option `--csharp-resources'. To convert a 11094`.resources' file back to a PO file, the `msgunfmt' program can be used 11095with the option `--csharp-resources'. You can also, in some cases, use 11096the `resgen' program (from the `pnet' package) or the `monoresgen' 11097program (from the `mono'/`mcs' package). These programs can also 11098convert a `.resources' file back to a PO file. But beware: as of this 11099writing (January 2004), the `monoresgen' converter is quite buggy and 11100the `resgen' converter ignores the encoding of the PO files. 11101 11102 To convert a PO file to a `.dll' file, the `msgfmt' program can be 11103used with the option `--csharp'. The result will be a `.dll' file 11104containing a subclass of `GettextResourceSet', which itself is a 11105subclass of `ResourceSet'. To convert a `.dll' file containing a 11106`GettextResourceSet' subclass back to a PO file, the `msgunfmt' program 11107can be used with the option `--csharp'. 11108 11109 The advantages of the `.dll' format over the `.resources' format are: 11110 11111 1. Freedom to localize: Users can add their own translations to an 11112 application after it has been built and distributed. Whereas when 11113 the programmer uses a `ResourceManager' constructor provided by 11114 the system, the set of `.resources' files for an application must 11115 be specified when the application is built and cannot be extended 11116 afterwards. 11117 11118 2. Plural handling: A message catalog in `.dll' format supports the 11119 plural handling function `GetPluralString'. Whereas `.resources' 11120 files can only contain data and only support lookups that depend 11121 on a single string. 11122 11123 3. The `GettextResourceManager' that loads the message catalogs in 11124 `.dll' format also provides for inheritance on a per-message basis. 11125 For example, in Austrian (`de_AT') locale, translations from the 11126 German (`de') message catalog will be used for messages not found 11127 in the Austrian message catalog. This has the consequence that 11128 the Austrian translators need only translate those few messages 11129 for which the translation into Austrian differs from the German 11130 one. Whereas when working with `.resources' files, each message 11131 catalog must provide the translations of all messages by itself. 11132 11133 4. The `GettextResourceManager' that loads the message catalogs in 11134 `.dll' format also provides for a fallback: The English MSGID is 11135 returned when no translation can be found. Whereas when working 11136 with `.resources' files, a language-neutral `.resources' file must 11137 explicitly be provided as a fallback. 11138 11139 On the side of the programmatic APIs, the programmer can use either 11140the standard `ResourceManager' API and the GNU `GettextResourceManager' 11141API. The latter is an extension of the former, because 11142`GettextResourceManager' is a subclass of `ResourceManager'. 11143 11144 1. The `System.Resources.ResourceManager' API. 11145 11146 This API works with resources in `.resources' format. 11147 11148 The creation of the `ResourceManager' is done through 11149 new ResourceManager(domainname, Assembly.GetExecutingAssembly()) 11150 The `GetString' function returns a string's translation. Note 11151 that this function returns null when a translation is missing 11152 (i.e. not even found in the fallback resource file). 11153 11154 2. The `GNU.Gettext.GettextResourceManager' API. 11155 11156 This API works with resources in `.dll' format. 11157 11158 Reference documentation is in the csharpdoc directory 11159 (csharpdoc/index.html). 11160 11161 The creation of the `ResourceManager' is done through 11162 new GettextResourceManager(domainname) 11163 11164 The `GetString' function returns a string's translation. Note 11165 that when a translation is missing, the MSGID argument is returned 11166 unchanged. 11167 11168 The `GetPluralString' function returns a string translation with 11169 plural handling, like the `ngettext' function in C. 11170 11171 To use this API, one needs the `GNU.Gettext.dll' file which is 11172 part of the GNU gettext package and distributed under the LGPL. 11173 11174 You can also mix both approaches: use the 11175`GNU.Gettext.GettextResourceManager' constructor, but otherwise use 11176only the `ResourceManager' type and only the `GetString' method. This 11177is appropriate when you want to profit from the tools for PO files, but 11178don't want to change an existing source code that uses 11179`ResourceManager' and don't (yet) need the `GetPluralString' method. 11180 11181 Two examples, using the second API, are available in the `examples' 11182directory: `hello-csharp', `hello-csharp-forms'. 11183 11184 Now, to make use of the API and define a shorthand for `GetString', 11185there are two idioms that you can choose from: 11186 11187 * In a unique class of your project, say `Util', define a static 11188 variable holding the `ResourceManager' instance: 11189 11190 public static GettextResourceManager MyResourceManager = 11191 new GettextResourceManager("domain-name"); 11192 11193 All classes containing internationalized strings then contain 11194 11195 private static GettextResourceManager Res = Util.MyResourceManager; 11196 private static String _(String s) { return Res.GetString(s); } 11197 11198 and the shorthand is used like this: 11199 11200 Console.WriteLine(_("Operation completed.")); 11201 11202 * You add a class with a very short name, say `S', containing just 11203 the definition of the resource manager and of the shorthand: 11204 11205 public class S { 11206 public static GettextResourceManager MyResourceManager = 11207 new GettextResourceManager("domain-name"); 11208 public static String _(String s) { 11209 return MyResourceManager.GetString(s); 11210 } 11211 } 11212 11213 and the shorthand is used like this: 11214 11215 Console.WriteLine(S._("Operation completed.")); 11216 11217 Which of the two idioms you choose, will depend on whether copying 11218two lines of codes into every class is more acceptable in your project 11219than a class with a single-letter name. 11220 11221 11222File: gettext.info, Node: gawk, Next: Pascal, Prev: C#, Up: List of Programming Languages 11223 1122415.5.13 GNU awk 11225--------------- 11226 11227RPMs 11228 gawk 3.1 or newer 11229 11230File extension 11231 `awk' 11232 11233String syntax 11234 `"abc"' 11235 11236gettext shorthand 11237 `_"abc"' 11238 11239gettext/ngettext functions 11240 `dcgettext', missing `dcngettext' in gawk-3.1.0 11241 11242textdomain 11243 `TEXTDOMAIN' variable 11244 11245bindtextdomain 11246 `bindtextdomain' function 11247 11248setlocale 11249 automatic, but missing `setlocale (LC_MESSAGES, "")' in gawk-3.1.0 11250 11251Prerequisite 11252 -- 11253 11254Use or emulate GNU gettext 11255 use 11256 11257Extractor 11258 `xgettext' 11259 11260Formatting with positions 11261 `printf "%2$d %1$d"' (GNU awk only) 11262 11263Portability 11264 On platforms without gettext, no translation. On non-GNU awks, 11265 you must define `dcgettext', `dcngettext' and `bindtextdomain' 11266 yourself. 11267 11268po-mode marking 11269 -- 11270 11271 An example is available in the `examples' directory: `hello-gawk'. 11272 11273 11274File: gettext.info, Node: Pascal, Next: wxWidgets, Prev: gawk, Up: List of Programming Languages 11275 1127615.5.14 Pascal - Free Pascal Compiler 11277------------------------------------- 11278 11279RPMs 11280 fpk 11281 11282File extension 11283 `pp', `pas' 11284 11285String syntax 11286 `'abc'' 11287 11288gettext shorthand 11289 automatic 11290 11291gettext/ngettext functions 11292 --, use `ResourceString' data type instead 11293 11294textdomain 11295 --, use `TranslateResourceStrings' function instead 11296 11297bindtextdomain 11298 --, use `TranslateResourceStrings' function instead 11299 11300setlocale 11301 automatic, but uses only LANG, not LC_MESSAGES or LC_ALL 11302 11303Prerequisite 11304 `{$mode delphi}' or `{$mode objfpc}' 11305 `uses gettext;' 11306 11307Use or emulate GNU gettext 11308 emulate partially 11309 11310Extractor 11311 `ppc386' followed by `xgettext' or `rstconv' 11312 11313Formatting with positions 11314 `uses sysutils;' 11315 `format "%1:d %0:d"' 11316 11317Portability 11318 ? 11319 11320po-mode marking 11321 -- 11322 11323 The Pascal compiler has special support for the `ResourceString' data 11324type. It generates a `.rst' file. This is then converted to a `.pot' 11325file by use of `xgettext' or `rstconv'. At runtime, a `.mo' file 11326corresponding to translations of this `.pot' file can be loaded using 11327the `TranslateResourceStrings' function in the `gettext' unit. 11328 11329 An example is available in the `examples' directory: `hello-pascal'. 11330 11331 11332File: gettext.info, Node: wxWidgets, Next: YCP, Prev: Pascal, Up: List of Programming Languages 11333 1133415.5.15 wxWidgets library 11335------------------------- 11336 11337RPMs 11338 wxGTK, gettext 11339 11340File extension 11341 `cpp' 11342 11343String syntax 11344 `"abc"' 11345 11346gettext shorthand 11347 `_("abc")' 11348 11349gettext/ngettext functions 11350 `wxLocale::GetString', `wxGetTranslation' 11351 11352textdomain 11353 `wxLocale::AddCatalog' 11354 11355bindtextdomain 11356 `wxLocale::AddCatalogLookupPathPrefix' 11357 11358setlocale 11359 `wxLocale::Init', `wxSetLocale' 11360 11361Prerequisite 11362 `#include <wx/intl.h>' 11363 11364Use or emulate GNU gettext 11365 emulate, see `include/wx/intl.h' and `src/common/intl.cpp' 11366 11367Extractor 11368 `xgettext' 11369 11370Formatting with positions 11371 wxString::Format supports positions if and only if the system has 11372 `wprintf()', `vswprintf()' functions and they support positions 11373 according to POSIX. 11374 11375Portability 11376 fully portable 11377 11378po-mode marking 11379 yes 11380 11381 11382File: gettext.info, Node: YCP, Next: Tcl, Prev: wxWidgets, Up: List of Programming Languages 11383 1138415.5.16 YCP - YaST2 scripting language 11385-------------------------------------- 11386 11387RPMs 11388 libycp, libycp-devel, yast2-core, yast2-core-devel 11389 11390File extension 11391 `ycp' 11392 11393String syntax 11394 `"abc"' 11395 11396gettext shorthand 11397 `_("abc")' 11398 11399gettext/ngettext functions 11400 `_()' with 1 or 3 arguments 11401 11402textdomain 11403 `textdomain' statement 11404 11405bindtextdomain 11406 -- 11407 11408setlocale 11409 -- 11410 11411Prerequisite 11412 -- 11413 11414Use or emulate GNU gettext 11415 use 11416 11417Extractor 11418 `xgettext' 11419 11420Formatting with positions 11421 `sformat "%2 %1"' 11422 11423Portability 11424 fully portable 11425 11426po-mode marking 11427 -- 11428 11429 An example is available in the `examples' directory: `hello-ycp'. 11430 11431 11432File: gettext.info, Node: Tcl, Next: Perl, Prev: YCP, Up: List of Programming Languages 11433 1143415.5.17 Tcl - Tk's scripting language 11435------------------------------------- 11436 11437RPMs 11438 tcl 11439 11440File extension 11441 `tcl' 11442 11443String syntax 11444 `"abc"' 11445 11446gettext shorthand 11447 `[_ "abc"]' 11448 11449gettext/ngettext functions 11450 `::msgcat::mc' 11451 11452textdomain 11453 -- 11454 11455bindtextdomain 11456 --, use `::msgcat::mcload' instead 11457 11458setlocale 11459 automatic, uses LANG, but ignores LC_MESSAGES and LC_ALL 11460 11461Prerequisite 11462 `package require msgcat' 11463 `proc _ {s} {return [::msgcat::mc $s]}' 11464 11465Use or emulate GNU gettext 11466 --, uses a Tcl specific message catalog format 11467 11468Extractor 11469 `xgettext -k_' 11470 11471Formatting with positions 11472 `format "%2\$d %1\$d"' 11473 11474Portability 11475 fully portable 11476 11477po-mode marking 11478 -- 11479 11480 Two examples are available in the `examples' directory: `hello-tcl', 11481`hello-tcl-tk'. 11482 11483 Before marking strings as internationalizable, substitutions of 11484variables into the string need to be converted to `format' 11485applications. For example, `"file $filename not found"' becomes 11486`[format "file %s not found" $filename]'. Only after this is done, can 11487the strings be marked and extracted. After marking, this example 11488becomes `[format [_ "file %s not found"] $filename]' or `[msgcat::mc 11489"file %s not found" $filename]'. Note that the `msgcat::mc' function 11490implicitly calls `format' when more than one argument is given. 11491 11492 11493File: gettext.info, Node: Perl, Next: PHP, Prev: Tcl, Up: List of Programming Languages 11494 1149515.5.18 Perl 11496------------ 11497 11498RPMs 11499 perl 11500 11501File extension 11502 `pl', `PL', `pm', `cgi' 11503 11504String syntax 11505 * `"abc"' 11506 11507 * `'abc'' 11508 11509 * `qq (abc)' 11510 11511 * `q (abc)' 11512 11513 * `qr /abc/' 11514 11515 * `qx (/bin/date)' 11516 11517 * `/pattern match/' 11518 11519 * `?pattern match?' 11520 11521 * `s/substitution/operators/' 11522 11523 * `$tied_hash{"message"}' 11524 11525 * `$tied_hash_reference->{"message"}' 11526 11527 * etc., issue the command `man perlsyn' for details 11528 11529 11530gettext shorthand 11531 `__' (double underscore) 11532 11533gettext/ngettext functions 11534 `gettext', `dgettext', `dcgettext', `ngettext', `dngettext', 11535 `dcngettext' 11536 11537textdomain 11538 `textdomain' function 11539 11540bindtextdomain 11541 `bindtextdomain' function 11542 11543bind_textdomain_codeset 11544 `bind_textdomain_codeset' function 11545 11546setlocale 11547 Use `setlocale (LC_ALL, "");' 11548 11549Prerequisite 11550 `use POSIX;' 11551 `use Locale::TextDomain;' (included in the package libintl-perl 11552 which is available on the Comprehensive Perl Archive Network CPAN, 11553 http://www.cpan.org/). 11554 11555Use or emulate GNU gettext 11556 platform dependent: gettext_pp emulates, gettext_xs uses GNU 11557 gettext 11558 11559Extractor 11560 `xgettext -k__ -k\$__ -k%__ -k__x -k__n:1,2 -k__nx:1,2 -k__xn:1,2 11561 -kN__ -k' 11562 11563Formatting with positions 11564 Both kinds of format strings support formatting with positions. 11565 `printf "%2\$d %1\$d", ...' (requires Perl 5.8.0 or newer) 11566 `__expand("[new] replaces [old]", old => $oldvalue, new => 11567 $newvalue)' 11568 11569Portability 11570 The `libintl-perl' package is platform independent but is not part 11571 of the Perl core. The programmer is responsible for providing a 11572 dummy implementation of the required functions if the package is 11573 not installed on the target system. 11574 11575po-mode marking 11576 -- 11577 11578Documentation 11579 Included in `libintl-perl', available on CPAN 11580 (http://www.cpan.org/). 11581 11582 11583 An example is available in the `examples' directory: `hello-perl'. 11584 11585 The `xgettext' parser backend for Perl differs significantly from 11586the parser backends for other programming languages, just as Perl 11587itself differs significantly from other programming languages. The 11588Perl parser backend offers many more string marking facilities than the 11589other backends but it also has some Perl specific limitations, the 11590worst probably being its imperfectness. 11591 11592* Menu: 11593 11594* General Problems:: General Problems Parsing Perl Code 11595* Default Keywords:: Which Keywords Will xgettext Look For? 11596* Special Keywords:: How to Extract Hash Keys 11597* Quote-like Expressions:: What are Strings And Quote-like Expressions? 11598* Interpolation I:: Invalid String Interpolation 11599* Interpolation II:: Valid String Interpolation 11600* Parentheses:: When To Use Parentheses 11601* Long Lines:: How To Grok with Long Lines 11602* Perl Pitfalls:: Bugs, Pitfalls, and Things That Do Not Work 11603 11604 11605File: gettext.info, Node: General Problems, Next: Default Keywords, Up: Perl 11606 1160715.5.18.1 General Problems Parsing Perl Code 11608............................................ 11609 11610It is often heard that only Perl can parse Perl. This is not true. 11611Perl cannot be _parsed_ at all, it can only be _executed_. Perl has 11612various built-in ambiguities that can only be resolved at runtime. 11613 11614 The following example may illustrate one common problem: 11615 11616 print gettext "Hello World!"; 11617 11618 Although this example looks like a bullet-proof case of a function 11619invocation, it is not: 11620 11621 open gettext, ">testfile" or die; 11622 print gettext "Hello world!" 11623 11624 In this context, the string `gettext' looks more like a file handle. 11625But not necessarily: 11626 11627 use Locale::Messages qw (:libintl_h); 11628 open gettext ">testfile" or die; 11629 print gettext "Hello world!"; 11630 11631 Now, the file is probably syntactically incorrect, provided that the 11632module `Locale::Messages' found first in the Perl include path exports a 11633function `gettext'. But what if the module `Locale::Messages' really 11634looks like this? 11635 11636 use vars qw (*gettext); 11637 11638 1; 11639 11640 In this case, the string `gettext' will be interpreted as a file 11641handle again, and the above example will create a file `testfile' and 11642write the string "Hello world!" into it. Even advanced control flow 11643analysis will not really help: 11644 11645 if (0.5 < rand) { 11646 eval "use Sane"; 11647 } else { 11648 eval "use InSane"; 11649 } 11650 print gettext "Hello world!"; 11651 11652 If the module `Sane' exports a function `gettext' that does what we 11653expect, and the module `InSane' opens a file for writing and associates 11654the _handle_ `gettext' with this output stream, we are clueless again 11655about what will happen at runtime. It is completely unpredictable. 11656The truth is that Perl has so many ways to fill its symbol table at 11657runtime that it is impossible to interpret a particular piece of code 11658without executing it. 11659 11660 Of course, `xgettext' will not execute your Perl sources while 11661scanning for translatable strings, but rather use heuristics in order 11662to guess what you meant. 11663 11664 Another problem is the ambiguity of the slash and the question mark. 11665Their interpretation depends on the context: 11666 11667 # A pattern match. 11668 print "OK\n" if /foobar/; 11669 11670 # A division. 11671 print 1 / 2; 11672 11673 # Another pattern match. 11674 print "OK\n" if ?foobar?; 11675 11676 # Conditional. 11677 print $x ? "foo" : "bar"; 11678 11679 The slash may either act as the division operator or introduce a 11680pattern match, whereas the question mark may act as the ternary 11681conditional operator or as a pattern match, too. Other programming 11682languages like `awk' present similar problems, but the consequences of a 11683misinterpretation are particularly nasty with Perl sources. In `awk' 11684for instance, a statement can never exceed one line and the parser can 11685recover from a parsing error at the next newline and interpret the rest 11686of the input stream correctly. Perl is different, as a pattern match 11687is terminated by the next appearance of the delimiter (the slash or the 11688question mark) in the input stream, regardless of the semantic context. 11689If a slash is really a division sign but mis-interpreted as a pattern 11690match, the rest of the input file is most probably parsed incorrectly. 11691 11692 If you find that `xgettext' fails to extract strings from portions 11693of your sources, you should therefore look out for slashes and/or 11694question marks preceding these sections. You may have come across a 11695bug in `xgettext''s Perl parser (and of course you should report that 11696bug). In the meantime you should consider to reformulate your code in 11697a manner less challenging to `xgettext'. 11698 11699 11700File: gettext.info, Node: Default Keywords, Next: Special Keywords, Prev: General Problems, Up: Perl 11701 1170215.5.18.2 Which keywords will xgettext look for? 11703................................................ 11704 11705Unless you instruct `xgettext' otherwise by invoking it with one of the 11706options `--keyword' or `-k', it will recognize the following keywords 11707in your Perl sources: 11708 11709 * `gettext' 11710 11711 * `dgettext' 11712 11713 * `dcgettext' 11714 11715 * `ngettext:1,2' 11716 11717 The first (singular) and the second (plural) argument will be 11718 extracted. 11719 11720 * `dngettext:1,2' 11721 11722 The first (singular) and the second (plural) argument will be 11723 extracted. 11724 11725 * `dcngettext:1,2' 11726 11727 The first (singular) and the second (plural) argument will be 11728 extracted. 11729 11730 * `gettext_noop' 11731 11732 * `%gettext' 11733 11734 The keys of lookups into the hash `%gettext' will be extracted. 11735 11736 * `$gettext' 11737 11738 The keys of lookups into the hash reference `$gettext' will be 11739 extracted. 11740 11741 11742 11743File: gettext.info, Node: Special Keywords, Next: Quote-like Expressions, Prev: Default Keywords, Up: Perl 11744 1174515.5.18.3 How to Extract Hash Keys 11746.................................. 11747 11748Translating messages at runtime is normally performed by looking up the 11749original string in the translation database and returning the 11750translated version. The "natural" Perl implementation is a hash 11751lookup, and, of course, `xgettext' supports such practice. 11752 11753 print __"Hello world!"; 11754 print $__{"Hello world!"}; 11755 print $__->{"Hello world!"}; 11756 print $$__{"Hello world!"}; 11757 11758 The above four lines all do the same thing. The Perl module 11759`Locale::TextDomain' exports by default a hash `%__' that is tied to 11760the function `__()'. It also exports a reference `$__' to `%__'. 11761 11762 If an argument to the `xgettext' option `--keyword', resp. `-k' 11763starts with a percent sign, the rest of the keyword is interpreted as 11764the name of a hash. If it starts with a dollar sign, the rest of the 11765keyword is interpreted as a reference to a hash. 11766 11767 Note that you can omit the quotation marks (single or double) around 11768the hash key (almost) whenever Perl itself allows it: 11769 11770 print $gettext{Error}; 11771 11772 The exact rule is: You can omit the surrounding quotes, when the hash 11773key is a valid C (!) identifier, i.e. when it starts with an underscore 11774or an ASCII letter and is followed by an arbitrary number of 11775underscores, ASCII letters or digits. Other Unicode characters are 11776_not_ allowed, regardless of the `use utf8' pragma. 11777 11778 11779File: gettext.info, Node: Quote-like Expressions, Next: Interpolation I, Prev: Special Keywords, Up: Perl 11780 1178115.5.18.4 What are Strings And Quote-like Expressions? 11782...................................................... 11783 11784Perl offers a plethora of different string constructs. Those that can 11785be used either as arguments to functions or inside braces for hash 11786lookups are generally supported by `xgettext'. 11787 11788 * *double-quoted strings* 11789 print gettext "Hello World!"; 11790 11791 * *single-quoted strings* 11792 print gettext 'Hello World!'; 11793 11794 * *the operator qq* 11795 print gettext qq |Hello World!|; 11796 print gettext qq <E-mail: <guido\@imperia.net>>; 11797 11798 The operator `qq' is fully supported. You can use arbitrary 11799 delimiters, including the four bracketing delimiters (round, angle, 11800 square, curly) that nest. 11801 11802 * *the operator q* 11803 print gettext q |Hello World!|; 11804 print gettext q <E-mail: <guido@imperia.net>>; 11805 11806 The operator `q' is fully supported. You can use arbitrary 11807 delimiters, including the four bracketing delimiters (round, angle, 11808 square, curly) that nest. 11809 11810 * *the operator qx* 11811 print gettext qx ;LANGUAGE=C /bin/date; 11812 print gettext qx [/usr/bin/ls | grep '^[A-Z]*']; 11813 11814 The operator `qx' is fully supported. You can use arbitrary 11815 delimiters, including the four bracketing delimiters (round, angle, 11816 square, curly) that nest. 11817 11818 The example is actually a useless use of `gettext'. It will 11819 invoke the `gettext' function on the output of the command 11820 specified with the `qx' operator. The feature was included in 11821 order to make the interface consistent (the parser will extract 11822 all strings and quote-like expressions). 11823 11824 * *here documents* 11825 print gettext <<'EOF'; 11826 program not found in $PATH 11827 EOF 11828 11829 print ngettext <<EOF, <<"EOF"; 11830 one file deleted 11831 EOF 11832 several files deleted 11833 EOF 11834 11835 Here-documents are recognized. If the delimiter is enclosed in 11836 single quotes, the string is not interpolated. If it is enclosed 11837 in double quotes or has no quotes at all, the string is 11838 interpolated. 11839 11840 Delimiters that start with a digit are not supported! 11841 11842 11843 11844File: gettext.info, Node: Interpolation I, Next: Interpolation II, Prev: Quote-like Expressions, Up: Perl 11845 1184615.5.18.5 Invalid Uses Of String Interpolation 11847.............................................. 11848 11849Perl is capable of interpolating variables into strings. This offers 11850some nice features in localized programs but can also lead to problems. 11851 11852 A common error is a construct like the following: 11853 11854 print gettext "This is the program $0!\n"; 11855 11856 Perl will interpolate at runtime the value of the variable `$0' into 11857the argument of the `gettext()' function. Hence, this argument is not 11858a string constant but a variable argument (`$0' is a global variable 11859that holds the name of the Perl script being executed). The 11860interpolation is performed by Perl before the string argument is passed 11861to `gettext()' and will therefore depend on the name of the script 11862which can only be determined at runtime. Consequently, it is almost 11863impossible that a translation can be looked up at runtime (except if, 11864by accident, the interpolated string is found in the message catalog). 11865 11866 The `xgettext' program will therefore terminate parsing with a fatal 11867error if it encounters a variable inside of an extracted string. In 11868general, this will happen for all kinds of string interpolations that 11869cannot be safely performed at compile time. If you absolutely know 11870what you are doing, you can always circumvent this behavior: 11871 11872 my $know_what_i_am_doing = "This is program $0!\n"; 11873 print gettext $know_what_i_am_doing; 11874 11875 Since the parser only recognizes strings and quote-like expressions, 11876but not variables or other terms, the above construct will be accepted. 11877You will have to find another way, however, to let your original 11878string make it into your message catalog. 11879 11880 If invoked with the option `--extract-all', resp. `-a', variable 11881interpolation will be accepted. Rationale: You will generally use this 11882option in order to prepare your sources for internationalization. 11883 11884 Please see the manual page `man perlop' for details of strings and 11885quote-like expressions that are subject to interpolation and those that 11886are not. Safe interpolations (that will not lead to a fatal error) are: 11887 11888 * the escape sequences `\t' (tab, HT, TAB), `\n' (newline, NL), `\r' 11889 (return, CR), `\f' (form feed, FF), `\b' (backspace, BS), `\a' 11890 (alarm, bell, BEL), and `\e' (escape, ESC). 11891 11892 * octal chars, like `\033' 11893 Note that octal escapes in the range of 400-777 are translated 11894 into a UTF-8 representation, regardless of the presence of the 11895 `use utf8' pragma. 11896 11897 * hex chars, like `\x1b' 11898 11899 * wide hex chars, like `\x{263a}' 11900 Note that this escape is translated into a UTF-8 representation, 11901 regardless of the presence of the `use utf8' pragma. 11902 11903 * control chars, like `\c[' (CTRL-[) 11904 11905 * named Unicode chars, like `\N{LATIN CAPITAL LETTER C WITH CEDILLA}' 11906 Note that this escape is translated into a UTF-8 representation, 11907 regardless of the presence of the `use utf8' pragma. 11908 11909 The following escapes are considered partially safe: 11910 11911 * `\l' lowercase next char 11912 11913 * `\u' uppercase next char 11914 11915 * `\L' lowercase till \E 11916 11917 * `\U' uppercase till \E 11918 11919 * `\E' end case modification 11920 11921 * `\Q' quote non-word characters till \E 11922 11923 11924 These escapes are only considered safe if the string consists of 11925ASCII characters only. Translation of characters outside the range 11926defined by ASCII is locale-dependent and can actually only be performed 11927at runtime; `xgettext' doesn't do these locale-dependent translations 11928at extraction time. 11929 11930 Except for the modifier `\Q', these translations, albeit valid, are 11931generally useless and only obfuscate your sources. If a translation 11932can be safely performed at compile time you can just as well write what 11933you mean. 11934 11935 11936File: gettext.info, Node: Interpolation II, Next: Parentheses, Prev: Interpolation I, Up: Perl 11937 1193815.5.18.6 Valid Uses Of String Interpolation 11939............................................ 11940 11941Perl is often used to generate sources for other programming languages 11942or arbitrary file formats. Web applications that output HTML code make 11943a prominent example for such usage. 11944 11945 You will often come across situations where you want to intersperse 11946code written in the target (programming) language with translatable 11947messages, like in the following HTML example: 11948 11949 print gettext <<EOF; 11950 <h1>My Homepage</h1> 11951 <script language="JavaScript"><!-- 11952 for (i = 0; i < 100; ++i) { 11953 alert ("Thank you so much for visiting my homepage!"); 11954 } 11955 //--></script> 11956 EOF 11957 11958 The parser will extract the entire here document, and it will appear 11959entirely in the resulting PO file, including the JavaScript snippet 11960embedded in the HTML code. If you exaggerate with constructs like the 11961above, you will run the risk that the translators of your package will 11962look out for a less challenging project. You should consider an 11963alternative expression here: 11964 11965 print <<EOF; 11966 <h1>$gettext{"My Homepage"}</h1> 11967 <script language="JavaScript"><!-- 11968 for (i = 0; i < 100; ++i) { 11969 alert ("$gettext{'Thank you so much for visiting my homepage!'}"); 11970 } 11971 //--></script> 11972 EOF 11973 11974 Only the translatable portions of the code will be extracted here, 11975and the resulting PO file will begrudgingly improve in terms of 11976readability. 11977 11978 You can interpolate hash lookups in all strings or quote-like 11979expressions that are subject to interpolation (see the manual page `man 11980perlop' for details). Double interpolation is invalid, however: 11981 11982 # TRANSLATORS: Replace "the earth" with the name of your planet. 11983 print gettext qq{Welcome to $gettext->{"the earth"}}; 11984 11985 The `qq'-quoted string is recognized as an argument to `xgettext' in 11986the first place, and checked for invalid variable interpolation. The 11987dollar sign of hash-dereferencing will therefore terminate the parser 11988with an "invalid interpolation" error. 11989 11990 It is valid to interpolate hash lookups in regular expressions: 11991 11992 if ($var =~ /$gettext{"the earth"}/) { 11993 print gettext "Match!\n"; 11994 } 11995 s/$gettext{"U. S. A."}/$gettext{"U. S. A."} $gettext{"(dial +0)"}/g; 11996 11997 11998File: gettext.info, Node: Parentheses, Next: Long Lines, Prev: Interpolation II, Up: Perl 11999 1200015.5.18.7 When To Use Parentheses 12001................................. 12002 12003In Perl, parentheses around function arguments are mostly optional. 12004`xgettext' will always assume that all recognized keywords (except for 12005hashes and hash references) are names of properly prototyped functions, 12006and will (hopefully) only require parentheses where Perl itself 12007requires them. All constructs in the following example are therefore 12008ok to use: 12009 12010 print gettext ("Hello World!\n"); 12011 print gettext "Hello World!\n"; 12012 print dgettext ($package => "Hello World!\n"); 12013 print dgettext $package, "Hello World!\n"; 12014 12015 # The "fat comma" => turns the left-hand side argument into a 12016 # single-quoted string! 12017 print dgettext smellovision => "Hello World!\n"; 12018 12019 # The following assignment only works with prototyped functions. 12020 # Otherwise, the functions will act as "greedy" list operators and 12021 # eat up all following arguments. 12022 my $anonymous_hash = { 12023 planet => gettext "earth", 12024 cakes => ngettext "one cake", "several cakes", $n, 12025 still => $works, 12026 }; 12027 # The same without fat comma: 12028 my $other_hash = { 12029 'planet', gettext "earth", 12030 'cakes', ngettext "one cake", "several cakes", $n, 12031 'still', $works, 12032 }; 12033 12034 # Parentheses are only significant for the first argument. 12035 print dngettext 'package', ("one cake", "several cakes", $n), $discarded; 12036 12037 12038File: gettext.info, Node: Long Lines, Next: Perl Pitfalls, Prev: Parentheses, Up: Perl 12039 1204015.5.18.8 How To Grok with Long Lines 12041..................................... 12042 12043The necessity of long messages can often lead to a cumbersome or 12044unreadable coding style. Perl has several options that may prevent you 12045from writing unreadable code, and `xgettext' does its best to do 12046likewise. This is where the dot operator (the string concatenation 12047operator) may come in handy: 12048 12049 print gettext ("This is a very long" 12050 . " message that is still" 12051 . " readable, because" 12052 . " it is split into" 12053 . " multiple lines.\n"); 12054 12055 Perl is smart enough to concatenate these constant string fragments 12056into one long string at compile time, and so is `xgettext'. You will 12057only find one long message in the resulting POT file. 12058 12059 Note that the future Perl 6 will probably use the underscore (`_') 12060as the string concatenation operator, and the dot (`.') for 12061dereferencing. This new syntax is not yet supported by `xgettext'. 12062 12063 If embedded newline characters are not an issue, or even desired, you 12064may also insert newline characters inside quoted strings wherever you 12065feel like it: 12066 12067 print gettext ("<em>In HTML output 12068 embedded newlines are generally no 12069 problem, since adjacent whitespace 12070 is always rendered into a single 12071 space character.</em>"); 12072 12073 You may also consider to use here documents: 12074 12075 print gettext <<EOF; 12076 <em>In HTML output 12077 embedded newlines are generally no 12078 problem, since adjacent whitespace 12079 is always rendered into a single 12080 space character.</em> 12081 EOF 12082 12083 Please do not forget that the line breaks are real, i.e. they 12084translate into newline characters that will consequently show up in the 12085resulting POT file. 12086 12087 12088File: gettext.info, Node: Perl Pitfalls, Prev: Long Lines, Up: Perl 12089 1209015.5.18.9 Bugs, Pitfalls, And Things That Do Not Work 12091..................................................... 12092 12093The foregoing sections should have proven that `xgettext' is quite 12094smart in extracting translatable strings from Perl sources. Yet, some 12095more or less exotic constructs that could be expected to work, actually 12096do not work. 12097 12098 One of the more relevant limitations can be found in the 12099implementation of variable interpolation inside quoted strings. Only 12100simple hash lookups can be used there: 12101 12102 print <<EOF; 12103 $gettext{"The dot operator" 12104 . " does not work" 12105 . "here!"} 12106 Likewise, you cannot @{[ gettext ("interpolate function calls") ]} 12107 inside quoted strings or quote-like expressions. 12108 EOF 12109 12110 This is valid Perl code and will actually trigger invocations of the 12111`gettext' function at runtime. Yet, the Perl parser in `xgettext' will 12112fail to recognize the strings. A less obvious example can be found in 12113the interpolation of regular expressions: 12114 12115 s/<!--START_OF_WEEK-->/gettext ("Sunday")/e; 12116 12117 The modifier `e' will cause the substitution to be interpreted as an 12118evaluable statement. Consequently, at runtime the function `gettext()' 12119is called, but again, the parser fails to extract the string "Sunday". 12120Use a temporary variable as a simple workaround if you really happen to 12121need this feature: 12122 12123 my $sunday = gettext "Sunday"; 12124 s/<!--START_OF_WEEK-->/$sunday/; 12125 12126 Hash slices would also be handy but are not recognized: 12127 12128 my @weekdays = @gettext{'Sunday', 'Monday', 'Tuesday', 'Wednesday', 12129 'Thursday', 'Friday', 'Saturday'}; 12130 # Or even: 12131 @weekdays = @gettext{qw (Sunday Monday Tuesday Wednesday Thursday 12132 Friday Saturday) }; 12133 12134 This is perfectly valid usage of the tied hash `%gettext' but the 12135strings are not recognized and therefore will not be extracted. 12136 12137 Another caveat of the current version is its rudimentary support for 12138non-ASCII characters in identifiers. You may encounter serious 12139problems if you use identifiers with characters outside the range of 12140'A'-'Z', 'a'-'z', '0'-'9' and the underscore '_'. 12141 12142 Maybe some of these missing features will be implemented in future 12143versions, but since you can always make do without them at minimal 12144effort, these todos have very low priority. 12145 12146 A nasty problem are brace format strings that already contain braces 12147as part of the normal text, for example the usage strings typically 12148encountered in programs: 12149 12150 die "usage: $0 {OPTIONS} FILENAME...\n"; 12151 12152 If you want to internationalize this code with Perl brace format 12153strings, you will run into a problem: 12154 12155 die __x ("usage: {program} {OPTIONS} FILENAME...\n", program => $0); 12156 12157 Whereas `{program}' is a placeholder, `{OPTIONS}' is not and should 12158probably be translated. Yet, there is no way to teach the Perl parser 12159in `xgettext' to recognize the first one, and leave the other one alone. 12160 12161 There are two possible work-arounds for this problem. If you are 12162sure that your program will run under Perl 5.8.0 or newer (these Perl 12163versions handle positional parameters in `printf()') or if you are sure 12164that the translator will not have to reorder the arguments in her 12165translation - for example if you have only one brace placeholder in 12166your string, or if it describes a syntax, like in this one -, you can 12167mark the string as `no-perl-brace-format' and use `printf()': 12168 12169 # xgettext: no-perl-brace-format 12170 die sprintf ("usage: %s {OPTIONS} FILENAME...\n", $0); 12171 12172 If you want to use the more portable Perl brace format, you will 12173have to do put placeholders in place of the literal braces: 12174 12175 die __x ("usage: {program} {[}OPTIONS{]} FILENAME...\n", 12176 program => $0, '[' => '{', ']' => '}'); 12177 12178 Perl brace format strings know no escaping mechanism. No matter how 12179this escaping mechanism looked like, it would either give the 12180programmer a hard time, make translating Perl brace format strings 12181heavy-going, or result in a performance penalty at runtime, when the 12182format directives get executed. Most of the time you will happily get 12183along with `printf()' for this special case. 12184 12185 12186File: gettext.info, Node: PHP, Next: Pike, Prev: Perl, Up: List of Programming Languages 12187 1218815.5.19 PHP Hypertext Preprocessor 12189---------------------------------- 12190 12191RPMs 12192 mod_php4, mod_php4-core, phpdoc 12193 12194File extension 12195 `php', `php3', `php4' 12196 12197String syntax 12198 `"abc"', `'abc'' 12199 12200gettext shorthand 12201 `_("abc")' 12202 12203gettext/ngettext functions 12204 `gettext', `dgettext', `dcgettext'; starting with PHP 4.2.0 also 12205 `ngettext', `dngettext', `dcngettext' 12206 12207textdomain 12208 `textdomain' function 12209 12210bindtextdomain 12211 `bindtextdomain' function 12212 12213setlocale 12214 Programmer must call `setlocale (LC_ALL, "")' 12215 12216Prerequisite 12217 -- 12218 12219Use or emulate GNU gettext 12220 use 12221 12222Extractor 12223 `xgettext' 12224 12225Formatting with positions 12226 `printf "%2\$d %1\$d"' 12227 12228Portability 12229 On platforms without gettext, the functions are not available. 12230 12231po-mode marking 12232 -- 12233 12234 An example is available in the `examples' directory: `hello-php'. 12235 12236 12237File: gettext.info, Node: Pike, Next: GCC-source, Prev: PHP, Up: List of Programming Languages 12238 1223915.5.20 Pike 12240------------ 12241 12242RPMs 12243 roxen 12244 12245File extension 12246 `pike' 12247 12248String syntax 12249 `"abc"' 12250 12251gettext shorthand 12252 -- 12253 12254gettext/ngettext functions 12255 `gettext', `dgettext', `dcgettext' 12256 12257textdomain 12258 `textdomain' function 12259 12260bindtextdomain 12261 `bindtextdomain' function 12262 12263setlocale 12264 `setlocale' function 12265 12266Prerequisite 12267 `import Locale.Gettext;' 12268 12269Use or emulate GNU gettext 12270 use 12271 12272Extractor 12273 -- 12274 12275Formatting with positions 12276 -- 12277 12278Portability 12279 On platforms without gettext, the functions are not available. 12280 12281po-mode marking 12282 -- 12283 12284 12285File: gettext.info, Node: GCC-source, Prev: Pike, Up: List of Programming Languages 12286 1228715.5.21 GNU Compiler Collection sources 12288--------------------------------------- 12289 12290RPMs 12291 gcc 12292 12293File extension 12294 `c', `h'. 12295 12296String syntax 12297 `"abc"' 12298 12299gettext shorthand 12300 `_("abc")' 12301 12302gettext/ngettext functions 12303 `gettext', `dgettext', `dcgettext', `ngettext', `dngettext', 12304 `dcngettext' 12305 12306textdomain 12307 `textdomain' function 12308 12309bindtextdomain 12310 `bindtextdomain' function 12311 12312setlocale 12313 Programmer must call `setlocale (LC_ALL, "")' 12314 12315Prerequisite 12316 `#include "intl.h"' 12317 12318Use or emulate GNU gettext 12319 Use 12320 12321Extractor 12322 `xgettext -k_' 12323 12324Formatting with positions 12325 -- 12326 12327Portability 12328 Uses autoconf macros 12329 12330po-mode marking 12331 yes 12332 12333 12334File: gettext.info, Node: List of Data Formats, Prev: List of Programming Languages, Up: Programming Languages 12335 1233615.6 Internationalizable Data 12337============================= 12338 12339Here is a list of other data formats which can be internationalized 12340using GNU gettext. 12341 12342* Menu: 12343 12344* POT:: POT - Portable Object Template 12345* RST:: Resource String Table 12346* Glade:: Glade - GNOME user interface description 12347 12348 12349File: gettext.info, Node: POT, Next: RST, Prev: List of Data Formats, Up: List of Data Formats 12350 1235115.6.1 POT - Portable Object Template 12352------------------------------------- 12353 12354RPMs 12355 gettext 12356 12357File extension 12358 `pot', `po' 12359 12360Extractor 12361 `xgettext' 12362 12363 12364File: gettext.info, Node: RST, Next: Glade, Prev: POT, Up: List of Data Formats 12365 1236615.6.2 Resource String Table 12367---------------------------- 12368 12369RPMs 12370 fpk 12371 12372File extension 12373 `rst' 12374 12375Extractor 12376 `xgettext', `rstconv' 12377 12378 12379File: gettext.info, Node: Glade, Prev: RST, Up: List of Data Formats 12380 1238115.6.3 Glade - GNOME user interface description 12382----------------------------------------------- 12383 12384RPMs 12385 glade, libglade, glade2, libglade2, intltool 12386 12387File extension 12388 `glade', `glade2' 12389 12390Extractor 12391 `xgettext', `libglade-xgettext', `xml-i18n-extract', 12392 `intltool-extract' 12393 12394 12395File: gettext.info, Node: Conclusion, Next: Language Codes, Prev: Programming Languages, Up: Top 12396 1239716 Concluding Remarks 12398********************* 12399 12400We would like to conclude this GNU `gettext' manual by presenting an 12401history of the Translation Project so far. We finally give a few 12402pointers for those who want to do further research or readings about 12403Native Language Support matters. 12404 12405* Menu: 12406 12407* History:: History of GNU `gettext' 12408* References:: Related Readings 12409 12410 12411File: gettext.info, Node: History, Next: References, Prev: Conclusion, Up: Conclusion 12412 1241316.1 History of GNU `gettext' 12414============================= 12415 12416Internationalization concerns and algorithms have been informally and 12417casually discussed for years in GNU, sometimes around GNU `libc', maybe 12418around the incoming `Hurd', or otherwise (nobody clearly remembers). 12419And even then, when the work started for real, this was somewhat 12420independently of these previous discussions. 12421 12422 This all began in July 1994, when Patrick D'Cruze had the idea and 12423initiative of internationalizing version 3.9.2 of GNU `fileutils'. He 12424then asked Jim Meyering, the maintainer, how to get those changes 12425folded into an official release. That first draft was full of 12426`#ifdef's and somewhat disconcerting, and Jim wanted to find nicer 12427ways. Patrick and Jim shared some tries and experimentations in this 12428area. Then, feeling that this might eventually have a deeper impact on 12429GNU, Jim wanted to know what standards were, and contacted Richard 12430Stallman, who very quickly and verbally described an overall design for 12431what was meant to become `glocale', at that time. 12432 12433 Jim implemented `glocale' and got a lot of exhausting feedback from 12434Patrick and Richard, of course, but also from Mitchum DSouza (who wrote 12435a `catgets'-like package), Roland McGrath, maybe David MacKenzie, 12436Franc,ois Pinard, and Paul Eggert, all pushing and pulling in various 12437directions, not always compatible, to the extent that after a couple of 12438test releases, `glocale' was torn apart. In particular, Paul Eggert - 12439always keeping an eye on developments in Solaris - advocated the use of 12440the `gettext' API over `glocale''s `catgets'-based API. 12441 12442 While Jim took some distance and time and became dad for a second 12443time, Roland wanted to get GNU `libc' internationalized, and got Ulrich 12444Drepper involved in that project. Instead of starting from `glocale', 12445Ulrich rewrote something from scratch, but more conforming to the set 12446of guidelines who emerged out of the `glocale' effort. Then, Ulrich 12447got people from the previous forum to involve themselves into this new 12448project, and the switch from `glocale' to what was first named 12449`msgutils', renamed `nlsutils', and later `gettext', became officially 12450accepted by Richard in May 1995 or so. 12451 12452 Let's summarize by saying that Ulrich Drepper wrote GNU `gettext' in 12453April 1995. The first official release of the package, including PO 12454mode, occurred in July 1995, and was numbered 0.7. Other people 12455contributed to the effort by providing a discussion forum around 12456Ulrich, writing little pieces of code, or testing. These are quoted in 12457the `THANKS' file which comes with the GNU `gettext' distribution. 12458 12459 While this was being done, Franc,ois adapted half a dozen of GNU 12460packages to `glocale' first, then later to `gettext', putting them in 12461pretest, so providing along the way an effective user environment for 12462fine tuning the evolving tools. He also took the responsibility of 12463organizing and coordinating the Translation Project. After nearly a 12464year of informal exchanges between people from many countries, 12465translator teams started to exist in May 1995, through the creation and 12466support by Patrick D'Cruze of twenty unmoderated mailing lists for that 12467many native languages, and two moderated lists: one for reaching all 12468teams at once, the other for reaching all willing maintainers of 12469internationalized free software packages. 12470 12471 Franc,ois also wrote PO mode in June 1995 with the collaboration of 12472Greg McGary, as a kind of contribution to Ulrich's package. He also 12473gave a hand with the GNU `gettext' Texinfo manual. 12474 12475 In 1997, Ulrich Drepper released the GNU libc 2.0, which included the 12476`gettext', `textdomain' and `bindtextdomain' functions. 12477 12478 In 2000, Ulrich Drepper added plural form handling (the `ngettext' 12479function) to GNU libc. Later, in 2001, he released GNU libc 2.2.x, 12480which is the first free C library with full internationalization 12481support. 12482 12483 Ulrich being quite busy in his role of General Maintainer of GNU 12484libc, he handed over the GNU `gettext' maintenance to Bruno Haible in 124852000. Bruno added the plural form handling to the tools as well, added 12486support for UTF-8 and CJK locales, and wrote a few new tools for 12487manipulating PO files. 12488 12489 12490File: gettext.info, Node: References, Prev: History, Up: Conclusion 12491 1249216.2 Related Readings 12493===================== 12494 12495* NOTE: * This documentation section is outdated and needs to be 12496revised. 12497 12498 Eugene H. Dorr (`dorre@well.com') maintains an interesting 12499bibliography on internationalization matters, called 12500`Internationalization Reference List', which is available as: 12501 ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt 12502 12503 Michael Gschwind (`mike@vlsivie.tuwien.ac.at') maintains a 12504Frequently Asked Questions (FAQ) list, entitled `Programming for 12505Internationalisation'. This FAQ discusses writing programs which can 12506handle different language conventions, character sets, etc.; and is 12507applicable to all character set encodings, with particular emphasis on 12508ISO 8859-1. It is regularly published in Usenet groups 12509`comp.unix.questions', `comp.std.internat', 12510`comp.software.international', `comp.lang.c', `comp.windows.x', 12511`comp.std.c', `comp.answers' and `news.answers'. The home location of 12512this document is: 12513 ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming 12514 12515 Patrick D'Cruze (`pdcruze@li.org') wrote a tutorial about NLS 12516matters, and Jochen Hein (`Hein@student.tu-clausthal.de') took over the 12517responsibility of maintaining it. It may be found as: 12518 ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/... 12519 ...locale-tutorial-0.8.txt.gz 12520 This site is mirrored in: 12521 ftp://ftp.ibp.fr/pub/linux/sunsite/ 12522 12523 A French version of the same tutorial should be findable at: 12524 ftp://ftp.ibp.fr/pub/linux/french/docs/ 12525 together with French translations of many Linux-related documents. 12526 12527 12528File: gettext.info, Node: Language Codes, Next: Country Codes, Prev: Conclusion, Up: Top 12529 12530Appendix A Language Codes 12531************************* 12532 12533The ISO 639 standard defines two-letter codes for many languages, and 12534three-letter codes for more rarely used languages. All abbreviations 12535for languages used in the Translation Project should come from this 12536standard. 12537 12538* Menu: 12539 12540* Usual Language Codes:: Two-letter ISO 639 language codes 12541* Rare Language Codes:: Three-letter ISO 639 language codes 12542 12543 12544File: gettext.info, Node: Usual Language Codes, Next: Rare Language Codes, Prev: Language Codes, Up: Language Codes 12545 12546A.1 Usual Language Codes 12547======================== 12548 12549For the commonly used languages, the ISO 639-1 standard defines 12550two-letter codes. 12551 12552`aa' 12553 Afar. 12554 12555`ab' 12556 Abkhazian. 12557 12558`ad' 12559 Adangme. 12560 12561`ae' 12562 Avestan. 12563 12564`af' 12565 Afrikaans. 12566 12567`ak' 12568 Akan. 12569 12570`am' 12571 Amharic. 12572 12573`an' 12574 Aragonese. 12575 12576`ar' 12577 Arabic. 12578 12579`as' 12580 Assamese. 12581 12582`av' 12583 Avaric. 12584 12585`ay' 12586 Aymara. 12587 12588`az' 12589 Azerbaijani. 12590 12591`ba' 12592 Bashkir. 12593 12594`be' 12595 Byelorussian; Belarusian. 12596 12597`bg' 12598 Bulgarian. 12599 12600`bh' 12601 Bihari. 12602 12603`bi' 12604 Bislama. 12605 12606`bm' 12607 Bambara. 12608 12609`bn' 12610 Bengali; Bangla. 12611 12612`bo' 12613 Tibetan. 12614 12615`br' 12616 Breton. 12617 12618`bs' 12619 Bosnian. 12620 12621`ca' 12622 Catalan. 12623 12624`ce' 12625 Chechen. 12626 12627`ch' 12628 Chamorro. 12629 12630`co' 12631 Corsican. 12632 12633`cr' 12634 Cree. 12635 12636`cs' 12637 Czech. 12638 12639`cu' 12640 Church Slavic. 12641 12642`cv' 12643 Chuvash. 12644 12645`cy' 12646 Welsh. 12647 12648`da' 12649 Danish. 12650 12651`de' 12652 German. 12653 12654`dv' 12655 Divehi; Maldivian. 12656 12657`dz' 12658 Dzongkha; Bhutani. 12659 12660`ee' 12661 E'we'. 12662 12663`el' 12664 Greek. 12665 12666`en' 12667 English. 12668 12669`eo' 12670 Esperanto. 12671 12672`es' 12673 Spanish. 12674 12675`et' 12676 Estonian. 12677 12678`eu' 12679 Basque. 12680 12681`fa' 12682 Persian. 12683 12684`ff' 12685 Fulah. 12686 12687`fi' 12688 Finnish. 12689 12690`fj' 12691 Fijian; Fiji. 12692 12693`fo' 12694 Faroese. 12695 12696`fr' 12697 French. 12698 12699`fy' 12700 Western Frisian. 12701 12702`ga' 12703 Irish. 12704 12705`gd' 12706 Scots; Gaelic. 12707 12708`gl' 12709 Galician. 12710 12711`gn' 12712 Guarani. 12713 12714`gu' 12715 Gujarati. 12716 12717`gv' 12718 Manx. 12719 12720`ha' 12721 Hausa. 12722 12723`he' 12724 Hebrew (formerly iw). 12725 12726`hi' 12727 Hindi. 12728 12729`ho' 12730 Hiri Motu. 12731 12732`hr' 12733 Croatian. 12734 12735`ht' 12736 Haitian; Haitian Creole. 12737 12738`hu' 12739 Hungarian. 12740 12741`hy' 12742 Armenian. 12743 12744`hz' 12745 Herero. 12746 12747`ia' 12748 Interlingua. 12749 12750`id' 12751 Indonesian (formerly in). 12752 12753`ie' 12754 Interlingue. 12755 12756`ig' 12757 Igbo. 12758 12759`ii' 12760 Sichuan Yi. 12761 12762`ik' 12763 Inupiak; Inupiaq. 12764 12765`io' 12766 Ido. 12767 12768`is' 12769 Icelandic. 12770 12771`it' 12772 Italian. 12773 12774`iu' 12775 Inuktitut. 12776 12777`ja' 12778 Japanese. 12779 12780`jv' 12781 Javanese. 12782 12783`ka' 12784 Georgian. 12785 12786`kg' 12787 Kongo. 12788 12789`ki' 12790 Kikuyu; Gikuyu. 12791 12792`kj' 12793 Kuanyama; Kwanyama. 12794 12795`kk' 12796 Kazakh. 12797 12798`kl' 12799 Kalaallisut; Greenlandic. 12800 12801`km' 12802 Khmer; Cambodian. 12803 12804`kn' 12805 Kannada. 12806 12807`ko' 12808 Korean. 12809 12810`kr' 12811 Kanuri. 12812 12813`ks' 12814 Kashmiri. 12815 12816`ku' 12817 Kurdish. 12818 12819`kv' 12820 Komi. 12821 12822`kw' 12823 Cornish. 12824 12825`ky' 12826 Kirghiz. 12827 12828`la' 12829 Latin. 12830 12831`lb' 12832 Letzeburgesch; Luxembourgish. 12833 12834`lg' 12835 Ganda. 12836 12837`li' 12838 Limburgish; Limburger; Limburgan. 12839 12840`ln' 12841 Lingala. 12842 12843`lo' 12844 Lao; Laotian. 12845 12846`lt' 12847 Lithuanian. 12848 12849`lu' 12850 Luba-Katanga. 12851 12852`lv' 12853 Latvian; Lettish. 12854 12855`mg' 12856 Malagasy. 12857 12858`mh' 12859 Marshallese. 12860 12861`mi' 12862 Maori. 12863 12864`mk' 12865 Macedonian. 12866 12867`ml' 12868 Malayalam. 12869 12870`mn' 12871 Mongolian. 12872 12873`mo' 12874 Moldavian. 12875 12876`mr' 12877 Marathi. 12878 12879`ms' 12880 Malay. 12881 12882`mt' 12883 Maltese. 12884 12885`my' 12886 Burmese. 12887 12888`na' 12889 Nauru. 12890 12891`nb' 12892 Norwegian Bokmaal. 12893 12894`nd' 12895 Ndebele, North. 12896 12897`ne' 12898 Nepali. 12899 12900`ng' 12901 Ndonga. 12902 12903`nl' 12904 Dutch. 12905 12906`nn' 12907 Norwegian Nynorsk. 12908 12909`no' 12910 Norwegian. 12911 12912`nr' 12913 Ndebele, South. 12914 12915`nv' 12916 Navajo; Navaho. 12917 12918`ny' 12919 Chichewa; Nyanja. 12920 12921`oc' 12922 Occitan; Provenc,al. 12923 12924`oj' 12925 Ojibwa. 12926 12927`om' 12928 (Afan) Oromo. 12929 12930`or' 12931 Oriya. 12932 12933`os' 12934 Ossetian; Ossetic. 12935 12936`pa' 12937 Panjabi; Punjabi. 12938 12939`pi' 12940 Pali. 12941 12942`pl' 12943 Polish. 12944 12945`ps' 12946 Pashto, Pushto. 12947 12948`pt' 12949 Portuguese. 12950 12951`qu' 12952 Quechua. 12953 12954`rm' 12955 Rhaeto-Romance. 12956 12957`rn' 12958 Rundi; Kirundi. 12959 12960`ro' 12961 Romanian. 12962 12963`ru' 12964 Russian. 12965 12966`rw' 12967 Kinyarwanda. 12968 12969`sa' 12970 Sanskrit. 12971 12972`sc' 12973 Sardinian. 12974 12975`sd' 12976 Sindhi. 12977 12978`se' 12979 Northern Sami. 12980 12981`sg' 12982 Sango; Sangro. 12983 12984`si' 12985 Sinhala; Sinhalese. 12986 12987`sk' 12988 Slovak. 12989 12990`sl' 12991 Slovenian. 12992 12993`sm' 12994 Samoan. 12995 12996`sn' 12997 Shona. 12998 12999`so' 13000 Somali. 13001 13002`sq' 13003 Albanian. 13004 13005`sr' 13006 Serbian. 13007 13008`ss' 13009 Swati; Siswati. 13010 13011`st' 13012 Sesotho; Sotho, Southern. 13013 13014`su' 13015 Sundanese. 13016 13017`sv' 13018 Swedish. 13019 13020`sw' 13021 Swahili. 13022 13023`ta' 13024 Tamil. 13025 13026`te' 13027 Telugu. 13028 13029`tg' 13030 Tajik. 13031 13032`th' 13033 Thai. 13034 13035`ti' 13036 Tigrinya. 13037 13038`tk' 13039 Turkmen. 13040 13041`tl' 13042 Tagalog. 13043 13044`tn' 13045 Tswana; Setswana. 13046 13047`to' 13048 Tonga. 13049 13050`tr' 13051 Turkish. 13052 13053`ts' 13054 Tsonga. 13055 13056`tt' 13057 Tatar. 13058 13059`tw' 13060 Twi. 13061 13062`ty' 13063 Tahitian. 13064 13065`ug' 13066 Uighur. 13067 13068`uk' 13069 Ukrainian. 13070 13071`ur' 13072 Urdu. 13073 13074`uz' 13075 Uzbek. 13076 13077`ve' 13078 Venda. 13079 13080`vi' 13081 Vietnamese. 13082 13083`vo' 13084 Volapu"k; Volapuk. 13085 13086`wa' 13087 Walloon. 13088 13089`wo' 13090 Wolof. 13091 13092`xh' 13093 Xhosa. 13094 13095`yi' 13096 Yiddish (formerly ji). 13097 13098`yo' 13099 Yoruba. 13100 13101`za' 13102 Zhuang. 13103 13104`zh' 13105 Chinese. 13106 13107`zu' 13108 Zulu. 13109 13110 13111File: gettext.info, Node: Rare Language Codes, Prev: Usual Language Codes, Up: Language Codes 13112 13113A.2 Rare Language Codes 13114======================= 13115 13116For rarely used languages, the ISO 639-2 standard defines three-letter 13117codes. Here is the current list, reduced to only living languages with 13118at least one million of speakers. 13119 13120`ace' 13121 Achinese. 13122 13123`awa' 13124 Awadhi. 13125 13126`bad' 13127 Banda. 13128 13129`bal' 13130 Baluchi. 13131 13132`ban' 13133 Balinese. 13134 13135`bem' 13136 Bemba. 13137 13138`bho' 13139 Bhojpuri. 13140 13141`bik' 13142 Bikol. 13143 13144`bin' 13145 Bini. 13146 13147`btk' 13148 Batak (Indonesia). 13149 13150`bug' 13151 Buginese. 13152 13153`ceb' 13154 Cebuano. 13155 13156`din' 13157 Dinka. 13158 13159`doi' 13160 Dogri. 13161 13162`fil' 13163 Filipino; Pilipino. 13164 13165`fon' 13166 Fon. 13167 13168`gon' 13169 Gondi. 13170 13171`gsw' 13172 Alemani; Swiss German. 13173 13174`hil' 13175 Hiligaynon. 13176 13177`hmn' 13178 Hmong. 13179 13180`ilo' 13181 Iloko. 13182 13183`kab' 13184 Kabyle. 13185 13186`kam' 13187 Kamba. 13188 13189`kbd' 13190 Kabardian. 13191 13192`kmb' 13193 Kimbundu. 13194 13195`kok' 13196 Konkani. 13197 13198`kru' 13199 Kurukh. 13200 13201`lua' 13202 Luba-Lulua. 13203 13204`luo' 13205 Luo (Kenya and Tanzania). 13206 13207`mad' 13208 Madurese. 13209 13210`mag' 13211 Magahi. 13212 13213`mai' 13214 Maithili. 13215 13216`mak' 13217 Makasar. 13218 13219`man' 13220 Mandingo. 13221 13222`men' 13223 Mende. 13224 13225`min' 13226 Minangkabau. 13227 13228`mni' 13229 Manipuri. 13230 13231`mos' 13232 Mossi. 13233 13234`mwr' 13235 Marwari. 13236 13237`nap' 13238 Neapolitan. 13239 13240`nso' 13241 Pedi; Sepedi; Northern Sotho. 13242 13243`nym' 13244 Nyamwezi. 13245 13246`nyn' 13247 Nyankole. 13248 13249`pag' 13250 Pangasinan. 13251 13252`pam' 13253 Pampanga. 13254 13255`raj' 13256 Rajasthani. 13257 13258`sas' 13259 Sasak. 13260 13261`sat' 13262 Santali. 13263 13264`scn' 13265 Sicilian. 13266 13267`shn' 13268 Shan. 13269 13270`sid' 13271 Sidamo. 13272 13273`srr' 13274 Serer. 13275 13276`suk' 13277 Sukuma. 13278 13279`sus' 13280 Susu. 13281 13282`tem' 13283 Timne. 13284 13285`tiv' 13286 Tiv. 13287 13288`tum' 13289 Tumbuka. 13290 13291`umb' 13292 Umbundu. 13293 13294`wal' 13295 Walamo. 13296 13297`war' 13298 Waray. 13299 13300`yao' 13301 Yao. 13302 13303 13304File: gettext.info, Node: Country Codes, Next: Licenses, Prev: Language Codes, Up: Top 13305 13306Appendix B Country Codes 13307************************ 13308 13309The ISO 3166 standard defines two character codes for many countries 13310and territories. All abbreviations for countries used in the 13311Translation Project should come from this standard. 13312 13313`AD' 13314 Andorra. 13315 13316`AE' 13317 United Arab Emirates. 13318 13319`AF' 13320 Afghanistan. 13321 13322`AG' 13323 Antigua and Barbuda. 13324 13325`AI' 13326 Anguilla. 13327 13328`AL' 13329 Albania. 13330 13331`AM' 13332 Armenia. 13333 13334`AN' 13335 Netherlands Antilles. 13336 13337`AO' 13338 Angola. 13339 13340`AQ' 13341 Antarctica. 13342 13343`AR' 13344 Argentina. 13345 13346`AS' 13347 Samoa (American). 13348 13349`AT' 13350 Austria. 13351 13352`AU' 13353 Australia. 13354 13355`AW' 13356 Aruba. 13357 13358`AX' 13359 Aaland Islands. 13360 13361`AZ' 13362 Azerbaijan. 13363 13364`BA' 13365 Bosnia and Herzegovina. 13366 13367`BB' 13368 Barbados. 13369 13370`BD' 13371 Bangladesh. 13372 13373`BE' 13374 Belgium. 13375 13376`BF' 13377 Burkina Faso. 13378 13379`BG' 13380 Bulgaria. 13381 13382`BH' 13383 Bahrain. 13384 13385`BI' 13386 Burundi. 13387 13388`BJ' 13389 Benin. 13390 13391`BM' 13392 Bermuda. 13393 13394`BN' 13395 Brunei. 13396 13397`BO' 13398 Bolivia. 13399 13400`BR' 13401 Brazil. 13402 13403`BS' 13404 Bahamas. 13405 13406`BT' 13407 Bhutan. 13408 13409`BV' 13410 Bouvet Island. 13411 13412`BW' 13413 Botswana. 13414 13415`BY' 13416 Belarus. 13417 13418`BZ' 13419 Belize. 13420 13421`CA' 13422 Canada. 13423 13424`CC' 13425 Cocos (Keeling) Islands. 13426 13427`CD' 13428 Congo (Dem. Rep.). 13429 13430`CF' 13431 Central African Republic. 13432 13433`CG' 13434 Congo (Rep.). 13435 13436`CH' 13437 Switzerland. 13438 13439`CI' 13440 Co^te d'Ivoire. 13441 13442`CK' 13443 Cook Islands. 13444 13445`CL' 13446 Chile. 13447 13448`CM' 13449 Cameroon. 13450 13451`CN' 13452 China. 13453 13454`CO' 13455 Colombia. 13456 13457`CR' 13458 Costa Rica. 13459 13460`CU' 13461 Cuba. 13462 13463`CV' 13464 Cape Verde. 13465 13466`CX' 13467 Christmas Island. 13468 13469`CY' 13470 Cyprus. 13471 13472`CZ' 13473 Czech Republic. 13474 13475`DE' 13476 Germany. 13477 13478`DJ' 13479 Djibouti. 13480 13481`DK' 13482 Denmark. 13483 13484`DM' 13485 Dominica. 13486 13487`DO' 13488 Dominican Republic. 13489 13490`DZ' 13491 Algeria. 13492 13493`EC' 13494 Ecuador. 13495 13496`EE' 13497 Estonia. 13498 13499`EG' 13500 Egypt. 13501 13502`EH' 13503 Western Sahara. 13504 13505`ER' 13506 Eritrea. 13507 13508`ES' 13509 Spain. 13510 13511`ET' 13512 Ethiopia. 13513 13514`FI' 13515 Finland. 13516 13517`FJ' 13518 Fiji. 13519 13520`FK' 13521 Falkland Islands. 13522 13523`FM' 13524 Micronesia. 13525 13526`FO' 13527 Faeroe Islands. 13528 13529`FR' 13530 France. 13531 13532`GA' 13533 Gabon. 13534 13535`GB' 13536 Britain (United Kingdom). 13537 13538`GD' 13539 Grenada. 13540 13541`GE' 13542 Georgia. 13543 13544`GF' 13545 French Guiana. 13546 13547`GG' 13548 Guernsey. 13549 13550`GH' 13551 Ghana. 13552 13553`GI' 13554 Gibraltar. 13555 13556`GL' 13557 Greenland. 13558 13559`GM' 13560 Gambia. 13561 13562`GN' 13563 Guinea. 13564 13565`GP' 13566 Guadeloupe. 13567 13568`GQ' 13569 Equatorial Guinea. 13570 13571`GR' 13572 Greece. 13573 13574`GS' 13575 South Georgia and the South Sandwich Islands. 13576 13577`GT' 13578 Guatemala. 13579 13580`GU' 13581 Guam. 13582 13583`GW' 13584 Guinea-Bissau. 13585 13586`GY' 13587 Guyana. 13588 13589`HK' 13590 Hong Kong. 13591 13592`HM' 13593 Heard Island and McDonald Islands. 13594 13595`HN' 13596 Honduras. 13597 13598`HR' 13599 Croatia. 13600 13601`HT' 13602 Haiti. 13603 13604`HU' 13605 Hungary. 13606 13607`ID' 13608 Indonesia. 13609 13610`IE' 13611 Ireland. 13612 13613`IL' 13614 Israel. 13615 13616`IM' 13617 Isle of Man. 13618 13619`IN' 13620 India. 13621 13622`IO' 13623 British Indian Ocean Territory. 13624 13625`IQ' 13626 Iraq. 13627 13628`IR' 13629 Iran. 13630 13631`IS' 13632 Iceland. 13633 13634`IT' 13635 Italy. 13636 13637`JE' 13638 Jersey. 13639 13640`JM' 13641 Jamaica. 13642 13643`JO' 13644 Jordan. 13645 13646`JP' 13647 Japan. 13648 13649`KE' 13650 Kenya. 13651 13652`KG' 13653 Kyrgyzstan. 13654 13655`KH' 13656 Cambodia. 13657 13658`KI' 13659 Kiribati. 13660 13661`KM' 13662 Comoros. 13663 13664`KN' 13665 St Kitts and Nevis. 13666 13667`KP' 13668 Korea (North). 13669 13670`KR' 13671 Korea (South). 13672 13673`KW' 13674 Kuwait. 13675 13676`KY' 13677 Cayman Islands. 13678 13679`KZ' 13680 Kazakhstan. 13681 13682`LA' 13683 Laos. 13684 13685`LB' 13686 Lebanon. 13687 13688`LC' 13689 St Lucia. 13690 13691`LI' 13692 Liechtenstein. 13693 13694`LK' 13695 Sri Lanka. 13696 13697`LR' 13698 Liberia. 13699 13700`LS' 13701 Lesotho. 13702 13703`LT' 13704 Lithuania. 13705 13706`LU' 13707 Luxembourg. 13708 13709`LV' 13710 Latvia. 13711 13712`LY' 13713 Libya. 13714 13715`MA' 13716 Morocco. 13717 13718`MC' 13719 Monaco. 13720 13721`MD' 13722 Moldova. 13723 13724`ME' 13725 Montenegro. 13726 13727`MG' 13728 Madagascar. 13729 13730`MH' 13731 Marshall Islands. 13732 13733`MK' 13734 Macedonia. 13735 13736`ML' 13737 Mali. 13738 13739`MM' 13740 Myanmar (Burma). 13741 13742`MN' 13743 Mongolia. 13744 13745`MO' 13746 Macao. 13747 13748`MP' 13749 Northern Mariana Islands. 13750 13751`MQ' 13752 Martinique. 13753 13754`MR' 13755 Mauritania. 13756 13757`MS' 13758 Montserrat. 13759 13760`MT' 13761 Malta. 13762 13763`MU' 13764 Mauritius. 13765 13766`MV' 13767 Maldives. 13768 13769`MW' 13770 Malawi. 13771 13772`MX' 13773 Mexico. 13774 13775`MY' 13776 Malaysia. 13777 13778`MZ' 13779 Mozambique. 13780 13781`NA' 13782 Namibia. 13783 13784`NC' 13785 New Caledonia. 13786 13787`NE' 13788 Niger. 13789 13790`NF' 13791 Norfolk Island. 13792 13793`NG' 13794 Nigeria. 13795 13796`NI' 13797 Nicaragua. 13798 13799`NL' 13800 Netherlands. 13801 13802`NO' 13803 Norway. 13804 13805`NP' 13806 Nepal. 13807 13808`NR' 13809 Nauru. 13810 13811`NU' 13812 Niue. 13813 13814`NZ' 13815 New Zealand. 13816 13817`OM' 13818 Oman. 13819 13820`PA' 13821 Panama. 13822 13823`PE' 13824 Peru. 13825 13826`PF' 13827 French Polynesia. 13828 13829`PG' 13830 Papua New Guinea. 13831 13832`PH' 13833 Philippines. 13834 13835`PK' 13836 Pakistan. 13837 13838`PL' 13839 Poland. 13840 13841`PM' 13842 St Pierre and Miquelon. 13843 13844`PN' 13845 Pitcairn. 13846 13847`PR' 13848 Puerto Rico. 13849 13850`PS' 13851 Palestine. 13852 13853`PT' 13854 Portugal. 13855 13856`PW' 13857 Palau. 13858 13859`PY' 13860 Paraguay. 13861 13862`QA' 13863 Qatar. 13864 13865`RE' 13866 Reunion. 13867 13868`RO' 13869 Romania. 13870 13871`RS' 13872 Serbia. 13873 13874`RU' 13875 Russia. 13876 13877`RW' 13878 Rwanda. 13879 13880`SA' 13881 Saudi Arabia. 13882 13883`SB' 13884 Solomon Islands. 13885 13886`SC' 13887 Seychelles. 13888 13889`SD' 13890 Sudan. 13891 13892`SE' 13893 Sweden. 13894 13895`SG' 13896 Singapore. 13897 13898`SH' 13899 St Helena. 13900 13901`SI' 13902 Slovenia. 13903 13904`SJ' 13905 Svalbard and Jan Mayen. 13906 13907`SK' 13908 Slovakia. 13909 13910`SL' 13911 Sierra Leone. 13912 13913`SM' 13914 San Marino. 13915 13916`SN' 13917 Senegal. 13918 13919`SO' 13920 Somalia. 13921 13922`SR' 13923 Suriname. 13924 13925`ST' 13926 Sao Tome and Principe. 13927 13928`SV' 13929 El Salvador. 13930 13931`SY' 13932 Syria. 13933 13934`SZ' 13935 Swaziland. 13936 13937`TC' 13938 Turks and Caicos Islands. 13939 13940`TD' 13941 Chad. 13942 13943`TF' 13944 French Southern and Antarctic Lands. 13945 13946`TG' 13947 Togo. 13948 13949`TH' 13950 Thailand. 13951 13952`TJ' 13953 Tajikistan. 13954 13955`TK' 13956 Tokelau. 13957 13958`TL' 13959 Timor-Leste. 13960 13961`TM' 13962 Turkmenistan. 13963 13964`TN' 13965 Tunisia. 13966 13967`TO' 13968 Tonga. 13969 13970`TR' 13971 Turkey. 13972 13973`TT' 13974 Trinidad and Tobago. 13975 13976`TV' 13977 Tuvalu. 13978 13979`TW' 13980 Taiwan. 13981 13982`TZ' 13983 Tanzania. 13984 13985`UA' 13986 Ukraine. 13987 13988`UG' 13989 Uganda. 13990 13991`UM' 13992 US minor outlying islands. 13993 13994`US' 13995 United States. 13996 13997`UY' 13998 Uruguay. 13999 14000`UZ' 14001 Uzbekistan. 14002 14003`VA' 14004 Vatican City. 14005 14006`VC' 14007 St Vincent and the Grenadines. 14008 14009`VE' 14010 Venezuela. 14011 14012`VG' 14013 Virgin Islands (UK). 14014 14015`VI' 14016 Virgin Islands (US). 14017 14018`VN' 14019 Vietnam. 14020 14021`VU' 14022 Vanuatu. 14023 14024`WF' 14025 Wallis and Futuna. 14026 14027`WS' 14028 Samoa (Western). 14029 14030`YE' 14031 Yemen. 14032 14033`YT' 14034 Mayotte. 14035 14036`ZA' 14037 South Africa. 14038 14039`ZM' 14040 Zambia. 14041 14042`ZW' 14043 Zimbabwe. 14044 14045 14046File: gettext.info, Node: Licenses, Next: Program Index, Prev: Country Codes, Up: Top 14047 14048Appendix C Licenses 14049******************* 14050 14051The files of this package are covered by the licenses indicated in each 14052particular file or directory. Here is a summary: 14053 14054 * The `libintl' and `libasprintf' libraries are covered by the GNU 14055 Library General Public License (LGPL). A copy of the license is 14056 included in *Note GNU LGPL::. 14057 14058 * The executable programs of this package and the `libgettextpo' 14059 library are covered by the GNU General Public License (GPL). A 14060 copy of the license is included in *Note GNU GPL::. 14061 14062 * This manual is free documentation. It is dually licensed under the 14063 GNU FDL and the GNU GPL. This means that you can redistribute this 14064 manual under either of these two licenses, at your choice. 14065 This manual is covered by the GNU FDL. Permission is granted to 14066 copy, distribute and/or modify this document under the terms of the 14067 GNU Free Documentation License (FDL), either version 1.2 of the 14068 License, or (at your option) any later version published by the 14069 Free Software Foundation (FSF); with no Invariant Sections, with no 14070 Front-Cover Text, and with no Back-Cover Texts. A copy of the 14071 license is included in *Note GNU FDL::. 14072 This manual is covered by the GNU GPL. You can redistribute it 14073 and/or modify it under the terms of the GNU General Public License 14074 (GPL), either version 2 of the License, or (at your option) any 14075 later version published by the Free Software Foundation (FSF). A 14076 copy of the license is included in *Note GNU GPL::. 14077 14078* Menu: 14079 14080* GNU GPL:: GNU General Public License 14081* GNU LGPL:: GNU Lesser General Public License 14082* GNU FDL:: GNU Free Documentation License 14083 14084 14085File: gettext.info, Node: GNU GPL, Next: GNU LGPL, Up: Licenses 14086 14087C.1 GNU GENERAL PUBLIC LICENSE 14088============================== 14089 14090 Version 2, June 1991 14091 14092 Copyright (C) 1989, 1991 Free Software Foundation, Inc. 14093 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA 14094 14095 Everyone is permitted to copy and distribute verbatim copies 14096 of this license document, but changing it is not allowed. 14097 14098Preamble 14099-------- 14100 14101The licenses for most software are designed to take away your freedom 14102to share and change it. By contrast, the GNU General Public License is 14103intended to guarantee your freedom to share and change free 14104software--to make sure the software is free for all its users. This 14105General Public License applies to most of the Free Software 14106Foundation's software and to any other program whose authors commit to 14107using it. (Some other Free Software Foundation software is covered by 14108the GNU Library General Public License instead.) You can apply it to 14109your programs, too. 14110 14111 When we speak of free software, we are referring to freedom, not 14112price. Our General Public Licenses are designed to make sure that you 14113have the freedom to distribute copies of free software (and charge for 14114this service if you wish), that you receive source code or can get it 14115if you want it, that you can change the software or use pieces of it in 14116new free programs; and that you know you can do these things. 14117 14118 To protect your rights, we need to make restrictions that forbid 14119anyone to deny you these rights or to ask you to surrender the rights. 14120These restrictions translate to certain responsibilities for you if you 14121distribute copies of the software, or if you modify it. 14122 14123 For example, if you distribute copies of such a program, whether 14124gratis or for a fee, you must give the recipients all the rights that 14125you have. You must make sure that they, too, receive or can get the 14126source code. And you must show them these terms so they know their 14127rights. 14128 14129 We protect your rights with two steps: (1) copyright the software, 14130and (2) offer you this license which gives you legal permission to copy, 14131distribute and/or modify the software. 14132 14133 Also, for each author's protection and ours, we want to make certain 14134that everyone understands that there is no warranty for this free 14135software. If the software is modified by someone else and passed on, we 14136want its recipients to know that what they have is not the original, so 14137that any problems introduced by others will not reflect on the original 14138authors' reputations. 14139 14140 Finally, any free program is threatened constantly by software 14141patents. We wish to avoid the danger that redistributors of a free 14142program will individually obtain patent licenses, in effect making the 14143program proprietary. To prevent this, we have made it clear that any 14144patent must be licensed for everyone's free use or not licensed at all. 14145 14146 The precise terms and conditions for copying, distribution and 14147modification follow. 14148 14149 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 14150 14151 0. This License applies to any program or other work which contains a 14152 notice placed by the copyright holder saying it may be distributed 14153 under the terms of this General Public License. The "Program", 14154 below, refers to any such program or work, and a "work based on 14155 the Program" means either the Program or any derivative work under 14156 copyright law: that is to say, a work containing the Program or a 14157 portion of it, either verbatim or with modifications and/or 14158 translated into another language. (Hereinafter, translation is 14159 included without limitation in the term "modification".) Each 14160 licensee is addressed as "you". 14161 14162 Activities other than copying, distribution and modification are 14163 not covered by this License; they are outside its scope. The act 14164 of running the Program is not restricted, and the output from the 14165 Program is covered only if its contents constitute a work based on 14166 the Program (independent of having been made by running the 14167 Program). Whether that is true depends on what the Program does. 14168 14169 1. You may copy and distribute verbatim copies of the Program's 14170 source code as you receive it, in any medium, provided that you 14171 conspicuously and appropriately publish on each copy an appropriate 14172 copyright notice and disclaimer of warranty; keep intact all the 14173 notices that refer to this License and to the absence of any 14174 warranty; and give any other recipients of the Program a copy of 14175 this License along with the Program. 14176 14177 You may charge a fee for the physical act of transferring a copy, 14178 and you may at your option offer warranty protection in exchange 14179 for a fee. 14180 14181 2. You may modify your copy or copies of the Program or any portion 14182 of it, thus forming a work based on the Program, and copy and 14183 distribute such modifications or work under the terms of Section 1 14184 above, provided that you also meet all of these conditions: 14185 14186 a. You must cause the modified files to carry prominent notices 14187 stating that you changed the files and the date of any change. 14188 14189 b. You must cause any work that you distribute or publish, that 14190 in whole or in part contains or is derived from the Program 14191 or any part thereof, to be licensed as a whole at no charge 14192 to all third parties under the terms of this License. 14193 14194 c. If the modified program normally reads commands interactively 14195 when run, you must cause it, when started running for such 14196 interactive use in the most ordinary way, to print or display 14197 an announcement including an appropriate copyright notice and 14198 a notice that there is no warranty (or else, saying that you 14199 provide a warranty) and that users may redistribute the 14200 program under these conditions, and telling the user how to 14201 view a copy of this License. (Exception: if the Program 14202 itself is interactive but does not normally print such an 14203 announcement, your work based on the Program is not required 14204 to print an announcement.) 14205 14206 These requirements apply to the modified work as a whole. If 14207 identifiable sections of that work are not derived from the 14208 Program, and can be reasonably considered independent and separate 14209 works in themselves, then this License, and its terms, do not 14210 apply to those sections when you distribute them as separate 14211 works. But when you distribute the same sections as part of a 14212 whole which is a work based on the Program, the distribution of 14213 the whole must be on the terms of this License, whose permissions 14214 for other licensees extend to the entire whole, and thus to each 14215 and every part regardless of who wrote it. 14216 14217 Thus, it is not the intent of this section to claim rights or 14218 contest your rights to work written entirely by you; rather, the 14219 intent is to exercise the right to control the distribution of 14220 derivative or collective works based on the Program. 14221 14222 In addition, mere aggregation of another work not based on the 14223 Program with the Program (or with a work based on the Program) on 14224 a volume of a storage or distribution medium does not bring the 14225 other work under the scope of this License. 14226 14227 3. You may copy and distribute the Program (or a work based on it, 14228 under Section 2) in object code or executable form under the terms 14229 of Sections 1 and 2 above provided that you also do one of the 14230 following: 14231 14232 a. Accompany it with the complete corresponding machine-readable 14233 source code, which must be distributed under the terms of 14234 Sections 1 and 2 above on a medium customarily used for 14235 software interchange; or, 14236 14237 b. Accompany it with a written offer, valid for at least three 14238 years, to give any third party, for a charge no more than your 14239 cost of physically performing source distribution, a complete 14240 machine-readable copy of the corresponding source code, to be 14241 distributed under the terms of Sections 1 and 2 above on a 14242 medium customarily used for software interchange; or, 14243 14244 c. Accompany it with the information you received as to the offer 14245 to distribute corresponding source code. (This alternative is 14246 allowed only for noncommercial distribution and only if you 14247 received the program in object code or executable form with 14248 such an offer, in accord with Subsection b above.) 14249 14250 The source code for a work means the preferred form of the work for 14251 making modifications to it. For an executable work, complete 14252 source code means all the source code for all modules it contains, 14253 plus any associated interface definition files, plus the scripts 14254 used to control compilation and installation of the executable. 14255 However, as a special exception, the source code distributed need 14256 not include anything that is normally distributed (in either 14257 source or binary form) with the major components (compiler, 14258 kernel, and so on) of the operating system on which the executable 14259 runs, unless that component itself accompanies the executable. 14260 14261 If distribution of executable or object code is made by offering 14262 access to copy from a designated place, then offering equivalent 14263 access to copy the source code from the same place counts as 14264 distribution of the source code, even though third parties are not 14265 compelled to copy the source along with the object code. 14266 14267 4. You may not copy, modify, sublicense, or distribute the Program 14268 except as expressly provided under this License. Any attempt 14269 otherwise to copy, modify, sublicense or distribute the Program is 14270 void, and will automatically terminate your rights under this 14271 License. However, parties who have received copies, or rights, 14272 from you under this License will not have their licenses 14273 terminated so long as such parties remain in full compliance. 14274 14275 5. You are not required to accept this License, since you have not 14276 signed it. However, nothing else grants you permission to modify 14277 or distribute the Program or its derivative works. These actions 14278 are prohibited by law if you do not accept this License. 14279 Therefore, by modifying or distributing the Program (or any work 14280 based on the Program), you indicate your acceptance of this 14281 License to do so, and all its terms and conditions for copying, 14282 distributing or modifying the Program or works based on it. 14283 14284 6. Each time you redistribute the Program (or any work based on the 14285 Program), the recipient automatically receives a license from the 14286 original licensor to copy, distribute or modify the Program 14287 subject to these terms and conditions. You may not impose any 14288 further restrictions on the recipients' exercise of the rights 14289 granted herein. You are not responsible for enforcing compliance 14290 by third parties to this License. 14291 14292 7. If, as a consequence of a court judgment or allegation of patent 14293 infringement or for any other reason (not limited to patent 14294 issues), conditions are imposed on you (whether by court order, 14295 agreement or otherwise) that contradict the conditions of this 14296 License, they do not excuse you from the conditions of this 14297 License. If you cannot distribute so as to satisfy simultaneously 14298 your obligations under this License and any other pertinent 14299 obligations, then as a consequence you may not distribute the 14300 Program at all. For example, if a patent license would not permit 14301 royalty-free redistribution of the Program by all those who 14302 receive copies directly or indirectly through you, then the only 14303 way you could satisfy both it and this License would be to refrain 14304 entirely from distribution of the Program. 14305 14306 If any portion of this section is held invalid or unenforceable 14307 under any particular circumstance, the balance of the section is 14308 intended to apply and the section as a whole is intended to apply 14309 in other circumstances. 14310 14311 It is not the purpose of this section to induce you to infringe any 14312 patents or other property right claims or to contest validity of 14313 any such claims; this section has the sole purpose of protecting 14314 the integrity of the free software distribution system, which is 14315 implemented by public license practices. Many people have made 14316 generous contributions to the wide range of software distributed 14317 through that system in reliance on consistent application of that 14318 system; it is up to the author/donor to decide if he or she is 14319 willing to distribute software through any other system and a 14320 licensee cannot impose that choice. 14321 14322 This section is intended to make thoroughly clear what is believed 14323 to be a consequence of the rest of this License. 14324 14325 8. If the distribution and/or use of the Program is restricted in 14326 certain countries either by patents or by copyrighted interfaces, 14327 the original copyright holder who places the Program under this 14328 License may add an explicit geographical distribution limitation 14329 excluding those countries, so that distribution is permitted only 14330 in or among countries not thus excluded. In such case, this 14331 License incorporates the limitation as if written in the body of 14332 this License. 14333 14334 9. The Free Software Foundation may publish revised and/or new 14335 versions of the General Public License from time to time. Such 14336 new versions will be similar in spirit to the present version, but 14337 may differ in detail to address new problems or concerns. 14338 14339 Each version is given a distinguishing version number. If the 14340 Program specifies a version number of this License which applies 14341 to it and "any later version", you have the option of following 14342 the terms and conditions either of that version or of any later 14343 version published by the Free Software Foundation. If the Program 14344 does not specify a version number of this License, you may choose 14345 any version ever published by the Free Software Foundation. 14346 14347 10. If you wish to incorporate parts of the Program into other free 14348 programs whose distribution conditions are different, write to the 14349 author to ask for permission. For software which is copyrighted 14350 by the Free Software Foundation, write to the Free Software 14351 Foundation; we sometimes make exceptions for this. Our decision 14352 will be guided by the two goals of preserving the free status of 14353 all derivatives of our free software and of promoting the sharing 14354 and reuse of software generally. 14355 14356 NO WARRANTY 14357 14358 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO 14359 WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE 14360 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 14361 HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT 14362 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT 14363 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 14364 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE 14365 QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE 14366 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY 14367 SERVICING, REPAIR OR CORRECTION. 14368 14369 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 14370 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY 14371 MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE 14372 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, 14373 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR 14374 INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 14375 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU 14376 OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY 14377 OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN 14378 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 14379 14380 END OF TERMS AND CONDITIONS 14381 14382Appendix: How to Apply These Terms to Your New Programs 14383------------------------------------------------------- 14384 14385If you develop a new program, and you want it to be of the greatest 14386possible use to the public, the best way to achieve this is to make it 14387free software which everyone can redistribute and change under these 14388terms. 14389 14390 To do so, attach the following notices to the program. It is safest 14391to attach them to the start of each source file to most effectively 14392convey the exclusion of warranty; and each file should have at least 14393the "copyright" line and a pointer to where the full notice is found. 14394 14395 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. 14396 Copyright (C) YYYY NAME OF AUTHOR 14397 14398 This program is free software; you can redistribute it and/or modify 14399 it under the terms of the GNU General Public License as published by 14400 the Free Software Foundation; either version 2 of the License, or 14401 (at your option) any later version. 14402 14403 This program is distributed in the hope that it will be useful, 14404 but WITHOUT ANY WARRANTY; without even the implied warranty of 14405 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14406 GNU General Public License for more details. 14407 14408 You should have received a copy of the GNU General Public License 14409 along with this program; if not, write to the Free Software 14410 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 14411 14412 Also add information on how to contact you by electronic and paper 14413mail. 14414 14415 If the program is interactive, make it output a short notice like 14416this when it starts in an interactive mode: 14417 14418 Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR 14419 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 14420 This is free software, and you are welcome to redistribute it 14421 under certain conditions; type `show c' for details. 14422 14423 The hypothetical commands `show w' and `show c' should show the 14424appropriate parts of the General Public License. Of course, the 14425commands you use may be called something other than `show w' and `show 14426c'; they could even be mouse-clicks or menu items--whatever suits your 14427program. 14428 14429 You should also get your employer (if you work as a programmer) or 14430your school, if any, to sign a "copyright disclaimer" for the program, 14431if necessary. Here is a sample; alter the names: 14432 14433 Yoyodyne, Inc., hereby disclaims all copyright interest in the program 14434 `Gnomovision' (which makes passes at compilers) written by James Hacker. 14435 14436 SIGNATURE OF TY COON, 1 April 1989 14437 Ty Coon, President of Vice 14438 14439 This General Public License does not permit incorporating your 14440program into proprietary programs. If your program is a subroutine 14441library, you may consider it more useful to permit linking proprietary 14442applications with the library. If this is what you want to do, use the 14443GNU Library General Public License instead of this License. 14444 14445 14446File: gettext.info, Node: GNU LGPL, Next: GNU FDL, Prev: GNU GPL, Up: Licenses 14447 14448C.2 GNU LESSER GENERAL PUBLIC LICENSE 14449===================================== 14450 14451 Version 2.1, February 1999 14452 14453 Copyright (C) 1991, 1999 Free Software Foundation, Inc. 14454 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA 14455 14456 Everyone is permitted to copy and distribute verbatim copies 14457 of this license document, but changing it is not allowed. 14458 14459 [This is the first released version of the Lesser GPL. It also counts 14460 as the successor of the GNU Library Public License, version 2, hence the 14461 version number 2.1.] 14462 14463Preamble 14464-------- 14465 14466The licenses for most software are designed to take away your freedom 14467to share and change it. By contrast, the GNU General Public Licenses 14468are intended to guarantee your freedom to share and change free 14469software--to make sure the software is free for all its users. 14470 14471 This license, the Lesser General Public License, applies to some 14472specially designated software--typically libraries--of the Free 14473Software Foundation and other authors who decide to use it. You can use 14474it too, but we suggest you first think carefully about whether this 14475license or the ordinary General Public License is the better strategy to 14476use in any particular case, based on the explanations below. 14477 14478 When we speak of free software, we are referring to freedom of use, 14479not price. Our General Public Licenses are designed to make sure that 14480you have the freedom to distribute copies of free software (and charge 14481for this service if you wish); that you receive source code or can get 14482it if you want it; that you can change the software and use pieces of it 14483in new free programs; and that you are informed that you can do these 14484things. 14485 14486 To protect your rights, we need to make restrictions that forbid 14487distributors to deny you these rights or to ask you to surrender these 14488rights. These restrictions translate to certain responsibilities for 14489you if you distribute copies of the library or if you modify it. 14490 14491 For example, if you distribute copies of the library, whether gratis 14492or for a fee, you must give the recipients all the rights that we gave 14493you. You must make sure that they, too, receive or can get the source 14494code. If you link other code with the library, you must provide 14495complete object files to the recipients, so that they can relink them 14496with the library after making changes to the library and recompiling 14497it. And you must show them these terms so they know their rights. 14498 14499 We protect your rights with a two-step method: (1) we copyright the 14500library, and (2) we offer you this license, which gives you legal 14501permission to copy, distribute and/or modify the library. 14502 14503 To protect each distributor, we want to make it very clear that 14504there is no warranty for the free library. Also, if the library is 14505modified by someone else and passed on, the recipients should know that 14506what they have is not the original version, so that the original 14507author's reputation will not be affected by problems that might be 14508introduced by others. 14509 14510 Finally, software patents pose a constant threat to the existence of 14511any free program. We wish to make sure that a company cannot 14512effectively restrict the users of a free program by obtaining a 14513restrictive license from a patent holder. Therefore, we insist that 14514any patent license obtained for a version of the library must be 14515consistent with the full freedom of use specified in this license. 14516 14517 Most GNU software, including some libraries, is covered by the 14518ordinary GNU General Public License. This license, the GNU Lesser 14519General Public License, applies to certain designated libraries, and is 14520quite different from the ordinary General Public License. We use this 14521license for certain libraries in order to permit linking those 14522libraries into non-free programs. 14523 14524 When a program is linked with a library, whether statically or using 14525a shared library, the combination of the two is legally speaking a 14526combined work, a derivative of the original library. The ordinary 14527General Public License therefore permits such linking only if the 14528entire combination fits its criteria of freedom. The Lesser General 14529Public License permits more lax criteria for linking other code with 14530the library. 14531 14532 We call this license the "Lesser" General Public License because it 14533does _Less_ to protect the user's freedom than the ordinary General 14534Public License. It also provides other free software developers Less 14535of an advantage over competing non-free programs. These disadvantages 14536are the reason we use the ordinary General Public License for many 14537libraries. However, the Lesser license provides advantages in certain 14538special circumstances. 14539 14540 For example, on rare occasions, there may be a special need to 14541encourage the widest possible use of a certain library, so that it 14542becomes a de-facto standard. To achieve this, non-free programs must be 14543allowed to use the library. A more frequent case is that a free 14544library does the same job as widely used non-free libraries. In this 14545case, there is little to gain by limiting the free library to free 14546software only, so we use the Lesser General Public License. 14547 14548 In other cases, permission to use a particular library in non-free 14549programs enables a greater number of people to use a large body of free 14550software. For example, permission to use the GNU C Library in non-free 14551programs enables many more people to use the whole GNU operating 14552system, as well as its variant, the GNU/Linux operating system. 14553 14554 Although the Lesser General Public License is Less protective of the 14555users' freedom, it does ensure that the user of a program that is 14556linked with the Library has the freedom and the wherewithal to run that 14557program using a modified version of the Library. 14558 14559 The precise terms and conditions for copying, distribution and 14560modification follow. Pay close attention to the difference between a 14561"work based on the library" and a "work that uses the library". The 14562former contains code derived from the library, whereas the latter must 14563be combined with the library in order to run. 14564 14565 GNU LESSER GENERAL PUBLIC LICENSE 14566 14567 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 14568 14569 0. This License Agreement applies to any software library or other 14570 program which contains a notice placed by the copyright holder or 14571 other authorized party saying it may be distributed under the 14572 terms of this Lesser General Public License (also called "this 14573 License"). Each licensee is addressed as "you". 14574 14575 A "library" means a collection of software functions and/or data 14576 prepared so as to be conveniently linked with application programs 14577 (which use some of those functions and data) to form executables. 14578 14579 The "Library", below, refers to any such software library or work 14580 which has been distributed under these terms. A "work based on the 14581 Library" means either the Library or any derivative work under 14582 copyright law: that is to say, a work containing the Library or a 14583 portion of it, either verbatim or with modifications and/or 14584 translated straightforwardly into another language. (Hereinafter, 14585 translation is included without limitation in the term 14586 "modification".) 14587 14588 "Source code" for a work means the preferred form of the work for 14589 making modifications to it. For a library, complete source code 14590 means all the source code for all modules it contains, plus any 14591 associated interface definition files, plus the scripts used to 14592 control compilation and installation of the library. 14593 14594 Activities other than copying, distribution and modification are 14595 not covered by this License; they are outside its scope. The act 14596 of running a program using the Library is not restricted, and 14597 output from such a program is covered only if its contents 14598 constitute a work based on the Library (independent of the use of 14599 the Library in a tool for writing it). Whether that is true 14600 depends on what the Library does and what the program that uses 14601 the Library does. 14602 14603 1. You may copy and distribute verbatim copies of the Library's 14604 complete source code as you receive it, in any medium, provided 14605 that you conspicuously and appropriately publish on each copy an 14606 appropriate copyright notice and disclaimer of warranty; keep 14607 intact all the notices that refer to this License and to the 14608 absence of any warranty; and distribute a copy of this License 14609 along with the Library. 14610 14611 You may charge a fee for the physical act of transferring a copy, 14612 and you may at your option offer warranty protection in exchange 14613 for a fee. 14614 14615 2. You may modify your copy or copies of the Library or any portion 14616 of it, thus forming a work based on the Library, and copy and 14617 distribute such modifications or work under the terms of Section 1 14618 above, provided that you also meet all of these conditions: 14619 14620 a. The modified work must itself be a software library. 14621 14622 b. You must cause the files modified to carry prominent notices 14623 stating that you changed the files and the date of any change. 14624 14625 c. You must cause the whole of the work to be licensed at no 14626 charge to all third parties under the terms of this License. 14627 14628 d. If a facility in the modified Library refers to a function or 14629 a table of data to be supplied by an application program that 14630 uses the facility, other than as an argument passed when the 14631 facility is invoked, then you must make a good faith effort 14632 to ensure that, in the event an application does not supply 14633 such function or table, the facility still operates, and 14634 performs whatever part of its purpose remains meaningful. 14635 14636 (For example, a function in a library to compute square roots 14637 has a purpose that is entirely well-defined independent of the 14638 application. Therefore, Subsection 2d requires that any 14639 application-supplied function or table used by this function 14640 must be optional: if the application does not supply it, the 14641 square root function must still compute square roots.) 14642 14643 These requirements apply to the modified work as a whole. If 14644 identifiable sections of that work are not derived from the 14645 Library, and can be reasonably considered independent and separate 14646 works in themselves, then this License, and its terms, do not 14647 apply to those sections when you distribute them as separate 14648 works. But when you distribute the same sections as part of a 14649 whole which is a work based on the Library, the distribution of 14650 the whole must be on the terms of this License, whose permissions 14651 for other licensees extend to the entire whole, and thus to each 14652 and every part regardless of who wrote it. 14653 14654 Thus, it is not the intent of this section to claim rights or 14655 contest your rights to work written entirely by you; rather, the 14656 intent is to exercise the right to control the distribution of 14657 derivative or collective works based on the Library. 14658 14659 In addition, mere aggregation of another work not based on the 14660 Library with the Library (or with a work based on the Library) on 14661 a volume of a storage or distribution medium does not bring the 14662 other work under the scope of this License. 14663 14664 3. You may opt to apply the terms of the ordinary GNU General Public 14665 License instead of this License to a given copy of the Library. 14666 To do this, you must alter all the notices that refer to this 14667 License, so that they refer to the ordinary GNU General Public 14668 License, version 2, instead of to this License. (If a newer 14669 version than version 2 of the ordinary GNU General Public License 14670 has appeared, then you can specify that version instead if you 14671 wish.) Do not make any other change in these notices. 14672 14673 Once this change is made in a given copy, it is irreversible for 14674 that copy, so the ordinary GNU General Public License applies to 14675 all subsequent copies and derivative works made from that copy. 14676 14677 This option is useful when you wish to copy part of the code of 14678 the Library into a program that is not a library. 14679 14680 4. You may copy and distribute the Library (or a portion or 14681 derivative of it, under Section 2) in object code or executable 14682 form under the terms of Sections 1 and 2 above provided that you 14683 accompany it with the complete corresponding machine-readable 14684 source code, which must be distributed under the terms of Sections 14685 1 and 2 above on a medium customarily used for software 14686 interchange. 14687 14688 If distribution of object code is made by offering access to copy 14689 from a designated place, then offering equivalent access to copy 14690 the source code from the same place satisfies the requirement to 14691 distribute the source code, even though third parties are not 14692 compelled to copy the source along with the object code. 14693 14694 5. A program that contains no derivative of any portion of the 14695 Library, but is designed to work with the Library by being 14696 compiled or linked with it, is called a "work that uses the 14697 Library". Such a work, in isolation, is not a derivative work of 14698 the Library, and therefore falls outside the scope of this License. 14699 14700 However, linking a "work that uses the Library" with the Library 14701 creates an executable that is a derivative of the Library (because 14702 it contains portions of the Library), rather than a "work that 14703 uses the library". The executable is therefore covered by this 14704 License. Section 6 states terms for distribution of such 14705 executables. 14706 14707 When a "work that uses the Library" uses material from a header 14708 file that is part of the Library, the object code for the work may 14709 be a derivative work of the Library even though the source code is 14710 not. Whether this is true is especially significant if the work 14711 can be linked without the Library, or if the work is itself a 14712 library. The threshold for this to be true is not precisely 14713 defined by law. 14714 14715 If such an object file uses only numerical parameters, data 14716 structure layouts and accessors, and small macros and small inline 14717 functions (ten lines or less in length), then the use of the object 14718 file is unrestricted, regardless of whether it is legally a 14719 derivative work. (Executables containing this object code plus 14720 portions of the Library will still fall under Section 6.) 14721 14722 Otherwise, if the work is a derivative of the Library, you may 14723 distribute the object code for the work under the terms of Section 14724 6. Any executables containing that work also fall under Section 6, 14725 whether or not they are linked directly with the Library itself. 14726 14727 6. As an exception to the Sections above, you may also combine or 14728 link a "work that uses the Library" with the Library to produce a 14729 work containing portions of the Library, and distribute that work 14730 under terms of your choice, provided that the terms permit 14731 modification of the work for the customer's own use and reverse 14732 engineering for debugging such modifications. 14733 14734 You must give prominent notice with each copy of the work that the 14735 Library is used in it and that the Library and its use are covered 14736 by this License. You must supply a copy of this License. If the 14737 work during execution displays copyright notices, you must include 14738 the copyright notice for the Library among them, as well as a 14739 reference directing the user to the copy of this License. Also, 14740 you must do one of these things: 14741 14742 a. Accompany the work with the complete corresponding 14743 machine-readable source code for the Library including 14744 whatever changes were used in the work (which must be 14745 distributed under Sections 1 and 2 above); and, if the work 14746 is an executable linked with the Library, with the complete 14747 machine-readable "work that uses the Library", as object code 14748 and/or source code, so that the user can modify the Library 14749 and then relink to produce a modified executable containing 14750 the modified Library. (It is understood that the user who 14751 changes the contents of definitions files in the Library will 14752 not necessarily be able to recompile the application to use 14753 the modified definitions.) 14754 14755 b. Use a suitable shared library mechanism for linking with the 14756 Library. A suitable mechanism is one that (1) uses at run 14757 time a copy of the library already present on the user's 14758 computer system, rather than copying library functions into 14759 the executable, and (2) will operate properly with a modified 14760 version of the library, if the user installs one, as long as 14761 the modified version is interface-compatible with the version 14762 that the work was made with. 14763 14764 c. Accompany the work with a written offer, valid for at least 14765 three years, to give the same user the materials specified in 14766 Subsection 6a, above, for a charge no more than the cost of 14767 performing this distribution. 14768 14769 d. If distribution of the work is made by offering access to copy 14770 from a designated place, offer equivalent access to copy the 14771 above specified materials from the same place. 14772 14773 e. Verify that the user has already received a copy of these 14774 materials or that you have already sent this user a copy. 14775 14776 For an executable, the required form of the "work that uses the 14777 Library" must include any data and utility programs needed for 14778 reproducing the executable from it. However, as a special 14779 exception, the materials to be distributed need not include 14780 anything that is normally distributed (in either source or binary 14781 form) with the major components (compiler, kernel, and so on) of 14782 the operating system on which the executable runs, unless that 14783 component itself accompanies the executable. 14784 14785 It may happen that this requirement contradicts the license 14786 restrictions of other proprietary libraries that do not normally 14787 accompany the operating system. Such a contradiction means you 14788 cannot use both them and the Library together in an executable 14789 that you distribute. 14790 14791 7. You may place library facilities that are a work based on the 14792 Library side-by-side in a single library together with other 14793 library facilities not covered by this License, and distribute 14794 such a combined library, provided that the separate distribution 14795 of the work based on the Library and of the other library 14796 facilities is otherwise permitted, and provided that you do these 14797 two things: 14798 14799 a. Accompany the combined library with a copy of the same work 14800 based on the Library, uncombined with any other library 14801 facilities. This must be distributed under the terms of the 14802 Sections above. 14803 14804 b. Give prominent notice with the combined library of the fact 14805 that part of it is a work based on the Library, and explaining 14806 where to find the accompanying uncombined form of the same 14807 work. 14808 14809 8. You may not copy, modify, sublicense, link with, or distribute the 14810 Library except as expressly provided under this License. Any 14811 attempt otherwise to copy, modify, sublicense, link with, or 14812 distribute the Library is void, and will automatically terminate 14813 your rights under this License. However, parties who have 14814 received copies, or rights, from you under this License will not 14815 have their licenses terminated so long as such parties remain in 14816 full compliance. 14817 14818 9. You are not required to accept this License, since you have not 14819 signed it. However, nothing else grants you permission to modify 14820 or distribute the Library or its derivative works. These actions 14821 are prohibited by law if you do not accept this License. 14822 Therefore, by modifying or distributing the Library (or any work 14823 based on the Library), you indicate your acceptance of this 14824 License to do so, and all its terms and conditions for copying, 14825 distributing or modifying the Library or works based on it. 14826 14827 10. Each time you redistribute the Library (or any work based on the 14828 Library), the recipient automatically receives a license from the 14829 original licensor to copy, distribute, link with or modify the 14830 Library subject to these terms and conditions. You may not impose 14831 any further restrictions on the recipients' exercise of the rights 14832 granted herein. You are not responsible for enforcing compliance 14833 by third parties with this License. 14834 14835 11. If, as a consequence of a court judgment or allegation of patent 14836 infringement or for any other reason (not limited to patent 14837 issues), conditions are imposed on you (whether by court order, 14838 agreement or otherwise) that contradict the conditions of this 14839 License, they do not excuse you from the conditions of this 14840 License. If you cannot distribute so as to satisfy simultaneously 14841 your obligations under this License and any other pertinent 14842 obligations, then as a consequence you may not distribute the 14843 Library at all. For example, if a patent license would not permit 14844 royalty-free redistribution of the Library by all those who 14845 receive copies directly or indirectly through you, then the only 14846 way you could satisfy both it and this License would be to refrain 14847 entirely from distribution of the Library. 14848 14849 If any portion of this section is held invalid or unenforceable 14850 under any particular circumstance, the balance of the section is 14851 intended to apply, and the section as a whole is intended to apply 14852 in other circumstances. 14853 14854 It is not the purpose of this section to induce you to infringe any 14855 patents or other property right claims or to contest validity of 14856 any such claims; this section has the sole purpose of protecting 14857 the integrity of the free software distribution system which is 14858 implemented by public license practices. Many people have made 14859 generous contributions to the wide range of software distributed 14860 through that system in reliance on consistent application of that 14861 system; it is up to the author/donor to decide if he or she is 14862 willing to distribute software through any other system and a 14863 licensee cannot impose that choice. 14864 14865 This section is intended to make thoroughly clear what is believed 14866 to be a consequence of the rest of this License. 14867 14868 12. If the distribution and/or use of the Library is restricted in 14869 certain countries either by patents or by copyrighted interfaces, 14870 the original copyright holder who places the Library under this 14871 License may add an explicit geographical distribution limitation 14872 excluding those countries, so that distribution is permitted only 14873 in or among countries not thus excluded. In such case, this 14874 License incorporates the limitation as if written in the body of 14875 this License. 14876 14877 13. The Free Software Foundation may publish revised and/or new 14878 versions of the Lesser General Public License from time to time. 14879 Such new versions will be similar in spirit to the present version, 14880 but may differ in detail to address new problems or concerns. 14881 14882 Each version is given a distinguishing version number. If the 14883 Library specifies a version number of this License which applies 14884 to it and "any later version", you have the option of following 14885 the terms and conditions either of that version or of any later 14886 version published by the Free Software Foundation. If the Library 14887 does not specify a license version number, you may choose any 14888 version ever published by the Free Software Foundation. 14889 14890 14. If you wish to incorporate parts of the Library into other free 14891 programs whose distribution conditions are incompatible with these, 14892 write to the author to ask for permission. For software which is 14893 copyrighted by the Free Software Foundation, write to the Free 14894 Software Foundation; we sometimes make exceptions for this. Our 14895 decision will be guided by the two goals of preserving the free 14896 status of all derivatives of our free software and of promoting 14897 the sharing and reuse of software generally. 14898 14899 NO WARRANTY 14900 14901 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO 14902 WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE 14903 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 14904 HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT 14905 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT 14906 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 14907 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE 14908 QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE 14909 LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY 14910 SERVICING, REPAIR OR CORRECTION. 14911 14912 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 14913 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY 14914 MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE 14915 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, 14916 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR 14917 INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF 14918 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU 14919 OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY 14920 OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN 14921 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 14922 14923 END OF TERMS AND CONDITIONS 14924 14925How to Apply These Terms to Your New Libraries 14926---------------------------------------------- 14927 14928If you develop a new library, and you want it to be of the greatest 14929possible use to the public, we recommend making it free software that 14930everyone can redistribute and change. You can do so by permitting 14931redistribution under these terms (or, alternatively, under the terms of 14932the ordinary General Public License). 14933 14934 To apply these terms, attach the following notices to the library. 14935It is safest to attach them to the start of each source file to most 14936effectively convey the exclusion of warranty; and each file should have 14937at least the "copyright" line and a pointer to where the full notice is 14938found. 14939 14940 ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES. 14941 Copyright (C) YEAR NAME OF AUTHOR 14942 14943 This library is free software; you can redistribute it and/or modify it 14944 under the terms of the GNU Lesser General Public License as published by 14945 the Free Software Foundation; either version 2.1 of the License, or (at 14946 your option) any later version. 14947 14948 This library is distributed in the hope that it will be useful, but 14949 WITHOUT ANY WARRANTY; without even the implied warranty of 14950 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14951 Lesser General Public License for more details. 14952 14953 You should have received a copy of the GNU Lesser General Public 14954 License along with this library; if not, write to the Free Software 14955 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 14956 USA. 14957 14958 Also add information on how to contact you by electronic and paper 14959mail. 14960 14961 You should also get your employer (if you work as a programmer) or 14962your school, if any, to sign a "copyright disclaimer" for the library, 14963if necessary. Here is a sample; alter the names: 14964 14965 Yoyodyne, Inc., hereby disclaims all copyright interest in the library 14966 `Frob' (a library for tweaking knobs) written by James Random Hacker. 14967 14968 SIGNATURE OF TY COON, 1 April 1990 14969 Ty Coon, President of Vice 14970 14971 That's all there is to it! 14972 14973 14974File: gettext.info, Node: GNU FDL, Prev: GNU LGPL, Up: Licenses 14975 14976C.3 GNU Free Documentation License 14977================================== 14978 14979 Version 1.2, November 2002 14980 14981 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 14982 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA 14983 14984 Everyone is permitted to copy and distribute verbatim copies 14985 of this license document, but changing it is not allowed. 14986 14987 0. PREAMBLE 14988 14989 The purpose of this License is to make a manual, textbook, or other 14990 functional and useful document "free" in the sense of freedom: to 14991 assure everyone the effective freedom to copy and redistribute it, 14992 with or without modifying it, either commercially or 14993 noncommercially. Secondarily, this License preserves for the 14994 author and publisher a way to get credit for their work, while not 14995 being considered responsible for modifications made by others. 14996 14997 This License is a kind of "copyleft", which means that derivative 14998 works of the document must themselves be free in the same sense. 14999 It complements the GNU General Public License, which is a copyleft 15000 license designed for free software. 15001 15002 We have designed this License in order to use it for manuals for 15003 free software, because free software needs free documentation: a 15004 free program should come with manuals providing the same freedoms 15005 that the software does. But this License is not limited to 15006 software manuals; it can be used for any textual work, regardless 15007 of subject matter or whether it is published as a printed book. 15008 We recommend this License principally for works whose purpose is 15009 instruction or reference. 15010 15011 1. APPLICABILITY AND DEFINITIONS 15012 15013 This License applies to any manual or other work, in any medium, 15014 that contains a notice placed by the copyright holder saying it 15015 can be distributed under the terms of this License. Such a notice 15016 grants a world-wide, royalty-free license, unlimited in duration, 15017 to use that work under the conditions stated herein. The 15018 "Document", below, refers to any such manual or work. Any member 15019 of the public is a licensee, and is addressed as "you". You 15020 accept the license if you copy, modify or distribute the work in a 15021 way requiring permission under copyright law. 15022 15023 A "Modified Version" of the Document means any work containing the 15024 Document or a portion of it, either copied verbatim, or with 15025 modifications and/or translated into another language. 15026 15027 A "Secondary Section" is a named appendix or a front-matter section 15028 of the Document that deals exclusively with the relationship of the 15029 publishers or authors of the Document to the Document's overall 15030 subject (or to related matters) and contains nothing that could 15031 fall directly within that overall subject. (Thus, if the Document 15032 is in part a textbook of mathematics, a Secondary Section may not 15033 explain any mathematics.) The relationship could be a matter of 15034 historical connection with the subject or with related matters, or 15035 of legal, commercial, philosophical, ethical or political position 15036 regarding them. 15037 15038 The "Invariant Sections" are certain Secondary Sections whose 15039 titles are designated, as being those of Invariant Sections, in 15040 the notice that says that the Document is released under this 15041 License. If a section does not fit the above definition of 15042 Secondary then it is not allowed to be designated as Invariant. 15043 The Document may contain zero Invariant Sections. If the Document 15044 does not identify any Invariant Sections then there are none. 15045 15046 The "Cover Texts" are certain short passages of text that are 15047 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 15048 that says that the Document is released under this License. A 15049 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 15050 be at most 25 words. 15051 15052 A "Transparent" copy of the Document means a machine-readable copy, 15053 represented in a format whose specification is available to the 15054 general public, that is suitable for revising the document 15055 straightforwardly with generic text editors or (for images 15056 composed of pixels) generic paint programs or (for drawings) some 15057 widely available drawing editor, and that is suitable for input to 15058 text formatters or for automatic translation to a variety of 15059 formats suitable for input to text formatters. A copy made in an 15060 otherwise Transparent file format whose markup, or absence of 15061 markup, has been arranged to thwart or discourage subsequent 15062 modification by readers is not Transparent. An image format is 15063 not Transparent if used for any substantial amount of text. A 15064 copy that is not "Transparent" is called "Opaque". 15065 15066 Examples of suitable formats for Transparent copies include plain 15067 ASCII without markup, Texinfo input format, LaTeX input format, 15068 SGML or XML using a publicly available DTD, and 15069 standard-conforming simple HTML, PostScript or PDF designed for 15070 human modification. Examples of transparent image formats include 15071 PNG, XCF and JPG. Opaque formats include proprietary formats that 15072 can be read and edited only by proprietary word processors, SGML or 15073 XML for which the DTD and/or processing tools are not generally 15074 available, and the machine-generated HTML, PostScript or PDF 15075 produced by some word processors for output purposes only. 15076 15077 The "Title Page" means, for a printed book, the title page itself, 15078 plus such following pages as are needed to hold, legibly, the 15079 material this License requires to appear in the title page. For 15080 works in formats which do not have any title page as such, "Title 15081 Page" means the text near the most prominent appearance of the 15082 work's title, preceding the beginning of the body of the text. 15083 15084 A section "Entitled XYZ" means a named subunit of the Document 15085 whose title either is precisely XYZ or contains XYZ in parentheses 15086 following text that translates XYZ in another language. (Here XYZ 15087 stands for a specific section name mentioned below, such as 15088 "Acknowledgements", "Dedications", "Endorsements", or "History".) 15089 To "Preserve the Title" of such a section when you modify the 15090 Document means that it remains a section "Entitled XYZ" according 15091 to this definition. 15092 15093 The Document may include Warranty Disclaimers next to the notice 15094 which states that this License applies to the Document. These 15095 Warranty Disclaimers are considered to be included by reference in 15096 this License, but only as regards disclaiming warranties: any other 15097 implication that these Warranty Disclaimers may have is void and 15098 has no effect on the meaning of this License. 15099 15100 2. VERBATIM COPYING 15101 15102 You may copy and distribute the Document in any medium, either 15103 commercially or noncommercially, provided that this License, the 15104 copyright notices, and the license notice saying this License 15105 applies to the Document are reproduced in all copies, and that you 15106 add no other conditions whatsoever to those of this License. You 15107 may not use technical measures to obstruct or control the reading 15108 or further copying of the copies you make or distribute. However, 15109 you may accept compensation in exchange for copies. If you 15110 distribute a large enough number of copies you must also follow 15111 the conditions in section 3. 15112 15113 You may also lend copies, under the same conditions stated above, 15114 and you may publicly display copies. 15115 15116 3. COPYING IN QUANTITY 15117 15118 If you publish printed copies (or copies in media that commonly 15119 have printed covers) of the Document, numbering more than 100, and 15120 the Document's license notice requires Cover Texts, you must 15121 enclose the copies in covers that carry, clearly and legibly, all 15122 these Cover Texts: Front-Cover Texts on the front cover, and 15123 Back-Cover Texts on the back cover. Both covers must also clearly 15124 and legibly identify you as the publisher of these copies. The 15125 front cover must present the full title with all words of the 15126 title equally prominent and visible. You may add other material 15127 on the covers in addition. Copying with changes limited to the 15128 covers, as long as they preserve the title of the Document and 15129 satisfy these conditions, can be treated as verbatim copying in 15130 other respects. 15131 15132 If the required texts for either cover are too voluminous to fit 15133 legibly, you should put the first ones listed (as many as fit 15134 reasonably) on the actual cover, and continue the rest onto 15135 adjacent pages. 15136 15137 If you publish or distribute Opaque copies of the Document 15138 numbering more than 100, you must either include a 15139 machine-readable Transparent copy along with each Opaque copy, or 15140 state in or with each Opaque copy a computer-network location from 15141 which the general network-using public has access to download 15142 using public-standard network protocols a complete Transparent 15143 copy of the Document, free of added material. If you use the 15144 latter option, you must take reasonably prudent steps, when you 15145 begin distribution of Opaque copies in quantity, to ensure that 15146 this Transparent copy will remain thus accessible at the stated 15147 location until at least one year after the last time you 15148 distribute an Opaque copy (directly or through your agents or 15149 retailers) of that edition to the public. 15150 15151 It is requested, but not required, that you contact the authors of 15152 the Document well before redistributing any large number of 15153 copies, to give them a chance to provide you with an updated 15154 version of the Document. 15155 15156 4. MODIFICATIONS 15157 15158 You may copy and distribute a Modified Version of the Document 15159 under the conditions of sections 2 and 3 above, provided that you 15160 release the Modified Version under precisely this License, with 15161 the Modified Version filling the role of the Document, thus 15162 licensing distribution and modification of the Modified Version to 15163 whoever possesses a copy of it. In addition, you must do these 15164 things in the Modified Version: 15165 15166 A. Use in the Title Page (and on the covers, if any) a title 15167 distinct from that of the Document, and from those of 15168 previous versions (which should, if there were any, be listed 15169 in the History section of the Document). You may use the 15170 same title as a previous version if the original publisher of 15171 that version gives permission. 15172 15173 B. List on the Title Page, as authors, one or more persons or 15174 entities responsible for authorship of the modifications in 15175 the Modified Version, together with at least five of the 15176 principal authors of the Document (all of its principal 15177 authors, if it has fewer than five), unless they release you 15178 from this requirement. 15179 15180 C. State on the Title page the name of the publisher of the 15181 Modified Version, as the publisher. 15182 15183 D. Preserve all the copyright notices of the Document. 15184 15185 E. Add an appropriate copyright notice for your modifications 15186 adjacent to the other copyright notices. 15187 15188 F. Include, immediately after the copyright notices, a license 15189 notice giving the public permission to use the Modified 15190 Version under the terms of this License, in the form shown in 15191 the Addendum below. 15192 15193 G. Preserve in that license notice the full lists of Invariant 15194 Sections and required Cover Texts given in the Document's 15195 license notice. 15196 15197 H. Include an unaltered copy of this License. 15198 15199 I. Preserve the section Entitled "History", Preserve its Title, 15200 and add to it an item stating at least the title, year, new 15201 authors, and publisher of the Modified Version as given on 15202 the Title Page. If there is no section Entitled "History" in 15203 the Document, create one stating the title, year, authors, 15204 and publisher of the Document as given on its Title Page, 15205 then add an item describing the Modified Version as stated in 15206 the previous sentence. 15207 15208 J. Preserve the network location, if any, given in the Document 15209 for public access to a Transparent copy of the Document, and 15210 likewise the network locations given in the Document for 15211 previous versions it was based on. These may be placed in 15212 the "History" section. You may omit a network location for a 15213 work that was published at least four years before the 15214 Document itself, or if the original publisher of the version 15215 it refers to gives permission. 15216 15217 K. For any section Entitled "Acknowledgements" or "Dedications", 15218 Preserve the Title of the section, and preserve in the 15219 section all the substance and tone of each of the contributor 15220 acknowledgements and/or dedications given therein. 15221 15222 L. Preserve all the Invariant Sections of the Document, 15223 unaltered in their text and in their titles. Section numbers 15224 or the equivalent are not considered part of the section 15225 titles. 15226 15227 M. Delete any section Entitled "Endorsements". Such a section 15228 may not be included in the Modified Version. 15229 15230 N. Do not retitle any existing section to be Entitled 15231 "Endorsements" or to conflict in title with any Invariant 15232 Section. 15233 15234 O. Preserve any Warranty Disclaimers. 15235 15236 If the Modified Version includes new front-matter sections or 15237 appendices that qualify as Secondary Sections and contain no 15238 material copied from the Document, you may at your option 15239 designate some or all of these sections as invariant. To do this, 15240 add their titles to the list of Invariant Sections in the Modified 15241 Version's license notice. These titles must be distinct from any 15242 other section titles. 15243 15244 You may add a section Entitled "Endorsements", provided it contains 15245 nothing but endorsements of your Modified Version by various 15246 parties--for example, statements of peer review or that the text 15247 has been approved by an organization as the authoritative 15248 definition of a standard. 15249 15250 You may add a passage of up to five words as a Front-Cover Text, 15251 and a passage of up to 25 words as a Back-Cover Text, to the end 15252 of the list of Cover Texts in the Modified Version. Only one 15253 passage of Front-Cover Text and one of Back-Cover Text may be 15254 added by (or through arrangements made by) any one entity. If the 15255 Document already includes a cover text for the same cover, 15256 previously added by you or by arrangement made by the same entity 15257 you are acting on behalf of, you may not add another; but you may 15258 replace the old one, on explicit permission from the previous 15259 publisher that added the old one. 15260 15261 The author(s) and publisher(s) of the Document do not by this 15262 License give permission to use their names for publicity for or to 15263 assert or imply endorsement of any Modified Version. 15264 15265 5. COMBINING DOCUMENTS 15266 15267 You may combine the Document with other documents released under 15268 this License, under the terms defined in section 4 above for 15269 modified versions, provided that you include in the combination 15270 all of the Invariant Sections of all of the original documents, 15271 unmodified, and list them all as Invariant Sections of your 15272 combined work in its license notice, and that you preserve all 15273 their Warranty Disclaimers. 15274 15275 The combined work need only contain one copy of this License, and 15276 multiple identical Invariant Sections may be replaced with a single 15277 copy. If there are multiple Invariant Sections with the same name 15278 but different contents, make the title of each such section unique 15279 by adding at the end of it, in parentheses, the name of the 15280 original author or publisher of that section if known, or else a 15281 unique number. Make the same adjustment to the section titles in 15282 the list of Invariant Sections in the license notice of the 15283 combined work. 15284 15285 In the combination, you must combine any sections Entitled 15286 "History" in the various original documents, forming one section 15287 Entitled "History"; likewise combine any sections Entitled 15288 "Acknowledgements", and any sections Entitled "Dedications". You 15289 must delete all sections Entitled "Endorsements." 15290 15291 6. COLLECTIONS OF DOCUMENTS 15292 15293 You may make a collection consisting of the Document and other 15294 documents released under this License, and replace the individual 15295 copies of this License in the various documents with a single copy 15296 that is included in the collection, provided that you follow the 15297 rules of this License for verbatim copying of each of the 15298 documents in all other respects. 15299 15300 You may extract a single document from such a collection, and 15301 distribute it individually under this License, provided you insert 15302 a copy of this License into the extracted document, and follow 15303 this License in all other respects regarding verbatim copying of 15304 that document. 15305 15306 7. AGGREGATION WITH INDEPENDENT WORKS 15307 15308 A compilation of the Document or its derivatives with other 15309 separate and independent documents or works, in or on a volume of 15310 a storage or distribution medium, is called an "aggregate" if the 15311 copyright resulting from the compilation is not used to limit the 15312 legal rights of the compilation's users beyond what the individual 15313 works permit. When the Document is included in an aggregate, this 15314 License does not apply to the other works in the aggregate which 15315 are not themselves derivative works of the Document. 15316 15317 If the Cover Text requirement of section 3 is applicable to these 15318 copies of the Document, then if the Document is less than one half 15319 of the entire aggregate, the Document's Cover Texts may be placed 15320 on covers that bracket the Document within the aggregate, or the 15321 electronic equivalent of covers if the Document is in electronic 15322 form. Otherwise they must appear on printed covers that bracket 15323 the whole aggregate. 15324 15325 8. TRANSLATION 15326 15327 Translation is considered a kind of modification, so you may 15328 distribute translations of the Document under the terms of section 15329 4. Replacing Invariant Sections with translations requires special 15330 permission from their copyright holders, but you may include 15331 translations of some or all Invariant Sections in addition to the 15332 original versions of these Invariant Sections. You may include a 15333 translation of this License, and all the license notices in the 15334 Document, and any Warranty Disclaimers, provided that you also 15335 include the original English version of this License and the 15336 original versions of those notices and disclaimers. In case of a 15337 disagreement between the translation and the original version of 15338 this License or a notice or disclaimer, the original version will 15339 prevail. 15340 15341 If a section in the Document is Entitled "Acknowledgements", 15342 "Dedications", or "History", the requirement (section 4) to 15343 Preserve its Title (section 1) will typically require changing the 15344 actual title. 15345 15346 9. TERMINATION 15347 15348 You may not copy, modify, sublicense, or distribute the Document 15349 except as expressly provided for under this License. Any other 15350 attempt to copy, modify, sublicense or distribute the Document is 15351 void, and will automatically terminate your rights under this 15352 License. However, parties who have received copies, or rights, 15353 from you under this License will not have their licenses 15354 terminated so long as such parties remain in full compliance. 15355 15356 10. FUTURE REVISIONS OF THIS LICENSE 15357 15358 The Free Software Foundation may publish new, revised versions of 15359 the GNU Free Documentation License from time to time. Such new 15360 versions will be similar in spirit to the present version, but may 15361 differ in detail to address new problems or concerns. See 15362 `http://www.gnu.org/copyleft/'. 15363 15364 Each version of the License is given a distinguishing version 15365 number. If the Document specifies that a particular numbered 15366 version of this License "or any later version" applies to it, you 15367 have the option of following the terms and conditions either of 15368 that specified version or of any later version that has been 15369 published (not as a draft) by the Free Software Foundation. If 15370 the Document does not specify a version number of this License, 15371 you may choose any version ever published (not as a draft) by the 15372 Free Software Foundation. 15373 15374ADDENDUM: How to use this License for your documents 15375---------------------------------------------------- 15376 15377To use this License in a document you have written, include a copy of 15378the License in the document and put the following copyright and license 15379notices just after the title page: 15380 15381 Copyright (C) YEAR YOUR NAME. 15382 Permission is granted to copy, distribute and/or modify this document 15383 under the terms of the GNU Free Documentation License, Version 1.2 15384 or any later version published by the Free Software Foundation; 15385 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 15386 Texts. A copy of the license is included in the section entitled ``GNU 15387 Free Documentation License''. 15388 15389 If you have Invariant Sections, Front-Cover Texts and Back-Cover 15390Texts, replace the "with...Texts." line with this: 15391 15392 with the Invariant Sections being LIST THEIR TITLES, with 15393 the Front-Cover Texts being LIST, and with the Back-Cover Texts 15394 being LIST. 15395 15396 If you have Invariant Sections without Cover Texts, or some other 15397combination of the three, merge those two alternatives to suit the 15398situation. 15399 15400 If your document contains nontrivial examples of program code, we 15401recommend releasing these examples in parallel under your choice of 15402free software license, such as the GNU General Public License, to 15403permit their use in free software. 15404 15405 15406File: gettext.info, Node: Program Index, Next: Option Index, Prev: Licenses, Up: Top 15407 15408Program Index 15409************* 15410 15411�[index�] 15412* Menu: 15413 15414* autopoint: autopoint Invocation. (line 6) 15415* envsubst: envsubst Invocation. (line 6) 15416* gettext <1>: gettext Invocation. (line 6) 15417* gettext: sh. (line 19) 15418* gettextize: gettextize Invocation. 15419 (line 34) 15420* msgattrib: msgattrib Invocation. (line 6) 15421* msgcat: msgcat Invocation. (line 6) 15422* msgcmp: msgcmp Invocation. (line 6) 15423* msgcomm: msgcomm Invocation. (line 6) 15424* msgconv: msgconv Invocation. (line 6) 15425* msgen: msgen Invocation. (line 6) 15426* msgexec: msgexec Invocation. (line 6) 15427* msgfilter: msgfilter Invocation. (line 6) 15428* msgfmt: msgfmt Invocation. (line 6) 15429* msggrep: msggrep Invocation. (line 6) 15430* msginit: msginit Invocation. (line 6) 15431* msgmerge: msgmerge Invocation. (line 6) 15432* msgunfmt: msgunfmt Invocation. (line 6) 15433* msguniq: msguniq Invocation. (line 6) 15434* ngettext <1>: ngettext Invocation. (line 6) 15435* ngettext: sh. (line 19) 15436* recode-sr-latin: msgfilter Invocation. (line 85) 15437* xgettext: xgettext Invocation. (line 6) 15438 15439 15440File: gettext.info, Node: Option Index, Next: Variable Index, Prev: Program Index, Up: Top 15441 15442Option Index 15443************ 15444 15445�[index�] 15446* Menu: 15447 15448* --add-comments, xgettext option: xgettext Invocation. (line 97) 15449* --add-location, msgattrib option: msgattrib Invocation. 15450 (line 127) 15451* --add-location, msgcat option: msgcat Invocation. (line 105) 15452* --add-location, msgcomm option: msgcomm Invocation. (line 95) 15453* --add-location, msgconv option: msgconv Invocation. (line 74) 15454* --add-location, msgen option: msgen Invocation. (line 70) 15455* --add-location, msgfilter option: msgfilter Invocation. 15456 (line 128) 15457* --add-location, msggrep option: msggrep Invocation. (line 152) 15458* --add-location, msgmerge option: msgmerge Invocation. (line 139) 15459* --add-location, msguniq option: msguniq Invocation. (line 92) 15460* --add-location, xgettext option: xgettext Invocation. (line 276) 15461* --alignment, msgfmt option: msgfmt Invocation. (line 209) 15462* --backup, msgmerge option: msgmerge Invocation. (line 65) 15463* --boost, xgettext option: xgettext Invocation. (line 244) 15464* --c++, xgettext option: xgettext Invocation. (line 64) 15465* --check, msgfmt option: msgfmt Invocation. (line 146) 15466* --check-accelerators, msgfmt option: msgfmt Invocation. (line 187) 15467* --check-compatibility, msgfmt option: msgfmt Invocation. (line 183) 15468* --check-domain, msgfmt option: msgfmt Invocation. (line 178) 15469* --check-format, msgfmt option: msgfmt Invocation. (line 150) 15470* --check-header, msgfmt option: msgfmt Invocation. (line 173) 15471* --clear-fuzzy, msgattrib option: msgattrib Invocation. 15472 (line 71) 15473* --clear-obsolete, msgattrib option: msgattrib Invocation. 15474 (line 77) 15475* --clear-previous, msgattrib option: msgattrib Invocation. 15476 (line 80) 15477* --comment, msggrep option: msggrep Invocation. (line 93) 15478* --compendium, msgmerge option: msgmerge Invocation. (line 36) 15479* --copyright-holder, xgettext option: xgettext Invocation. (line 323) 15480* --csharp, msgfmt option: msgfmt Invocation. (line 36) 15481* --csharp, msgunfmt option: msgunfmt Invocation. (line 19) 15482* --csharp-resources, msgfmt option: msgfmt Invocation. (line 40) 15483* --csharp-resources, msgunfmt option: msgunfmt Invocation. (line 23) 15484* --debug, xgettext option: xgettext Invocation. (line 248) 15485* --default-domain, xgettext option: xgettext Invocation. (line 36) 15486* --directory, msgattrib option: msgattrib Invocation. 15487 (line 19) 15488* --directory, msgcat option: msgcat Invocation. (line 32) 15489* --directory, msgcmp option: msgcmp Invocation. (line 27) 15490* --directory, msgcomm option: msgcomm Invocation. (line 30) 15491* --directory, msgconv option: msgconv Invocation. (line 19) 15492* --directory, msgen option: msgen Invocation. (line 25) 15493* --directory, msgexec option: msgexec Invocation. (line 44) 15494* --directory, msgfilter option: msgfilter Invocation. 15495 (line 20) 15496* --directory, msgfmt option: msgfmt Invocation. (line 18) 15497* --directory, msggrep option: msggrep Invocation. (line 19) 15498* --directory, msgmerge option: msgmerge Invocation. (line 30) 15499* --directory, msguniq option: msguniq Invocation. (line 26) 15500* --directory, xgettext option: xgettext Invocation. (line 24) 15501* --domain, gettext option: gettext Invocation. (line 16) 15502* --domain, msggrep option: msggrep Invocation. (line 77) 15503* --domain, ngettext option: ngettext Invocation. (line 15) 15504* --dry-run, autopoint option: autopoint Invocation. 15505 (line 24) 15506* --dry-run, gettextize option: gettextize Invocation. 15507 (line 65) 15508* --exclude-file, xgettext option: xgettext Invocation. (line 92) 15509* --expression, msgfilter option: msgfilter Invocation. 15510 (line 70) 15511* --extended-regexp, msggrep option: msggrep Invocation. (line 101) 15512* --extract-all, xgettext option: xgettext Invocation. (line 106) 15513* --extracted-comment, msggrep option: msggrep Invocation. (line 97) 15514* --file, msgfilter option: msgfilter Invocation. 15515 (line 74) 15516* --file, msggrep option: msggrep Invocation. (line 113) 15517* --files-from, msgcat option: msgcat Invocation. (line 27) 15518* --files-from, msgcomm option: msgcomm Invocation. (line 25) 15519* --files-from, xgettext option: xgettext Invocation. (line 19) 15520* --fixed-strings, msggrep option: msggrep Invocation. (line 105) 15521* --flag, xgettext option: xgettext Invocation. (line 195) 15522* --force, autopoint option: autopoint Invocation. 15523 (line 20) 15524* --force, gettextize option: gettextize Invocation. 15525 (line 40) 15526* --force-po, msgattrib option: msgattrib Invocation. 15527 (line 116) 15528* --force-po, msgcat option: msgcat Invocation. (line 94) 15529* --force-po, msgcomm option: msgcomm Invocation. (line 84) 15530* --force-po, msgconv option: msgconv Invocation. (line 64) 15531* --force-po, msgen option: msgen Invocation. (line 60) 15532* --force-po, msgfilter option: msgfilter Invocation. 15533 (line 114) 15534* --force-po, msggrep option: msggrep Invocation. (line 143) 15535* --force-po, msgmerge option: msgmerge Invocation. (line 129) 15536* --force-po, msgunfmt option: msgunfmt Invocation. (line 108) 15537* --force-po, msguniq option: msguniq Invocation. (line 81) 15538* --force-po, xgettext option: xgettext Invocation. (line 265) 15539* --foreign-user, xgettext option: xgettext Invocation. (line 338) 15540* --from-code, xgettext option: xgettext Invocation. (line 74) 15541* --fuzzy, msgattrib option: msgattrib Invocation. 15542 (line 91) 15543* --help, autopoint option: autopoint Invocation. 15544 (line 33) 15545* --help, envsubst option: envsubst Invocation. (line 22) 15546* --help, gettext option: gettext Invocation. (line 32) 15547* --help, gettextize option: gettextize Invocation. 15548 (line 70) 15549* --help, msgattrib option: msgattrib Invocation. 15550 (line 172) 15551* --help, msgcat option: msgcat Invocation. (line 150) 15552* --help, msgcmp option: msgcmp Invocation. (line 67) 15553* --help, msgcomm option: msgcomm Invocation. (line 143) 15554* --help, msgconv option: msgconv Invocation. (line 119) 15555* --help, msgen option: msgen Invocation. (line 115) 15556* --help, msgexec option: msgexec Invocation. (line 69) 15557* --help, msgfilter option: msgfilter Invocation. 15558 (line 173) 15559* --help, msgfmt option: msgfmt Invocation. (line 222) 15560* --help, msggrep option: msggrep Invocation. (line 195) 15561* --help, msginit option: msginit Invocation. (line 90) 15562* --help, msgmerge option: msgmerge Invocation. (line 184) 15563* --help, msgunfmt option: msgunfmt Invocation. (line 153) 15564* --help, msguniq option: msguniq Invocation. (line 137) 15565* --help, ngettext option: ngettext Invocation. (line 31) 15566* --help, xgettext option: xgettext Invocation. (line 384) 15567* --ignore-case, msggrep option: msggrep Invocation. (line 117) 15568* --ignore-file, msgattrib option: msgattrib Invocation. 15569 (line 87) 15570* --indent, msgattrib option: msgattrib Invocation. 15571 (line 120) 15572* --indent, msgcat option: msgcat Invocation. (line 98) 15573* --indent, msgcomm option: msgcomm Invocation. (line 88) 15574* --indent, msgconv option: msgconv Invocation. (line 68) 15575* --indent, msgen option: msgen Invocation. (line 64) 15576* --indent, msgfilter option: msgfilter Invocation. 15577 (line 117) 15578* --indent, msggrep option: msggrep Invocation. (line 146) 15579* --indent, msgmerge option: msgmerge Invocation. (line 133) 15580* --indent, msgunfmt option: msgunfmt Invocation. (line 112) 15581* --indent, msguniq option: msguniq Invocation. (line 85) 15582* --indent, xgettext option: xgettext Invocation. (line 269) 15583* --input, msgexec option: msgexec Invocation. (line 40) 15584* --input, msgfilter option: msgfilter Invocation. 15585 (line 16) 15586* --input, msginit option: msginit Invocation. (line 16) 15587* --intl, gettextize option: gettextize Invocation. 15588 (line 43) 15589* --invert-match, msggrep option: msggrep Invocation. (line 121) 15590* --java, msgfmt option: msgfmt Invocation. (line 30) 15591* --java, msgunfmt option: msgunfmt Invocation. (line 16) 15592* --java2, msgfmt option: msgfmt Invocation. (line 33) 15593* --join-existing, xgettext option: xgettext Invocation. (line 88) 15594* --keep-header, msgfilter option: msgfilter Invocation. 15595 (line 120) 15596* --keyword, xgettext option: xgettext Invocation. (line 114) 15597* --language, xgettext option: xgettext Invocation. (line 56) 15598* --less-than, msgcat option: msgcat Invocation. (line 55) 15599* --less-than, msgcomm option: msgcomm Invocation. (line 53) 15600* --locale, msgfmt option: msgfmt Invocation. (line 79) 15601* --locale, msginit option: msginit Invocation. (line 52) 15602* --locale, msgunfmt option: msgunfmt Invocation. (line 47) 15603* --location, msggrep option: msggrep Invocation. (line 72) 15604* --more-than, msgcat option: msgcat Invocation. (line 60) 15605* --more-than, msgcomm option: msgcomm Invocation. (line 58) 15606* --msgctxt, msggrep option: msggrep Invocation. (line 81) 15607* --msgid, msggrep option: msggrep Invocation. (line 85) 15608* --msgid-bugs-address, xgettext option: xgettext Invocation. (line 344) 15609* --msgstr, msggrep option: msggrep Invocation. (line 89) 15610* --msgstr-prefix, xgettext option: xgettext Invocation. (line 372) 15611* --msgstr-suffix, xgettext option: xgettext Invocation. (line 376) 15612* --multi-domain, msgcmp option: msgcmp Invocation. (line 36) 15613* --multi-domain, msgmerge option: msgmerge Invocation. (line 101) 15614* --no-changelog, gettextize option: gettextize Invocation. 15615 (line 51) 15616* --no-fuzzy, msgattrib option: msgattrib Invocation. 15617 (line 47) 15618* --no-fuzzy-matching, msgmerge option: msgmerge Invocation. (line 105) 15619* --no-hash, msgfmt option: msgfmt Invocation. (line 212) 15620* --no-location, msgattrib option: msgattrib Invocation. 15621 (line 123) 15622* --no-location, msgcat option: msgcat Invocation. (line 101) 15623* --no-location, msgcomm option: msgcomm Invocation. (line 91) 15624* --no-location, msgconv option: msgconv Invocation. (line 71) 15625* --no-location, msgen option: msgen Invocation. (line 67) 15626* --no-location, msgfilter option: msgfilter Invocation. 15627 (line 125) 15628* --no-location, msggrep option: msggrep Invocation. (line 149) 15629* --no-location, msgmerge option: msgmerge Invocation. (line 136) 15630* --no-location, msguniq option: msguniq Invocation. (line 88) 15631* --no-location, xgettext option: xgettext Invocation. (line 272) 15632* --no-obsolete, msgattrib option: msgattrib Invocation. 15633 (line 53) 15634* --no-translator, msginit option: msginit Invocation. (line 58) 15635* --no-wrap, msgattrib option: msgattrib Invocation. 15636 (line 152) 15637* --no-wrap, msgcat option: msgcat Invocation. (line 130) 15638* --no-wrap, msgcomm option: msgcomm Invocation. (line 120) 15639* --no-wrap, msgconv option: msgconv Invocation. (line 99) 15640* --no-wrap, msgen option: msgen Invocation. (line 95) 15641* --no-wrap, msgfilter option: msgfilter Invocation. 15642 (line 153) 15643* --no-wrap, msggrep option: msggrep Invocation. (line 177) 15644* --no-wrap, msginit option: msginit Invocation. (line 79) 15645* --no-wrap, msgmerge option: msgmerge Invocation. (line 164) 15646* --no-wrap, msgunfmt option: msgunfmt Invocation. (line 137) 15647* --no-wrap, msguniq option: msguniq Invocation. (line 117) 15648* --no-wrap, xgettext option: xgettext Invocation. (line 300) 15649* --obsolete, msgattrib option: msgattrib Invocation. 15650 (line 95) 15651* --omit-header, msgcomm option: msgcomm Invocation. (line 135) 15652* --omit-header, xgettext option: xgettext Invocation. (line 315) 15653* --only-file, msgattrib option: msgattrib Invocation. 15654 (line 83) 15655* --only-fuzzy, msgattrib option: msgattrib Invocation. 15656 (line 50) 15657* --only-obsolete, msgattrib option: msgattrib Invocation. 15658 (line 56) 15659* --output, xgettext option: xgettext Invocation. (line 40) 15660* --output-dir, xgettext option: xgettext Invocation. (line 45) 15661* --output-file, msgattrib option: msgattrib Invocation. 15662 (line 31) 15663* --output-file, msgcat option: msgcat Invocation. (line 44) 15664* --output-file, msgcomm option: msgcomm Invocation. (line 42) 15665* --output-file, msgconv option: msgconv Invocation. (line 31) 15666* --output-file, msgen option: msgen Invocation. (line 37) 15667* --output-file, msgfilter option: msgfilter Invocation. 15668 (line 32) 15669* --output-file, msgfmt option: msgfmt Invocation. (line 54) 15670* --output-file, msggrep option: msggrep Invocation. (line 31) 15671* --output-file, msginit option: msginit Invocation. (line 27) 15672* --output-file, msgmerge option: msgmerge Invocation. (line 53) 15673* --output-file, msgunfmt option: msgunfmt Invocation. (line 98) 15674* --output-file, msguniq option: msguniq Invocation. (line 38) 15675* --previous, msgmerge option: msgmerge Invocation. (line 109) 15676* --properties-input, msgattrib option: msgattrib Invocation. 15677 (line 104) 15678* --properties-input, msgcat option: msgcat Invocation. (line 74) 15679* --properties-input, msgcmp option: msgcmp Invocation. (line 54) 15680* --properties-input, msgcomm option: msgcomm Invocation. (line 72) 15681* --properties-input, msgconv option: msgconv Invocation. (line 52) 15682* --properties-input, msgen option: msgen Invocation. (line 48) 15683* --properties-input, msgexec option: msgexec Invocation. (line 56) 15684* --properties-input, msgfilter option: msgfilter Invocation. 15685 (line 102) 15686* --properties-input, msgfmt option: msgfmt Invocation. (line 133) 15687* --properties-input, msggrep option: msggrep Invocation. (line 131) 15688* --properties-input, msginit option: msginit Invocation. (line 39) 15689* --properties-input, msgmerge option: msgmerge Invocation. (line 117) 15690* --properties-input, msguniq option: msguniq Invocation. (line 61) 15691* --properties-output, msgattrib option: msgattrib Invocation. 15692 (line 136) 15693* --properties-output, msgcat option: msgcat Invocation. (line 114) 15694* --properties-output, msgcomm option: msgcomm Invocation. (line 104) 15695* --properties-output, msgconv option: msgconv Invocation. (line 83) 15696* --properties-output, msgen option: msgen Invocation. (line 79) 15697* --properties-output, msgfilter option: msgfilter Invocation. 15698 (line 137) 15699* --properties-output, msggrep option: msggrep Invocation. (line 161) 15700* --properties-output, msginit option: msginit Invocation. (line 63) 15701* --properties-output, msgmerge option: msgmerge Invocation. (line 148) 15702* --properties-output, msgunfmt option: msgunfmt Invocation. (line 121) 15703* --properties-output, msguniq option: msguniq Invocation. (line 101) 15704* --properties-output, xgettext option: xgettext Invocation. (line 284) 15705* --qt, msgfmt option: msgfmt Invocation. (line 46) 15706* --qt, xgettext option: xgettext Invocation. (line 240) 15707* --quiet, msgfilter option: msgfilter Invocation. 15708 (line 79) 15709* --quiet, msgmerge option: msgmerge Invocation. (line 197) 15710* --regexp=, msggrep option: msggrep Invocation. (line 109) 15711* --repeated, msguniq option: msguniq Invocation. (line 49) 15712* --resource, msgfmt option: msgfmt Invocation. (line 75) 15713* --resource, msgunfmt option: msgunfmt Invocation. (line 43) 15714* --set-fuzzy, msgattrib option: msgattrib Invocation. 15715 (line 68) 15716* --set-obsolete, msgattrib option: msgattrib Invocation. 15717 (line 74) 15718* --silent, msgfilter option: msgfilter Invocation. 15719 (line 79) 15720* --silent, msgmerge option: msgmerge Invocation. (line 197) 15721* --sort-by-file, msgattrib option: msgattrib Invocation. 15722 (line 164) 15723* --sort-by-file, msgcat option: msgcat Invocation. (line 142) 15724* --sort-by-file, msgcomm option: msgcomm Invocation. (line 132) 15725* --sort-by-file, msgconv option: msgconv Invocation. (line 111) 15726* --sort-by-file, msgen option: msgen Invocation. (line 107) 15727* --sort-by-file, msgfilter option: msgfilter Invocation. 15728 (line 165) 15729* --sort-by-file, msggrep option: msggrep Invocation. (line 187) 15730* --sort-by-file, msgmerge option: msgmerge Invocation. (line 176) 15731* --sort-by-file, msguniq option: msguniq Invocation. (line 129) 15732* --sort-by-file, xgettext option: xgettext Invocation. (line 312) 15733* --sort-output, msgattrib option: msgattrib Invocation. 15734 (line 159) 15735* --sort-output, msgcat option: msgcat Invocation. (line 137) 15736* --sort-output, msgcomm option: msgcomm Invocation. (line 127) 15737* --sort-output, msgconv option: msgconv Invocation. (line 106) 15738* --sort-output, msgen option: msgen Invocation. (line 102) 15739* --sort-output, msgfilter option: msgfilter Invocation. 15740 (line 160) 15741* --sort-output, msggrep option: msggrep Invocation. (line 183) 15742* --sort-output, msgmerge option: msgmerge Invocation. (line 171) 15743* --sort-output, msgunfmt option: msgunfmt Invocation. (line 144) 15744* --sort-output, msguniq option: msguniq Invocation. (line 124) 15745* --sort-output, xgettext option: xgettext Invocation. (line 307) 15746* --statistics, msgfmt option: msgfmt Invocation. (line 229) 15747* --strict, msgattrib option: msgattrib Invocation. 15748 (line 130) 15749* --strict, msgcat option: msgcat Invocation. (line 108) 15750* --strict, msgcomm option: msgcomm Invocation. (line 98) 15751* --strict, msgconv option: msgconv Invocation. (line 77) 15752* --strict, msgen option: msgen Invocation. (line 73) 15753* --strict, msgfilter option: msgfilter Invocation. 15754 (line 131) 15755* --strict, msgfmt option: msgfmt Invocation. (line 57) 15756* --strict, msggrep option: msggrep Invocation. (line 155) 15757* --strict, msgmerge option: msgmerge Invocation. (line 142) 15758* --strict, msgunfmt option: msgunfmt Invocation. (line 115) 15759* --strict, msguniq option: msguniq Invocation. (line 95) 15760* --strict, xgettext option: xgettext Invocation. (line 279) 15761* --stringtable-input, msgattrib option: msgattrib Invocation. 15762 (line 108) 15763* --stringtable-input, msgcat option: msgcat Invocation. (line 78) 15764* --stringtable-input, msgcmp option: msgcmp Invocation. (line 58) 15765* --stringtable-input, msgcomm option: msgcomm Invocation. (line 76) 15766* --stringtable-input, msgen option: msgen Invocation. (line 52) 15767* --stringtable-input, msgexec option: msgexec Invocation. (line 60) 15768* --stringtable-input, msgfilter option: msgfilter Invocation. 15769 (line 106) 15770* --stringtable-input, msgfmt option: msgfmt Invocation. (line 137) 15771* --stringtable-input, msggrep option: msggrep Invocation. (line 135) 15772* --stringtable-input, msginit option: msginit Invocation. (line 43) 15773* --stringtable-input, msgmerge option: msgmerge Invocation. (line 121) 15774* --stringtable-input, msgonv option: msgconv Invocation. (line 56) 15775* --stringtable-input, msguniq option: msguniq Invocation. (line 65) 15776* --stringtable-output, msgattrib option: msgattrib Invocation. 15777 (line 141) 15778* --stringtable-output, msgcat option: msgcat Invocation. (line 119) 15779* --stringtable-output, msgcomm option: msgcomm Invocation. (line 109) 15780* --stringtable-output, msgconv option: msgconv Invocation. (line 88) 15781* --stringtable-output, msgen option: msgen Invocation. (line 84) 15782* --stringtable-output, msgfilter option: msgfilter Invocation. 15783 (line 142) 15784* --stringtable-output, msggrep option: msggrep Invocation. (line 166) 15785* --stringtable-output, msginit option: msginit Invocation. (line 68) 15786* --stringtable-output, msgmerge option: msgmerge Invocation. (line 153) 15787* --stringtable-output, msgunfmt option: msgunfmt Invocation. (line 126) 15788* --stringtable-output, msguniq option: msguniq Invocation. (line 106) 15789* --stringtable-output, xgettext option: xgettext Invocation. (line 289) 15790* --suffix, msgmerge option: msgmerge Invocation. (line 68) 15791* --symlink, gettextize option: gettextize Invocation. 15792 (line 56) 15793* --tcl, msgfmt option: msgfmt Invocation. (line 43) 15794* --tcl, msgunfmt option: msgunfmt Invocation. (line 26) 15795* --to-code, msgcat option: msgcat Invocation. (line 87) 15796* --to-code, msgconv option: msgconv Invocation. (line 42) 15797* --to-code, msguniq option: msguniq Invocation. (line 74) 15798* --translated, msgattrib option: msgattrib Invocation. 15799 (line 41) 15800* --trigraphs, xgettext option: xgettext Invocation. (line 235) 15801* --unique, msgcat option: msgcat Invocation. (line 65) 15802* --unique, msgcomm option: msgcomm Invocation. (line 63) 15803* --unique, msguniq option: msguniq Invocation. (line 53) 15804* --untranslated, msgattrib option: msgattrib Invocation. 15805 (line 44) 15806* --update, msgmerge option: msgmerge Invocation. (line 45) 15807* --use-first, msgcat option: msgcat Invocation. (line 90) 15808* --use-first, msguniq option: msguniq Invocation. (line 77) 15809* --use-fuzzy, msgcmp option: msgcmp Invocation. (line 39) 15810* --use-fuzzy, msgfmt option: msgfmt Invocation. (line 199) 15811* --use-untranslated, msgcmp option: msgcmp Invocation. (line 45) 15812* --variables, envsubst option: envsubst Invocation. (line 15) 15813* --verbose, msgfmt option: msgfmt Invocation. (line 233) 15814* --verbose, msgmerge option: msgmerge Invocation. (line 192) 15815* --verbose, msgunfmt option: msgunfmt Invocation. (line 161) 15816* --version, autopoint option: autopoint Invocation. 15817 (line 36) 15818* --version, envsubst option: envsubst Invocation. (line 26) 15819* --version, gettext option: gettext Invocation. (line 40) 15820* --version, gettextize option: gettextize Invocation. 15821 (line 73) 15822* --version, msgattrib option: msgattrib Invocation. 15823 (line 176) 15824* --version, msgcat option: msgcat Invocation. (line 154) 15825* --version, msgcmp option: msgcmp Invocation. (line 71) 15826* --version, msgcomm option: msgcomm Invocation. (line 147) 15827* --version, msgconv option: msgconv Invocation. (line 123) 15828* --version, msgen option: msgen Invocation. (line 119) 15829* --version, msgexec option: msgexec Invocation. (line 73) 15830* --version, msgfilter option: msgfilter Invocation. 15831 (line 177) 15832* --version, msgfmt option: msgfmt Invocation. (line 226) 15833* --version, msggrep option: msggrep Invocation. (line 199) 15834* --version, msginit option: msginit Invocation. (line 94) 15835* --version, msgmerge option: msgmerge Invocation. (line 188) 15836* --version, msgunfmt option: msgunfmt Invocation. (line 157) 15837* --version, msguniq option: msguniq Invocation. (line 141) 15838* --version, ngettext option: ngettext Invocation. (line 35) 15839* --version, xgettext option: xgettext Invocation. (line 388) 15840* --width, msgattrib option: msgattrib Invocation. 15841 (line 146) 15842* --width, msgcat option: msgcat Invocation. (line 124) 15843* --width, msgcomm option: msgcomm Invocation. (line 114) 15844* --width, msgconv option: msgconv Invocation. (line 93) 15845* --width, msgen option: msgen Invocation. (line 89) 15846* --width, msgfilter option: msgfilter Invocation. 15847 (line 147) 15848* --width, msggrep option: msggrep Invocation. (line 171) 15849* --width, msginit option: msginit Invocation. (line 73) 15850* --width, msgmerge option: msgmerge Invocation. (line 158) 15851* --width, msgunfmt option: msgunfmt Invocation. (line 131) 15852* --width, msguniq option: msguniq Invocation. (line 111) 15853* --width, xgettext option: xgettext Invocation. (line 294) 15854* -<, msgcat option: msgcat Invocation. (line 55) 15855* -<, msgcomm option: msgcomm Invocation. (line 53) 15856* ->, msgcat option: msgcat Invocation. (line 60) 15857* ->, msgcomm option: msgcomm Invocation. (line 58) 15858* -a, msgfmt option: msgfmt Invocation. (line 209) 15859* -a, xgettext option: xgettext Invocation. (line 106) 15860* -C, msgfmt option: msgfmt Invocation. (line 183) 15861* -c, msgfmt option: msgfmt Invocation. (line 146) 15862* -C, msggrep option: msggrep Invocation. (line 93) 15863* -C, msgmerge option: msgmerge Invocation. (line 36) 15864* -c, xgettext option: xgettext Invocation. (line 97) 15865* -C, xgettext option: xgettext Invocation. (line 64) 15866* -d, autopoint option: autopoint Invocation. 15867 (line 24) 15868* -d, gettext option: gettext Invocation. (line 16) 15869* -d, gettextize option: gettextize Invocation. 15870 (line 65) 15871* -D, msgattrib option: msgattrib Invocation. 15872 (line 19) 15873* -D, msgcat option: msgcat Invocation. (line 32) 15874* -D, msgcmp option: msgcmp Invocation. (line 27) 15875* -D, msgcomm option: msgcomm Invocation. (line 30) 15876* -D, msgconv option: msgconv Invocation. (line 19) 15877* -D, msgen option: msgen Invocation. (line 25) 15878* -D, msgexec option: msgexec Invocation. (line 44) 15879* -D, msgfilter option: msgfilter Invocation. 15880 (line 20) 15881* -d, msgfmt option: msgfmt Invocation. (line 84) 15882* -D, msgfmt option: msgfmt Invocation. (line 18) 15883* -D, msggrep option: msggrep Invocation. (line 19) 15884* -D, msgmerge option: msgmerge Invocation. (line 30) 15885* -d, msgunfmt option: msgunfmt Invocation. (line 70) 15886* -d, msguniq option: msguniq Invocation. (line 49) 15887* -D, msguniq option: msguniq Invocation. (line 26) 15888* -d, ngettext option: ngettext Invocation. (line 15) 15889* -d, xgettext option: xgettext Invocation. (line 36) 15890* -D, xgettext option: xgettext Invocation. (line 24) 15891* -E, gettext option: gettext Invocation. (line 27) 15892* -e, gettext option: gettext Invocation. (line 20) 15893* -e, msgfilter option: msgfilter Invocation. 15894 (line 70) 15895* -e, msggrep option: msggrep Invocation. (line 109) 15896* -E, msggrep option: msggrep Invocation. (line 101) 15897* -E, ngettext option: ngettext Invocation. (line 26) 15898* -e, ngettext option: ngettext Invocation. (line 19) 15899* -f, autopoint option: autopoint Invocation. 15900 (line 20) 15901* -f, gettextize option: gettextize Invocation. 15902 (line 40) 15903* -F, msgattrib option: msgattrib Invocation. 15904 (line 164) 15905* -F, msgcat option: msgcat Invocation. (line 142) 15906* -f, msgcat option: msgcat Invocation. (line 27) 15907* -F, msgcomm option: msgcomm Invocation. (line 132) 15908* -f, msgcomm option: msgcomm Invocation. (line 25) 15909* -F, msgconv option: msgconv Invocation. (line 111) 15910* -F, msgen option: msgen Invocation. (line 107) 15911* -F, msgfilter option: msgfilter Invocation. 15912 (line 165) 15913* -f, msgfilter option: msgfilter Invocation. 15914 (line 74) 15915* -f, msgfmt option: msgfmt Invocation. (line 199) 15916* -f, msggrep option: msggrep Invocation. (line 113) 15917* -F, msggrep option: msggrep Invocation. (line 105) 15918* -F, msgmerge option: msgmerge Invocation. (line 176) 15919* -F, msguniq option: msguniq Invocation. (line 129) 15920* -F, xgettext option: xgettext Invocation. (line 312) 15921* -f, xgettext option: xgettext Invocation. (line 19) 15922* -h, envsubst option: envsubst Invocation. (line 22) 15923* -h, gettext option: gettext Invocation. (line 32) 15924* -h, msgattrib option: msgattrib Invocation. 15925 (line 172) 15926* -h, msgcat option: msgcat Invocation. (line 150) 15927* -h, msgcmp option: msgcmp Invocation. (line 67) 15928* -h, msgcomm option: msgcomm Invocation. (line 143) 15929* -h, msgconv option: msgconv Invocation. (line 119) 15930* -h, msgen option: msgen Invocation. (line 115) 15931* -h, msgexec option: msgexec Invocation. (line 69) 15932* -h, msgfilter option: msgfilter Invocation. 15933 (line 173) 15934* -h, msgfmt option: msgfmt Invocation. (line 222) 15935* -h, msggrep option: msggrep Invocation. (line 195) 15936* -h, msginit option: msginit Invocation. (line 90) 15937* -h, msgmerge option: msgmerge Invocation. (line 184) 15938* -h, msgunfmt option: msgunfmt Invocation. (line 153) 15939* -h, msguniq option: msguniq Invocation. (line 137) 15940* -h, ngettext option: ngettext Invocation. (line 31) 15941* -h, xgettext option: xgettext Invocation. (line 384) 15942* -i, msgattrib option: msgattrib Invocation. 15943 (line 120) 15944* -i, msgcat option: msgcat Invocation. (line 98) 15945* -i, msgcomm option: msgcomm Invocation. (line 88) 15946* -i, msgconv option: msgconv Invocation. (line 68) 15947* -i, msgen option: msgen Invocation. (line 64) 15948* -i, msgexec option: msgexec Invocation. (line 40) 15949* -i, msgfilter option: msgfilter Invocation. 15950 (line 16) 15951* -i, msggrep option: msggrep Invocation. (line 117) 15952* -i, msginit option: msginit Invocation. (line 16) 15953* -i, msgmerge option: msgmerge Invocation. (line 133) 15954* -i, msgunfmt option: msgunfmt Invocation. (line 112) 15955* -i, msguniq option: msguniq Invocation. (line 85) 15956* -i, xgettext option: xgettext Invocation. (line 269) 15957* -j, msgfmt option: msgfmt Invocation. (line 30) 15958* -J, msggrep option: msggrep Invocation. (line 81) 15959* -j, msgunfmt option: msgunfmt Invocation. (line 16) 15960* -j, xgettext option: xgettext Invocation. (line 88) 15961* -K, msggrep option: msggrep Invocation. (line 85) 15962* -k, xgettext option: xgettext Invocation. (line 114) 15963* -l, msgfmt option: msgfmt Invocation. (line 79) 15964* -l, msginit option: msginit Invocation. (line 52) 15965* -l, msgunfmt option: msgunfmt Invocation. (line 47) 15966* -L, xgettext option: xgettext Invocation. (line 56) 15967* -m, msgcmp option: msgcmp Invocation. (line 36) 15968* -M, msggrep option: msggrep Invocation. (line 77) 15969* -m, msgmerge option: msgmerge Invocation. (line 101) 15970* -M, xgettext option: xgettext Invocation. (line 376) 15971* -m, xgettext option: xgettext Invocation. (line 372) 15972* -n, gettext option: gettext Invocation. (line 35) 15973* -n, msgattrib option: msgattrib Invocation. 15974 (line 127) 15975* -n, msgcat option: msgcat Invocation. (line 105) 15976* -n, msgcomm option: msgcomm Invocation. (line 95) 15977* -n, msgfilter option: msgfilter Invocation. 15978 (line 79) 15979* -N, msggrep option: msggrep Invocation. (line 72) 15980* -N, msgmerge option: msgmerge Invocation. (line 105) 15981* -n, msguniq option: msguniq Invocation. (line 92) 15982* -n, xgettext option: xgettext Invocation. (line 276) 15983* -o, msgattrib option: msgattrib Invocation. 15984 (line 31) 15985* -o, msgcat option: msgcat Invocation. (line 44) 15986* -o, msgcomm option: msgcomm Invocation. (line 42) 15987* -o, msgconv option: msgconv Invocation. (line 31) 15988* -o, msgen option: msgen Invocation. (line 37) 15989* -o, msgfilter option: msgfilter Invocation. 15990 (line 32) 15991* -o, msgfmt option: msgfmt Invocation. (line 54) 15992* -o, msggrep option: msggrep Invocation. (line 31) 15993* -o, msginit option: msginit Invocation. (line 27) 15994* -o, msgmerge option: msgmerge Invocation. (line 53) 15995* -o, msgunfmt option: msgunfmt Invocation. (line 98) 15996* -o, msguniq option: msguniq Invocation. (line 38) 15997* -o, xgettext option: xgettext Invocation. (line 40) 15998* -p, msgattrib option: msgattrib Invocation. 15999 (line 136) 16000* -P, msgattrib option: msgattrib Invocation. 16001 (line 104) 16002* -p, msgcat option: msgcat Invocation. (line 114) 16003* -P, msgcat option: msgcat Invocation. (line 74) 16004* -P, msgcmp option: msgcmp Invocation. (line 54) 16005* -p, msgcomm option: msgcomm Invocation. (line 104) 16006* -P, msgcomm option: msgcomm Invocation. (line 72) 16007* -p, msgconv option: msgconv Invocation. (line 83) 16008* -P, msgconv option: msgconv Invocation. (line 52) 16009* -p, msgen option: msgen Invocation. (line 79) 16010* -P, msgen option: msgen Invocation. (line 48) 16011* -P, msgexec option: msgexec Invocation. (line 56) 16012* -p, msgfilter option: msgfilter Invocation. 16013 (line 137) 16014* -P, msgfilter option: msgfilter Invocation. 16015 (line 102) 16016* -P, msgfmt option: msgfmt Invocation. (line 133) 16017* -p, msggrep option: msggrep Invocation. (line 161) 16018* -P, msggrep option: msggrep Invocation. (line 131) 16019* -p, msginit option: msginit Invocation. (line 63) 16020* -P, msginit option: msginit Invocation. (line 39) 16021* -p, msgmerge option: msgmerge Invocation. (line 148) 16022* -P, msgmerge option: msgmerge Invocation. (line 117) 16023* -p, msgunfmt option: msgunfmt Invocation. (line 121) 16024* -p, msguniq option: msguniq Invocation. (line 101) 16025* -P, msguniq option: msguniq Invocation. (line 61) 16026* -p, xgettext option: xgettext Invocation. (line 45) 16027* -q, msgmerge option: msgmerge Invocation. (line 197) 16028* -r, msgfmt option: msgfmt Invocation. (line 75) 16029* -r, msgunfmt option: msgunfmt Invocation. (line 43) 16030* -s, msgattrib option: msgattrib Invocation. 16031 (line 159) 16032* -s, msgcat option: msgcat Invocation. (line 137) 16033* -s, msgcomm option: msgcomm Invocation. (line 127) 16034* -s, msgconv option: msgconv Invocation. (line 106) 16035* -s, msgen option: msgen Invocation. (line 102) 16036* -s, msgfilter option: msgfilter Invocation. 16037 (line 160) 16038* -s, msgmerge option: msgmerge Invocation. (line 171) 16039* -s, msgunfmt option: msgunfmt Invocation. (line 144) 16040* -s, msguniq option: msguniq Invocation. (line 124) 16041* -s, xgettext option: xgettext Invocation. (line 307) 16042* -t, msgcat option: msgcat Invocation. (line 87) 16043* -t, msgconv option: msgconv Invocation. (line 42) 16044* -T, msggrep option: msggrep Invocation. (line 89) 16045* -t, msguniq option: msguniq Invocation. (line 74) 16046* -T, xgettext option: xgettext Invocation. (line 235) 16047* -u, msgcat option: msgcat Invocation. (line 65) 16048* -u, msgcomm option: msgcomm Invocation. (line 63) 16049* -U, msgmerge option: msgmerge Invocation. (line 45) 16050* -u, msguniq option: msguniq Invocation. (line 53) 16051* -V, envsubst option: envsubst Invocation. (line 26) 16052* -v, envsubst option: envsubst Invocation. (line 15) 16053* -V, gettext option: gettext Invocation. (line 40) 16054* -V, msgattrib option: msgattrib Invocation. 16055 (line 176) 16056* -V, msgcat option: msgcat Invocation. (line 154) 16057* -V, msgcmp option: msgcmp Invocation. (line 71) 16058* -V, msgcomm option: msgcomm Invocation. (line 147) 16059* -V, msgconv option: msgconv Invocation. (line 123) 16060* -V, msgen option: msgen Invocation. (line 119) 16061* -V, msgexec option: msgexec Invocation. (line 73) 16062* -V, msgfilter option: msgfilter Invocation. 16063 (line 177) 16064* -v, msgfmt option: msgfmt Invocation. (line 233) 16065* -V, msgfmt option: msgfmt Invocation. (line 226) 16066* -V, msggrep option: msggrep Invocation. (line 199) 16067* -v, msggrep option: msggrep Invocation. (line 121) 16068* -V, msginit option: msginit Invocation. (line 94) 16069* -v, msgmerge option: msgmerge Invocation. (line 192) 16070* -V, msgmerge option: msgmerge Invocation. (line 188) 16071* -v, msgunfmt option: msgunfmt Invocation. (line 161) 16072* -V, msgunfmt option: msgunfmt Invocation. (line 157) 16073* -V, msguniq option: msguniq Invocation. (line 141) 16074* -V, ngettext option: ngettext Invocation. (line 35) 16075* -V, xgettext option: xgettext Invocation. (line 388) 16076* -w, msgattrib option: msgattrib Invocation. 16077 (line 146) 16078* -w, msgcat option: msgcat Invocation. (line 124) 16079* -w, msgcomm option: msgcomm Invocation. (line 114) 16080* -w, msgconv option: msgconv Invocation. (line 93) 16081* -w, msgen option: msgen Invocation. (line 89) 16082* -w, msgfilter option: msgfilter Invocation. 16083 (line 147) 16084* -w, msggrep option: msggrep Invocation. (line 171) 16085* -w, msginit option: msginit Invocation. (line 73) 16086* -w, msgmerge option: msgmerge Invocation. (line 158) 16087* -w, msgunfmt option: msgunfmt Invocation. (line 131) 16088* -w, msguniq option: msguniq Invocation. (line 111) 16089* -w, xgettext option: xgettext Invocation. (line 294) 16090* -X, msggrep option: msggrep Invocation. (line 97) 16091* -x, xgettext option: xgettext Invocation. (line 92) 16092 16093 16094File: gettext.info, Node: Variable Index, Next: PO Mode Index, Prev: Option Index, Up: Top 16095 16096Variable Index 16097************** 16098 16099�[index�] 16100* Menu: 16101 16102* GETTEXT_LOG_UNTRANSLATED, environment variable: Prioritizing messages. 16103 (line 23) 16104* LANG, environment variable <1>: gettext grok. (line 32) 16105* LANG, environment variable: End Users. (line 6) 16106* LANGUAGE, environment variable <1>: po/Rules-*. (line 11) 16107* LANGUAGE, environment variable: gettext grok. (line 28) 16108* LC_ALL, environment variable: gettext grok. (line 28) 16109* LC_COLLATE, environment variable: gettext grok. (line 30) 16110* LC_CTYPE, environment variable: gettext grok. (line 30) 16111* LC_MESSAGES, environment variable: gettext grok. (line 30) 16112* LC_MONETARY, environment variable: gettext grok. (line 30) 16113* LC_NUMERIC, environment variable: gettext grok. (line 30) 16114* LC_TIME, environment variable: gettext grok. (line 30) 16115* LINGUAS, environment variable: Installers. (line 17) 16116* MSGEXEC_LOCATION, environment variable: msgexec Invocation. (line 18) 16117* MSGEXEC_MSGCTXT, environment variable: msgexec Invocation. (line 18) 16118* MSGEXEC_MSGID, environment variable: msgexec Invocation. (line 18) 16119* TEXTDOMAIN, environment variable: sh. (line 23) 16120* TEXTDOMAINDIR, environment variable: sh. (line 26) 16121 16122 16123File: gettext.info, Node: PO Mode Index, Next: Autoconf Macro Index, Prev: Variable Index, Up: Top 16124 16125PO Mode Index 16126************* 16127 16128�[index�] 16129* Menu: 16130 16131* #, PO Mode command: Modifying Comments. (line 24) 16132* ,, PO Mode command: Marking. (line 44) 16133* ., PO Mode command: Entry Positioning. (line 20) 16134* .emacs customizations: Installation. (line 13) 16135* 0, PO Mode command: Main PO Commands. (line 40) 16136* <, PO Mode command: Entry Positioning. (line 29) 16137* =, PO Mode command: Main PO Commands. (line 47) 16138* >, PO Mode command: Entry Positioning. (line 32) 16139* ?, PO Mode command: Main PO Commands. (line 44) 16140* _, PO Mode command: Main PO Commands. (line 30) 16141* a, PO Mode command: Auxiliary. (line 40) 16142* A, PO Mode command: Auxiliary. (line 28) 16143* a, PO Mode command: Auxiliary. (line 21) 16144* auxiliary PO file: Auxiliary. (line 13) 16145* C-c C-a, PO Mode command <1>: Auxiliary. (line 25) 16146* C-c C-a, PO Mode command: Subedit. (line 17) 16147* C-c C-c, PO Mode command: Subedit. (line 11) 16148* C-c C-k, PO Mode command: Subedit. (line 14) 16149* C-j, PO Mode command: Modifying Translations. 16150 (line 26) 16151* commands: Main PO Commands. (line 6) 16152* comment out PO file entry: Obsolete Entries. (line 47) 16153* consulting program sources: C Sources Context. (line 6) 16154* consulting translations to other languages: Auxiliary. (line 6) 16155* current entry of a PO file: Entry Positioning. (line 6) 16156* cut and paste for translated strings: Modifying Translations. 16157 (line 74) 16158* DEL, PO Mode command <1>: Obsolete Entries. (line 32) 16159* DEL, PO Mode command: Fuzzy Entries. (line 60) 16160* editing comments: Modifying Comments. (line 6) 16161* editing multiple entries: Subedit. (line 62) 16162* editing translations: Modifying Translations. 16163 (line 6) 16164* etags, using for marking strings: Marking. (line 17) 16165* exiting PO subedit: Subedit. (line 20) 16166* find source fragment for a PO file entry: C Sources Context. 16167 (line 33) 16168* h, PO Mode command: Main PO Commands. (line 44) 16169* installing PO mode: Installation. (line 13) 16170* K, PO Mode command: Modifying Comments. (line 27) 16171* k, PO Mode command <1>: Modifying Translations. 16172 (line 30) 16173* k, PO Mode command: Untranslated Entries. 16174 (line 32) 16175* LFD, PO Mode command: Modifying Translations. 16176 (line 26) 16177* looking at the source to aid translation: C Sources Context. 16178 (line 6) 16179* m, PO Mode command: Entry Positioning. (line 35) 16180* M-,, PO Mode command: Marking. (line 48) 16181* M-., PO Mode command: Marking. (line 51) 16182* M-A, PO Mode command: Auxiliary. (line 32) 16183* M-S, PO Mode command: C Sources Context. (line 89) 16184* M-s, PO Mode command: C Sources Context. (line 53) 16185* M-S, PO Mode command: C Sources Context. (line 49) 16186* M-s, PO Mode command: C Sources Context. (line 41) 16187* marking strings for translation: Marking. (line 6) 16188* moving by fuzzy entries: Fuzzy Entries. (line 24) 16189* moving by obsolete entries: Obsolete Entries. (line 22) 16190* moving by translated entries: Translated Entries. (line 12) 16191* moving by untranslated entries: Untranslated Entries. 16192 (line 18) 16193* moving through a PO file: Entry Positioning. (line 14) 16194* n, PO Mode command: Entry Positioning. (line 23) 16195* next-error, stepping through PO file validation results: Main PO Commands. 16196 (line 99) 16197* normalize, PO Mode command: Auxiliary. (line 64) 16198* O, PO Mode command: Obsolete Entries. (line 36) 16199* o, PO Mode command: Obsolete Entries. (line 36) 16200* O, PO Mode command: Obsolete Entries. (line 29) 16201* o, PO Mode command: Obsolete Entries. (line 26) 16202* obsolete active entry: Obsolete Entries. (line 47) 16203* p, PO Mode command: Entry Positioning. (line 26) 16204* pending subedits: Subedit. (line 73) 16205* po-auto-edit-with-msgid, PO Mode variable: Modifying Translations. 16206 (line 57) 16207* po-auto-fuzzy-on-edit, PO Mode variable: Translated Entries. 16208 (line 28) 16209* po-auto-select-on-unfuzzy, PO Mode variable: Fuzzy Entries. (line 44) 16210* po-confirm-and-quit, PO Mode command: Main PO Commands. (line 62) 16211* po-consider-as-auxiliary, PO Mode command: Auxiliary. (line 36) 16212* po-consider-source-path, PO Mode command: C Sources Context. 16213 (line 89) 16214* po-current-entry, PO Mode command: Entry Positioning. (line 46) 16215* po-cycle-auxiliary, PO Mode command: Auxiliary. (line 40) 16216* po-cycle-source-reference, PO Mode command: C Sources Context. 16217 (line 53) 16218* po-edit-comment, PO Mode command: Modifying Comments. (line 46) 16219* po-edit-msgstr, PO Mode command: Modifying Translations. 16220 (line 42) 16221* po-exchange-location, PO Mode command: Entry Positioning. (line 106) 16222* po-fade-out-entry, PO Mode command <1>: Obsolete Entries. (line 47) 16223* po-fade-out-entry, PO Mode command: Fuzzy Entries. (line 60) 16224* po-first-entry, PO Mode command: Entry Positioning. (line 74) 16225* po-help, PO Mode command: Main PO Commands. (line 83) 16226* po-ignore-as-auxiliary, PO Mode command: Auxiliary. (line 36) 16227* po-ignore-source-path, PO Mode command: C Sources Context. (line 89) 16228* po-kill-comment, PO Mode command: Modifying Comments. (line 60) 16229* po-kill-msgstr, PO Mode command <1>: Modifying Translations. 16230 (line 74) 16231* po-kill-msgstr, PO Mode command: Untranslated Entries. 16232 (line 40) 16233* po-kill-ring-save-comment, PO Mode command: Modifying Comments. 16234 (line 60) 16235* po-kill-ring-save-msgstr, PO Mode command: Modifying Translations. 16236 (line 74) 16237* po-last-entry, PO Mode command: Entry Positioning. (line 74) 16238* po-mark-translatable, PO Mode command: Marking. (line 98) 16239* po-msgid-to-msgstr, PO Mode command: Modifying Translations. 16240 (line 52) 16241* po-next-entry, PO Mode command: Entry Positioning. (line 69) 16242* po-next-fuzzy-entry, PO Mode command: Fuzzy Entries. (line 39) 16243* po-next-obsolete-entry, PO Mode command: Obsolete Entries. (line 36) 16244* po-next-translated-entry, PO Mode command: Translated Entries. 16245 (line 23) 16246* po-next-untranslated-entry, PO Mode command: Untranslated Entries. 16247 (line 35) 16248* po-normalize, PO Mode command: Normalizing. (line 31) 16249* po-other-window, PO Mode command: Main PO Commands. (line 72) 16250* po-pop-location, PO Mode command: Entry Positioning. (line 92) 16251* po-previous-entry, PO Mode command: Entry Positioning. (line 69) 16252* po-previous-fuzzy-entry, PO Mode command: Fuzzy Entries. (line 39) 16253* po-previous-obsolete-entry, PO Mode command: Obsolete Entries. 16254 (line 36) 16255* po-previous-translated-entry, PO Mode command: Translated Entries. 16256 (line 23) 16257* po-previous-untransted-entry, PO Mode command: Untranslated Entries. 16258 (line 35) 16259* po-push-location, PO Mode command: Entry Positioning. (line 92) 16260* po-quit, PO Mode command: Main PO Commands. (line 62) 16261* po-select-auxiliary, PO Mode command: Auxiliary. (line 49) 16262* po-select-mark-and-mark, PO Mode command: Marking. (line 98) 16263* po-select-source-reference, PO Mode command: C Sources Context. 16264 (line 53) 16265* po-statistics, PO Mode command: Main PO Commands. (line 87) 16266* po-subedit-abort, PO Mode command: Subedit. (line 27) 16267* po-subedit-cycle-auxiliary, PO Mode command: Subedit. (line 35) 16268* po-subedit-exit, PO Mode command: Subedit. (line 20) 16269* po-subedit-mode-hook, PO Mode variable: Modifying Comments. (line 57) 16270* po-tags-search, PO Mode command: Marking. (line 56) 16271* po-undo, PO Mode command: Main PO Commands. (line 53) 16272* po-unfuzzy, PO Mode command: Fuzzy Entries. (line 44) 16273* po-validate, PO Mode command: Main PO Commands. (line 92) 16274* po-yank-comment, PO Mode command: Modifying Comments. (line 60) 16275* po-yank-msgstr, PO Mode command: Modifying Translations. 16276 (line 98) 16277* q, PO Mode command: Main PO Commands. (line 62) 16278* Q, PO Mode command: Main PO Commands. (line 62) 16279* q, PO Mode command: Main PO Commands. (line 36) 16280* Q, PO Mode command: Main PO Commands. (line 33) 16281* r, PO Mode command: Entry Positioning. (line 39) 16282* RET, PO Mode command: Modifying Translations. 16283 (line 22) 16284* S, PO Mode command: C Sources Context. (line 89) 16285* s, PO Mode command: C Sources Context. (line 53) 16286* S, PO Mode command: C Sources Context. (line 45) 16287* s, PO Mode command: C Sources Context. (line 37) 16288* starting a string translation: Modifying Translations. 16289 (line 63) 16290* string normalization in entries: Normalizing. (line 30) 16291* subedit minor mode: Subedit. (line 6) 16292* T, PO Mode command: Translated Entries. (line 23) 16293* t, PO Mode command: Translated Entries. (line 23) 16294* T, PO Mode command: Translated Entries. (line 19) 16295* t, PO Mode command: Translated Entries. (line 16) 16296* TAB, PO Mode command: Fuzzy Entries. (line 36) 16297* TAGS, and marking translatable strings: Marking. (line 31) 16298* U, PO Mode command: Untranslated Entries. 16299 (line 35) 16300* u, PO Mode command: Untranslated Entries. 16301 (line 35) 16302* U, PO Mode command: Untranslated Entries. 16303 (line 28) 16304* u, PO Mode command: Untranslated Entries. 16305 (line 25) 16306* use the source, Luke: C Sources Context. (line 6) 16307* using obsolete translations to make new entries: Modifying Translations. 16308 (line 124) 16309* using translation compendia: Compendium. (line 6) 16310* V, PO Mode command: Main PO Commands. (line 50) 16311* W, PO Mode command: Modifying Comments. (line 31) 16312* w, PO Mode command: Modifying Translations. 16313 (line 34) 16314* x, PO Mode command: Entry Positioning. (line 42) 16315* Y, PO Mode command: Modifying Comments. (line 35) 16316* y, PO Mode command: Modifying Translations. 16317 (line 38) 16318* Z, PO Mode command: Fuzzy Entries. (line 39) 16319* z, PO Mode command: Fuzzy Entries. (line 39) 16320* Z, PO Mode command: Fuzzy Entries. (line 33) 16321* z, PO Mode command: Fuzzy Entries. (line 30) 16322 16323 16324File: gettext.info, Node: Autoconf Macro Index, Next: Index, Prev: PO Mode Index, Up: Top 16325 16326Autoconf Macro Index 16327******************** 16328 16329�[index�] 16330* Menu: 16331 16332* AM_GNU_GETTEXT: AM_GNU_GETTEXT. (line 6) 16333* AM_GNU_GETTEXT_INTL_SUBDIR: AM_GNU_GETTEXT_INTL_SUBDIR. 16334 (line 6) 16335* AM_GNU_GETTEXT_NEED: AM_GNU_GETTEXT_NEED. (line 6) 16336* AM_GNU_GETTEXT_VERSION: AM_GNU_GETTEXT_VERSION. 16337 (line 6) 16338* AM_ICONV: AM_ICONV. (line 6) 16339* AM_PO_SUBDIRS: AM_PO_SUBDIRS. (line 6) 16340 16341 16342File: gettext.info, Node: Index, Prev: Autoconf Macro Index, Up: Top 16343 16344General Index 16345************* 16346 16347�[index�] 16348* Menu: 16349 16350* _, a macro to mark strings for translation: Mark Keywords. (line 45) 16351* _nl_msg_cat_cntr: gettext grok. (line 62) 16352* ABOUT-NLS file: Matrix. (line 6) 16353* acconfig.h file: acconfig. (line 6) 16354* accumulating translations: Creating Compendia. (line 14) 16355* aclocal.m4 file: aclocal. (line 6) 16356* adding keywords, xgettext: xgettext Invocation. (line 117) 16357* ambiguities: Preparing Strings. (line 41) 16358* apply a filter to translations: msgfilter Invocation. 16359 (line 8) 16360* apply command to all translations in a catalog: msgexec Invocation. 16361 (line 8) 16362* Arabic digits: c-format. (line 28) 16363* attribute manipulation: msgattrib Invocation. 16364 (line 8) 16365* attribute, fuzzy: Fuzzy Entries. (line 6) 16366* attributes of a PO file entry: Fuzzy Entries. (line 6) 16367* attributes, manipulating: Manipulating. (line 56) 16368* autoconf macros for gettext: autoconf macros. (line 6) 16369* autopoint program, usage: autopoint Invocation. 16370 (line 6) 16371* auxiliary PO file: Auxiliary. (line 13) 16372* available translations: Matrix. (line 6) 16373* awk: gawk. (line 6) 16374* awk-format flag: PO Files. (line 149) 16375* backup old file, and msgmerge program: msgmerge Invocation. (line 65) 16376* bash: bash. (line 6) 16377* bibliography: References. (line 6) 16378* big picture: Overview. (line 6) 16379* bind_textdomain_codeset: Charset conversion. (line 28) 16380* Boost format strings: xgettext Invocation. (line 244) 16381* boost-format flag: PO Files. (line 185) 16382* bug report address: Introduction. (line 24) 16383* C and C-like languages: C. (line 6) 16384* C trigraphs: xgettext Invocation. (line 235) 16385* C#: C#. (line 6) 16386* C# mode, and msgfmt program: msgfmt Invocation. (line 36) 16387* C# mode, and msgunfmt program: msgunfmt Invocation. (line 19) 16388* C# resources mode, and msgfmt program: msgfmt Invocation. (line 40) 16389* C# resources mode, and msgunfmt program: msgunfmt Invocation. 16390 (line 23) 16391* C#, string concatenation: Preparing Strings. (line 168) 16392* c-format flag: PO Files. (line 90) 16393* c-format, and xgettext: c-format Flag. (line 48) 16394* catalog encoding and msgexec output: msgexec Invocation. (line 25) 16395* catclose, a catgets function: Interface to catgets. 16396 (line 44) 16397* catgets, a catgets function: Interface to catgets. 16398 (line 25) 16399* catgets, X/Open specification: catgets. (line 6) 16400* catopen, a catgets function: Interface to catgets. 16401 (line 13) 16402* character encoding: Aspects. (line 67) 16403* charset conversion at runtime: Charset conversion. (line 6) 16404* charset of PO files: Header Entry. (line 65) 16405* check format strings: msgfmt Invocation. (line 150) 16406* checking of translations: Manipulating. (line 41) 16407* clisp: Common Lisp. (line 6) 16408* clisp C sources: clisp C. (line 6) 16409* codeset: Aspects. (line 67) 16410* comments in PO files: PO Files. (line 284) 16411* comments, automatic: PO Files. (line 36) 16412* comments, extracted: PO Files. (line 36) 16413* comments, translator: PO Files. (line 36) 16414* Common Lisp: Common Lisp. (line 6) 16415* compare PO files: msgcmp Invocation. (line 8) 16416* comparison of interfaces: Comparison. (line 6) 16417* compatibility with X/Open msgfmt: msgfmt Invocation. (line 183) 16418* compendium: Compendium. (line 6) 16419* compendium, creating: Creating Compendia. (line 6) 16420* concatenate PO files: msgcat Invocation. (line 8) 16421* concatenating PO files into a compendium: Creating Compendia. 16422 (line 14) 16423* concatenation of strings: Preparing Strings. (line 117) 16424* config.h.in file: config.h.in. (line 6) 16425* context: Contexts. (line 6) 16426* context, argument specification in xgettext: xgettext Invocation. 16427 (line 117) 16428* context, in MO files: MO Files. (line 63) 16429* context, in PO files: PO Files. (line 189) 16430* control characters: Preparing Strings. (line 190) 16431* convert binary message catalog into PO file: msgunfmt Invocation. 16432 (line 8) 16433* convert translations to a different encoding: msgconv Invocation. 16434 (line 8) 16435* converting a package to use gettext: Prerequisites. (line 6) 16436* country codes: Country Codes. (line 6) 16437* create new PO file: msginit Invocation. (line 8) 16438* creating a new PO file: Creating. (line 6) 16439* creating compendia: Creating Compendia. (line 6) 16440* csharp-format flag: PO Files. (line 145) 16441* currency symbols: Aspects. (line 79) 16442* date format: Aspects. (line 84) 16443* dcngettext: Plural forms. (line 128) 16444* dcpgettext: Contexts. (line 56) 16445* dcpgettext_expr: Contexts. (line 112) 16446* debugging messages marked as format strings: xgettext Invocation. 16447 (line 248) 16448* dialect: Manipulating. (line 28) 16449* disabling NLS: lib/gettext.h. (line 6) 16450* distribution tarball: Release Management. (line 6) 16451* dngettext: Plural forms. (line 120) 16452* dollar substitution: envsubst Invocation. (line 8) 16453* domain ambiguities: Ambiguities. (line 6) 16454* dpgettext: Contexts. (line 56) 16455* dpgettext_expr: Contexts. (line 112) 16456* duplicate elimination: Manipulating. (line 45) 16457* duplicate removal: msguniq Invocation. (line 8) 16458* editing comments in PO files: Modifying Comments. (line 6) 16459* Editing PO Files: Editing. (line 6) 16460* editing translations: Modifying Translations. 16461 (line 6) 16462* elisp-format flag: PO Files. (line 125) 16463* Emacs Lisp: Emacs Lisp. (line 6) 16464* Emacs PO Mode: PO Mode. (line 6) 16465* encoding: Aspects. (line 67) 16466* encoding conversion: Manipulating. (line 17) 16467* encoding conversion at runtime: Charset conversion. (line 6) 16468* encoding for your language: Header Entry. (line 94) 16469* encoding list: Header Entry. (line 78) 16470* encoding of PO files: Header Entry. (line 65) 16471* environment variables: envsubst Invocation. (line 8) 16472* envsubst program, usage: envsubst Invocation. (line 6) 16473* eval_gettext function, usage: eval_gettext Invocation. 16474 (line 6) 16475* eval_ngettext function, usage: eval_ngettext Invocation. 16476 (line 6) 16477* evolution of packages: Overview. (line 127) 16478* extracting parts of a PO file into a compendium: Creating Compendia. 16479 (line 65) 16480* FDL, GNU Free Documentation License: GNU FDL. (line 6) 16481* file format, .mo: MO Files. (line 6) 16482* file format, .po: PO Files. (line 6) 16483* files, .po and .mo: Files. (line 6) 16484* files, .pot: Overview. (line 67) 16485* filter messages according to attributes: msgattrib Invocation. 16486 (line 8) 16487* find common messages: msgcomm Invocation. (line 8) 16488* force use of fuzzy entries: msgfmt Invocation. (line 199) 16489* format strings: c-format Flag. (line 6) 16490* Free Pascal: Pascal. (line 6) 16491* function attribute, __format__: xgettext Invocation. (line 199) 16492* function attribute, __format_arg__: xgettext Invocation. (line 213) 16493* fuzzy entries: Fuzzy Entries. (line 6) 16494* fuzzy flag: PO Files. (line 80) 16495* gawk: gawk. (line 6) 16496* gcc-internal-format flag: PO Files. (line 177) 16497* GCC-source: GCC-source. (line 6) 16498* generate binary message catalog from PO file: msgfmt Invocation. 16499 (line 8) 16500* generate translation catalog in English: msgen Invocation. (line 8) 16501* gettext files: Adjusting Files. (line 6) 16502* gettext installation: Installation. (line 6) 16503* gettext interface: Interface to gettext. 16504 (line 6) 16505* gettext program, usage: gettext Invocation. (line 6) 16506* gettext vs catgets: Comparison. (line 6) 16507* gettext, a programmer's view: gettext. (line 6) 16508* gettext.h file: lib/gettext.h. (line 6) 16509* gettextize program, usage: gettextize Invocation. 16510 (line 34) 16511* GNOME PO file editor: Gtranslator. (line 6) 16512* GPL, GNU General Public License: GNU GPL. (line 6) 16513* GUI programs: Contexts. (line 6) 16514* guile: Scheme. (line 6) 16515* hash table, inside MO files: MO Files. (line 47) 16516* he, she, and they: Introduction. (line 15) 16517* header entry of a PO file: Header Entry. (line 6) 16518* help option: Preparing Strings. (line 109) 16519* history of GNU gettext: History. (line 6) 16520* i18n: Concepts. (line 6) 16521* importing PO files: Normalizing. (line 55) 16522* include file libintl.h <1>: lib/gettext.h. (line 29) 16523* include file libintl.h <2>: Comparison. (line 33) 16524* include file libintl.h <3>: Importing. (line 11) 16525* include file libintl.h: Overview. (line 57) 16526* initialization: Triggering. (line 6) 16527* initialize new PO file: msginit Invocation. (line 8) 16528* initialize translations from a compendium: Using Compendia. (line 12) 16529* installing gettext: Installation. (line 6) 16530* interface to catgets: Interface to catgets. 16531 (line 6) 16532* internationalization: Concepts. (line 16) 16533* inttypes.h: Preparing Strings. (line 133) 16534* ISO 3166: Country Codes. (line 6) 16535* ISO 639: Language Codes. (line 6) 16536* Java: Java. (line 6) 16537* Java mode, and msgfmt program: msgfmt Invocation. (line 30) 16538* Java mode, and msgunfmt program: msgunfmt Invocation. (line 16) 16539* Java, string concatenation: Preparing Strings. (line 168) 16540* java-format flag: PO Files. (line 141) 16541* KDE PO file editor: KBabel. (line 6) 16542* keyboard accelerator checking: msgfmt Invocation. (line 187) 16543* l10n: Concepts. (line 6) 16544* language codes: Language Codes. (line 6) 16545* language selection: End Users. (line 6) 16546* language selection at runtime: gettext grok. (line 14) 16547* large package: Ambiguities. (line 6) 16548* LGPL, GNU Lesser General Public License: GNU LGPL. (line 6) 16549* libiconv library: AM_ICONV. (line 21) 16550* libintl for C#: C#. (line 161) 16551* libintl for Java: Java. (line 104) 16552* libintl library: AM_GNU_GETTEXT. (line 53) 16553* librep Lisp: librep. (line 6) 16554* librep-format flag: PO Files. (line 129) 16555* License, GNU FDL: GNU FDL. (line 6) 16556* License, GNU GPL: GNU GPL. (line 6) 16557* License, GNU LGPL: GNU LGPL. (line 6) 16558* Licenses: Licenses. (line 6) 16559* LINGUAS file: po/LINGUAS. (line 6) 16560* link with libintl: Overview. (line 62) 16561* Linux <1>: Header Entry. (line 91) 16562* Linux <2>: Overview. (line 62) 16563* Linux: Aspects. (line 114) 16564* Lisp: Common Lisp. (line 6) 16565* lisp-format flag: PO Files. (line 121) 16566* list of translation teams, where to find: Header Entry. (line 58) 16567* locale facet, LC_ALL: Triggering. (line 23) 16568* locale facet, LC_COLLATE: Triggering. (line 52) 16569* locale facet, LC_CTYPE <1>: Triggering. (line 23) 16570* locale facet, LC_CTYPE: Aspects. (line 67) 16571* locale facet, LC_MESSAGES <1>: Triggering. (line 52) 16572* locale facet, LC_MESSAGES: Aspects. (line 108) 16573* locale facet, LC_MONETARY <1>: Triggering. (line 52) 16574* locale facet, LC_MONETARY: Aspects. (line 79) 16575* locale facet, LC_NUMERIC <1>: Triggering. (line 52) 16576* locale facet, LC_NUMERIC: Aspects. (line 94) 16577* locale facet, LC_RESPONSES: Triggering. (line 52) 16578* locale facet, LC_TIME <1>: Triggering. (line 52) 16579* locale facet, LC_TIME: Aspects. (line 84) 16580* locale facets: Aspects. (line 61) 16581* locale program: Header Entry. (line 71) 16582* localization: Concepts. (line 26) 16583* lookup message translation <1>: eval_gettext Invocation. 16584 (line 8) 16585* lookup message translation: gettext Invocation. (line 9) 16586* lookup plural message translation <1>: eval_ngettext Invocation. 16587 (line 8) 16588* lookup plural message translation: ngettext Invocation. (line 8) 16589* magic signature of MO files: MO Files. (line 9) 16590* Makefile.in.in extensions: po/Rules-*. (line 6) 16591* Makevars file: po/Makevars. (line 6) 16592* manipulating PO files: Manipulating. (line 6) 16593* marking Perl sources: Perl. (line 93) 16594* marking string initializers: Special cases. (line 6) 16595* marking strings that require translation: Mark Keywords. (line 6) 16596* marking strings, preparations: Preparing Strings. (line 6) 16597* marking translatable strings: Overview. (line 34) 16598* markup: Preparing Strings. (line 190) 16599* menu entries: Contexts. (line 6) 16600* menu, keyboard accelerator support: msgfmt Invocation. (line 187) 16601* merge PO files: msgcat Invocation. (line 8) 16602* merging two PO files: Manipulating. (line 10) 16603* message catalog files location: Locating Catalogs. (line 6) 16604* messages: Aspects. (line 108) 16605* migration from earlier versions of gettext: Prerequisites. (line 6) 16606* mkinstalldirs file: mkinstalldirs. (line 6) 16607* mnemonics of menu entries: msgfmt Invocation. (line 187) 16608* MO file's format: MO Files. (line 6) 16609* modify message attributes: msgattrib Invocation. 16610 (line 62) 16611* msgattrib program, usage: msgattrib Invocation. 16612 (line 6) 16613* msgcat program, usage: msgcat Invocation. (line 6) 16614* msgcmp program, usage: msgcmp Invocation. (line 6) 16615* msgcomm program, usage: msgcomm Invocation. (line 6) 16616* msgconv program, usage: msgconv Invocation. (line 6) 16617* msgctxt: PO Files. (line 189) 16618* msgen program, usage: msgen Invocation. (line 6) 16619* msgexec program, usage: msgexec Invocation. (line 6) 16620* msgfilter filter and catalog encoding: msgfilter Invocation. 16621 (line 46) 16622* msgfilter program, usage: msgfilter Invocation. 16623 (line 6) 16624* msgfmt program, usage: msgfmt Invocation. (line 6) 16625* msggrep program, usage: msggrep Invocation. (line 6) 16626* msgid: PO Files. (line 56) 16627* msgid_plural: PO Files. (line 209) 16628* msginit program, usage: msginit Invocation. (line 6) 16629* msgmerge program, usage: msgmerge Invocation. (line 6) 16630* msgstr: PO Files. (line 56) 16631* msgunfmt program, usage: msgunfmt Invocation. (line 6) 16632* msguniq program, usage: msguniq Invocation. (line 6) 16633* multi-line strings: Normalizing. (line 65) 16634* N_, a convenience macro: Comparison. (line 41) 16635* Native Language Support: Concepts. (line 51) 16636* Natural Language Support: Concepts. (line 51) 16637* newlines in PO files: PO Files. (line 279) 16638* ngettext: Plural forms. (line 84) 16639* ngettext program, usage: ngettext Invocation. (line 6) 16640* NLS: Concepts. (line 51) 16641* no-awk-format flag: PO Files. (line 150) 16642* no-boost-format flag: PO Files. (line 186) 16643* no-c-format flag: PO Files. (line 91) 16644* no-c-format, and xgettext: c-format Flag. (line 48) 16645* no-csharp-format flag: PO Files. (line 146) 16646* no-elisp-format flag: PO Files. (line 126) 16647* no-gcc-internal-format flag: PO Files. (line 178) 16648* no-java-format flag: PO Files. (line 142) 16649* no-librep-format flag: PO Files. (line 130) 16650* no-lisp-format flag: PO Files. (line 122) 16651* no-objc-format flag: PO Files. (line 110) 16652* no-object-pascal-format flag: PO Files. (line 154) 16653* no-perl-brace-format flag: PO Files. (line 170) 16654* no-perl-format flag: PO Files. (line 166) 16655* no-php-format flag: PO Files. (line 174) 16656* no-python-format flag: PO Files. (line 118) 16657* no-qt-format flag: PO Files. (line 182) 16658* no-scheme-format flag: PO Files. (line 134) 16659* no-sh-format flag: PO Files. (line 114) 16660* no-smalltalk-format flag: PO Files. (line 138) 16661* no-tcl-format flag: PO Files. (line 162) 16662* no-ycp-format flag: PO Files. (line 158) 16663* nplurals, in a PO file header: Plural forms. (line 145) 16664* number format: Aspects. (line 94) 16665* objc-format flag: PO Files. (line 109) 16666* Object Pascal: Pascal. (line 6) 16667* object-pascal-format flag: PO Files. (line 153) 16668* obsolete entries: Obsolete Entries. (line 6) 16669* optimization of gettext functions: Optimized gettext. (line 6) 16670* orthography: Manipulating. (line 28) 16671* outdigits: c-format. (line 28) 16672* output to stdout, xgettext: xgettext Invocation. (line 48) 16673* overview of gettext: Overview. (line 6) 16674* package and version declaration in configure.in: configure.in. 16675 (line 9) 16676* package build and installation options: Installers. (line 6) 16677* package distributor's view of gettext: Installers. (line 6) 16678* package installer's view of gettext: Installers. (line 6) 16679* package maintainer's view of gettext: Maintainers. (line 6) 16680* paragraphs: Preparing Strings. (line 101) 16681* Pascal: Pascal. (line 6) 16682* Perl: Perl. (line 6) 16683* Perl default keywords: Default Keywords. (line 6) 16684* Perl invalid string interpolation: Interpolation I. (line 6) 16685* Perl long lines: Long Lines. (line 6) 16686* Perl parentheses: Parentheses. (line 6) 16687* Perl pitfalls: Perl Pitfalls. (line 6) 16688* Perl quote-like expressions: Quote-like Expressions. 16689 (line 6) 16690* Perl special keywords for hash-lookups: Special Keywords. (line 6) 16691* Perl valid string interpolation: Interpolation II. (line 6) 16692* perl-brace-format flag: PO Files. (line 169) 16693* perl-format flag: PO Files. (line 165) 16694* pgettext: Contexts. (line 33) 16695* pgettext_expr: Contexts. (line 112) 16696* PHP: PHP. (line 6) 16697* php-format flag: PO Files. (line 173) 16698* Pike: Pike. (line 6) 16699* plural form formulas: Plural forms. (line 165) 16700* plural forms: Plural forms. (line 6) 16701* plural forms, in MO files: MO Files. (line 66) 16702* plural forms, in PO files: PO Files. (line 209) 16703* plural, in a PO file header: Plural forms. (line 145) 16704* PO files' format: PO Files. (line 6) 16705* PO mode (Emacs) commands: Main PO Commands. (line 6) 16706* PO template file: Template. (line 6) 16707* po_file_domains: libgettextpo. (line 41) 16708* po_file_free: libgettextpo. (line 36) 16709* po_file_read: libgettextpo. (line 30) 16710* po_message_iterator: libgettextpo. (line 50) 16711* po_message_iterator_free: libgettextpo. (line 57) 16712* po_message_msgid: libgettextpo. (line 70) 16713* po_message_msgid_plural: libgettextpo. (line 75) 16714* po_message_msgstr: libgettextpo. (line 80) 16715* po_message_msgstr_plural: libgettextpo. (line 86) 16716* po_next_message: libgettextpo. (line 62) 16717* portability problems with sed: msgfilter Invocation. 16718 (line 57) 16719* POTFILES.in file: po/POTFILES.in. (line 6) 16720* preparing programs for translation: Sources. (line 6) 16721* preparing shell scripts for translation: Preparing Shell Scripts. 16722 (line 6) 16723* problems with catgets interface: Problems with catgets. 16724 (line 6) 16725* programming languages: Language Implementors. 16726 (line 6) 16727* Python: Python. (line 6) 16728* python-format flag: PO Files. (line 117) 16729* Qt format strings: xgettext Invocation. (line 240) 16730* Qt mode, and msgfmt program: msgfmt Invocation. (line 46) 16731* qt-format flag: PO Files. (line 181) 16732* quotation marks <1>: po/Rules-*. (line 11) 16733* quotation marks: Header Entry. (line 145) 16734* quote characters, use in PO files: Header Entry. (line 145) 16735* recode-sr-latin program: msgfilter Invocation. 16736 (line 85) 16737* related reading: References. (line 6) 16738* release: Release Management. (line 6) 16739* RST: RST. (line 6) 16740* Scheme: Scheme. (line 6) 16741* scheme-format flag: PO Files. (line 133) 16742* scripting languages: Language Implementors. 16743 (line 6) 16744* search messages in a catalog: msggrep Invocation. (line 8) 16745* selecting message language: End Users. (line 6) 16746* sentences: Preparing Strings. (line 44) 16747* setting up gettext at build time: Installers. (line 6) 16748* setting up gettext at run time: End Users. (line 6) 16749* several domains: Ambiguities. (line 6) 16750* sex: Introduction. (line 15) 16751* sh-format flag: PO Files. (line 113) 16752* she, he, and they: Introduction. (line 15) 16753* shell format string: envsubst Invocation. (line 8) 16754* shell scripts: sh. (line 6) 16755* Smalltalk: Smalltalk. (line 6) 16756* smalltalk-format flag: PO Files. (line 137) 16757* sorting msgcat output: msgcat Invocation. (line 137) 16758* sorting msgmerge output: msgmerge Invocation. (line 171) 16759* sorting msgunfmt output: msgunfmt Invocation. (line 144) 16760* sorting output of xgettext: xgettext Invocation. (line 307) 16761* specifying plural form in a PO file: Plural forms. (line 145) 16762* standard output, and msgcat: msgcat Invocation. (line 47) 16763* standard output, and msgmerge program: msgmerge Invocation. (line 56) 16764* string concatenation: Preparing Strings. (line 117) 16765* string normalization in entries: Normalizing. (line 6) 16766* style: Preparing Strings. (line 24) 16767* supported languages, xgettext: xgettext Invocation. (line 56) 16768* Tcl: Tcl. (line 6) 16769* Tcl mode, and msgfmt program: msgfmt Invocation. (line 43) 16770* Tcl mode, and msgunfmt program: msgunfmt Invocation. (line 26) 16771* tcl-format flag: PO Files. (line 161) 16772* template PO file: Overview. (line 67) 16773* testing .po files for equivalence: xgettext Invocation. (line 317) 16774* Tk's scripting language: Tcl. (line 6) 16775* translated entries: Translated Entries. (line 6) 16776* translating menu entries: Contexts. (line 6) 16777* translation aspects: Aspects. (line 6) 16778* Translation Matrix: Matrix. (line 6) 16779* Translation Project: Why. (line 17) 16780* turning off NLS support: lib/gettext.h. (line 6) 16781* tutorial of gettext usage: Overview. (line 6) 16782* unify duplicate translations: msguniq Invocation. (line 8) 16783* untranslated entries: Untranslated Entries. 16784 (line 6) 16785* update translations from a compendium: Using Compendia. (line 20) 16786* upgrading to new versions of gettext: Prerequisites. (line 6) 16787* version control for backup files, msgmerge: msgmerge Invocation. 16788 (line 71) 16789* wxWidgets library: wxWidgets. (line 6) 16790* xargs, and output from msgexec: msgexec Invocation. (line 14) 16791* xgettext program, usage: xgettext Invocation. (line 6) 16792* xmodmap program, and typing quotation marks: Header Entry. (line 157) 16793* YaST2 scripting language: YCP. (line 6) 16794* YCP: YCP. (line 6) 16795* ycp-format flag: PO Files. (line 157) 16796 16797 16798 16799Tag Table: 16800Node: Top2955 16801Node: Introduction16247 16802Node: Why17867 16803Ref: Why-Footnote-121077 16804Node: Concepts21233 16805Node: Aspects24651 16806Node: Files30509 16807Node: Overview32415 16808Node: Users42333 16809Node: Matrix43765 16810Node: End Users44973 16811Node: PO Files45622 16812Ref: PO Files-Footnote-156970 16813Node: Sources57097 16814Node: Importing58250 16815Node: Triggering58930 16816Node: Preparing Strings61967 16817Node: Mark Keywords71007 16818Node: Marking75317 16819Node: c-format Flag83044 16820Node: Special cases86960 16821Node: Names89686 16822Node: Libraries93284 16823Node: Template96316 16824Node: xgettext Invocation97037 16825Node: Creating111353 16826Node: msginit Invocation112235 16827Node: Header Entry114861 16828Node: Updating121867 16829Node: msgmerge Invocation122082 16830Node: Editing127234 16831Node: KBabel127532 16832Node: Gtranslator127670 16833Node: PO Mode127812 16834Node: Installation129504 16835Node: Main PO Commands131465 16836Node: Entry Positioning136550 16837Node: Normalizing142016 16838Node: Translated Entries146507 16839Node: Fuzzy Entries147862 16840Node: Untranslated Entries151039 16841Node: Obsolete Entries152968 16842Node: Modifying Translations156190 16843Node: Modifying Comments164156 16844Node: Subedit168580 16845Node: C Sources Context172473 16846Node: Auxiliary177594 16847Node: Compendium180826 16848Node: Creating Compendia181446 16849Node: Using Compendia183931 16850Node: Manipulating184864 16851Node: msgcat Invocation188626 16852Node: msgconv Invocation192876 16853Node: msggrep Invocation196055 16854Node: msgfilter Invocation201236 16855Node: msguniq Invocation206860 16856Node: msgcomm Invocation210749 16857Node: msgcmp Invocation214794 16858Node: msgattrib Invocation216806 16859Node: msgen Invocation221488 16860Node: msgexec Invocation224823 16861Node: libgettextpo227404 16862Node: Binaries232526 16863Node: msgfmt Invocation232870 16864Node: msgunfmt Invocation239875 16865Node: MO Files244037 16866Node: Programmers252278 16867Node: catgets253457 16868Node: Interface to catgets254868 16869Node: Problems with catgets256874 16870Node: gettext257786 16871Node: Interface to gettext259286 16872Node: Ambiguities261643 16873Node: Locating Catalogs264347 16874Ref: Locating Catalogs-Footnote-1265505 16875Ref: Locating Catalogs-Footnote-2265730 16876Node: Charset conversion265879 16877Node: Contexts268330 16878Node: Plural forms273830 16879Ref: Plural forms-Footnote-1288026 16880Node: Optimized gettext288148 16881Node: Comparison289484 16882Node: Using libintl.a293751 16883Node: gettext grok294191 16884Node: Temp Programmers296820 16885Node: Temp Implementations297345 16886Node: Temp catgets298722 16887Node: Temp WSI300420 16888Node: Temp Notes302419 16889Node: Translators302919 16890Node: Trans Intro 0303382 16891Node: Trans Intro 1306116 16892Node: Discussions308065 16893Node: Organization311720 16894Node: Central Coordination313786 16895Node: National Teams314925 16896Node: Sub-Cultures317449 16897Node: Organizational Ideas318383 16898Node: Mailing Lists319401 16899Node: Information Flow321215 16900Node: Prioritizing messages323463 16901Node: Maintainers327759 16902Node: Flat and Non-Flat329712 16903Node: Prerequisites331202 16904Node: gettextize Invocation335349 16905Node: Adjusting Files342313 16906Node: po/POTFILES.in344099 16907Node: po/LINGUAS345345 16908Node: po/Makevars347034 16909Node: po/Rules-*347782 16910Node: configure.in349250 16911Node: config.guess352269 16912Node: mkinstalldirs353622 16913Node: aclocal354024 16914Node: acconfig356021 16915Node: config.h.in356518 16916Node: Makefile357983 16917Node: src/Makefile360577 16918Node: lib/gettext.h364964 16919Node: autoconf macros367209 16920Node: AM_GNU_GETTEXT367986 16921Node: AM_GNU_GETTEXT_VERSION371948 16922Node: AM_GNU_GETTEXT_NEED372400 16923Node: AM_GNU_GETTEXT_INTL_SUBDIR373290 16924Node: AM_PO_SUBDIRS373942 16925Node: AM_ICONV374724 16926Node: CVS Issues376931 16927Node: Distributed CVS377519 16928Node: Files under CVS379444 16929Node: autopoint Invocation382717 16930Node: Release Management384561 16931Node: Installers385071 16932Node: Programming Languages386295 16933Node: Language Implementors387118 16934Node: Programmers for other Languages391932 16935Node: Translators for other Languages392513 16936Node: c-format394039 16937Node: objc-format395752 16938Node: sh-format396104 16939Node: python-format396906 16940Node: lisp-format397344 16941Node: elisp-format397670 16942Node: librep-format398160 16943Node: scheme-format398560 16944Node: smalltalk-format398836 16945Node: java-format399336 16946Node: csharp-format399784 16947Node: awk-format400159 16948Node: object-pascal-format400484 16949Node: ycp-format400713 16950Node: tcl-format401112 16951Node: perl-format401407 16952Node: php-format402152 16953Node: gcc-internal-format402517 16954Node: qt-format403559 16955Node: boost-format403993 16956Node: Maintainers for other Languages404537 16957Node: List of Programming Languages405772 16958Node: C407055 16959Node: sh408355 16960Node: Preparing Shell Scripts409629 16961Node: gettext.sh413018 16962Node: gettext Invocation413565 16963Node: ngettext Invocation415320 16964Node: envsubst Invocation416908 16965Node: eval_gettext Invocation418329 16966Node: eval_ngettext Invocation418790 16967Node: bash419304 16968Node: Python421280 16969Node: Common Lisp422430 16970Node: clisp C423230 16971Node: Emacs Lisp423945 16972Node: librep424671 16973Node: Scheme425406 16974Node: Smalltalk426190 16975Node: Java427224 16976Node: C#432932 16977Node: gawk441349 16978Node: Pascal442261 16979Node: wxWidgets443569 16980Node: YCP444476 16981Node: Tcl445215 16982Node: Perl446625 16983Node: General Problems449633 16984Node: Default Keywords453291 16985Node: Special Keywords454243 16986Node: Quote-like Expressions455756 16987Node: Interpolation I458031 16988Node: Interpolation II461821 16989Node: Parentheses464186 16990Node: Long Lines465704 16991Node: Perl Pitfalls467549 16992Node: PHP471791 16993Node: Pike472722 16994Node: GCC-source473383 16995Node: List of Data Formats474130 16996Node: POT474596 16997Node: RST474854 16998Node: Glade475080 16999Node: Conclusion475440 17000Node: History475943 17001Node: References480209 17002Node: Language Codes481853 17003Node: Usual Language Codes482365 17004Node: Rare Language Codes486736 17005Node: Country Codes488393 17006Node: Licenses494279 17007Node: GNU GPL496121 17008Node: GNU LGPL515298 17009Node: GNU FDL543431 17010Node: Program Index565817 17011Node: Option Index567703 17012Node: Variable Index613933 17013Node: PO Mode Index615471 17014Node: Autoconf Macro Index629307 17015Node: Index630041 17016 17017End Tag Table 17018