   This file provides documentation for GNU `gettext' utilities.  It
also serves as a reference for the free Translation Project.

   Copyright (C) 1995, 1996, 1997, 1998, 2001, 2002 Free Software
Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

wxWindows library
-----------------

RPMs
     wxGTK, gettext

File extension
     `cpp'

String syntax
     `"abc"'

gettext shorthand
     `_("abc")'

gettext/ngettext functions
     `wxLocale::GetString', `wxGetTranslation'

textdomain
     `wxLocale::AddCatalog'

bindtextdomain
     `wxLocale::AddCatalogLookupPathPrefix'

setlocale
     `wxLocale::Init', `wxSetLocale'

Prerequisite
     `#include <wx/intl.h>'

Use or emulate GNU gettext
     emulate, see `include/wx/intl.h' and `src/common/intl.cpp'

Extractor
     `xgettext'

Formatting with positions
     --

Portability
     fully portable

po-mode marking
     yes

YCP - YaST2 scripting language
------------------------------

RPMs
     libycp, libycp-devel, yast2-core-translator

File extension
     `ycp'

String syntax
     `"abc"'

gettext shorthand
     `_("abc")'

gettext/ngettext functions
     `_()' with 1 or 3 arguments

textdomain
     `textdomain' statement

bindtextdomain
     --

setlocale
     --

Prerequisite
     --

Use or emulate GNU gettext
     use maps instead

Extractor
     `xgettext'

Formatting with positions
     `sformat "%2 %1"'

Portability
     fully portable

po-mode marking
     --

Tcl - Tk's scripting language
-----------------------------

RPMs
     tcl

File extension
     `tcl'

String syntax
     `"abc"'

gettext shorthand
     `[_ "abc"]'

gettext/ngettext functions
     `::msgcat::mc'

textdomain
     --

bindtextdomain
     --, use `::msgcat::mcload' instead

setlocale
     automatic, uses LANG, but ignores LC_MESSAGES and LC_ALL

Prerequisite
     `package require msgcat'
     `proc _ {s} {return [::msgcat::mc $s]}'

Use or emulate GNU gettext
     --, uses a Tcl specific message catalog format

Extractor
     `xgettext -k_'

Formatting with positions
     `format "%2\$d %1\$d"'

Portability
     fully portable

po-mode marking
     --

   Before marking strings as internationalizable, substitutions of
variables into the string need to be converted to `format'
applications. For example, `"file $filename not found"' becomes
`[format "file %s not found" $filename]'.  Only after this is done, can
the strings be marked and extracted.  After marking, this example
becomes `[format [_ "file %s not found"] $filename]' or `[msgcat::mc
"file %s not found" $filename]'. Note that the `msgcat::mc' function
implicitly calls `format' when more than one argument is given.

Perl
----

RPMs
     perl, perl-gettext

File extension
     `pl', `PL'

String syntax
     `"abc"'

gettext shorthand
     --

gettext/ngettext functions
     `gettext', `dgettext', `dcgettext'

textdomain
     `textdomain' function

bindtextdomain
     `bindtextdomain' function

setlocale
     Use `setlocale (LC_ALL, "");'

Prerequisite
     `use POSIX;'
     `use Locale::gettext;'

Use or emulate GNU gettext
     use

Extractor
     ?

Formatting with positions
     --

Portability
     ?

po-mode marking
     --

PHP Hypertext Preprocessor
--------------------------

RPMs
     mod_php4, phplib, phpdoc

File extension
     `php', `php3', `php4'

String syntax
     `"abc"'

gettext shorthand
     `_("abc")'

gettext/ngettext functions
     `gettext', `dgettext', `dcgettext'

textdomain
     `textdomain' function

bindtextdomain
     `bindtextdomain' function

setlocale
     `setlocale' function

Prerequisite
     --

Use or emulate GNU gettext
     use

Extractor
     --

Formatting with positions
     --

Portability
     On platforms without gettext, the functions are not available.

po-mode marking
     --

Pike
----

RPMs
     roxen

File extension
     `pike'

String syntax
     `"abc"'

gettext shorthand
     --

gettext/ngettext functions
     `gettext', `dgettext', `dcgettext'

textdomain
     `textdomain' function

bindtextdomain
     `bindtextdomain' function

setlocale
     `setlocale' function

Prerequisite
     `import Locale.Gettext;'

Use or emulate GNU gettext
     use

Extractor
     --

Formatting with positions
     --

Portability
     On platforms without gettext, the functions are not available.

po-mode marking
     --

Internationalizable Data
========================

   Here is a list of other data formats which can be internationalized
using GNU gettext.

POT - Portable Object Template
------------------------------

RPMs
     gettext

File extension
     `pot', `po'

Extractor
     `xgettext'

Resource String Table
---------------------

RPMs
     fpk

File extension
     `rst'

Extractor
     `xgettext', `rstconv'

Glade - GNOME user interface description
----------------------------------------

RPMs
     glade, libglade, xml-i18n-tools

File extension
     `glade'

Extractor
     `xgettext', `libglade-xgettext'

Concluding Remarks
******************

   We would like to conclude this GNU `gettext' manual by presenting an
history of the Translation Project so far.  We finally give a few
pointers for those who want to do further research or readings about
Native Language Support matters.

History of GNU `gettext'
========================

   Internationalization concerns and algorithms have been informally
and casually discussed for years in GNU, sometimes around GNU `libc',
maybe around the incoming `Hurd', or otherwise (nobody clearly
remembers).  And even then, when the work started for real, this was
somewhat independently of these previous discussions.

   This all began in July 1994, when Patrick D'Cruze had the idea and
initiative of internationalizing version 3.9.2 of GNU `fileutils'.  He
then asked Jim Meyering, the maintainer, how to get those changes
folded into an official release.  That first draft was full of
`#ifdef's and somewhat disconcerting, and Jim wanted to find nicer
ways.  Patrick and Jim shared some tries and experimentations in this
area.  Then, feeling that this might eventually have a deeper impact on
GNU, Jim wanted to know what standards were, and contacted Richard
Stallman, who very quickly and verbally described an overall design for
what was meant to become `glocale', at that time.

   Jim implemented `glocale' and got a lot of exhausting feedback from
Patrick and Richard, of course, but also from Mitchum DSouza (who wrote
a `catgets'-like package), Roland McGrath, maybe David MacKenzie,
Franc,ois Pinard, and Paul Eggert, all pushing and pulling in various
directions, not always compatible, to the extent that after a couple of
test releases, `glocale' was torn apart.

   While Jim took some distance and time and became dad for a second
time, Roland wanted to get GNU `libc' internationalized, and got Ulrich
Drepper involved in that project.  Instead of starting from `glocale',
Ulrich rewrote something from scratch, but more conformant to the set
of guidelines who emerged out of the `glocale' effort.  Then, Ulrich
got people from the previous forum to involve themselves into this new
project, and the switch from `glocale' to what was first named
`msgutils', renamed `nlsutils', and later `gettext', became officially
accepted by Richard in May 1995 or so.

   Let's summarize by saying that Ulrich Drepper wrote GNU `gettext' in
April 1995.  The first official release of the package, including PO
mode, occurred in July 1995, and was numbered 0.7.  Other people
contributed to the effort by providing a discussion forum around
Ulrich, writing little pieces of code, or testing.  These are quoted in
the `THANKS' file which comes with the GNU `gettext' distribution.

   While this was being done, Franc,ois adapted half a dozen of GNU
packages to `glocale' first, then later to `gettext', putting them in
pretest, so providing along the way an effective user environment for
fine tuning the evolving tools.  He also took the responsibility of
organizing and coordinating the Translation Project.  After nearly a
year of informal exchanges between people from many countries,
translator teams started to exist in May 1995, through the creation and
support by Patrick D'Cruze of twenty unmoderated mailing lists for that
many native languages, and two moderated lists: one for reaching all
teams at once, the other for reaching all willing maintainers of
internationalized free software packages.

   Franc,ois also wrote PO mode in June 1995 with the collaboration of
Greg McGary, as a kind of contribution to Ulrich's package.  He also
gave a hand with the GNU `gettext' Texinfo manual.

   In 1997, Ulrich Drepper released the GNU libc 2.0, which included the
`gettext', `textdomain' and `bindtextdomain' functions.

   In 2000, Ulrich Drepper added plural form handling (the `ngettext'
function) to GNU libc.  Later, in 2001, he released GNU libc 2.2.x,
which is the first free C library with full internationalization
support.

   Ulrich being quite busy in his role of General Maintainer of GNU
libc, he handed over the GNU `gettext' maintenance to Bruno Haible in
2000.  Bruno added the plural form handling to the tools as well, added
support for UTF-8 and CJK locales, and wrote a few new tools for
manipulating PO files.

Related Readings
================

   Eugene H. Dorr (`dorre@well.com') maintains an interesting
bibliography on internationalization matters, called
`Internationalization Reference List', which is available as:
     ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt

   Michael Gschwind (`mike@vlsivie.tuwien.ac.at') maintains a
Frequently Asked Questions (FAQ) list, entitled `Programming for
Internationalisation'.  This FAQ discusses writing programs which can
handle different language conventions, character sets, etc.; and is
applicable to all character set encodings, with particular emphasis on
ISO 8859-1.  It is regularly published in Usenet groups
`comp.unix.questions', `comp.std.internat',
`comp.software.international', `comp.lang.c', `comp.windows.x',
`comp.std.c', `comp.answers' and `news.answers'.  The home location of
this document is:
     ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming

   Patrick D'Cruze (`pdcruze@li.org') wrote a tutorial about NLS
matters, and Jochen Hein (`Hein@student.tu-clausthal.de') took over the
responsibility of maintaining it.  It may be found as:
     ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/...
          ...locale-tutorial-0.8.txt.gz

This site is mirrored in:
     ftp://ftp.ibp.fr/pub/linux/sunsite/

   A French version of the same tutorial should be findable at:
     ftp://ftp.ibp.fr/pub/linux/french/docs/

together with French translations of many Linux-related documents.

Language Codes
**************

   The ISO 639 standard defines two character codes for many languages.
All abbreviations for languages used in the Translation Project should
come from this standard.

`aa'
     Afar.

`ab'
     Abkhazian.

`ae'
     Avestan.

`af'
     Afrikaans.

`am'
     Amharic.

`ar'
     Arabic.

`as'
     Assamese.

`ay'
     Aymara.

`az'
     Azerbaijani.

`ba'
     Bashkir.

`be'
     Byelorussian; Belarusian.

`bg'
     Bulgarian.

`bh'
     Bihari.

`bi'
     Bislama.

`bn'
     Bengali; Bangla.

`bo'
     Tibetan.

`br'
     Breton.

`bs'
     Bosnian.

`ca'
     Catalan.

`ce'
     Chechen.

`ch'
     Chamorro.

`co'
     Corsican.

`cs'
     Czech.

`cu'
     Church Slavic.

`cv'
     Chuvash.

`cy'
     Welsh.

`da'
     Danish.

`de'
     German.

`dz'
     Dzongkha; Bhutani.

`el'
     Greek.

`en'
     English.

`eo'
     Esperanto.

`es'
     Spanish.

`et'
     Estonian.

`eu'
     Basque.

`fa'
     Persian.

`fi'
     Finnish.

`fj'
     Fijian; Fiji.

`fo'
     Faroese.

`fr'
     French.

`fy'
     Frisian.

`ga'
     Irish.

`gd'
     Scots; Gaelic.

`gl'
     Gallegan; Galician.

`gn'
     Guarani.

`gu'
     Gujarati.

`gv'
     Manx.

`ha'
     Hausa (?).

`he'
     Hebrew (formerly iw).

`hi'
     Hindi.

`ho'
     Hiri Motu.

`hr'
     Croatian.

`hu'
     Hungarian.

`hy'
     Armenian.

`hz'
     Herero.

`ia'
     Interlingua.

`id'
     Indonesian (formerly in).

`ie'
     Interlingue.

`ik'
     Inupiak.

`io'
     Ido.

`is'
     Icelandic.

`it'
     Italian.

`iu'
     Inuktitut.

`ja'
     Japanese.

`jv'
     Javanese.

`ka'
     Georgian.

`ki'
     Kikuyu.

`kj'
     Kuanyama.

`kk'
     Kazakh.

`kl'
     Kalaallisut; Greenlandic.

`km'
     Khmer; Cambodian.

`kn'
     Kannada.

`ko'
     Korean.

`ks'
     Kashmiri.

`ku'
     Kurdish.

`kv'
     Komi.

`kw'
     Cornish.

`ky'
     Kirghiz.

`la'
     Latin.

`lb'
     Letzeburgesch.

`ln'
     Lingala.

`lo'
     Lao; Laotian.

`lt'
     Lithuanian.

`lv'
     Latvian; Lettish.

`mg'
     Malagasy.

`mh'
     Marshall.

`mi'
     Maori.

`mk'
     Macedonian.

`ml'
     Malayalam.

`mn'
     Mongolian.

`mo'
     Moldavian.

`mr'
     Marathi.

`ms'
     Malay.

`mt'
     Maltese.

`my'
     Burmese.

`na'
     Nauru.

`nb'
     Norwegian Bokmaal.

`nd'
     Ndebele, North.

`ne'
     Nepali.

`ng'
     Ndonga.

`nl'
     Dutch.

`nn'
     Norwegian Nynorsk.

`no'
     Norwegian.

`nr'
     Ndebele, South.

`nv'
     Navajo.

`ny'
     Chichewa; Nyanja.

`oc'
     Occitan; Provenc,al.

`om'
     (Afan) Oromo.

`or'
     Oriya.

`os'
     Ossetian; Ossetic.

`pa'
     Panjabi; Punjabi.

`pi'
     Pali.

`pl'
     Polish.

`ps'
     Pashto, Pushto.

`pt'
     Portuguese.

`qu'
     Quechua.

`rm'
     Rhaeto-Romance.

`rn'
     Rundi; Kirundi.

`ro'
     Romanian.

`ru'
     Russian.

`rw'
     Kinyarwanda.

`sa'
     Sanskrit.

`sc'
     Sardinian.

`sd'
     Sindhi.

`se'
     Northern Sami.

`sg'
     Sango; Sangro.

`si'
     Sinhalese.

`sk'
     Slovak.

`sl'
     Slovenian.

`sm'
     Samoan.

`sn'
     Shona.

`so'
     Somali.

`sq'
     Albanian.

`sr'
     Serbian.

`ss'
     Swati; Siswati.

`st'
     Sesotho; Sotho, Southern.

`su'
     Sundanese.

`sv'
     Swedish.

`sw'
     Swahili.

`ta'
     Tamil.

`te'
     Telugu.

`tg'
     Tajik.

`th'
     Thai.

`ti'
     Tigrinya.

`tk'
     Turkmen.

`tl'
     Tagalog.

`tn'
     Tswana; Setswana.

`to'
     Tonga (?).

`tr'
     Turkish.

`ts'
     Tsonga.

`tt'
     Tatar.

`tw'
     Twi.

`ty'
     Tahitian.

`ug'
     Uighur.

`uk'
     Ukrainian.

`ur'
     Urdu.

`uz'
     Uzbek.

`vi'
     Vietnamese.

`vo'
     Volapu"k; Volapuk.

`wa'
     Walloon.

`wo'
     Wolof.

`xh'
     Xhosa.

`yi'
     Yiddish (formerly ji).

`yo'
     Yoruba.

`za'
     Zhuang.

`zh'
     Chinese.

`zu'
     Zulu.

Country Codes
*************

   The ISO 3166 standard defines two character codes for many countries
and territories.  All abbreviations for countries used in the
Translation Project should come from this standard.

`AD'
     Andorra.

`AE'
     United Arab Emirates.

`AF'
     Afghanistan.

`AG'
     Antigua and Barbuda.

`AI'
     Anguilla.

`AL'
     Albania.

`AM'
     Armenia.

`AN'
     Netherlands Antilles.

`AO'
     Angola.

`AQ'
     Antarctica.

`AR'
     Argentina.

`AS'
     Samoa (American).

`AT'
     Austria.

`AU'
     Australia.

`AW'
     Aruba.

`AZ'
     Azerbaijan.

`BA'
     Bosnia and Herzegovina.

`BB'
     Barbados.

`BD'
     Bangladesh.

`BE'
     Belgium.

`BF'
     Burkina Faso.

`BG'
     Bulgaria.

`BH'
     Bahrain.

`BI'
     Burundi.

`BJ'
     Benin.

`BM'
     Bermuda.

`BN'
     Brunei.

`BO'
     Bolivia.

`BR'
     Brazil.

`BS'
     Bahamas.

`BT'
     Bhutan.

`BV'
     Bouvet Island.

`BW'
     Botswana.

`BY'
     Belarus.

`BZ'
     Belize.

`CA'
     Canada.

`CC'
     Cocos (Keeling) Islands.

`CD'
     Congo (Dem. Rep.).

`CF'
     Central African Rep..

`CG'
     Congo (Rep.).

`CH'
     Switzerland.

`CI'
     Cote d'Ivoire.

`CK'
     Cook Islands.

`CL'
     Chile.

`CM'
     Cameroon.

`CN'
     China.

`CO'
     Colombia.

`CR'
     Costa Rica.

`CU'
     Cuba.

`CV'
     Cape Verde.

`CX'
     Christmas Island.

`CY'
     Cyprus.

`CZ'
     Czech Republic.

`DE'
     Germany.

`DJ'
     Djibouti.

`DK'
     Denmark.

`DM'
     Dominica.

`DO'
     Dominican Republic.

`DZ'
     Algeria.

`EC'
     Ecuador.

`EE'
     Estonia.

`EG'
     Egypt.

`EH'
     Western Sahara.

`ER'
     Eritrea.

`ES'
     Spain.

`ET'
     Ethiopia.

`FI'
     Finland.

`FJ'
     Fiji.

`FK'
     Falkland Islands.

`FM'
     Micronesia.

`FO'
     Faeroe Islands.

`FR'
     France.

`GA'
     Gabon.

`GB'
     Britain (UK).

`GD'
     Grenada.

`GE'
     Georgia.

`GF'
     French Guiana.

`GH'
     Ghana.

`GI'
     Gibraltar.

`GL'
     Greenland.

`GM'
     Gambia.

`GN'
     Guinea.

`GP'
     Guadeloupe.

`GQ'
     Equatorial Guinea.

`GR'
     Greece.

`GS'
     South Georgia and the South Sandwich Islands.

`GT'
     Guatemala.

`GU'
     Guam.

`GW'
     Guinea-Bissau.

`GY'
     Guyana.

`HK'
     Hong Kong.

`HM'
     Heard Island and McDonald Islands.

`HN'
     Honduras.

`HR'
     Croatia.

`HT'
     Haiti.

`HU'
     Hungary.

`ID'
     Indonesia.

`IE'
     Ireland.

`IL'
     Israel.

`IN'
     India.

`IO'
     British Indian Ocean Territory.

`IQ'
     Iraq.

`IR'
     Iran.

`IS'
     Iceland.

`IT'
     Italy.

`JM'
     Jamaica.

`JO'
     Jordan.

`JP'
     Japan.

`KE'
     Kenya.

`KG'
     Kyrgyzstan.

`KH'
     Cambodia.

`KI'
     Kiribati.

`KM'
     Comoros.

`KN'
     St Kitts and Nevis.

`KP'
     Korea (North).

`KR'
     Korea (South).

`KW'
     Kuwait.

`KY'
     Cayman Islands.

`KZ'
     Kazakhstan.

`LA'
     Laos.

`LB'
     Lebanon.

`LC'
     St Lucia.

`LI'
     Liechtenstein.

`LK'
     Sri Lanka.

`LR'
     Liberia.

`LS'
     Lesotho.

`LT'
     Lithuania.

`LU'
     Luxembourg.

`LV'
     Latvia.

`LY'
     Libya.

`MA'
     Morocco.

`MC'
     Monaco.

`MD'
     Moldova.

`MG'
     Madagascar.

`MH'
     Marshall Islands.

`MK'
     Macedonia.

`ML'
     Mali.

`MM'
     Myanmar (Burma).

`MN'
     Mongolia.

`MO'
     Macao.

`MP'
     Northern Mariana Islands.

`MQ'
     Martinique.

`MR'
     Mauritania.

`MS'
     Montserrat.

`MT'
     Malta.

`MU'
     Mauritius.

`MV'
     Maldives.

`MW'
     Malawi.

`MX'
     Mexico.

`MY'
     Malaysia.

`MZ'
     Mozambique.

`NA'
     Namibia.

`NC'
     New Caledonia.

`NE'
     Niger.

`NF'
     Norfolk Island.

`NG'
     Nigeria.

`NI'
     Nicaragua.

`NL'
     Netherlands.

`NO'
     Norway.

`NP'
     Nepal.

`NR'
     Nauru.

`NU'
     Niue.

`NZ'
     New Zealand.

`OM'
     Oman.

`PA'
     Panama.

`PE'
     Peru.

`PF'
     French Polynesia.

`PG'
     Papua New Guinea.

`PH'
     Philippines.

`PK'
     Pakistan.

`PL'
     Poland.

`PM'
     St Pierre and Miquelon.

`PN'
     Pitcairn.

`PR'
     Puerto Rico.

`PS'
     Palestine.

`PT'
     Portugal.

`PW'
     Palau.

`PY'
     Paraguay.

`QA'
     Qatar.

`RE'
     Reunion.

`RO'
     Romania.

`RU'
     Russia.

`RW'
     Rwanda.

`SA'
     Saudi Arabia.

`SB'
     Solomon Islands.

`SC'
     Seychelles.

`SD'
     Sudan.

`SE'
     Sweden.

`SG'
     Singapore.

`SH'
     St Helena.

`SI'
     Slovenia.

`SJ'
     Svalbard and Jan Mayen.

`SK'
     Slovakia.

`SL'
     Sierra Leone.

`SM'
     San Marino.

`SN'
     Senegal.

`SO'
     Somalia.

`SR'
     Suriname.

`ST'
     Sao Tome and Principe.

`SV'
     El Salvador.

`SY'
     Syria.

`SZ'
     Swaziland.

`TC'
     Turks and Caicos Is.

`TD'
     Chad.

`TF'
     French Southern and Antarctic Lands.

`TG'
     Togo.

`TH'
     Thailand.

`TJ'
     Tajikistan.

`TK'
     Tokelau.

`TM'
     Turkmenistan.

`TN'
     Tunisia.

`TO'
     Tonga.

`TP'
     East Timor.

`TR'
     Turkey.

`TT'
     Trinidad and Tobago.

`TV'
     Tuvalu.

`TW'
     Taiwan.

`TZ'
     Tanzania.

`UA'
     Ukraine.

`UG'
     Uganda.

`UM'
     US minor outlying islands.

`US'
     United States.

`UY'
     Uruguay.

`UZ'
     Uzbekistan.

`VA'
     Vatican City.

`VC'
     St Vincent.

`VE'
     Venezuela.

`VG'
     Virgin Islands (UK).

`VI'
     Virgin Islands (US).

`VN'
     Vietnam.

`VU'
     Vanuatu.

`WF'
     Wallis and Futuna.

`WS'
     Samoa (Western).

`YE'
     Yemen.

`YT'
     Mayotte.

`YU'
     Yugoslavia.

`ZA'
     South Africa.

`ZM'
     Zambia.

`ZW'
     Zimbabwe.