diff options
| author | Waldemar Brodkorb <mail@waldemar-brodkorb.de> | 2013-10-03 19:52:47 +0200 |
|---|---|---|
| committer | Waldemar Brodkorb <mail@waldemar-brodkorb.de> | 2013-10-03 19:52:47 +0200 |
| commit | ae8520cfbb9cce8cfe38b00b52f202584ae1fab4 (patch) | |
| tree | f03f2553582d3647393f0c1617c74ae0438192ab /package/gettext-tiny | |
| parent | 05a7f514cca7e6858e5f5dd46cecd0c3bd6f9f71 (diff) | |
update samba to latest version, use stub gettext-tiny; use utf8 charset by default for vfat
Diffstat (limited to 'package/gettext-tiny')
| -rw-r--r-- | package/gettext-tiny/Makefile | 22 | ||||
| -rw-r--r-- | package/gettext-tiny/src/LICENSE | 21 | ||||
| -rw-r--r-- | package/gettext-tiny/src/Makefile | 73 | ||||
| -rwxr-xr-x | package/gettext-tiny/src/create-dist.sh | 21 | ||||
| -rw-r--r-- | package/gettext-tiny/src/docs/gettext.html | 18036 | ||||
| -rw-r--r-- | package/gettext-tiny/src/docs/msgfmt.txt | 74 | ||||
| -rw-r--r-- | package/gettext-tiny/src/docs/msgmerge.txt | 81 | ||||
| -rw-r--r-- | package/gettext-tiny/src/docs/xgettext.txt | 101 | ||||
| -rw-r--r-- | package/gettext-tiny/src/include/libintl.h | 61 | ||||
| -rw-r--r-- | package/gettext-tiny/src/libintl/libintl.c | 82 | ||||
| -rw-r--r-- | package/gettext-tiny/src/src/StringEscape.c | 111 | ||||
| -rw-r--r-- | package/gettext-tiny/src/src/StringEscape.h | 7 | ||||
| -rw-r--r-- | package/gettext-tiny/src/src/msgfmt.c | 278 | ||||
| -rw-r--r-- | package/gettext-tiny/src/src/msgmerge.c | 222 | ||||
| -rw-r--r-- | package/gettext-tiny/src/src/poparser.c | 144 | ||||
| -rw-r--r-- | package/gettext-tiny/src/src/poparser.h | 36 | ||||
| -rwxr-xr-x | package/gettext-tiny/src/src/xgettext.sh | 112 |
17 files changed, 19482 insertions, 0 deletions
diff --git a/package/gettext-tiny/Makefile b/package/gettext-tiny/Makefile new file mode 100644 index 000000000..a61061cd6 --- /dev/null +++ b/package/gettext-tiny/Makefile @@ -0,0 +1,22 @@ +# This file is part of the OpenADK project. OpenADK is copyrighted +# material, please see the LICENCE file in the top-level directory. + +include $(TOPDIR)/rules.mk + +PKG_NAME:= gettext-tiny +PKG_VERSION:= 0.1 +PKG_RELEASE:= 1 +PKG_DESCR:= Gettext stub and replacement +PKG_SECTION:= libs +PKG_URL:= https://github.com/rofl0r/gettext-tiny + +WRKDIST= ${WRKDIR}/${PKG_NAME}-${PKG_VERSION} +NO_DISTFILES:= 1 + +include $(TOPDIR)/mk/package.mk + +$(eval $(call PKG_template,GETTEXT_TINY,gettext-tiny,$(PKG_VERSION)-${PKG_RELEASE},${PKG_DEPENDS},${PKG_DESCR},${PKG_SECTION})) + +CONFIG_STYLE:= manual + +include ${TOPDIR}/mk/pkg-bottom.mk diff --git a/package/gettext-tiny/src/LICENSE b/package/gettext-tiny/src/LICENSE new file mode 100644 index 000000000..465ec8a88 --- /dev/null +++ b/package/gettext-tiny/src/LICENSE @@ -0,0 +1,21 @@ +Copyright (C) 2012 rofl0r + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + diff --git a/package/gettext-tiny/src/Makefile b/package/gettext-tiny/src/Makefile new file mode 100644 index 000000000..6709ad1e8 --- /dev/null +++ b/package/gettext-tiny/src/Makefile @@ -0,0 +1,73 @@ +prefix=/usr +bindir=$(prefix)/bin +includedir=$(prefix)/include +libdir=$(prefix)/lib +sysconfdir=$(prefix)/etc + +LIBSRC = $(sort $(wildcard libintl/*.c)) +PROGSRC = $(sort $(wildcard src/*.c)) + +PARSEROBJS = src/poparser.o src/StringEscape.o +PROGOBJS = $(PROGSRC:.c=.o) +LIBOBJS = $(LIBSRC:.c=.o) +OBJS = $(PROGOBJS) $(LIBOBJS) + + +HEADERS = libintl.h +ALL_INCLUDES = $(HEADERS) + +ALL_LIBS=libintl.a +ALL_TOOLS=msgfmt msgmerge xgettext + +CFLAGS?=-O0 -fPIC + +AR ?= $(CROSS_COMPILE)ar +RANLIB ?= $(CROSS_COMPILE)ranlib +CC ?= $(CROSS_COMPILE)cc + +-include config.mak + +BUILDCFLAGS=$(CFLAGS) + +all: $(ALL_LIBS) $(ALL_TOOLS) + +install: $(ALL_LIBS:lib%=$(DESTDIR)$(libdir)/lib%) $(ALL_INCLUDES:%=$(DESTDIR)$(includedir)/%) $(ALL_TOOLS:%=$(DESTDIR)$(bindir)/%) + +clean: + rm -f $(ALL_LIBS) + rm -f $(OBJS) + rm -f $(ALL_TOOLS) + +%.o: %.c + $(CC) $(BUILDCFLAGS) -c -o $@ $< + +libintl.a: $(LIBOBJS) + rm -f $@ + $(AR) rc $@ $(LIBOBJS) + $(RANLIB) $@ + +msgmerge: $(OBJS) + $(CC) $(LDFLAGS) -static -o $@ src/msgmerge.o $(PARSEROBJS) + +msgfmt: $(OBJS) + $(CC) $(LDFLAGS) -static -o $@ src/msgfmt.o $(PARSEROBJS) + +xgettext: + cp src/xgettext.sh ./xgettext + +$(DESTDIR)$(libdir)/%.a: %.a + mkdir -p $(DESTDIR)$(libdir) + install -m 755 $< $@ + +$(DESTDIR)$(includedir)/%.h: include/%.h + mkdir -p $(DESTDIR)$(includedir) + install -m 644 $< $@ + +$(DESTDIR)$(bindir)/%: % + mkdir -p $(DESTDIR)$(bindir) + install -m 755 $< $@ + +.PHONY: all clean install + + + diff --git a/package/gettext-tiny/src/create-dist.sh b/package/gettext-tiny/src/create-dist.sh new file mode 100755 index 000000000..b1d1b7a89 --- /dev/null +++ b/package/gettext-tiny/src/create-dist.sh @@ -0,0 +1,21 @@ +#!/bin/sh +if [[ -z "$VER" ]] ; then + echo set VER! + exit +fi +me=`pwd` + +proj=gettext-tiny +projver=${proj}-${VER} + +tempdir=/tmp/${proj}-0000 +rm -rf $tempdir +mkdir -p $tempdir + +cd $tempdir +git clone http://github.com/rofl0r/$proj $projver +rm -rf $projver/.git +rm -rf $projver/docs + +tar cjf $proj.tar.bz2 $projver/ +mv $proj.tar.bz2 $me/$projver.tar.bz2 diff --git a/package/gettext-tiny/src/docs/gettext.html b/package/gettext-tiny/src/docs/gettext.html new file mode 100644 index 000000000..05d4c9c43 --- /dev/null +++ b/package/gettext-tiny/src/docs/gettext.html @@ -0,0 +1,18036 @@ +<html lang="en"> +<head> +<title>GNU `gettext' utilities</title> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<meta name="description" content="GNU `gettext' utilities"> +<meta name="generator" content="makeinfo 4.13"> +<link title="Top" rel="top" href="#Top"> +<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> +<meta http-equiv="Content-Style-Type" content="text/css"> +<style type="text/css"><!-- + pre.display { font-family:inherit } + pre.format { font-family:inherit } + pre.smalldisplay { font-family:inherit; font-size:smaller } + pre.smallformat { font-family:inherit; font-size:smaller } + pre.smallexample { font-size:smaller } + pre.smalllisp { font-size:smaller } + span.sc { font-variant:small-caps } + span.roman { font-family:serif; font-weight:normal; } + span.sansserif { font-family:sans-serif; font-weight:normal; } +--></style> +</head> +<body> +<h1 class="settitle">GNU `gettext' utilities</h1> + <div class="contents"> +<h2>Table of Contents</h2> +<ul> +<li><a name="toc_Top" href="#Top">GNU <code>gettext</code> utilities</a> +<li><a name="toc_Introduction" href="#Introduction">1 Introduction</a> +<ul> +<li><a href="#Why">1.1 The Purpose of GNU <code>gettext</code></a> +<li><a href="#Concepts">1.2 I18n, L10n, and Such</a> +<li><a href="#Aspects">1.3 Aspects in Native Language Support</a> +<li><a href="#Files">1.4 Files Conveying Translations</a> +<li><a href="#Overview">1.5 Overview of GNU <code>gettext</code></a> +</li></ul> +<li><a name="toc_Users" href="#Users">2 The User's View</a> +<ul> +<li><a href="#System-Installation">2.1 Operating System Installation</a> +<li><a href="#Setting-the-GUI-Locale">2.2 Setting the Locale Used by GUI Programs</a> +<li><a href="#Setting-the-POSIX-Locale">2.3 Setting the Locale through Environment Variables</a> +<ul> +<li><a href="#Locale-Names">2.3.1 Locale Names</a> +<li><a href="#Locale-Environment-Variables">2.3.2 Locale Environment Variables</a> +<li><a href="#The-LANGUAGE-variable">2.3.3 Specifying a Priority List of Languages</a> +</li></ul> +<li><a href="#Installing-Localizations">2.4 Installing Translations for Particular Programs</a> +</li></ul> +<li><a name="toc_PO-Files" href="#PO-Files">3 The Format of PO Files</a> +<li><a name="toc_Sources" href="#Sources">4 Preparing Program Sources</a> +<ul> +<li><a href="#Importing">4.1 Importing the <code>gettext</code> declaration</a> +<li><a href="#Triggering">4.2 Triggering <code>gettext</code> Operations</a> +<li><a href="#Preparing-Strings">4.3 Preparing Translatable Strings</a> +<li><a href="#Mark-Keywords">4.4 How Marks Appear in Sources</a> +<li><a href="#Marking">4.5 Marking Translatable Strings</a> +<li><a href="#c_002dformat-Flag">4.6 Special Comments preceding Keywords</a> +<li><a href="#Special-cases">4.7 Special Cases of Translatable Strings</a> +<li><a href="#Bug-Report-Address">4.8 Letting Users Report Translation Bugs</a> +<li><a href="#Names">4.9 Marking Proper Names for Translation</a> +<li><a href="#Libraries">4.10 Preparing Library Sources</a> +</li></ul> +<li><a name="toc_Template" href="#Template">5 Making the PO Template File</a> +<ul> +<li><a href="#xgettext-Invocation">5.1 Invoking the <code>xgettext</code> Program</a> +<ul> +<li><a href="#xgettext-Invocation">5.1.1 Input file location</a> +<li><a href="#xgettext-Invocation">5.1.2 Output file location</a> +<li><a href="#xgettext-Invocation">5.1.3 Choice of input file language</a> +<li><a href="#xgettext-Invocation">5.1.4 Input file interpretation</a> +<li><a href="#xgettext-Invocation">5.1.5 Operation mode</a> +<li><a href="#xgettext-Invocation">5.1.6 Language specific options</a> +<li><a href="#xgettext-Invocation">5.1.7 Output details</a> +<li><a href="#xgettext-Invocation">5.1.8 Informative output</a> +</li></ul> +</li></ul> +<li><a name="toc_Creating" href="#Creating">6 Creating a New PO File</a> +<ul> +<li><a href="#msginit-Invocation">6.1 Invoking the <code>msginit</code> Program</a> +<ul> +<li><a href="#msginit-Invocation">6.1.1 Input file location</a> +<li><a href="#msginit-Invocation">6.1.2 Output file location</a> +<li><a href="#msginit-Invocation">6.1.3 Input file syntax</a> +<li><a href="#msginit-Invocation">6.1.4 Output details</a> +<li><a href="#msginit-Invocation">6.1.5 Informative output</a> +</li></ul> +<li><a href="#Header-Entry">6.2 Filling in the Header Entry</a> +</li></ul> +<li><a name="toc_Updating" href="#Updating">7 Updating Existing PO Files</a> +<ul> +<li><a href="#msgmerge-Invocation">7.1 Invoking the <code>msgmerge</code> Program</a> +<ul> +<li><a href="#msgmerge-Invocation">7.1.1 Input file location</a> +<li><a href="#msgmerge-Invocation">7.1.2 Operation mode</a> +<li><a href="#msgmerge-Invocation">7.1.3 Output file location</a> +<li><a href="#msgmerge-Invocation">7.1.4 Output file location in update mode</a> +<li><a href="#msgmerge-Invocation">7.1.5 Operation modifiers</a> +<li><a href="#msgmerge-Invocation">7.1.6 Input file syntax</a> +<li><a href="#msgmerge-Invocation">7.1.7 Output details</a> +<li><a href="#msgmerge-Invocation">7.1.8 Informative output</a> +</li></ul> +</li></ul> +<li><a name="toc_Editing" href="#Editing">8 Editing PO Files</a> +<ul> +<li><a href="#KBabel">8.1 KDE's PO File Editor</a> +<li><a href="#Gtranslator">8.2 GNOME's PO File Editor</a> +<li><a href="#PO-Mode">8.3 Emacs's PO File Editor</a> +<ul> +<li><a href="#Installation">8.3.1 Completing GNU <code>gettext</code> Installation</a> +<li><a href="#Main-PO-Commands">8.3.2 Main PO mode Commands</a> +<li><a href="#Entry-Positioning">8.3.3 Entry Positioning</a> +<li><a href="#Normalizing">8.3.4 Normalizing Strings in Entries</a> +<li><a href="#Translated-Entries">8.3.5 Translated Entries</a> +<li><a href="#Fuzzy-Entries">8.3.6 Fuzzy Entries</a> +<li><a href="#Untranslated-Entries">8.3.7 Untranslated Entries</a> +<li><a href="#Obsolete-Entries">8.3.8 Obsolete Entries</a> +<li><a href="#Modifying-Translations">8.3.9 Modifying Translations</a> +<li><a href="#Modifying-Comments">8.3.10 Modifying Comments</a> +<li><a href="#Subedit">8.3.11 Details of Sub Edition</a> +<li><a href="#C-Sources-Context">8.3.12 C Sources Context</a> +<li><a href="#Auxiliary">8.3.13 Consulting Auxiliary PO Files</a> +</li></ul> +<li><a href="#Compendium">8.4 Using Translation Compendia</a> +<ul> +<li><a href="#Creating-Compendia">8.4.1 Creating Compendia</a> +<ul> +<li><a href="#Creating-Compendia">8.4.1.1 Concatenate PO Files</a> +<li><a href="#Creating-Compendia">8.4.1.2 Extract a Message Subset from a PO File</a> +</li></ul> +<li><a href="#Using-Compendia">8.4.2 Using Compendia</a> +<ul> +<li><a href="#Using-Compendia">8.4.2.1 Initialize a New Translation File</a> +<li><a href="#Using-Compendia">8.4.2.2 Update an Existing Translation File</a> +</li></ul> +</li></ul> +</li></ul> +<li><a name="toc_Manipulating" href="#Manipulating">9 Manipulating PO Files</a> +<ul> +<li><a href="#msgcat-Invocation">9.1 Invoking the <code>msgcat</code> Program</a> +<ul> +<li><a href="#msgcat-Invocation">9.1.1 Input file location</a> +<li><a href="#msgcat-Invocation">9.1.2 Output file location</a> +<li><a href="#msgcat-Invocation">9.1.3 Message selection</a> +<li><a href="#msgcat-Invocation">9.1.4 Input file syntax</a> +<li><a href="#msgcat-Invocation">9.1.5 Output details</a> +<li><a href="#msgcat-Invocation">9.1.6 Informative output</a> +</li></ul> +<li><a href="#msgconv-Invocation">9.2 Invoking the <code>msgconv</code> Program</a> +<ul> +<li><a href="#msgconv-Invocation">9.2.1 Input file location</a> +<li><a href="#msgconv-Invocation">9.2.2 Output file location</a> +<li><a href="#msgconv-Invocation">9.2.3 Conversion target</a> +<li><a href="#msgconv-Invocation">9.2.4 Input file syntax</a> +<li><a href="#msgconv-Invocation">9.2.5 Output details</a> +<li><a href="#msgconv-Invocation">9.2.6 Informative output</a> +</li></ul> +<li><a href="#msggrep-Invocation">9.3 Invoking the <code>msggrep</code> Program</a> +<ul> +<li><a href="#msggrep-Invocation">9.3.1 Input file location</a> +<li><a href="#msggrep-Invocation">9.3.2 Output file location</a> +<li><a href="#msggrep-Invocation">9.3.3 Message selection</a> +<li><a href="#msggrep-Invocation">9.3.4 Input file syntax</a> +<li><a href="#msggrep-Invocation">9.3.5 Output details</a> +<li><a href="#msggrep-Invocation">9.3.6 Informative output</a> +<li><a href="#msggrep-Invocation">9.3.7 Examples</a> +</li></ul> +<li><a href="#msgfilter-Invocation">9.4 Invoking the <code>msgfilter</code> Program</a> +<ul> +<li><a href="#msgfilter-Invocation">9.4.1 Input file location</a> +<li><a href="#msgfilter-Invocation">9.4.2 Output file location</a> +<li><a href="#msgfilter-Invocation">9.4.3 The filter</a> +<li><a href="#msgfilter-Invocation">9.4.4 Useful <var>filter-option</var>s when the <var>filter</var> is ‘<samp><span class="samp">sed</span></samp>’</a> +<li><a href="#msgfilter-Invocation">9.4.5 Built-in <var>filter</var>s</a> +<li><a href="#msgfilter-Invocation">9.4.6 Input file syntax</a> +<li><a href="#msgfilter-Invocation">9.4.7 Output details</a> +<li><a href="#msgfilter-Invocation">9.4.8 Informative output</a> +<li><a href="#msgfilter-Invocation">9.4.9 Examples</a> +</li></ul> +<li><a href="#msguniq-Invocation">9.5 Invoking the <code>msguniq</code> Program</a> +<ul> +<li><a href="#msguniq-Invocation">9.5.1 Input file location</a> +<li><a href="#msguniq-Invocation">9.5.2 Output file location</a> +<li><a href="#msguniq-Invocation">9.5.3 Message selection</a> +<li><a href="#msguniq-Invocation">9.5.4 Input file syntax</a> +<li><a href="#msguniq-Invocation">9.5.5 Output details</a> +<li><a href="#msguniq-Invocation">9.5.6 Informative output</a> +</li></ul> +<li><a href="#msgcomm-Invocation">9.6 Invoking the <code>msgcomm</code> Program</a> +<ul> +<li><a href="#msgcomm-Invocation">9.6.1 Input file location</a> +<li><a href="#msgcomm-Invocation">9.6.2 Output file location</a> +<li><a href="#msgcomm-Invocation">9.6.3 Message selection</a> +<li><a href="#msgcomm-Invocation">9.6.4 Input file syntax</a> +<li><a href="#msgcomm-Invocation">9.6.5 Output details</a> +<li><a href="#msgcomm-Invocation">9.6.6 Informative output</a> +</li></ul> +<li><a href="#msgcmp-Invocation">9.7 Invoking the <code>msgcmp</code> Program</a> +<ul> +<li><a href="#msgcmp-Invocation">9.7.1 Input file location</a> +<li><a href="#msgcmp-Invocation">9.7.2 Operation modifiers</a> +<li><a href="#msgcmp-Invocation">9.7.3 Input file syntax</a> +<li><a href="#msgcmp-Invocation">9.7.4 Informative output</a> +</li></ul> +<li><a href="#msgattrib-Invocation">9.8 Invoking the <code>msgattrib</code> Program</a> +<ul> +<li><a href="#msgattrib-Invocation">9.8.1 Input file location</a> +<li><a href="#msgattrib-Invocation">9.8.2 Output file location</a> +<li><a href="#msgattrib-Invocation">9.8.3 Message selection</a> +<li><a href="#msgattrib-Invocation">9.8.4 Attribute manipulation</a> +<li><a href="#msgattrib-Invocation">9.8.5 Input file syntax</a> +<li><a href="#msgattrib-Invocation">9.8.6 Output details</a> +<li><a href="#msgattrib-Invocation">9.8.7 Informative output</a> +</li></ul> +<li><a href="#msgen-Invocation">9.9 Invoking the <code>msgen</code> Program</a> +<ul> +<li><a href="#msgen-Invocation">9.9.1 Input file location</a> +<li><a href="#msgen-Invocation">9.9.2 Output file location</a> +<li><a href="#msgen-Invocation">9.9.3 Input file syntax</a> +<li><a href="#msgen-Invocation">9.9.4 Output details</a> +<li><a href="#msgen-Invocation">9.9.5 Informative output</a> +</li></ul> +<li><a href="#msgexec-Invocation">9.10 Invoking the <code>msgexec</code> Program</a> +<ul> +<li><a href="#msgexec-Invocation">9.10.1 Input file location</a> +<li><a href="#msgexec-Invocation">9.10.2 Input file syntax</a> +<li><a href="#msgexec-Invocation">9.10.3 Informative output</a> +</li></ul> +<li><a href="#Colorizing">9.11 Highlighting parts of PO files</a> +<ul> +<li><a href="#The-_002d_002dcolor-option">9.11.1 The <code>--color</code> option</a> +<li><a href="#The-TERM-variable">9.11.2 The environment variable <code>TERM</code></a> +<li><a href="#The-_002d_002dstyle-option">9.11.3 The <code>--style</code> option</a> +<li><a href="#Style-rules">9.11.4 Style rules for PO files</a> +<li><a href="#Customizing-less">9.11.5 Customizing <code>less</code> for viewing PO files</a> +</li></ul> +<li><a href="#libgettextpo">9.12 Writing your own programs that process PO files</a> +</li></ul> +<li><a name="toc_Binaries" href="#Binaries">10 Producing Binary MO Files</a> +<ul> +<li><a href="#msgfmt-Invocation">10.1 Invoking the <code>msgfmt</code> Program</a> +<ul> +<li><a href="#msgfmt-Invocation">10.1.1 Input file location</a> +<li><a href="#msgfmt-Invocation">10.1.2 Operation mode</a> +<li><a href="#msgfmt-Invocation">10.1.3 Output file location</a> +<li><a href="#msgfmt-Invocation">10.1.4 Output file location in Java mode</a> +<li><a href="#msgfmt-Invocation">10.1.5 Output file location in C# mode</a> +<li><a href="#msgfmt-Invocation">10.1.6 Output file location in Tcl mode</a> +<li><a href="#msgfmt-Invocation">10.1.7 Input file syntax</a> +<li><a href="#msgfmt-Invocation">10.1.8 Input file interpretation</a> +<li><a href="#msgfmt-Invocation">10.1.9 Output details</a> +<li><a href="#msgfmt-Invocation">10.1.10 Informative output</a> +</li></ul> +<li><a href="#msgunfmt-Invocation">10.2 Invoking the <code>msgunfmt</code> Program</a> +<ul> +<li><a href="#msgunfmt-Invocation">10.2.1 Operation mode</a> +<li><a href="#msgunfmt-Invocation">10.2.2 Input file location</a> +<li><a href="#msgunfmt-Invocation">10.2.3 Input file location in Java mode</a> +<li><a href="#msgunfmt-Invocation">10.2.4 Input file location in C# mode</a> +<li><a href="#msgunfmt-Invocation">10.2.5 Input file location in Tcl mode</a> +<li><a href="#msgunfmt-Invocation">10.2.6 Output file location</a> +<li><a href="#msgunfmt-Invocation">10.2.7 Output details</a> +<li><a href="#msgunfmt-Invocation">10.2.8 Informative output</a> +</li></ul> +<li><a href="#MO-Files">10.3 The Format of GNU MO Files</a> +</li></ul> +<li><a name="toc_Programmers" href="#Programmers">11 The Programmer's View</a> +<ul> +<li><a href="#catgets">11.1 About <code>catgets</code></a> +<ul> +<li><a href="#Interface-to-catgets">11.1.1 The Interface</a> +<li><a href="#Problems-with-catgets">11.1.2 Problems with the <code>catgets</code> Interface?!</a> +</li></ul> +<li><a href="#gettext">11.2 About <code>gettext</code></a> +<ul> +<li><a href="#Interface-to-gettext">11.2.1 The Interface</a> +<li><a href="#Ambiguities">11.2.2 Solving Ambiguities</a> +<li><a href="#Locating-Catalogs">11.2.3 Locating Message Catalog Files</a> +<li><a href="#Charset-conversion">11.2.4 How to specify the output character set <code>gettext</code> uses</a> +<li><a href="#Contexts">11.2.5 Using contexts for solving ambiguities</a> +<li><a href="#Plural-forms">11.2.6 Additional functions for plural forms</a> +<li><a href="#Optimized-gettext">11.2.7 Optimization of the *gettext functions</a> +</li></ul> +<li><a href="#Comparison">11.3 Comparing the Two Interfaces</a> +<li><a href="#Using-libintl_002ea">11.4 Using libintl.a in own programs</a> +<li><a href="#gettext-grok">11.5 Being a <code>gettext</code> grok</a> +<li><a href="#Temp-Programmers">11.6 Temporary Notes for the Programmers Chapter</a> +<ul> +<li><a href="#Temp-Implementations">11.6.1 Temporary - Two Possible Implementations</a> +<li><a href="#Temp-catgets">11.6.2 Temporary - About <code>catgets</code></a> +<li><a href="#Temp-WSI">11.6.3 Temporary - Why a single implementation</a> +<li><a href="#Temp-Notes">11.6.4 Temporary - Notes</a> +</li></ul> +</li></ul> +<li><a name="toc_Translators" href="#Translators">12 The Translator's View</a> +<ul> +<li><a href="#Trans-Intro-0">12.1 Introduction 0</a> +<li><a href="#Trans-Intro-1">12.2 Introduction 1</a> +<li><a href="#Discussions">12.3 Discussions</a> +<li><a href="#Organization">12.4 Organization</a> +<ul> +<li><a href="#Central-Coordination">12.4.1 Central Coordination</a> +<li><a href="#National-Teams">12.4.2 National Teams</a> +<ul> +<li><a href="#Sub_002dCultures">12.4.2.1 Sub-Cultures</a> +<li><a href="#Organizational-Ideas">12.4.2.2 Organizational Ideas</a> +</li></ul> +<li><a href="#Mailing-Lists">12.4.3 Mailing Lists</a> +</li></ul> +<li><a href="#Information-Flow">12.5 Information Flow</a> +<li><a href="#Translating-plural-forms">12.6 Translating plural forms</a> +<li><a href="#Prioritizing-messages">12.7 Prioritizing messages: How to determine which messages to translate first</a> +</li></ul> +<li><a name="toc_Maintainers" href="#Maintainers">13 The Maintainer's View</a> +<ul> +<li><a href="#Flat-and-Non_002dFlat">13.1 Flat or Non-Flat Directory Structures</a> +<li><a href="#Prerequisites">13.2 Prerequisite Works</a> +<li><a href="#gettextize-Invocation">13.3 Invoking the <code>gettextize</code> Program</a> +<li><a href="#Adjusting-Files">13.4 Files You Must Create or Alter</a> +<ul> +<li><a href="#po_002fPOTFILES_002ein">13.4.1 <samp><span class="file">POTFILES.in</span></samp> in <samp><span class="file">po/</span></samp></a> +<li><a href="#po_002fLINGUAS">13.4.2 <samp><span class="file">LINGUAS</span></samp> in <samp><span class="file">po/</span></samp></a> +<li><a href="#po_002fMakevars">13.4.3 <samp><span class="file">Makevars</span></samp> in <samp><span class="file">po/</span></samp></a> +<li><a href="#po_002fRules_002d_002a">13.4.4 Extending <samp><span class="file">Makefile</span></samp> in <samp><span class="file">po/</span></samp></a> +<li><a href="#configure_002eac">13.4.5 <samp><span class="file">configure.ac</span></samp> at top level</a> +<li><a href="#config_002eguess">13.4.6 <samp><span class="file">config.guess</span></samp>, <samp><span class="file">config.sub</span></samp> at top level</a> +<li><a href="#mkinstalldirs">13.4.7 <samp><span class="file">mkinstalldirs</span></samp> at top level</a> +<li><a href="#aclocal">13.4.8 <samp><span class="file">aclocal.m4</span></samp> at top level</a> +<li><a href="#acconfig">13.4.9 <samp><span class="file">acconfig.h</span></samp> at top level</a> +<li><a href="#config_002eh_002ein">13.4.10 <samp><span class="file">config.h.in</span></samp> at top level</a> +<li><a href="#Makefile">13.4.11 <samp><span class="file">Makefile.in</span></samp> at top level</a> +<li><a href="#src_002fMakefile">13.4.12 <samp><span class="file">Makefile.in</span></samp> in <samp><span class="file">src/</span></samp></a> +<li><a href="#lib_002fgettext_002eh">13.4.13 <samp><span class="file">gettext.h</span></samp> in <samp><span class="file">lib/</span></samp></a> +</li></ul> +<li><a href="#autoconf-macros">13.5 Autoconf macros for use in <samp><span class="file">configure.ac</span></samp></a> +<ul> +<li><a href="#AM_005fGNU_005fGETTEXT">13.5.1 AM_GNU_GETTEXT in <samp><span class="file">gettext.m4</span></samp></a> +<li><a href="#AM_005fGNU_005fGETTEXT_005fVERSION">13.5.2 AM_GNU_GETTEXT_VERSION in <samp><span class="file">gettext.m4</span></samp></a> +<li><a href="#AM_005fGNU_005fGETTEXT_005fNEED">13.5.3 AM_GNU_GETTEXT_NEED in <samp><span class="file">gettext.m4</span></samp></a> +<li><a href="#AM_005fGNU_005fGETTEXT_005fINTL_005fSUBDIR">13.5.4 AM_GNU_GETTEXT_INTL_SUBDIR in <samp><span class="file">intldir.m4</span></samp></a> +<li><a href="#AM_005fPO_005fSUBDIRS">13.5.5 AM_PO_SUBDIRS in <samp><span class="file">po.m4</span></samp></a> +<li><a href="#AM_005fXGETTEXT_005fOPTION">13.5.6 AM_XGETTEXT_OPTION in <samp><span class="file">po.m4</span></samp></a> +<li><a href="#AM_005fICONV">13.5.7 AM_ICONV in <samp><span class="file">iconv.m4</span></samp></a> +</li></ul> +<li><a href="#CVS-Issues">13.6 Integrating with CVS</a> +<ul> +<li><a href="#Distributed-CVS">13.6.1 Avoiding version mismatch in distributed development</a> +<li><a href="#Files-under-CVS">13.6.2 Files to put under CVS version control</a> +<li><a href="#autopoint-Invocation">13.6.3 Invoking the <code>autopoint</code> Program</a> +<ul> +<li><a href="#autopoint-Invocation">13.6.3.1 Options</a> +<li><a href="#autopoint-Invocation">13.6.3.2 Informative output</a> +</li></ul> +</li></ul> +<li><a href="#Release-Management">13.7 Creating a Distribution Tarball</a> +</li></ul> +<li><a name="toc_Installers" href="#Installers">14 The Installer's and Distributor's View</a> +<li><a name="toc_Programming-Languages" href="#Programming-Languages">15 Other Programming Languages</a> +<ul> +<li><a href="#Language-Implementors">15.1 The Language Implementor's View</a> +<li><a href="#Programmers-for-other-Languages">15.2 The Programmer's View</a> +<li><a href="#Translators-for-other-Languages">15.3 The Translator's View</a> +<ul> +<li><a href="#c_002dformat">15.3.1 C Format Strings</a> +<li><a href="#objc_002dformat">15.3.2 Objective C Format Strings</a> +<li><a href="#sh_002dformat">15.3.3 Shell Format Strings</a> +<li><a href="#python_002dformat">15.3.4 Python Format Strings</a> +<li><a href="#lisp_002dformat">15.3.5 Lisp Format Strings</a> +<li><a href="#elisp_002dformat">15.3.6 Emacs Lisp Format Strings</a> +<li><a href="#librep_002dformat">15.3.7 librep Format Strings</a> +<li><a href="#scheme_002dformat">15.3.8 Scheme Format Strings</a> +<li><a href="#smalltalk_002dformat">15.3.9 Smalltalk Format Strings</a> +<li><a href="#java_002dformat">15.3.10 Java Format Strings</a> +<li><a href="#csharp_002dformat">15.3.11 C# Format Strings</a> +<li><a href="#awk_002dformat">15.3.12 awk Format Strings</a> +<li><a href="#object_002dpascal_002dformat">15.3.13 Object Pascal Format Strings</a> +<li><a href="#ycp_002dformat">15.3.14 YCP Format Strings</a> +<li><a href="#tcl_002dformat">15.3.15 Tcl Format Strings</a> +<li><a href="#perl_002dformat">15.3.16 Perl Format Strings</a> +<li><a href="#php_002dformat">15.3.17 PHP Format Strings</a> +<li><a href="#gcc_002dinternal_002dformat">15.3.18 GCC internal Format Strings</a> +<li><a href="#gfc_002dinternal_002dformat">15.3.19 GFC internal Format Strings</a> +<li><a href="#qt_002dformat">15.3.20 Qt Format Strings</a> +<li><a href="#qt_002dplural_002dformat">15.3.21 Qt Format Strings</a> +<li><a href="#kde_002dformat">15.3.22 KDE Format Strings</a> +<li><a href="#boost_002dformat">15.3.23 Boost Format Strings</a> +</li></ul> +<li><a href="#Maintainers-for-other-Languages">15.4 The Maintainer's View</a> +<li><a href="#List-of-Programming-Languages">15.5 Individual Programming Languages</a> +<ul> +<li><a href="#C">15.5.1 C, C++, Objective C</a> +<li><a href="#sh">15.5.2 sh - Shell Script</a> +<ul> +<li><a href="#Preparing-Shell-Scripts">15.5.2.1 Preparing Shell Scripts for Internationalization</a> +<li><a href="#gettext_002esh">15.5.2.2 Contents of <code>gettext.sh</code></a> +<li><a href="#gettext-Invocation">15.5.2.3 Invoking the <code>gettext</code> program</a> +<li><a href="#ngettext-Invocation">15.5.2.4 Invoking the <code>ngettext</code> program</a> +<li><a href="#envsubst-Invocation">15.5.2.5 Invoking the <code>envsubst</code> program</a> +<li><a href="#eval_005fgettext-Invocation">15.5.2.6 Invoking the <code>eval_gettext</code> function</a> +<li><a href="#eval_005fngettext-Invocation">15.5.2.7 Invoking the <code>eval_ngettext</code> function</a> +</li></ul> +<li><a href="#bash">15.5.3 bash - Bourne-Again Shell Script</a> +<li><a href="#Python">15.5.4 Python</a> +<li><a href="#Common-Lisp">15.5.5 GNU clisp - Common Lisp</a> +<li><a href="#clisp-C">15.5.6 GNU clisp C sources</a> +<li><a href="#Emacs-Lisp">15.5.7 Emacs Lisp</a> +<li><a href="#librep">15.5.8 librep</a> +<li><a href="#Scheme">15.5.9 GNU guile - Scheme</a> +<li><a href="#Smalltalk">15.5.10 GNU Smalltalk</a> +<li><a href="#Java">15.5.11 Java</a> +<li><a href="#C_0023">15.5.12 C#</a> +<li><a href="#gawk">15.5.13 GNU awk</a> +<li><a href="#Pascal">15.5.14 Pascal - Free Pascal Compiler</a> +<li><a href="#wxWidgets">15.5.15 wxWidgets library</a> +<li><a href="#YCP">15.5.16 YCP - YaST2 scripting language</a> +<li><a href="#Tcl">15.5.17 Tcl - Tk's scripting language</a> +<li><a href="#Perl">15.5.18 Perl</a> +<ul> +<li><a href="#General-Problems">15.5.18.1 General Problems Parsing Perl Code</a> +<li><a href="#Default-Keywords">15.5.18.2 Which keywords will xgettext look for?</a> +<li><a href="#Special-Keywords">15.5.18.3 How to Extract Hash Keys</a> +<li><a href="#Quote_002dlike-Expressions">15.5.18.4 What are Strings And Quote-like Expressions?</a> +<li><a href="#Interpolation-I">15.5.18.5 Invalid Uses Of String Interpolation</a> +<li><a href="#Interpolation-II">15.5.18.6 Valid Uses Of String Interpolation</a> +<li><a href="#Parentheses">15.5.18.7 When To Use Parentheses</a> +<li><a href="#Long-Lines">15.5.18.8 How To Grok with Long Lines</a> +<li><a href="#Perl-Pitfalls">15.5.18.9 Bugs, Pitfalls, And Things That Do Not Work</a> +</li></ul> +<li><a href="#PHP">15.5.19 PHP Hypertext Preprocessor</a> +<li><a href="#Pike">15.5.20 Pike</a> +<li><a href="#GCC_002dsource">15.5.21 GNU Compiler Collection sources</a> +</li></ul> +<li><a href="#List-of-Data-Formats">15.6 Internationalizable Data</a> +<ul> +<li><a href="#POT">15.6.1 POT - Portable Object Template</a> +<li><a href="#RST">15.6.2 Resource String Table</a> +<li><a href="#Glade">15.6.3 Glade - GNOME user interface description</a> +</li></ul> +</li></ul> +<li><a name="toc_Conclusion" href="#Conclusion">16 Concluding Remarks</a> +<ul> +<li><a href="#History">16.1 History of GNU <code>gettext</code></a> +<li><a href="#References">16.2 Related Readings</a> +</li></ul> +<li><a name="toc_Language-Codes" href="#Language-Codes">Appendix A Language Codes</a> +<ul> +<li><a href="#Usual-Language-Codes">A.1 Usual Language Codes</a> +<li><a href="#Rare-Language-Codes">A.2 Rare Language Codes</a> +</li></ul> +<li><a name="toc_Country-Codes" href="#Country-Codes">Appendix B Country Codes</a> +<li><a name="toc_Licenses" href="#Licenses">Appendix C Licenses</a> +<ul> +<li><a href="#GNU-GPL">C.1 GNU GENERAL PUBLIC LICENSE</a> +<ul> +<li><a href="#GNU-GPL">Preamble</a> +<li><a href="#GNU-GPL">Appendix: How to Apply These Terms to Your New Programs</a> +</li></ul> +<li><a href="#GNU-LGPL">C.2 GNU LESSER GENERAL PUBLIC LICENSE</a> +<ul> +<li><a href="#GNU-LGPL">Preamble</a> +<li><a href="#GNU-LGPL">How to Apply These Terms to Your New Libraries</a> +</li></ul> +<li><a href="#GNU-FDL">C.3 GNU Free Documentation License</a> +<ul> +<li><a href="#GNU-FDL">ADDENDUM: How to use this License for your documents</a> +</li></ul> +</li></ul> +<li><a name="toc_Program-Index" href="#Program-Index">Program Index</a> +<li><a name="toc_Option-Index" href="#Option-Index">Option Index</a> +<li><a name="toc_Variable-Index" href="#Variable-Index">Variable Index</a> +<li><a name="toc_PO-Mode-Index" href="#PO-Mode-Index">PO Mode Index</a> +<li><a name="toc_Autoconf-Macro-Index" href="#Autoconf-Macro-Index">Autoconf Macro Index</a> +<li><a name="toc_Index" href="#Index">General Index</a> +</li></ul> +</div> + + + +<div class="node"> +<a name="Top"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Introduction">Introduction</a>, +Previous: <a rel="previous" accesskey="p" href="#dir">(dir)</a>, +Up: <a rel="up" accesskey="u" href="#dir">(dir)</a> + +</div> + +<h2 class="unnumbered">GNU <code>gettext</code> utilities</h2> + + <p>This manual documents the GNU gettext tools and the GNU libintl library, +version 0.18. + +<ul class="menu"> +<li><a accesskey="1" href="#Introduction">Introduction</a>: Introduction +<li><a accesskey="2" href="#Users">Users</a>: The User's View +<li><a accesskey="3" href="#PO-Files">PO Files</a>: The Format of PO Files +<li><a accesskey="4" href="#Sources">Sources</a>: Preparing Program Sources +<li><a accesskey="5" href="#Template">Template</a>: Making the PO Template File +<li><a accesskey="6" href="#Creating">Creating</a>: Creating a New PO File +<li><a accesskey="7" href="#Updating">Updating</a>: Updating Existing PO Files +<li><a accesskey="8" href="#Editing">Editing</a>: Editing PO Files +<li><a accesskey="9" href="#Manipulating">Manipulating</a>: Manipulating PO Files +<li><a href="#Binaries">Binaries</a>: Producing Binary MO Files +<li><a href="#Programmers">Programmers</a>: The Programmer's View +<li><a href="#Translators">Translators</a>: The Translator's View +<li><a href="#Maintainers">Maintainers</a>: The Maintainer's View +<li><a href="#Installers">Installers</a>: The Installer's and Distributor's View +<li><a href="#Programming-Languages">Programming Languages</a>: Other Programming Languages +<li><a href="#Conclusion">Conclusion</a>: Concluding Remarks + +<li><a href="#Language-Codes">Language Codes</a>: ISO 639 language codes +<li><a href="#Country-Codes">Country Codes</a>: ISO 3166 country codes +<li><a href="#Licenses">Licenses</a>: Licenses + +<li><a href="#Program-Index">Program Index</a>: Index of Programs +<li><a href="#Option-Index">Option Index</a>: Index of Command-Line Options +<li><a href="#Variable-Index">Variable Index</a>: Index of Environment Variables +<li><a href="#PO-Mode-Index">PO Mode Index</a>: Index of Emacs PO Mode Commands +<li><a href="#Autoconf-Macro-Index">Autoconf Macro Index</a>: Index of Autoconf Macros +<li><a href="#Index">Index</a>: General Index + +</li></ul> +<p>--- The Detailed Node Listing --- + +<p>Introduction + +</p> +<ul class="menu"> +<li><a href="#Why">Why</a>: The Purpose of GNU <code>gettext</code> +<li><a href="#Concepts">Concepts</a>: I18n, L10n, and Such +<li><a href="#Aspects">Aspects</a>: Aspects in Native Language Support +<li><a href="#Files">Files</a>: Files Conveying Translations +<li><a href="#Overview">Overview</a>: Overview of GNU <code>gettext</code> + +</li></ul> +<p>The User's View + +</p> +<ul class="menu"> +<li><a href="#System-Installation">System Installation</a>: Questions During Operating System Installation +<li><a href="#Setting-the-GUI-Locale">Setting the GUI Locale</a>: How to Specify the Locale Used by GUI Programs +<li><a href="#Setting-the-POSIX-Locale">Setting the POSIX Locale</a>: How to Specify the Locale According to POSIX +<li><a href="#Installing-Localizations">Installing Localizations</a>: How to Install Additional Translations + +</li></ul> +<p>Setting the POSIX Locale + +</p> +<ul class="menu"> +<li><a href="#Locale-Names">Locale Names</a>: How a Locale Specification Looks Like +<li><a href="#Locale-Environment-Variables">Locale Environment Variables</a>: Which Environment Variable Specfies What +<li><a href="#The-LANGUAGE-variable">The LANGUAGE variable</a>: How to Specify a Priority List of Languages + +</li></ul> +<p>Preparing Program Sources + +</p> +<ul class="menu"> +<li><a href="#Importing">Importing</a>: Importing the <code>gettext</code> declaration +<li><a href="#Triggering">Triggering</a>: Triggering <code>gettext</code> Operations +<li><a href="#Preparing-Strings">Preparing Strings</a>: Preparing Translatable Strings +<li><a href="#Mark-Keywords">Mark Keywords</a>: How Marks Appear in Sources +<li><a href="#Marking">Marking</a>: Marking Translatable Strings +<li><a href="#c_002dformat-Flag">c-format Flag</a>: Telling something about the following string +<li><a href="#Special-cases">Special cases</a>: Special Cases of Translatable Strings +<li><a href="#Bug-Report-Address">Bug Report Address</a>: Letting Users Report Translation Bugs +<li><a href="#Names">Names</a>: Marking Proper Names for Translation +<li><a href="#Libraries">Libraries</a>: Preparing Library Sources + +</li></ul> +<p>Making the PO Template File + +</p> +<ul class="menu"> +<li><a href="#xgettext-Invocation">xgettext Invocation</a>: Invoking the <code>xgettext</code> Program + +</li></ul> +<p>Creating a New PO File + +</p> +<ul class="menu"> +<li><a href="#msginit-Invocation">msginit Invocation</a>: Invoking the <code>msginit</code> Program +<li><a href="#Header-Entry">Header Entry</a>: Filling in the Header Entry + +</li></ul> +<p>Updating Existing PO Files + +</p> +<ul class="menu"> +<li><a href="#msgmerge-Invocation">msgmerge Invocation</a>: Invoking the <code>msgmerge</code> Program + +</li></ul> +<p>Editing PO Files + +</p> +<ul class="menu"> +<li><a href="#KBabel">KBabel</a>: KDE's PO File Editor +<li><a href="#Gtranslator">Gtranslator</a>: GNOME's PO File Editor +<li><a href="#PO-Mode">PO Mode</a>: Emacs's PO File Editor +<li><a href="#Compendium">Compendium</a>: Using Translation Compendia + +</li></ul> +<p>Emacs's PO File Editor + +</p> +<ul class="menu"> +<li><a href="#Installation">Installation</a>: Completing GNU <code>gettext</code> Installation +<li><a href="#Main-PO-Commands">Main PO Commands</a>: Main Commands +<li><a href="#Entry-Positioning">Entry Positioning</a>: Entry Positioning +<li><a href="#Normalizing">Normalizing</a>: Normalizing Strings in Entries +<li><a href="#Translated-Entries">Translated Entries</a>: Translated Entries +<li><a href="#Fuzzy-Entries">Fuzzy Entries</a>: Fuzzy Entries +<li><a href="#Untranslated-Entries">Untranslated Entries</a>: Untranslated Entries +<li><a href="#Obsolete-Entries">Obsolete Entries</a>: Obsolete Entries +<li><a href="#Modifying-Translations">Modifying Translations</a>: Modifying Translations +<li><a href="#Modifying-Comments">Modifying Comments</a>: Modifying Comments +<li><a href="#Subedit">Subedit</a>: Mode for Editing Translations +<li><a href="#C-Sources-Context">C Sources Context</a>: C Sources Context +<li><a href="#Auxiliary">Auxiliary</a>: Consulting Auxiliary PO Files + +</li></ul> +<p>Using Translation Compendia + +</p> +<ul class="menu"> +<li><a href="#Creating-Compendia">Creating Compendia</a>: Merging translations for later use +<li><a href="#Using-Compendia">Using Compendia</a>: Using older translations if they fit + +</li></ul> +<p>Manipulating PO Files + +</p> +<ul class="menu"> +<li><a href="#msgcat-Invocation">msgcat Invocation</a>: Invoking the <code>msgcat</code> Program +<li><a href="#msgconv-Invocation">msgconv Invocation</a>: Invoking the <code>msgconv</code> Program +<li><a href="#msggrep-Invocation">msggrep Invocation</a>: Invoking the <code>msggrep</code> Program +<li><a href="#msgfilter-Invocation">msgfilter Invocation</a>: Invoking the <code>msgfilter</code> Program +<li><a href="#msguniq-Invocation">msguniq Invocation</a>: Invoking the <code>msguniq</code> Program +<li><a href="#msgcomm-Invocation">msgcomm Invocation</a>: Invoking the <code>msgcomm</code> Program +<li><a href="#msgcmp-Invocation">msgcmp Invocation</a>: Invoking the <code>msgcmp</code> Program +<li><a href="#msgattrib-Invocation">msgattrib Invocation</a>: Invoking the <code>msgattrib</code> Program +<li><a href="#msgen-Invocation">msgen Invocation</a>: Invoking the <code>msgen</code> Program +<li><a href="#msgexec-Invocation">msgexec Invocation</a>: Invoking the <code>msgexec</code> Program +<li><a href="#Colorizing">Colorizing</a>: Highlighting parts of PO files +<li><a href="#libgettextpo">libgettextpo</a>: Writing your own programs that process PO files + +</li></ul> +<p>Highlighting parts of PO files + +</p> +<ul class="menu"> +<li><a href="#The-_002d_002dcolor-option">The --color option</a>: Triggering colorized output +<li><a href="#The-TERM-variable">The TERM variable</a>: The environment variable <code>TERM</code> +<li><a href="#The-_002d_002dstyle-option">The --style option</a>: The <code>--style</code> option +<li><a href="#Style-rules">Style rules</a>: Style rules for PO files +<li><a href="#Customizing-less">Customizing less</a>: Customizing <code>less</code> for viewing PO files + +</li></ul> +<p>Producing Binary MO Files + +</p> +<ul class="menu"> +<li><a href="#msgfmt-Invocation">msgfmt Invocation</a>: Invoking the <code>msgfmt</code> Program +<li><a href="#msgunfmt-Invocation">msgunfmt Invocation</a>: Invoking the <code>msgunfmt</code> Program +<li><a href="#MO-Files">MO Files</a>: The Format of GNU MO Files + +</li></ul> +<p>The Programmer's View + +</p> +<ul class="menu"> +<li><a href="#catgets">catgets</a>: About <code>catgets</code> +<li><a href="#gettext">gettext</a>: About <code>gettext</code> +<li><a href="#Comparison">Comparison</a>: Comparing the two interfaces +<li><a href="#Using-libintl_002ea">Using libintl.a</a>: Using libintl.a in own programs +<li><a href="#gettext-grok">gettext grok</a>: Being a <code>gettext</code> grok +<li><a href="#Temp-Programmers">Temp Programmers</a>: Temporary Notes for the Programmers Chapter + +</li></ul> +<p>About <code>catgets</code> + +</p> +<ul class="menu"> +<li><a href="#Interface-to-catgets">Interface to catgets</a>: The interface +<li><a href="#Problems-with-catgets">Problems with catgets</a>: Problems with the <code>catgets</code> interface?! + +</li></ul> +<p>About <code>gettext</code> + +</p> +<ul class="menu"> +<li><a href="#Interface-to-gettext">Interface to gettext</a>: The interface +<li><a href="#Ambiguities">Ambiguities</a>: Solving ambiguities +<li><a href="#Locating-Catalogs">Locating Catalogs</a>: Locating message catalog files +<li><a href="#Charset-conversion">Charset conversion</a>: How to request conversion to Unicode +<li><a href="#Contexts">Contexts</a>: Solving ambiguities in GUI programs +<li><a href="#Plural-forms">Plural forms</a>: Additional functions for handling plurals +<li><a href="#Optimized-gettext">Optimized gettext</a>: Optimization of the *gettext functions + +</li></ul> +<p>Temporary Notes for the Programmers Chapter + +</p> +<ul class="menu"> +<li><a href="#Temp-Implementations">Temp Implementations</a>: Temporary - Two Possible Implementations +<li><a href="#Temp-catgets">Temp catgets</a>: Temporary - About <code>catgets</code> +<li><a href="#Temp-WSI">Temp WSI</a>: Temporary - Why a single implementation +<li><a href="#Temp-Notes">Temp Notes</a>: Temporary - Notes + +</li></ul> +<p>The Translator's View + +</p> +<ul class="menu"> +<li><a href="#Trans-Intro-0">Trans Intro 0</a>: Introduction 0 +<li><a href="#Trans-Intro-1">Trans Intro 1</a>: Introduction 1 +<li><a href="#Discussions">Discussions</a>: Discussions +<li><a href="#Organization">Organization</a>: Organization +<li><a href="#Information-Flow">Information Flow</a>: Information Flow +<li><a href="#Translating-plural-forms">Translating plural forms</a>: How to fill in <code>msgstr[0]</code>, <code>msgstr[1]</code> +<li><a href="#Prioritizing-messages">Prioritizing messages</a>: How to find which messages to translate first + +</li></ul> +<p>Organization + +</p> +<ul class="menu"> +<li><a href="#Central-Coordination">Central Coordination</a>: Central Coordination +<li><a href="#National-Teams">National Teams</a>: National Teams +<li><a href="#Mailing-Lists">Mailing Lists</a>: Mailing Lists + +</li></ul> +<p>National Teams + +</p> +<ul class="menu"> +<li><a href="#Sub_002dCultures">Sub-Cultures</a>: Sub-Cultures +<li><a href="#Organizational-Ideas">Organizational Ideas</a>: Organizational Ideas + +</li></ul> +<p>The Maintainer's View + +</p> +<ul class="menu"> +<li><a href="#Flat-and-Non_002dFlat">Flat and Non-Flat</a>: Flat or Non-Flat Directory Structures +<li><a href="#Prerequisites">Prerequisites</a>: Prerequisite Works +<li><a href="#gettextize-Invocation">gettextize Invocation</a>: Invoking the <code>gettextize</code> Program +<li><a href="#Adjusting-Files">Adjusting Files</a>: Files You Must Create or Alter +<li><a href="#autoconf-macros">autoconf macros</a>: Autoconf macros for use in <samp><span class="file">configure.ac</span></samp> +<li><a href="#CVS-Issues">CVS Issues</a>: Integrating with CVS +<li><a href="#Release-Management">Release Management</a>: Creating a Distribution Tarball + +</li></ul> +<p>Files You Must Create or Alter + +</p> +<ul class="menu"> +<li><a href="#po_002fPOTFILES_002ein">po/POTFILES.in</a>: <samp><span class="file">POTFILES.in</span></samp> in <samp><span class="file">po/</span></samp> +<li><a href="#po_002fLINGUAS">po/LINGUAS</a>: <samp><span class="file">LINGUAS</span></samp> in <samp><span class="file">po/</span></samp> +<li><a href="#po_002fMakevars">po/Makevars</a>: <samp><span class="file">Makevars</span></samp> in <samp><span class="file">po/</span></samp> +<li><a href="#po_002fRules_002d_002a">po/Rules-*</a>: Extending <samp><span class="file">Makefile</span></samp> in <samp><span class="file">po/</span></samp> +<li><a href="#configure_002eac">configure.ac</a>: <samp><span class="file">configure.ac</span></samp> at top level +<li><a href="#config_002eguess">config.guess</a>: <samp><span class="file">config.guess</span></samp>, <samp><span class="file">config.sub</span></samp> at top level +<li><a href="#mkinstalldirs">mkinstalldirs</a>: <samp><span class="file">mkinstalldirs</span></samp> at top level +<li><a href="#aclocal">aclocal</a>: <samp><span class="file">aclocal.m4</span></samp> at top level +<li><a href="#acconfig">acconfig</a>: <samp><span class="file">acconfig.h</span></samp> at top level +<li><a href="#config_002eh_002ein">config.h.in</a>: <samp><span class="file">config.h.in</span></samp> at top level +<li><a href="#Makefile">Makefile</a>: <samp><span class="file">Makefile.in</span></samp> at top level +<li><a href="#src_002fMakefile">src/Makefile</a>: <samp><span class="file">Makefile.in</span></samp> in <samp><span class="file">src/</span></samp> +<li><a href="#lib_002fgettext_002eh">lib/gettext.h</a>: <samp><span class="file">gettext.h</span></samp> in <samp><span class="file">lib/</span></samp> + +</li></ul> +<p>Autoconf macros for use in <samp><span class="file">configure.ac</span></samp> + +</p> +<ul class="menu"> +<li><a href="#AM_005fGNU_005fGETTEXT">AM_GNU_GETTEXT</a>: AM_GNU_GETTEXT in <samp><span class="file">gettext.m4</span></samp> +<li><a href="#AM_005fGNU_005fGETTEXT_005fVERSION">AM_GNU_GETTEXT_VERSION</a>: AM_GNU_GETTEXT_VERSION in <samp><span class="file">gettext.m4</span></samp> +<li><a href="#AM_005fGNU_005fGETTEXT_005fNEED">AM_GNU_GETTEXT_NEED</a>: AM_GNU_GETTEXT_NEED in <samp><span class="file">gettext.m4</span></samp> +<li><a href="#AM_005fGNU_005fGETTEXT_005fINTL_005fSUBDIR">AM_GNU_GETTEXT_INTL_SUBDIR</a>: AM_GNU_GETTEXT_INTL_SUBDIR in <samp><span class="file">intldir.m4</span></samp> +<li><a href="#AM_005fPO_005fSUBDIRS">AM_PO_SUBDIRS</a>: AM_PO_SUBDIRS in <samp><span class="file">po.m4</span></samp> +<li><a href="#AM_005fICONV">AM_ICONV</a>: AM_ICONV in <samp><span class="file">iconv.m4</span></samp> + +</li></ul> +<p>Integrating with CVS + +</p> +<ul class="menu"> +<li><a href="#Distributed-CVS">Distributed CVS</a>: Avoiding version mismatch in distributed development +<li><a href="#Files-under-CVS">Files under CVS</a>: Files to put under CVS version control +<li><a href="#autopoint-Invocation">autopoint Invocation</a>: Invoking the <code>autopoint</code> Program + +</li></ul> +<p>Other Programming Languages + +</p> +<ul class="menu"> +<li><a href="#Language-Implementors">Language Implementors</a>: The Language Implementor's View +<li><a href="#Programmers-for-other-Languages">Programmers for other Languages</a>: The Programmer's View +<li><a href="#Translators-for-other-Languages">Translators for other Languages</a>: The Translator's View +<li><a href="#Maintainers-for-other-Languages">Maintainers for other Languages</a>: The Maintainer's View +<li><a href="#List-of-Programming-Languages">List of Programming Languages</a>: Individual Programming Languages +<li><a href="#List-of-Data-Formats">List of Data Formats</a>: Internationalizable Data + +</li></ul> +<p>The Translator's View + +</p> +<ul class="menu"> +<li><a href="#c_002dformat">c-format</a>: C Format Strings +<li><a href="#objc_002dformat">objc-format</a>: Objective C Format Strings +<li><a href="#sh_002dformat">sh-format</a>: Shell Format Strings +<li><a href="#python_002dformat">python-format</a>: Python Format Strings +<li><a href="#lisp_002dformat">lisp-format</a>: Lisp Format Strings +<li><a href="#elisp_002dformat">elisp-format</a>: Emacs Lisp Format Strings +<li><a href="#librep_002dformat">librep-format</a>: librep Format Strings +<li><a href="#scheme_002dformat">scheme-format</a>: Scheme Format Strings +<li><a href="#smalltalk_002dformat">smalltalk-format</a>: Smalltalk Format Strings +<li><a href="#java_002dformat">java-format</a>: Java Format Strings +<li><a href="#csharp_002dformat">csharp-format</a>: C# Format Strings +<li><a href="#awk_002dformat">awk-format</a>: awk Format Strings +<li><a href="#object_002dpascal_002dformat">object-pascal-format</a>: Object Pascal Format Strings +<li><a href="#ycp_002dformat">ycp-format</a>: YCP Format Strings +<li><a href="#tcl_002dformat">tcl-format</a>: Tcl Format Strings +<li><a href="#perl_002dformat">perl-format</a>: Perl Format Strings +<li><a href="#php_002dformat">php-format</a>: PHP Format Strings +<li><a href="#gcc_002dinternal_002dformat">gcc-internal-format</a>: GCC internal Format Strings +<li><a href="#gfc_002dinternal_002dformat">gfc-internal-format</a>: GFC internal Format Strings +<li><a href="#qt_002dformat">qt-format</a>: Qt Format Strings +<li><a href="#qt_002dplural_002dformat">qt-plural-format</a>: Qt Plural Format Strings +<li><a href="#kde_002dformat">kde-format</a>: KDE Format Strings +<li><a href="#boost_002dformat">boost-format</a>: Boost Format Strings + +</li></ul> +<p>Individual Programming Languages + +</p> +<ul class="menu"> +<li><a href="#C">C</a>: C, C++, Objective C +<li><a href="#sh">sh</a>: sh - Shell Script +<li><a href="#bash">bash</a>: bash - Bourne-Again Shell Script +<li><a href="#Python">Python</a>: Python +<li><a href="#Common-Lisp">Common Lisp</a>: GNU clisp - Common Lisp +<li><a href="#clisp-C">clisp C</a>: GNU clisp C sources +<li><a href="#Emacs-Lisp">Emacs Lisp</a>: Emacs Lisp +<li><a href="#librep">librep</a>: librep +<li><a href="#Scheme">Scheme</a>: GNU guile - Scheme +<li><a href="#Smalltalk">Smalltalk</a>: GNU Smalltalk +<li><a href="#Java">Java</a>: Java +<li><a href="#C_0023">C#</a>: C# +<li><a href="#gawk">gawk</a>: GNU awk +<li><a href="#Pascal">Pascal</a>: Pascal - Free Pascal Compiler +<li><a href="#wxWidgets">wxWidgets</a>: wxWidgets library +<li><a href="#YCP">YCP</a>: YCP - YaST2 scripting language +<li><a href="#Tcl">Tcl</a>: Tcl - Tk's scripting language +<li><a href="#Perl">Perl</a>: Perl +<li><a href="#PHP">PHP</a>: PHP Hypertext Preprocessor +<li><a href="#Pike">Pike</a>: Pike +<li><a href="#GCC_002dsource">GCC-source</a>: GNU Compiler Collection sources + +</li></ul> +<p>sh - Shell Script + +</p> +<ul class="menu"> +<li><a href="#Preparing-Shell-Scripts">Preparing Shell Scripts</a>: Preparing Shell Scripts for Internationalization +<li><a href="#gettext_002esh">gettext.sh</a>: Contents of <code>gettext.sh</code> +<li><a href="#gettext-Invocation">gettext Invocation</a>: Invoking the <code>gettext</code> program +<li><a href="#ngettext-Invocation">ngettext Invocation</a>: Invoking the <code>ngettext</code> program +<li><a href="#envsubst-Invocation">envsubst Invocation</a>: Invoking the <code>envsubst</code> program +<li><a href="#eval_005fgettext-Invocation">eval_gettext Invocation</a>: Invoking the <code>eval_gettext</code> function +<li><a href="#eval_005fngettext-Invocation">eval_ngettext Invocation</a>: Invoking the <code>eval_ngettext</code> function + +</li></ul> +<p>Perl + +</p> +<ul class="menu"> +<li><a href="#General-Problems">General Problems</a>: General Problems Parsing Perl Code +<li><a href="#Default-Keywords">Default Keywords</a>: Which Keywords Will xgettext Look For? +<li><a href="#Special-Keywords">Special Keywords</a>: How to Extract Hash Keys +<li><a href="#Quote_002dlike-Expressions">Quote-like Expressions</a>: What are Strings And Quote-like Expressions? +<li><a href="#Interpolation-I">Interpolation I</a>: Invalid String Interpolation +<li><a href="#Interpolation-II">Interpolation II</a>: Valid String Interpolation +<li><a href="#Parentheses">Parentheses</a>: When To Use Parentheses +<li><a href="#Long-Lines">Long Lines</a>: How To Grok with Long Lines +<li><a href="#Perl-Pitfalls">Perl Pitfalls</a>: Bugs, Pitfalls, and Things That Do Not Work + +</li></ul> +<p>Internationalizable Data + +</p> +<ul class="menu"> +<li><a href="#POT">POT</a>: POT - Portable Object Template +<li><a href="#RST">RST</a>: Resource String Table +<li><a href="#Glade">Glade</a>: Glade - GNOME user interface description + +</li></ul> +<p>Concluding Remarks + +</p> +<ul class="menu"> +<li><a href="#History">History</a>: History of GNU <code>gettext</code> +<li><a href="#References">References</a>: Related Readings + +</li></ul> +<p>Language Codes + +</p> +<ul class="menu"> +<li><a href="#Usual-Language-Codes">Usual Language Codes</a>: Two-letter ISO 639 language codes +<li><a href="#Rare-Language-Codes">Rare Language Codes</a>: Three-letter ISO 639 language codes + +</li></ul> +<p>Licenses + +</p> +<ul class="menu"> +<li><a href="#GNU-GPL">GNU GPL</a>: GNU General Public License +<li><a href="#GNU-LGPL">GNU LGPL</a>: GNU Lesser General Public License +<li><a href="#GNU-FDL">GNU FDL</a>: GNU Free Documentation License + + </ul> + +<div class="node"> +<a name="Introduction"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Users">Users</a>, +Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">1 Introduction</h2> + + <p>This chapter explains the goals sought in the creation +of GNU <code>gettext</code> and the free Translation Project. +Then, it explains a few broad concepts around +Native Language Support, and positions message translation with regard +to other aspects of national and cultural variance, as they apply +to programs. It also surveys those files used to convey the +translations. It explains how the various tools interact in the +initial generation of these files, and later, how the maintenance +cycle should usually operate. + + <p><a name="index-sex-1"></a><a name="index-he_002c-she_002c-and-they-2"></a><a name="index-she_002c-he_002c-and-they-3"></a>In this manual, we use <em>he</em> when speaking of the programmer or +maintainer, <em>she</em> when speaking of the translator, and <em>they</em> +when speaking of the installers or end users of the translated program. +This is only a convenience for clarifying the documentation. It is +<em>absolutely</em> not meant to imply that some roles are more appropriate +to males or females. Besides, as you might guess, GNU <code>gettext</code> +is meant to be useful for people using computers, whatever their sex, +race, religion or nationality! + + <p><a name="index-bug-report-address-4"></a>Please send suggestions and corrections to: + +<pre class="example"> <span class="roman">Internet address:</span> + bug-gnu-gettext@gnu.org +</pre> + <p class="noindent">Please include the manual's edition number and update date in your messages. + +<ul class="menu"> +<li><a accesskey="1" href="#Why">Why</a>: The Purpose of GNU <code>gettext</code> +<li><a accesskey="2" href="#Concepts">Concepts</a>: I18n, L10n, and Such +<li><a accesskey="3" href="#Aspects">Aspects</a>: Aspects in Native Language Support +<li><a accesskey="4" href="#Files">Files</a>: Files Conveying Translations +<li><a accesskey="5" href="#Overview">Overview</a>: Overview of GNU <code>gettext</code> +</ul> + +<div class="node"> +<a name="Why"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Concepts">Concepts</a>, +Previous: <a rel="previous" accesskey="p" href="#Introduction">Introduction</a>, +Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a> + +</div> + +<h3 class="section">1.1 The Purpose of GNU <code>gettext</code></h3> + + <p>Usually, programs are written and documented in English, and use +English at execution time to interact with users. This is true +not only of GNU software, but also of a great deal of proprietary +and free software. Using a common language is quite handy for +communication between developers, maintainers and users from all +countries. On the other hand, most people are less comfortable with +English than with their own native language, and would prefer to +use their mother tongue for day to day's work, as far as possible. +Many would simply <em>love</em> to see their computer screen showing +a lot less of English, and far more of their own language. + + <p><a name="index-Translation-Project-5"></a>However, to many people, this dream might appear so far fetched that +they may believe it is not even worth spending time thinking about +it. They have no confidence at all that the dream might ever +become true. Yet some have not lost hope, and have organized themselves. +The Translation Project is a formalization of this hope into a +workable structure, which has a good chance to get all of us nearer +the achievement of a truly multi-lingual set of programs. + + <p>GNU <code>gettext</code> is an important step for the Translation Project, +as it is an asset on which we may build many other steps. This package +offers to programmers, translators and even users, a well integrated +set of tools and documentation. Specifically, the GNU <code>gettext</code> +utilities are a set of tools that provides a framework within which +other free packages may produce multi-lingual messages. These tools +include + + <ul> +<li>A set of conventions about how programs should be written to support +message catalogs. + + <li>A directory and file naming organization for the message catalogs +themselves. + + <li>A runtime library supporting the retrieval of translated messages. + + <li>A few stand-alone programs to massage in various ways the sets of +translatable strings, or already translated strings. + + <li>A library supporting the parsing and creation of files containing +translated messages. + + <li>A special mode for Emacs<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a> which helps preparing these sets +and bringing them up to date. +</ul> + + <p>GNU <code>gettext</code> is designed to minimize the impact of +internationalization on program sources, keeping this impact as small +and hardly noticeable as possible. Internationalization has better +chances of succeeding if it is very light weighted, or at least, +appear to be so, when looking at program sources. + + <p>The Translation Project also uses the GNU <code>gettext</code> distribution +as a vehicle for documenting its structure and methods. This goes +beyond the strict technicalities of documenting the GNU <code>gettext</code> +proper. By so doing, translators will find in a single place, as +far as possible, all they need to know for properly doing their +translating work. Also, this supplemental documentation might also +help programmers, and even curious users, in understanding how GNU +<code>gettext</code> is related to the remainder of the Translation +Project, and consequently, have a glimpse at the <em>big picture</em>. + +<div class="node"> +<a name="Concepts"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Aspects">Aspects</a>, +Previous: <a rel="previous" accesskey="p" href="#Why">Why</a>, +Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a> + +</div> + +<h3 class="section">1.2 I18n, L10n, and Such</h3> + + <p><a name="index-i18n-6"></a><a name="index-l10n-7"></a>Two long words appear all the time when we discuss support of native +language in programs, and these words have a precise meaning, worth +being explained here, once and for all in this document. The words are +<em>internationalization</em> and <em>localization</em>. Many people, +tired of writing these long words over and over again, took the +habit of writing <dfn>i18n</dfn> and <dfn>l10n</dfn> instead, quoting the first +and last letter of each word, and replacing the run of intermediate +letters by a number merely telling how many such letters there are. +But in this manual, in the sake of clarity, we will patiently write +the names in full, each time<small class="dots">...</small> + + <p><a name="index-internationalization-8"></a>By <dfn>internationalization</dfn>, one refers to the operation by which a +program, or a set of programs turned into a package, is made aware of and +able to support multiple languages. This is a generalization process, +by which the programs are untied from calling only English strings or +other English specific habits, and connected to generic ways of doing +the same, instead. Program developers may use various techniques to +internationalize their programs. Some of these have been standardized. +GNU <code>gettext</code> offers one of these standards. See <a href="#Programmers">Programmers</a>. + + <p><a name="index-localization-9"></a>By <dfn>localization</dfn>, one means the operation by which, in a set +of programs already internationalized, one gives the program all +needed information so that it can adapt itself to handle its input +and output in a fashion which is correct for some native language and +cultural habits. This is a particularisation process, by which generic +methods already implemented in an internationalized program are used +in specific ways. The programming environment puts several functions +to the programmers disposal which allow this runtime configuration. +The formal description of specific set of cultural habits for some +country, together with all associated translations targeted to the +same native language, is called the <dfn>locale</dfn> for this language +or country. Users achieve localization of programs by setting proper +values to special environment variables, prior to executing those +programs, identifying which locale should be used. + + <p>In fact, locale message support is only one component of the cultural +data that makes up a particular locale. There are a whole host of +routines and functions provided to aid programmers in developing +internationalized software and which allow them to access the data +stored in a particular locale. When someone presently refers to a +particular locale, they are obviously referring to the data stored +within that particular locale. Similarly, if a programmer is referring +to “accessing the locale routines”, they are referring to the +complete suite of routines that access all of the locale's information. + + <p><a name="index-NLS-10"></a><a name="index-Native-Language-Support-11"></a><a name="index-Natural-Language-Support-12"></a>One uses the expression <dfn>Native Language Support</dfn>, or merely NLS, +for speaking of the overall activity or feature encompassing both +internationalization and localization, allowing for multi-lingual +interactions in a program. In a nutshell, one could say that +internationalization is the operation by which further localizations +are made possible. + + <p>Also, very roughly said, when it comes to multi-lingual messages, +internationalization is usually taken care of by programmers, and +localization is usually taken care of by translators. + +<div class="node"> +<a name="Aspects"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Files">Files</a>, +Previous: <a rel="previous" accesskey="p" href="#Concepts">Concepts</a>, +Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a> + +</div> + +<h3 class="section">1.3 Aspects in Native Language Support</h3> + + <p><a name="index-translation-aspects-13"></a>For a totally multi-lingual distribution, there are many things to +translate beyond output messages. + + <ul> +<li>As of today, GNU <code>gettext</code> offers a complete toolset for +translating messages output by C programs. Perl scripts and shell +scripts will also need to be translated. Even if there are today some hooks +by which this can be done, these hooks are not integrated as well as they +should be. + + <li>Some programs, like <code>autoconf</code> or <code>bison</code>, are able +to produce other programs (or scripts). Even if the generating +programs themselves are internationalized, the generated programs they +produce may need internationalization on their own, and this indirect +internationalization could be automated right from the generating +program. In fact, quite usually, generating and generated programs +could be internationalized independently, as the effort needed is +fairly orthogonal. + + <li>A few programs include textual tables which might need translation +themselves, independently of the strings contained in the program +itself. For example, RFC 1345<!-- /@w --> gives an English description for each +character which the <code>recode</code> program is able to reconstruct at execution. +Since these descriptions are extracted from the RFC by mechanical means, +translating them properly would require a prior translation of the RFC +itself. + + <li>Almost all programs accept options, which are often worded out so to +be descriptive for the English readers; one might want to consider +offering translated versions for program options as well. + + <li>Many programs read, interpret, compile, or are somewhat driven by +input files which are texts containing keywords, identifiers, or +replies which are inherently translatable. For example, one may want +<code>gcc</code> to allow diacriticized characters in identifiers or use +translated keywords; ‘<samp><span class="samp">rm -i</span></samp>’ might accept something else than +‘<samp><span class="samp">y</span></samp>’ or ‘<samp><span class="samp">n</span></samp>’ for replies, etc. Even if the program will +eventually make most of its output in the foreign languages, one has +to decide whether the input syntax, option values, etc., are to be +localized or not. + + <li>The manual accompanying a package, as well as all documentation files +in the distribution, could surely be translated, too. Translating a +manual, with the intent of later keeping up with updates, is a major +undertaking in itself, generally. + + </ul> + + <p>As we already stressed, translation is only one aspect of locales. +Other internationalization aspects are system services and are handled +in GNU <code>libc</code>. There +are many attributes that are needed to define a country's cultural +conventions. These attributes include beside the country's native +language, the formatting of the date and time, the representation of +numbers, the symbols for currency, etc. These local <dfn>rules</dfn> are +termed the country's locale. The locale represents the knowledge +needed to support the country's native attributes. + + <p><a name="index-locale-categories-14"></a>There are a few major areas which may vary between countries and +hence, define what a locale must describe. The following list helps +putting multi-lingual messages into the proper context of other tasks +related to locales. See the GNU <code>libc</code> manual for details. + + <dl> +<dt><em>Characters and Codesets</em><dd><a name="index-codeset-15"></a><a name="index-encoding-16"></a><a name="index-character-encoding-17"></a><a name="index-locale-category_002c-LC_005fCTYPE-18"></a> +The codeset most commonly used through out the USA and most English +speaking parts of the world is the ASCII codeset. However, there are +many characters needed by various locales that are not found within +this codeset. The 8-bit ISO 8859-1<!-- /@w --> code set has most of the special +characters needed to handle the major European languages. However, in +many cases, choosing ISO 8859-1<!-- /@w --> is nevertheless not adequate: it +doesn't even handle the major European currency. Hence each locale +will need to specify which codeset they need to use and will need +to have the appropriate character handling routines to cope with +the codeset. + + <br><dt><em>Currency</em><dd><a name="index-currency-symbols-19"></a><a name="index-locale-category_002c-LC_005fMONETARY-20"></a> +The symbols used vary from country to country as does the position +used by the symbol. Software needs to be able to transparently +display currency figures in the native mode for each locale. + + <br><dt><em>Dates</em><dd><a name="index-date-format-21"></a><a name="index-locale-category_002c-LC_005fTIME-22"></a> +The format of date varies between locales. For example, Christmas day +in 1994 is written as 12/25/94 in the USA and as 25/12/94 in Australia. +Other countries might use ISO 8601<!-- /@w --> dates, etc. + + <p>Time of the day may be noted as <var>hh</var>:<var>mm</var>, <var>hh</var>.<var>mm</var>, +or otherwise. Some locales require time to be specified in 24-hour +mode rather than as AM or PM. Further, the nature and yearly extent +of the Daylight Saving correction vary widely between countries. + + <br><dt><em>Numbers</em><dd><a name="index-number-format-23"></a><a name="index-locale-category_002c-LC_005fNUMERIC-24"></a> +Numbers can be represented differently in different locales. +For example, the following numbers are all written correctly for +their respective locales: + + <pre class="example"> 12,345.67 English + 12.345,67 German + 12345,67 French + 1,2345.67 Asia +</pre> + <p>Some programs could go further and use different unit systems, like +English units or Metric units, or even take into account variants +about how numbers are spelled in full. + + <br><dt><em>Messages</em><dd><a name="index-messages-25"></a><a name="index-locale-category_002c-LC_005fMESSAGES-26"></a> +The most obvious area is the language support within a locale. This is +where GNU <code>gettext</code> provides the means for developers and users to +easily change the language that the software uses to communicate to +the user. + + </dl> + + <p><a name="index-locale-categories-27"></a>These areas of cultural conventions are called <em>locale categories</em>. +It is an unfortunate term; <em>locale aspects</em> or <em>locale feature +categories</em> would be a better term, because each “locale category” +describes an area or task that requires localization. The concrete data +that describes the cultural conventions for such an area and for a particular +culture is also called a <em>locale category</em>. In this sense, a locale +is composed of several locale categories: the locale category describing +the codeset, the locale category describing the formatting of numbers, +the locale category containing the translated messages, and so on. + + <p><a name="index-Linux-28"></a>Components of locale outside of message handling are standardized in +the ISO C standard and the POSIX:2001 standard (also known as the SUSV3 +specification). GNU <code>libc</code> +fully implements this, and most other modern systems provide a more +or less reasonable support for at least some of the missing components. + +<div class="node"> +<a name="Files"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Overview">Overview</a>, +Previous: <a rel="previous" accesskey="p" href="#Aspects">Aspects</a>, +Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a> + +</div> + +<h3 class="section">1.4 Files Conveying Translations</h3> + + <p><a name="index-files_002c-_0040file_007b_002epo_007d-and-_0040file_007b_002emo_007d-29"></a>The letters PO in <samp><span class="file">.po</span></samp> files means Portable Object, to +distinguish it from <samp><span class="file">.mo</span></samp> files, where MO stands for Machine +Object. This paradigm, as well as the PO file format, is inspired +by the NLS standard developed by Uniforum, and first implemented by +Sun in their Solaris system. + + <p>PO files are meant to be read and edited by humans, and associate each +original, translatable string of a given package with its translation +in a particular target language. A single PO file is dedicated to +a single target language. If a package supports many languages, +there is one such PO file per language supported, and each package +has its own set of PO files. These PO files are best created by +the <code>xgettext</code> program, and later updated or refreshed through +the <code>msgmerge</code> program. Program <code>xgettext</code> extracts all +marked messages from a set of C files and initializes a PO file with +empty translations. Program <code>msgmerge</code> takes care of adjusting +PO files between releases of the corresponding sources, commenting +obsolete entries, initializing new ones, and updating all source +line references. Files ending with <samp><span class="file">.pot</span></samp> are kind of base +translation files found in distributions, in PO file format. + + <p>MO files are meant to be read by programs, and are binary in nature. +A few systems already offer tools for creating and handling MO files +as part of the Native Language Support coming with the system, but the +format of these MO files is often different from system to system, +and non-portable. The tools already provided with these systems don't +support all the features of GNU <code>gettext</code>. Therefore GNU +<code>gettext</code> uses its own format for MO files. Files ending with +<samp><span class="file">.gmo</span></samp> are really MO files, when it is known that these files use +the GNU format. + +<div class="node"> +<a name="Overview"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Files">Files</a>, +Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a> + +</div> + +<h3 class="section">1.5 Overview of GNU <code>gettext</code></h3> + + <p><a name="index-overview-of-_0040code_007bgettext_007d-30"></a><a name="index-big-picture-31"></a><a name="index-tutorial-of-_0040code_007bgettext_007d-usage-32"></a>The following diagram summarizes the relation between the files +handled by GNU <code>gettext</code> and the tools acting on these files. +It is followed by somewhat detailed explanations, which you should +read while keeping an eye on the diagram. Having a clear understanding +of these interrelations will surely help programmers, translators +and maintainers. + +<pre class="example"> Original C Sources ───> Preparation ───> Marked C Sources ───╮ + │ + â•â”€â”€â”€â”€â”€â”€â”€â”€â”€<─── GNU gettext Library │ + â•â”€â”€â”€ make <───┤ │ + │ ╰─────────<────────────────────┬───────────────╯ + │ │ + │ â•â”€â”€â”€â”€â”€<─── PACKAGE.pot <─── xgettext <───╯ â•â”€â”€â”€<─── PO Compendium + │ │ │ ↑ + │ │ ╰───╮ │ + │ ╰───╮ ├───> PO editor ───╮ + │ ├────> msgmerge ──────> LANG.po ────>────────╯ │ + │ â•â”€â”€â”€â•¯ │ + │ │ │ + │ ╰─────────────<───────────────╮ │ + │ ├─── New LANG.po <────────────────────╯ + │ â•â”€â”€â”€ LANG.gmo <─── msgfmt <───╯ + │ │ + │ ╰───> install ───> /.../LANG/PACKAGE.mo ───╮ + │ ├───> "Hello world!" + ╰───────> install ───> /.../bin/PROGRAM ───────╯ +</pre> + <p><a name="index-marking-translatable-strings-33"></a>As a programmer, the first step to bringing GNU <code>gettext</code> +into your package is identifying, right in the C sources, those strings +which are meant to be translatable, and those which are untranslatable. +This tedious job can be done a little more comfortably using emacs PO +mode, but you can use any means familiar to you for modifying your +C sources. Beside this some other simple, standard changes are needed to +properly initialize the translation library. See <a href="#Sources">Sources</a>, for +more information about all this. + + <p>For newly written software the strings of course can and should be +marked while writing it. The <code>gettext</code> approach makes this +very easy. Simply put the following lines at the beginning of each file +or in a central header file: + +<pre class="example"> #define _(String) (String) + #define N_(String) String + #define textdomain(Domain) + #define bindtextdomain(Package, Directory) +</pre> + <p class="noindent">Doing this allows you to prepare the sources for internationalization. +Later when you feel ready for the step to use the <code>gettext</code> library +simply replace these definitions by the following: + + <p><a name="index-include-file-_0040file_007blibintl_002eh_007d-34"></a> +<pre class="example"> #include <libintl.h> + #define _(String) gettext (String) + #define gettext_noop(String) String + #define N_(String) gettext_noop (String) +</pre> + <p><a name="index-link-with-_0040file_007blibintl_007d-35"></a><a name="index-Linux-36"></a>and link against <samp><span class="file">libintl.a</span></samp> or <samp><span class="file">libintl.so</span></samp>. Note that on +GNU systems, you don't need to link with <code>libintl</code> because the +<code>gettext</code> library functions are already contained in GNU libc. +That is all you have to change. + + <p><a name="index-template-PO-file-37"></a><a name="index-files_002c-_0040file_007b_002epot_007d-38"></a>Once the C sources have been modified, the <code>xgettext</code> program +is used to find and extract all translatable strings, and create a +PO template file out of all these. This <samp><var>package</var><span class="file">.pot</span></samp> file +contains all original program strings. It has sets of pointers to +exactly where in C sources each string is used. All translations +are set to empty. The letter <code>t</code> in <samp><span class="file">.pot</span></samp> marks this as +a Template PO file, not yet oriented towards any particular language. +See <a href="#xgettext-Invocation">xgettext Invocation</a>, for more details about how one calls the +<code>xgettext</code> program. If you are <em>really</em> lazy, you might +be interested at working a lot more right away, and preparing the +whole distribution setup (see <a href="#Maintainers">Maintainers</a>). By doing so, you +spare yourself typing the <code>xgettext</code> command, as <code>make</code> +should now generate the proper things automatically for you! + + <p>The first time through, there is no <samp><var>lang</var><span class="file">.po</span></samp> yet, so the +<code>msgmerge</code> step may be skipped and replaced by a mere copy of +<samp><var>package</var><span class="file">.pot</span></samp> to <samp><var>lang</var><span class="file">.po</span></samp>, where <var>lang</var> +represents the target language. See <a href="#Creating">Creating</a> for details. + + <p>Then comes the initial translation of messages. Translation in +itself is a whole matter, still exclusively meant for humans, +and whose complexity far overwhelms the level of this manual. +Nevertheless, a few hints are given in some other chapter of this +manual (see <a href="#Translators">Translators</a>). You will also find there indications +about how to contact translating teams, or becoming part of them, +for sharing your translating concerns with others who target the same +native language. + + <p>While adding the translated messages into the <samp><var>lang</var><span class="file">.po</span></samp> +PO file, if you are not using one of the dedicated PO file editors +(see <a href="#Editing">Editing</a>), you are on your own +for ensuring that your efforts fully respect the PO file format, and quoting +conventions (see <a href="#PO-Files">PO Files</a>). This is surely not an impossible task, +as this is the way many people have handled PO files around 1995. +On the other hand, by using a PO file editor, most details +of PO file format are taken care of for you, but you have to acquire +some familiarity with PO file editor itself. + + <p>If some common translations have already been saved into a compendium +PO file, translators may use PO mode for initializing untranslated +entries from the compendium, and also save selected translations into +the compendium, updating it (see <a href="#Compendium">Compendium</a>). Compendium files +are meant to be exchanged between members of a given translation team. + + <p>Programs, or packages of programs, are dynamic in nature: users write +bug reports and suggestion for improvements, maintainers react by +modifying programs in various ways. The fact that a package has +already been internationalized should not make maintainers shy +of adding new strings, or modifying strings already translated. +They just do their job the best they can. For the Translation +Project to work smoothly, it is important that maintainers do not +carry translation concerns on their already loaded shoulders, and that +translators be kept as free as possible of programming concerns. + + <p>The only concern maintainers should have is carefully marking new +strings as translatable, when they should be, and do not otherwise +worry about them being translated, as this will come in proper time. +Consequently, when programs and their strings are adjusted in various +ways by maintainers, and for matters usually unrelated to translation, +<code>xgettext</code> would construct <samp><var>package</var><span class="file">.pot</span></samp> files which are +evolving over time, so the translations carried by <samp><var>lang</var><span class="file">.po</span></samp> +are slowly fading out of date. + + <p><a name="index-evolution-of-packages-39"></a>It is important for translators (and even maintainers) to understand +that package translation is a continuous process in the lifetime of a +package, and not something which is done once and for all at the start. +After an initial burst of translation activity for a given package, +interventions are needed once in a while, because here and there, +translated entries become obsolete, and new untranslated entries +appear, needing translation. + + <p>The <code>msgmerge</code> program has the purpose of refreshing an already +existing <samp><var>lang</var><span class="file">.po</span></samp> file, by comparing it with a newer +<samp><var>package</var><span class="file">.pot</span></samp> template file, extracted by <code>xgettext</code> +out of recent C sources. The refreshing operation adjusts all +references to C source locations for strings, since these strings +move as programs are modified. Also, <code>msgmerge</code> comments out as +obsolete, in <samp><var>lang</var><span class="file">.po</span></samp>, those already translated entries +which are no longer used in the program sources (see <a href="#Obsolete-Entries">Obsolete Entries</a>). It finally discovers new strings and inserts them in +the resulting PO file as untranslated entries (see <a href="#Untranslated-Entries">Untranslated Entries</a>). See <a href="#msgmerge-Invocation">msgmerge Invocation</a>, for more information about what +<code>msgmerge</code> really does. + + <p>Whatever route or means taken, the goal is to obtain an updated +<samp><var>lang</var><span class="file">.po</span></samp> file offering translations for all strings. + + <p>The temporal mobility, or fluidity of PO files, is an integral part of +the translation game, and should be well understood, and accepted. +People resisting it will have a hard time participating in the +Translation Project, or will give a hard time to other participants! In +particular, maintainers should relax and include all available official +PO files in their distributions, even if these have not recently been +updated, without exerting pressure on the translator teams to get the +job done. The pressure should rather come +from the community of users speaking a particular language, and +maintainers should consider themselves fairly relieved of any concern +about the adequacy of translation files. On the other hand, translators +should reasonably try updating the PO files they are responsible for, +while the package is undergoing pretest, prior to an official +distribution. + + <p>Once the PO file is complete and dependable, the <code>msgfmt</code> program +is used for turning the PO file into a machine-oriented format, which +may yield efficient retrieval of translations by the programs of the +package, whenever needed at runtime (see <a href="#MO-Files">MO Files</a>). See <a href="#msgfmt-Invocation">msgfmt Invocation</a>, for more information about all modes of execution +for the <code>msgfmt</code> program. + + <p>Finally, the modified and marked C sources are compiled and linked +with the GNU <code>gettext</code> library, usually through the operation of +<code>make</code>, given a suitable <samp><span class="file">Makefile</span></samp> exists for the project, +and the resulting executable is installed somewhere users will find it. +The MO files themselves should also be properly installed. Given the +appropriate environment variables are set (see <a href="#Setting-the-POSIX-Locale">Setting the POSIX Locale</a>), +the program should localize itself automatically, whenever it executes. + + <p>The remainder of this manual has the purpose of explaining in depth the various +steps outlined above. + +<div class="node"> +<a name="Users"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#PO-Files">PO Files</a>, +Previous: <a rel="previous" accesskey="p" href="#Introduction">Introduction</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">2 The User's View</h2> + + <p>Nowadays, when users log into a computer, they usually find that all +their programs show messages in their native language – at least for +users of languages with an active free software community, like French or +German; to a lesser extent for languages with a smaller participation in +free software and the GNU project, like Hindi and Filipino. + + <p>How does this work? How can the user influence the language that is used +by the programs? This chapter will answer it. + +<ul class="menu"> +<li><a accesskey="1" href="#System-Installation">System Installation</a>: Questions During Operating System Installation +<li><a accesskey="2" href="#Setting-the-GUI-Locale">Setting the GUI Locale</a>: How to Specify the Locale Used by GUI Programs +<li><a accesskey="3" href="#Setting-the-POSIX-Locale">Setting the POSIX Locale</a>: How to Specify the Locale According to POSIX +<li><a accesskey="4" href="#Installing-Localizations">Installing Localizations</a>: How to Install Additional Translations +</ul> + +<div class="node"> +<a name="System-Installation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Setting-the-GUI-Locale">Setting the GUI Locale</a>, +Previous: <a rel="previous" accesskey="p" href="#Users">Users</a>, +Up: <a rel="up" accesskey="u" href="#Users">Users</a> + +</div> + +<h3 class="section">2.1 Operating System Installation</h3> + + <p>The default language is often already specified during operating system +installation. When the operating system is installed, the installer +typically asks for the language used for the installation process and, +separately, for the language to use in the installed system. Some OS +installers only ask for the language once. + + <p>This determines the system-wide default language for all users. But the +installers often give the possibility to install extra localizations for +additional languages. For example, the localizations of KDE (the K +Desktop Environment) and OpenOffice.org are often bundled separately, +as one installable package per language. + + <p>At this point it is good to consider the intended use of the machine: If +it is a machine designated for personal use, additional localizations are +probably not necessary. If, however, the machine is in use in an +organization or company that has international relationships, one can +consider the needs of guest users. If you have a guest from abroad, for +a week, what could be his preferred locales? It may be worth installing +these additional localizations ahead of time, since they cost only a bit +of disk space at this point. + + <p>The system-wide default language is the locale configuration that is used +when a new user account is created. But the user can have his own locale +configuration that is different from the one of the other users of the +same machine. He can specify it, typically after the first login, as +described in the next section. + +<div class="node"> +<a name="Setting-the-GUI-Locale"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Setting-the-POSIX-Locale">Setting the POSIX Locale</a>, +Previous: <a rel="previous" accesskey="p" href="#System-Installation">System Installation</a>, +Up: <a rel="up" accesskey="u" href="#Users">Users</a> + +</div> + +<h3 class="section">2.2 Setting the Locale Used by GUI Programs</h3> + + <p>The immediately available programs in a user's desktop come from a group +of programs called a “desktop environment”; it usually includes the window +manager, a web browser, a text editor, and more. The most common free +desktop environments are KDE, GNOME, and Xfce. + + <p>The locale used by GUI programs of the desktop environment can be specified +in a configuration screen called “control center”, “language settings” +or “country settings”. + + <p>Individual GUI programs that are not part of the desktop environment can +have their locale specified either in a settings panel, or through environment +variables. + + <p>For some programs, it is possible to specify the locale through environment +variables, possibly even to a different locale than the desktop's locale. +This means, instead of starting a program through a menu or from the file +system, you can start it from the command-line, after having set some +environment variables. The environment variables can be those specified +in the next section (<a href="#Setting-the-POSIX-Locale">Setting the POSIX Locale</a>); for some versions of +KDE, however, the locale is specified through a variable <code>KDE_LANG</code>, +rather than <code>LANG</code> or <code>LC_ALL</code>. + +<div class="node"> +<a name="Setting-the-POSIX-Locale"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Installing-Localizations">Installing Localizations</a>, +Previous: <a rel="previous" accesskey="p" href="#Setting-the-GUI-Locale">Setting the GUI Locale</a>, +Up: <a rel="up" accesskey="u" href="#Users">Users</a> + +</div> + +<h3 class="section">2.3 Setting the Locale through Environment Variables</h3> + + <p>As a user, if your language has been installed for this package, in the +simplest case, you only have to set the <code>LANG</code> environment variable +to the appropriate ‘<samp><var>ll</var><span class="samp">_</span><var>CC</var></samp>’ combination. For example, +let's suppose that you speak German and live in Germany. At the shell +prompt, merely execute +‘<samp><span class="samp">setenv LANG de_DE</span></samp>’<!-- /@w --> (in <code>csh</code>), +‘<samp><span class="samp">export LANG; LANG=de_DE</span></samp>’<!-- /@w --> (in <code>sh</code>) or +‘<samp><span class="samp">export LANG=de_DE</span></samp>’<!-- /@w --> (in <code>bash</code>). This can be done from your +<samp><span class="file">.login</span></samp> or <samp><span class="file">.profile</span></samp> file, once and for all. + +<ul class="menu"> +<li><a accesskey="1" href="#Locale-Names">Locale Names</a>: How a Locale Specification Looks Like +<li><a accesskey="2" href="#Locale-Environment-Variables">Locale Environment Variables</a>: Which Environment Variable Specfies What +<li><a accesskey="3" href="#The-LANGUAGE-variable">The LANGUAGE variable</a>: How to Specify a Priority List of Languages +</ul> + +<div class="node"> +<a name="Locale-Names"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Locale-Environment-Variables">Locale Environment Variables</a>, +Previous: <a rel="previous" accesskey="p" href="#Setting-the-POSIX-Locale">Setting the POSIX Locale</a>, +Up: <a rel="up" accesskey="u" href="#Setting-the-POSIX-Locale">Setting the POSIX Locale</a> + +</div> + +<h4 class="subsection">2.3.1 Locale Names</h4> + + <p>A locale name usually has the form ‘<samp><var>ll</var><span class="samp">_</span><var>CC</var></samp>’. Here +‘<samp><var>ll</var></samp>’ is an ISO 639<!-- /@w --> two-letter language code, and +‘<samp><var>CC</var></samp>’ is an ISO 3166<!-- /@w --> two-letter country code. For example, +for German in Germany, <var>ll</var> is <code>de</code>, and <var>CC</var> is <code>DE</code>. +You find a list of the language codes in appendix <a href="#Language-Codes">Language Codes</a> and +a list of the country codes in appendix <a href="#Country-Codes">Country Codes</a>. + + <p>You might think that the country code specification is redundant. But in +fact, some languages have dialects in different countries. For example, +‘<samp><span class="samp">de_AT</span></samp>’ is used for Austria, and ‘<samp><span class="samp">pt_BR</span></samp>’ for Brazil. The country +code serves to distinguish the dialects. + + <p>Many locale names have an extended syntax +‘<samp><var>ll</var><span class="samp">_</span><var>CC</var><span class="samp">.</span><var>encoding</var></samp>’ that also specifies the character +encoding. These are in use because between 2000 and 2005, most users have +switched to locales in UTF-8 encoding. For example, the German locale on +glibc systems is nowadays ‘<samp><span class="samp">de_DE.UTF-8</span></samp>’. The older name ‘<samp><span class="samp">de_DE</span></samp>’ +still refers to the German locale as of 2000 that stores characters in +ISO-8859-1 encoding – a text encoding that cannot even accomodate the Euro +currency sign. + + <p>Some locale names use ‘<samp><var>ll</var><span class="samp">_</span><var>CC</var><span class="samp">.@</span><var>variant</var></samp>’ instead of +‘<samp><var>ll</var><span class="samp">_</span><var>CC</var></samp>’. The ‘<samp><span class="samp">@</span><var>variant</var></samp>’ can denote any kind of +characteristics that is not already implied by the language <var>ll</var> and +the country <var>CC</var>. It can denote a particular monetary unit. For example, +on glibc systems, ‘<samp><span class="samp">de_DE@euro</span></samp>’ denotes the locale that uses the Euro +currency, in contrast to the older locale ‘<samp><span class="samp">de_DE</span></samp>’ which implies the use +of the currency before 2002. It can also denote a dialect of the language, +or the script used to write text (for example, ‘<samp><span class="samp">sr_RS@latin</span></samp>’ uses the +Latin script, whereas ‘<samp><span class="samp">sr_RS</span></samp>’ uses the Cyrillic script to write Serbian), +or the orthography rules, or similar. + + <p>On other systems, some variations of this scheme are used, such as +‘<samp><var>ll</var></samp>’. You can get the list of locales supported by your system +for your language by running the command ‘<samp><span class="samp">locale -a | grep '^</span><var>ll</var><span class="samp">'</span></samp>’. + + <p>There is also a special locale, called ‘<samp><span class="samp">C</span></samp>’. +<!-- Don't mention that this locale also has the name "POSIX". When we talk about --> +<!-- the "POSIX locale", we mean the "locale as specified in the POSIX way", and --> +<!-- mentioning a locale called "POSIX" would bring total confusion. --> +When it is used, it disables all localization: in this locale, all programs +standardized by POSIX use English messages and an unspecified character +encoding (often US-ASCII, but sometimes also ISO-8859-1 or UTF-8, depending on +the operating system). + +<div class="node"> +<a name="Locale-Environment-Variables"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#The-LANGUAGE-variable">The LANGUAGE variable</a>, +Previous: <a rel="previous" accesskey="p" href="#Locale-Names">Locale Names</a>, +Up: <a rel="up" accesskey="u" href="#Setting-the-POSIX-Locale">Setting the POSIX Locale</a> + +</div> + +<h4 class="subsection">2.3.2 Locale Environment Variables</h4> + + <p><a name="index-setting-up-_0040code_007bgettext_007d-at-run-time-40"></a><a name="index-selecting-message-language-41"></a><a name="index-language-selection-42"></a> +A locale is composed of several <em>locale categories</em>, see <a href="#Aspects">Aspects</a>. +When a program looks up locale dependent values, it does this according to +the following environment variables, in priority order: + + <ol type=1 start=1> +<a name="index-LANGUAGE_0040r_007b_002c-environment-variable_007d-43"></a><li><code>LANGUAGE</code> +<a name="index-LC_005fALL_0040r_007b_002c-environment-variable_007d-44"></a><li><code>LC_ALL</code> +<a name="index-LC_005fCTYPE_0040r_007b_002c-environment-variable_007d-45"></a><a name="index-LC_005fNUMERIC_0040r_007b_002c-environment-variable_007d-46"></a><a name="index-LC_005fTIME_0040r_007b_002c-environment-variable_007d-47"></a><a name="index-LC_005fCOLLATE_0040r_007b_002c-environment-variable_007d-48"></a><a name="index-LC_005fMONETARY_0040r_007b_002c-environment-variable_007d-49"></a><a name="index-LC_005fMESSAGES_0040r_007b_002c-environment-variable_007d-50"></a><li><code>LC_xxx</code>, according to selected locale category: +<code>LC_CTYPE</code>, <code>LC_NUMERIC</code>, <code>LC_TIME</code>, <code>LC_COLLATE</code>, +<code>LC_MONETARY</code>, <code>LC_MESSAGES</code>, ... +<a name="index-LANG_0040r_007b_002c-environment-variable_007d-51"></a><li><code>LANG</code> + </ol> + + <p>Variables whose value is set but is empty are ignored in this lookup. + + <p><code>LANG</code> is the normal environment variable for specifying a locale. +As a user, you normally set this variable (unless some of the other variables +have already been set by the system, in <samp><span class="file">/etc/profile</span></samp> or similar +initialization files). + + <p><code>LC_CTYPE</code>, <code>LC_NUMERIC</code>, <code>LC_TIME</code>, <code>LC_COLLATE</code>, +<code>LC_MONETARY</code>, <code>LC_MESSAGES</code>, and so on, are the environment +variables meant to override <code>LANG</code> and affecting a single locale +category only. For example, assume you are a Swedish user in Spain, and you +want your programs to handle numbers and dates according to Spanish +conventions, and only the messages should be in Swedish. Then you could +create a locale named ‘<samp><span class="samp">sv_ES</span></samp>’ or ‘<samp><span class="samp">sv_ES.UTF-8</span></samp>’ by use of the +<code>localedef</code> program. But it is simpler, and achieves the same effect, +to set the <code>LANG</code> variable to <code>es_ES.UTF-8</code> and the +<code>LC_MESSAGES</code> variable to <code>sv_SE.UTF-8</code>; these two locales come +already preinstalled with the operating system. + + <p><code>LC_ALL</code> is an environment variable that overrides all of these. +It is typically used in scripts that run particular programs. For example, +<code>configure</code> scripts generated by GNU autoconf use <code>LC_ALL</code> to make +sure that the configuration tests don't operate in locale dependent ways. + + <p>Some systems, unfortunately, set <code>LC_ALL</code> in <samp><span class="file">/etc/profile</span></samp> or in +similar initialization files. As a user, you therefore have to unset this +variable if you want to set <code>LANG</code> and optionally some of the other +<code>LC_xxx</code> variables. + + <p>The <code>LANGUAGE</code> variable is described in the next subsection. + +<div class="node"> +<a name="The-LANGUAGE-variable"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Locale-Environment-Variables">Locale Environment Variables</a>, +Up: <a rel="up" accesskey="u" href="#Setting-the-POSIX-Locale">Setting the POSIX Locale</a> + +</div> + +<h4 class="subsection">2.3.3 Specifying a Priority List of Languages</h4> + + <p>Not all programs have translations for all languages. By default, an +English message is shown in place of a nonexistent translation. If you +understand other languages, you can set up a priority list of languages. +This is done through a different environment variable, called +<code>LANGUAGE</code>. GNU <code>gettext</code> gives preference to <code>LANGUAGE</code> +over <code>LC_ALL</code> and <code>LANG</code> for the purpose of message handling, +but you still need to have <code>LANG</code> (or <code>LC_ALL</code>) set to the primary +language; this is required by other parts of the system libraries. +For example, some Swedish users who would rather read translations in +German than English for when Swedish is not available, set <code>LANGUAGE</code> +to ‘<samp><span class="samp">sv:de</span></samp>’ while leaving <code>LANG</code> to ‘<samp><span class="samp">sv_SE</span></samp>’. + + <p>Special advice for Norwegian users: The language code for Norwegian +bokma*l changed from ‘<samp><span class="samp">no</span></samp>’ to ‘<samp><span class="samp">nb</span></samp>’ recently (in 2003). +During the transition period, while some message catalogs for this language +are installed under ‘<samp><span class="samp">nb</span></samp>’ and some older ones under ‘<samp><span class="samp">no</span></samp>’, it is +recommended for Norwegian users to set <code>LANGUAGE</code> to ‘<samp><span class="samp">nb:no</span></samp>’ so that +both newer and older translations are used. + + <p>In the <code>LANGUAGE</code> environment variable, but not in the other +environment variables, ‘<samp><var>ll</var><span class="samp">_</span><var>CC</var></samp>’ combinations can be +abbreviated as ‘<samp><var>ll</var></samp>’ to denote the language's main dialect. +For example, ‘<samp><span class="samp">de</span></samp>’ is equivalent to ‘<samp><span class="samp">de_DE</span></samp>’ (German as spoken in +Germany), and ‘<samp><span class="samp">pt</span></samp>’ to ‘<samp><span class="samp">pt_PT</span></samp>’ (Portuguese as spoken in Portugal) +in this context. + + <p>Note: The variable <code>LANGUAGE</code> is ignored if the locale is set to +‘<samp><span class="samp">C</span></samp>’. In other words, you have to first enable localization, by setting +<code>LANG</code> (or <code>LC_ALL</code>) to a value other than ‘<samp><span class="samp">C</span></samp>’, before you can +use a language priority list through the <code>LANGUAGE</code> variable. + +<div class="node"> +<a name="Installing-Localizations"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Setting-the-POSIX-Locale">Setting the POSIX Locale</a>, +Up: <a rel="up" accesskey="u" href="#Users">Users</a> + +</div> + +<h3 class="section">2.4 Installing Translations for Particular Programs</h3> + + <p><a name="index-Translation-Matrix-52"></a><a name="index-available-translations-53"></a> +Languages are not equally well supported in all packages using GNU +<code>gettext</code>, and more translations are added over time. Usually, you +use the translations that are shipped with the operating system +or with particular packages that you install afterwards. But you can also +install newer localizations directly. For doing this, you will need an +understanding where each localization file is stored on the file system. + + <p><a name="index-g_t_0040file_007bABOUT_002dNLS_007d-file-54"></a>For programs that participate in the Translation Project, you can start +looking for translations here: +<a href="http://translationproject.org/team/index.html">http://translationproject.org/team/index.html</a>. +A snapshot of this information is also found in the <samp><span class="file">ABOUT-NLS</span></samp> file +that is shipped with GNU gettext. + + <p>For programs that are part of the KDE project, the starting point is: +<a href="http://i18n.kde.org/">http://i18n.kde.org/</a>. + + <p>For programs that are part of the GNOME project, the starting point is: +<a href="http://www.gnome.org/i18n/">http://www.gnome.org/i18n/</a>. + + <p>For other programs, you may check whether the program's source code package +contains some <samp><var>ll</var><span class="file">.po</span></samp> files; often they are kept together in a +directory called <samp><span class="file">po/</span></samp>. Each <samp><var>ll</var><span class="file">.po</span></samp> file contains the +message translations for the language whose abbreviation of <var>ll</var>. + +<div class="node"> +<a name="PO-Files"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Sources">Sources</a>, +Previous: <a rel="previous" accesskey="p" href="#Users">Users</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">3 The Format of PO Files</h2> + + <p><a name="index-PO-files_0027-format-55"></a><a name="index-file-format_002c-_0040file_007b_002epo_007d-56"></a> +The GNU <code>gettext</code> toolset helps programmers and translators +at producing, updating and using translation files, mainly those +PO files which are textual, editable files. This chapter explains +the format of PO files. + + <p>A PO file is made up of many entries, each entry holding the relation +between an original untranslated string and its corresponding +translation. All entries in a given PO file usually pertain +to a single project, and all translations are expressed in a single +target language. One PO file <dfn>entry</dfn> has the following schematic +structure: + +<pre class="example"> <var>white-space</var> + # <var>translator-comments</var> + #. <var>extracted-comments</var> + #: <var>reference</var>... + #, <var>flag</var>... + #| msgid <var>previous-untranslated-string</var> + msgid <var>untranslated-string</var> + msgstr <var>translated-string</var> +</pre> + <p>The general structure of a PO file should be well understood by +the translator. When using PO mode, very little has to be known +about the format details, as PO mode takes care of them for her. + + <p>A simple entry can look like this: + +<pre class="example"> #: lib/error.c:116 + msgid "Unknown system error" + msgstr "Error desconegut del sistema" +</pre> + <p><a name="index-comments_002c-translator-57"></a><a name="index-comments_002c-automatic-58"></a><a name="index-comments_002c-extracted-59"></a>Entries begin with some optional white space. Usually, when generated +through GNU <code>gettext</code> tools, there is exactly one blank line +between entries. Then comments follow, on lines all starting with the +character <code>#</code>. There are two kinds of comments: those which have +some white space immediately following the <code>#</code> - the <var>translator +comments</var> -, which comments are created and maintained exclusively by the +translator, and those which have some non-white character just after the +<code>#</code> - the <var>automatic comments</var> -, which comments are created and +maintained automatically by GNU <code>gettext</code> tools. Comment lines +starting with <code>#.</code> contain comments given by the programmer, directed +at the translator; these comments are called <var>extracted comments</var> +because the <code>xgettext</code> program extracts them from the program's +source code. Comment lines starting with <code>#:</code> contain references to +the program's source code. Comment lines starting with <code>#,</code> contain +flags; more about these below. Comment lines starting with <code>#|</code> +contain the previous untranslated string for which the translator gave +a translation. + + <p>All comments, of either kind, are optional. + + <p><a name="index-msgid-60"></a><a name="index-msgstr-61"></a>After white space and comments, entries show two strings, namely +first the untranslated string as it appears in the original program +sources, and then, the translation of this string. The original +string is introduced by the keyword <code>msgid</code>, and the translation, +by <code>msgstr</code>. The two strings, untranslated and translated, +are quoted in various ways in the PO file, using <code>"</code> +delimiters and <code>\</code> escapes, but the translator does not really +have to pay attention to the precise quoting format, as PO mode fully +takes care of quoting for her. + + <p>The <code>msgid</code> strings, as well as automatic comments, are produced +and managed by other GNU <code>gettext</code> tools, and PO mode does not +provide means for the translator to alter these. The most she can +do is merely deleting them, and only by deleting the whole entry. +On the other hand, the <code>msgstr</code> string, as well as translator +comments, are really meant for the translator, and PO mode gives her +the full control she needs. + + <p>The comment lines beginning with <code>#,</code> are special because they are +not completely ignored by the programs as comments generally are. The +comma separated list of <var>flag</var>s is used by the <code>msgfmt</code> +program to give the user some better diagnostic messages. Currently +there are two forms of flags defined: + + <dl> +<dt><code>fuzzy</code><dd><a name="index-fuzzy_0040r_007b-flag_007d-62"></a>This flag can be generated by the <code>msgmerge</code> program or it can be +inserted by the translator herself. It shows that the <code>msgstr</code> +string might not be a correct translation (anymore). Only the translator +can judge if the translation requires further modification, or is +acceptable as is. Once satisfied with the translation, she then removes +this <code>fuzzy</code> attribute. The <code>msgmerge</code> program inserts this +when it combined the <code>msgid</code> and <code>msgstr</code> entries after fuzzy +search only. See <a href="#Fuzzy-Entries">Fuzzy Entries</a>. + + <br><dt><code>c-format</code><dd><a name="index-c_002dformat_0040r_007b-flag_007d-63"></a><dt><code>no-c-format</code><dd><a name="index-no_002dc_002dformat_0040r_007b-flag_007d-64"></a>These flags should not be added by a human. Instead only the +<code>xgettext</code> program adds them. In an automated PO file processing +system as proposed here, the user's changes would be thrown away again as +soon as the <code>xgettext</code> program generates a new template file. + + <p>The <code>c-format</code> flag indicates that the untranslated string and the +translation are supposed to be C format strings. The <code>no-c-format</code> +flag indicates that they are not C format strings, even though the untranslated +string happens to look like a C format string (with ‘<samp><span class="samp">%</span></samp>’ directives). + + <p>When the <code>c-format</code> flag is given for a string the <code>msgfmt</code> +program does some more tests to check the validity of the translation. +See <a href="#msgfmt-Invocation">msgfmt Invocation</a>, <a href="#c_002dformat-Flag">c-format Flag</a> and <a href="#c_002dformat">c-format</a>. + + <br><dt><code>objc-format</code><dd><a name="index-objc_002dformat_0040r_007b-flag_007d-65"></a><dt><code>no-objc-format</code><dd><a name="index-no_002dobjc_002dformat_0040r_007b-flag_007d-66"></a>Likewise for Objective C, see <a href="#objc_002dformat">objc-format</a>. + + <br><dt><code>sh-format</code><dd><a name="index-sh_002dformat_0040r_007b-flag_007d-67"></a><dt><code>no-sh-format</code><dd><a name="index-no_002dsh_002dformat_0040r_007b-flag_007d-68"></a>Likewise for Shell, see <a href="#sh_002dformat">sh-format</a>. + + <br><dt><code>python-format</code><dd><a name="index-python_002dformat_0040r_007b-flag_007d-69"></a><dt><code>no-python-format</code><dd><a name="index-no_002dpython_002dformat_0040r_007b-flag_007d-70"></a>Likewise for Python, see <a href="#python_002dformat">python-format</a>. + + <br><dt><code>lisp-format</code><dd><a name="index-lisp_002dformat_0040r_007b-flag_007d-71"></a><dt><code>no-lisp-format</code><dd><a name="index-no_002dlisp_002dformat_0040r_007b-flag_007d-72"></a>Likewise for Lisp, see <a href="#lisp_002dformat">lisp-format</a>. + + <br><dt><code>elisp-format</code><dd><a name="index-elisp_002dformat_0040r_007b-flag_007d-73"></a><dt><code>no-elisp-format</code><dd><a name="index-no_002delisp_002dformat_0040r_007b-flag_007d-74"></a>Likewise for Emacs Lisp, see <a href="#elisp_002dformat">elisp-format</a>. + + <br><dt><code>librep-format</code><dd><a name="index-librep_002dformat_0040r_007b-flag_007d-75"></a><dt><code>no-librep-format</code><dd><a name="index-no_002dlibrep_002dformat_0040r_007b-flag_007d-76"></a>Likewise for librep, see <a href="#librep_002dformat">librep-format</a>. + + <br><dt><code>scheme-format</code><dd><a name="index-scheme_002dformat_0040r_007b-flag_007d-77"></a><dt><code>no-scheme-format</code><dd><a name="index-no_002dscheme_002dformat_0040r_007b-flag_007d-78"></a>Likewise for Scheme, see <a href="#scheme_002dformat">scheme-format</a>. + + <br><dt><code>smalltalk-format</code><dd><a name="index-smalltalk_002dformat_0040r_007b-flag_007d-79"></a><dt><code>no-smalltalk-format</code><dd><a name="index-no_002dsmalltalk_002dformat_0040r_007b-flag_007d-80"></a>Likewise for Smalltalk, see <a href="#smalltalk_002dformat">smalltalk-format</a>. + + <br><dt><code>java-format</code><dd><a name="index-java_002dformat_0040r_007b-flag_007d-81"></a><dt><code>no-java-format</code><dd><a name="index-no_002djava_002dformat_0040r_007b-flag_007d-82"></a>Likewise for Java, see <a href="#java_002dformat">java-format</a>. + + <br><dt><code>csharp-format</code><dd><a name="index-csharp_002dformat_0040r_007b-flag_007d-83"></a><dt><code>no-csharp-format</code><dd><a name="index-no_002dcsharp_002dformat_0040r_007b-flag_007d-84"></a>Likewise for C#, see <a href="#csharp_002dformat">csharp-format</a>. + + <br><dt><code>awk-format</code><dd><a name="index-awk_002dformat_0040r_007b-flag_007d-85"></a><dt><code>no-awk-format</code><dd><a name="index-no_002dawk_002dformat_0040r_007b-flag_007d-86"></a>Likewise for awk, see <a href="#awk_002dformat">awk-format</a>. + + <br><dt><code>object-pascal-format</code><dd><a name="index-object_002dpascal_002dformat_0040r_007b-flag_007d-87"></a><dt><code>no-object-pascal-format</code><dd><a name="index-no_002dobject_002dpascal_002dformat_0040r_007b-flag_007d-88"></a>Likewise for Object Pascal, see <a href="#object_002dpascal_002dformat">object-pascal-format</a>. + + <br><dt><code>ycp-format</code><dd><a name="index-ycp_002dformat_0040r_007b-flag_007d-89"></a><dt><code>no-ycp-format</code><dd><a name="index-no_002dycp_002dformat_0040r_007b-flag_007d-90"></a>Likewise for YCP, see <a href="#ycp_002dformat">ycp-format</a>. + + <br><dt><code>tcl-format</code><dd><a name="index-tcl_002dformat_0040r_007b-flag_007d-91"></a><dt><code>no-tcl-format</code><dd><a name="index-no_002dtcl_002dformat_0040r_007b-flag_007d-92"></a>Likewise for Tcl, see <a href="#tcl_002dformat">tcl-format</a>. + + <br><dt><code>perl-format</code><dd><a name="index-perl_002dformat_0040r_007b-flag_007d-93"></a><dt><code>no-perl-format</code><dd><a name="index-no_002dperl_002dformat_0040r_007b-flag_007d-94"></a>Likewise for Perl, see <a href="#perl_002dformat">perl-format</a>. + + <br><dt><code>perl-brace-format</code><dd><a name="index-perl_002dbrace_002dformat_0040r_007b-flag_007d-95"></a><dt><code>no-perl-brace-format</code><dd><a name="index-no_002dperl_002dbrace_002dformat_0040r_007b-flag_007d-96"></a>Likewise for Perl brace, see <a href="#perl_002dformat">perl-format</a>. + + <br><dt><code>php-format</code><dd><a name="index-php_002dformat_0040r_007b-flag_007d-97"></a><dt><code>no-php-format</code><dd><a name="index-no_002dphp_002dformat_0040r_007b-flag_007d-98"></a>Likewise for PHP, see <a href="#php_002dformat">php-format</a>. + + <br><dt><code>gcc-internal-format</code><dd><a name="index-gcc_002dinternal_002dformat_0040r_007b-flag_007d-99"></a><dt><code>no-gcc-internal-format</code><dd><a name="index-no_002dgcc_002dinternal_002dformat_0040r_007b-flag_007d-100"></a>Likewise for the GCC sources, see <a href="#gcc_002dinternal_002dformat">gcc-internal-format</a>. + + <br><dt><code>gfc-internal-format</code><dd><a name="index-gfc_002dinternal_002dformat_0040r_007b-flag_007d-101"></a><dt><code>no-gfc-internal-format</code><dd><a name="index-no_002dgfc_002dinternal_002dformat_0040r_007b-flag_007d-102"></a>Likewise for the GNU Fortran Compiler sources, see <a href="#gfc_002dinternal_002dformat">gfc-internal-format</a>. + + <br><dt><code>qt-format</code><dd><a name="index-qt_002dformat_0040r_007b-flag_007d-103"></a><dt><code>no-qt-format</code><dd><a name="index-no_002dqt_002dformat_0040r_007b-flag_007d-104"></a>Likewise for Qt, see <a href="#qt_002dformat">qt-format</a>. + + <br><dt><code>qt-plural-format</code><dd><a name="index-qt_002dplural_002dformat_0040r_007b-flag_007d-105"></a><dt><code>no-qt-plural-format</code><dd><a name="index-no_002dqt_002dplural_002dformat_0040r_007b-flag_007d-106"></a>Likewise for Qt plural forms, see <a href="#qt_002dplural_002dformat">qt-plural-format</a>. + + <br><dt><code>kde-format</code><dd><a name="index-kde_002dformat_0040r_007b-flag_007d-107"></a><dt><code>no-kde-format</code><dd><a name="index-no_002dkde_002dformat_0040r_007b-flag_007d-108"></a>Likewise for KDE, see <a href="#kde_002dformat">kde-format</a>. + + <br><dt><code>boost-format</code><dd><a name="index-boost_002dformat_0040r_007b-flag_007d-109"></a><dt><code>no-boost-format</code><dd><a name="index-no_002dboost_002dformat_0040r_007b-flag_007d-110"></a>Likewise for Boost, see <a href="#boost_002dformat">boost-format</a>. + + </dl> + + <p><a name="index-msgctxt-111"></a><a name="index-context_002c-in-PO-files-112"></a>It is also possible to have entries with a context specifier. They look like +this: + +<pre class="example"> <var>white-space</var> + # <var>translator-comments</var> + #. <var>extracted-comments</var> + #: <var>reference</var>... + #, <var>flag</var>... + #| msgctxt <var>previous-context</var> + #| msgid <var>previous-untranslated-string</var> + msgctxt <var>context</var> + msgid <var>untranslated-string</var> + msgstr <var>translated-string</var> +</pre> + <p>The context serves to disambiguate messages with the same +<var>untranslated-string</var>. It is possible to have several entries with +the same <var>untranslated-string</var> in a PO file, provided that they each +have a different <var>context</var>. Note that an empty <var>context</var> string +and an absent <code>msgctxt</code> line do not mean the same thing. + + <p><a name="index-msgid_005fplural-113"></a><a name="index-plural-forms_002c-in-PO-files-114"></a>A different kind of entries is used for translations which involve +plural forms. + +<pre class="example"> <var>white-space</var> + # <var>translator-comments</var> + #. <var>extracted-comments</var> + #: <var>reference</var>... + #, <var>flag</var>... + #| msgid <var>previous-untranslated-string-singular</var> + #| msgid_plural <var>previous-untranslated-string-plural</var> + msgid <var>untranslated-string-singular</var> + msgid_plural <var>untranslated-string-plural</var> + msgstr[0] <var>translated-string-case-0</var> + ... + msgstr[N] <var>translated-string-case-n</var> +</pre> + <p>Such an entry can look like this: + +<pre class="example"> #: src/msgcmp.c:338 src/po-lex.c:699 + #, c-format + msgid "found %d fatal error" + msgid_plural "found %d fatal errors" + msgstr[0] "s'ha trobat %d error fatal" + msgstr[1] "s'han trobat %d errors fatals" +</pre> + <p>Here also, a <code>msgctxt</code> context can be specified before <code>msgid</code>, +like above. + + <p>Here, additional kinds of flags can be used: + + <dl> +<dt><code>range:</code><dd><a name="index-range_003a_0040r_007b-flag_007d-115"></a>This flag is followed by a range of non-negative numbers, using the syntax +<code>range: </code><var>minimum-value</var><code>..</code><var>maximum-value</var>. It designates the +possible values that the numeric parameter of the message can take. In some +languages, translators may produce slightly better translations if they know +that the value can only take on values between 0 and 10, for example. +</dl> + + <p>The <var>previous-untranslated-string</var> is optionally inserted by the +<code>msgmerge</code> program, at the same time when it marks a message fuzzy. +It helps the translator to see which changes were done by the developers +on the <var>untranslated-string</var>. + + <p>It happens that some lines, usually whitespace or comments, follow the +very last entry of a PO file. Such lines are not part of any entry, +and will be dropped when the PO file is processed by the tools, or may +disturb some PO file editors. + + <p>The remainder of this section may be safely skipped by those using +a PO file editor, yet it may be interesting for everybody to have a better +idea of the precise format of a PO file. On the other hand, those +wishing to modify PO files by hand should carefully continue reading on. + + <p>Each of <var>untranslated-string</var> and <var>translated-string</var> respects +the C syntax for a character string, including the surrounding quotes +and embedded backslashed escape sequences. When the time comes +to write multi-line strings, one should not use escaped newlines. +Instead, a closing quote should follow the last character on the +line to be continued, and an opening quote should resume the string +at the beginning of the following PO file line. For example: + +<pre class="example"> msgid "" + "Here is an example of how one might continue a very long string\n" + "for the common case the string represents multi-line output.\n" +</pre> + <p class="noindent">In this example, the empty string is used on the first line, to +allow better alignment of the <code>H</code> from the word ‘<samp><span class="samp">Here</span></samp>’ +over the <code>f</code> from the word ‘<samp><span class="samp">for</span></samp>’. In this example, the +<code>msgid</code> keyword is followed by three strings, which are meant +to be concatenated. Concatenating the empty string does not change +the resulting overall string, but it is a way for us to comply with +the necessity of <code>msgid</code> to be followed by a string on the same +line, while keeping the multi-line presentation left-justified, as +we find this to be a cleaner disposition. The empty string could have +been omitted, but only if the string starting with ‘<samp><span class="samp">Here</span></samp>’ was +promoted on the first line, right after <code>msgid</code>.<a rel="footnote" href="#fn-2" name="fnd-2"><sup>2</sup></a> It was not really necessary +either to switch between the two last quoted strings immediately after +the newline ‘<samp><span class="samp">\n</span></samp>’, the switch could have occurred after <em>any</em> +other character, we just did it this way because it is neater. + + <p><a name="index-newlines-in-PO-files-116"></a>One should carefully distinguish between end of lines marked as +‘<samp><span class="samp">\n</span></samp>’ <em>inside</em> quotes, which are part of the represented +string, and end of lines in the PO file itself, outside string quotes, +which have no incidence on the represented string. + + <p><a name="index-comments-in-PO-files-117"></a>Outside strings, white lines and comments may be used freely. +Comments start at the beginning of a line with ‘<samp><span class="samp">#</span></samp>’ and extend +until the end of the PO file line. Comments written by translators +should have the initial ‘<samp><span class="samp">#</span></samp>’ immediately followed by some white +space. If the ‘<samp><span class="samp">#</span></samp>’ is not immediately followed by white space, +this comment is most likely generated and managed by specialized GNU +tools, and might disappear or be replaced unexpectedly when the PO +file is given to <code>msgmerge</code>. + +<div class="node"> +<a name="Sources"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Template">Template</a>, +Previous: <a rel="previous" accesskey="p" href="#PO-Files">PO Files</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">4 Preparing Program Sources</h2> + + <p><a name="index-preparing-programs-for-translation-118"></a> +<!-- FIXME: Rewrite (the whole chapter). --> + + <p>For the programmer, changes to the C source code fall into three +categories. First, you have to make the localization functions +known to all modules needing message translation. Second, you should +properly trigger the operation of GNU <code>gettext</code> when the program +initializes, usually from the <code>main</code> function. Last, you should +identify, adjust and mark all constant strings in your program +needing translation. + +<ul class="menu"> +<li><a accesskey="1" href="#Importing">Importing</a>: Importing the <code>gettext</code> declaration +<li><a accesskey="2" href="#Triggering">Triggering</a>: Triggering <code>gettext</code> Operations +<li><a accesskey="3" href="#Preparing-Strings">Preparing Strings</a>: Preparing Translatable Strings +<li><a accesskey="4" href="#Mark-Keywords">Mark Keywords</a>: How Marks Appear in Sources +<li><a accesskey="5" href="#Marking">Marking</a>: Marking Translatable Strings +<li><a accesskey="6" href="#c_002dformat-Flag">c-format Flag</a>: Telling something about the following string +<li><a accesskey="7" href="#Special-cases">Special cases</a>: Special Cases of Translatable Strings +<li><a accesskey="8" href="#Bug-Report-Address">Bug Report Address</a>: Letting Users Report Translation Bugs +<li><a accesskey="9" href="#Names">Names</a>: Marking Proper Names for Translation +<li><a href="#Libraries">Libraries</a>: Preparing Library Sources +</ul> + +<div class="node"> +<a name="Importing"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Triggering">Triggering</a>, +Previous: <a rel="previous" accesskey="p" href="#Sources">Sources</a>, +Up: <a rel="up" accesskey="u" href="#Sources">Sources</a> + +</div> + +<h3 class="section">4.1 Importing the <code>gettext</code> declaration</h3> + + <p>Presuming that your set of programs, or package, has been adjusted +so all needed GNU <code>gettext</code> files are available, and your +<samp><span class="file">Makefile</span></samp> files are adjusted (see <a href="#Maintainers">Maintainers</a>), each C module +having translated C strings should contain the line: + + <p><a name="index-include-file-_0040file_007blibintl_002eh_007d-119"></a> +<pre class="example"> #include <libintl.h> +</pre> + <p>Similarly, each C module containing <code>printf()</code>/<code>fprintf()</code>/... +calls with a format string that could be a translated C string (even if +the C string comes from a different C module) should contain the line: + +<pre class="example"> #include <libintl.h> +</pre> + <div class="node"> +<a name="Triggering"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Preparing-Strings">Preparing Strings</a>, +Previous: <a rel="previous" accesskey="p" href="#Importing">Importing</a>, +Up: <a rel="up" accesskey="u" href="#Sources">Sources</a> + +</div> + +<h3 class="section">4.2 Triggering <code>gettext</code> Operations</h3> + + <p><a name="index-initialization-120"></a>The initialization of locale data should be done with more or less +the same code in every program, as demonstrated below: + +<pre class="example"> int + main (int argc, char *argv[]) + { + ... + setlocale (LC_ALL, ""); + bindtextdomain (PACKAGE, LOCALEDIR); + textdomain (PACKAGE); + ... + } +</pre> + <p><var>PACKAGE</var> and <var>LOCALEDIR</var> should be provided either by +<samp><span class="file">config.h</span></samp> or by the Makefile. For now consult the <code>gettext</code> +or <code>hello</code> sources for more information. + + <p><a name="index-locale-category_002c-LC_005fALL-121"></a><a name="index-locale-category_002c-LC_005fCTYPE-122"></a>The use of <code>LC_ALL</code> might not be appropriate for you. +<code>LC_ALL</code> includes all locale categories and especially +<code>LC_CTYPE</code>. This latter category is responsible for determining +character classes with the <code>isalnum</code> etc. functions from +<samp><span class="file">ctype.h</span></samp> which could especially for programs, which process some +kind of input language, be wrong. For example this would mean that a +source code using the ç (c-cedilla character) is runnable in +France but not in the U.S. + + <p>Some systems also have problems with parsing numbers using the +<code>scanf</code> functions if an other but the <code>LC_ALL</code> locale category is +used. The standards say that additional formats but the one known in the +<code>"C"</code> locale might be recognized. But some systems seem to reject +numbers in the <code>"C"</code> locale format. In some situation, it might +also be a problem with the notation itself which makes it impossible to +recognize whether the number is in the <code>"C"</code> locale or the local +format. This can happen if thousands separator characters are used. +Some locales define this character according to the national +conventions to <code>'.'</code> which is the same character used in the +<code>"C"</code> locale to denote the decimal point. + + <p>So it is sometimes necessary to replace the <code>LC_ALL</code> line in the +code above by a sequence of <code>setlocale</code> lines + +<pre class="example"> { + ... + setlocale (LC_CTYPE, ""); + setlocale (LC_MESSAGES, ""); + ... + } +</pre> + <p><a name="index-locale-category_002c-LC_005fCTYPE-123"></a><a name="index-locale-category_002c-LC_005fCOLLATE-124"></a><a name="index-locale-category_002c-LC_005fMONETARY-125"></a><a name="index-locale-category_002c-LC_005fNUMERIC-126"></a><a name="index-locale-category_002c-LC_005fTIME-127"></a><a name="index-locale-category_002c-LC_005fMESSAGES-128"></a><a name="index-locale-category_002c-LC_005fRESPONSES-129"></a>On all POSIX conformant systems the locale categories <code>LC_CTYPE</code>, +<code>LC_MESSAGES</code>, <code>LC_COLLATE</code>, <code>LC_MONETARY</code>, +<code>LC_NUMERIC</code>, and <code>LC_TIME</code> are available. On some systems +which are only ISO C compliant, <code>LC_MESSAGES</code> is missing, but +a substitute for it is defined in GNU gettext's <code><libintl.h></code> and +in GNU gnulib's <code><locale.h></code>. + + <p>Note that changing the <code>LC_CTYPE</code> also affects the functions +declared in the <code><ctype.h></code> standard header and some functions +declared in the <code><string.h></code> and <code><stdlib.h></code> standard headers. +If this is not +desirable in your application (for example in a compiler's parser), +you can use a set of substitute functions which hardwire the C locale, +such as found in the modules ‘<samp><span class="samp">c-ctype</span></samp>’, ‘<samp><span class="samp">c-strcase</span></samp>’, +‘<samp><span class="samp">c-strcasestr</span></samp>’, ‘<samp><span class="samp">c-strtod</span></samp>’, ‘<samp><span class="samp">c-strtold</span></samp>’ in the GNU gnulib +source distribution. + + <p>It is also possible to switch the locale forth and back between the +environment dependent locale and the C locale, but this approach is +normally avoided because a <code>setlocale</code> call is expensive, +because it is tedious to determine the places where a locale switch +is needed in a large program's source, and because switching a locale +is not multithread-safe. + +<div class="node"> +<a name="Preparing-Strings"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Mark-Keywords">Mark Keywords</a>, +Previous: <a rel="previous" accesskey="p" href="#Triggering">Triggering</a>, +Up: <a rel="up" accesskey="u" href="#Sources">Sources</a> + +</div> + +<h3 class="section">4.3 Preparing Translatable Strings</h3> + + <p><a name="index-marking-strings_002c-preparations-130"></a>Before strings can be marked for translations, they sometimes need to +be adjusted. Usually preparing a string for translation is done right +before marking it, during the marking phase which is described in the +next sections. What you have to keep in mind while doing that is the +following. + + <ul> +<li>Decent English style. + + <li>Entire sentences. + + <li>Split at paragraphs. + + <li>Use format strings instead of string concatenation. + + <li>Avoid unusual markup and unusual control characters. +</ul> + +<p class="noindent">Let's look at some examples of these guidelines. + + <p><a name="index-style-131"></a>Translatable strings should be in good English style. If slang language +with abbreviations and shortcuts is used, often translators will not +understand the message and will produce very inappropriate translations. + +<pre class="example"> "%s: is parameter\n" +</pre> + <p class="noindent">This is nearly untranslatable: Is the displayed item <em>a</em> parameter or +<em>the</em> parameter? + +<pre class="example"> "No match" +</pre> + <p class="noindent">The ambiguity in this message makes it unintelligible: Is the program +attempting to set something on fire? Does it mean "The given object does +not match the template"? Does it mean "The template does not fit for any +of the objects"? + + <p><a name="index-ambiguities-132"></a>In both cases, adding more words to the message will help both the +translator and the English speaking user. + + <p><a name="index-sentences-133"></a>Translatable strings should be entire sentences. It is often not possible +to translate single verbs or adjectives in a substitutable way. + +<pre class="example"> printf ("File %s is %s protected", filename, rw ? "write" : "read"); +</pre> + <p class="noindent">Most translators will not look at the source and will thus only see the +string <code>"File %s is %s protected"</code>, which is unintelligible. Change +this to + +<pre class="example"> printf (rw ? "File %s is write protected" : "File %s is read protected", + filename); +</pre> + <p class="noindent">This way the translator will not only understand the message, she will +also be able to find the appropriate grammatical construction. A French +translator for example translates "write protected" like "protected +against writing". + + <p>Entire sentences are also important because in many languages, the +declination of some word in a sentence depends on the gender or the +number (singular/plural) of another part of the sentence. There are +usually more interdependencies between words than in English. The +consequence is that asking a translator to translate two half-sentences +and then combining these two half-sentences through dumb string concatenation +will not work, for many languages, even though it would work for English. +That's why translators need to handle entire sentences. + + <p>Often sentences don't fit into a single line. If a sentence is output +using two subsequent <code>printf</code> statements, like this + +<pre class="example"> printf ("Locale charset \"%s\" is different from\n", lcharset); + printf ("input file charset \"%s\".\n", fcharset); +</pre> + <p class="noindent">the translator would have to translate two half sentences, but nothing +in the POT file would tell her that the two half sentences belong together. +It is necessary to merge the two <code>printf</code> statements so that the +translator can handle the entire sentence at once and decide at which +place to insert a line break in the translation (if at all): + +<pre class="example"> printf ("Locale charset \"%s\" is different from\n\ + input file charset \"%s\".\n", lcharset, fcharset); +</pre> + <p>You may now ask: how about two or more adjacent sentences? Like in this case: + +<pre class="example"> puts ("Apollo 13 scenario: Stack overflow handling failed."); + puts ("On the next stack overflow we will crash!!!"); +</pre> + <p class="noindent">Should these two statements merged into a single one? I would recommend to +merge them if the two sentences are related to each other, because then it +makes it easier for the translator to understand and translate both. On +the other hand, if one of the two messages is a stereotypic one, occurring +in other places as well, you will do a favour to the translator by not +merging the two. (Identical messages occurring in several places are +combined by xgettext, so the translator has to handle them once only.) + + <p><a name="index-paragraphs-134"></a>Translatable strings should be limited to one paragraph; don't let a +single message be longer than ten lines. The reason is that when the +translatable string changes, the translator is faced with the task of +updating the entire translated string. Maybe only a single word will +have changed in the English string, but the translator doesn't see that +(with the current translation tools), therefore she has to proofread +the entire message. + + <p><a name="index-help-option-135"></a>Many GNU programs have a ‘<samp><span class="samp">--help</span></samp>’ output that extends over several +screen pages. It is a courtesy towards the translators to split such a +message into several ones of five to ten lines each. While doing that, +you can also attempt to split the documented options into groups, +such as the input options, the output options, and the informative +output options. This will help every user to find the option he is +looking for. + + <p><a name="index-string-concatenation-136"></a><a name="index-concatenation-of-strings-137"></a>Hardcoded string concatenation is sometimes used to construct English +strings: + +<pre class="example"> strcpy (s, "Replace "); + strcat (s, object1); + strcat (s, " with "); + strcat (s, object2); + strcat (s, "?"); +</pre> + <p class="noindent">In order to present to the translator only entire sentences, and also +because in some languages the translator might want to swap the order +of <code>object1</code> and <code>object2</code>, it is necessary to change this +to use a format string: + +<pre class="example"> sprintf (s, "Replace %s with %s?", object1, object2); +</pre> + <p><a name="index-g_t_0040code_007binttypes_002eh_007d-138"></a>A similar case is compile time concatenation of strings. The ISO C 99 +include file <code><inttypes.h></code> contains a macro <code>PRId64</code> that +can be used as a formatting directive for outputting an ‘<samp><span class="samp">int64_t</span></samp>’ +integer through <code>printf</code>. It expands to a constant string, usually +"d" or "ld" or "lld" or something like this, depending on the platform. +Assume you have code like + +<pre class="example"> printf ("The amount is %0" PRId64 "\n", number); +</pre> + <p class="noindent">The <code>gettext</code> tools and library have special support for these +<code><inttypes.h></code> macros. You can therefore simply write + +<pre class="example"> printf (gettext ("The amount is %0" PRId64 "\n"), number); +</pre> + <p class="noindent">The PO file will contain the string "The amount is %0<PRId64>\n". +The translators will provide a translation containing "%0<PRId64>" +as well, and at runtime the <code>gettext</code> function's result will +contain the appropriate constant string, "d" or "ld" or "lld". + + <p>This works only for the predefined <code><inttypes.h></code> macros. If +you have defined your own similar macros, let's say ‘<samp><span class="samp">MYPRId64</span></samp>’, +that are not known to <code>xgettext</code>, the solution for this problem +is to change the code like this: + +<pre class="example"> char buf1[100]; + sprintf (buf1, "%0" MYPRId64, number); + printf (gettext ("The amount is %s\n"), buf1); +</pre> + <p>This means, you put the platform dependent code in one statement, and the +internationalization code in a different statement. Note that a buffer length +of 100 is safe, because all available hardware integer types are limited to +128 bits, and to print a 128 bit integer one needs at most 54 characters, +regardless whether in decimal, octal or hexadecimal. + + <p><a name="index-Java_002c-string-concatenation-139"></a><a name="index-C_0023_002c-string-concatenation-140"></a>All this applies to other programming languages as well. For example, in +Java and C#, string concatenation is very frequently used, because it is a +compiler built-in operator. Like in C, in Java, you would change + +<pre class="example"> System.out.println("Replace "+object1+" with "+object2+"?"); +</pre> + <p class="noindent">into a statement involving a format string: + +<pre class="example"> System.out.println( + MessageFormat.format("Replace {0} with {1}?", + new Object[] { object1, object2 })); +</pre> + <p class="noindent">Similarly, in C#, you would change + +<pre class="example"> Console.WriteLine("Replace "+object1+" with "+object2+"?"); +</pre> + <p class="noindent">into a statement involving a format string: + +<pre class="example"> Console.WriteLine( + String.Format("Replace {0} with {1}?", object1, object2)); +</pre> + <p><a name="index-markup-141"></a><a name="index-control-characters-142"></a>Unusual markup or control characters should not be used in translatable +strings. Translators will likely not understand the particular meaning +of the markup or control characters. + + <p>For example, if you have a convention that ‘<samp><span class="samp">|</span></samp>’ delimits the +left-hand and right-hand part of some GUI elements, translators will +often not understand it without specific comments. It might be +better to have the translator translate the left-hand and right-hand +part separately. + + <p>Another example is the ‘<samp><span class="samp">argp</span></samp>’ convention to use a single ‘<samp><span class="samp">\v</span></samp>’ +(vertical tab) control character to delimit two sections inside a +string. This is flawed. Some translators may convert it to a simple +newline, some to blank lines. With some PO file editors it may not be +easy to even enter a vertical tab control character. So, you cannot +be sure that the translation will contain a ‘<samp><span class="samp">\v</span></samp>’ character, at the +corresponding position. The solution is, again, to let the translator +translate two separate strings and combine at run-time the two translated +strings with the ‘<samp><span class="samp">\v</span></samp>’ required by the convention. + + <p>HTML markup, however, is common enough that it's probably ok to use in +translatable strings. But please bear in mind that the GNU gettext tools +don't verify that the translations are well-formed HTML. + +<div class="node"> +<a name="Mark-Keywords"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Marking">Marking</a>, +Previous: <a rel="previous" accesskey="p" href="#Preparing-Strings">Preparing Strings</a>, +Up: <a rel="up" accesskey="u" href="#Sources">Sources</a> + +</div> + +<h3 class="section">4.4 How Marks Appear in Sources</h3> + + <p><a name="index-marking-strings-that-require-translation-143"></a> +All strings requiring translation should be marked in the C sources. Marking +is done in such a way that each translatable string appears to be +the sole argument of some function or preprocessor macro. There are +only a few such possible functions or macros meant for translation, +and their names are said to be marking keywords. The marking is +attached to strings themselves, rather than to what we do with them. +This approach has more uses. A blatant example is an error message +produced by formatting. The format string needs translation, as +well as some strings inserted through some ‘<samp><span class="samp">%s</span></samp>’ specification +in the format, while the result from <code>sprintf</code> may have so many +different instances that it is impractical to list them all in some +‘<samp><span class="samp">error_string_out()</span></samp>’ routine, say. + + <p>This marking operation has two goals. The first goal of marking +is for triggering the retrieval of the translation, at run time. +The keyword is possibly resolved into a routine able to dynamically +return the proper translation, as far as possible or wanted, for the +argument string. Most localizable strings are found in executable +positions, that is, attached to variables or given as parameters to +functions. But this is not universal usage, and some translatable +strings appear in structured initializations. See <a href="#Special-cases">Special cases</a>. + + <p>The second goal of the marking operation is to help <code>xgettext</code> +at properly extracting all translatable strings when it scans a set +of program sources and produces PO file templates. + + <p>The canonical keyword for marking translatable strings is +‘<samp><span class="samp">gettext</span></samp>’, it gave its name to the whole GNU <code>gettext</code> +package. For packages making only light use of the ‘<samp><span class="samp">gettext</span></samp>’ +keyword, macro or function, it is easily used <em>as is</em>. However, +for packages using the <code>gettext</code> interface more heavily, it +is usually more convenient to give the main keyword a shorter, less +obtrusive name. Indeed, the keyword might appear on a lot of strings +all over the package, and programmers usually do not want nor need +their program sources to remind them forcefully, all the time, that they +are internationalized. Further, a long keyword has the disadvantage +of using more horizontal space, forcing more indentation work on +sources for those trying to keep them within 79 or 80 columns. + + <p><a name="index-g_t_0040code_007b_005f_007d_002c-a-macro-to-mark-strings-for-translation-144"></a>Many packages use ‘<samp><span class="samp">_</span></samp>’ (a simple underline) as a keyword, +and write ‘<samp><span class="samp">_("Translatable string")</span></samp>’ instead of ‘<samp><span class="samp">gettext +("Translatable string")</span></samp>’. Further, the coding rule, from GNU standards, +wanting that there is a space between the keyword and the opening +parenthesis is relaxed, in practice, for this particular usage. +So, the textual overhead per translatable string is reduced to +only three characters: the underline and the two parentheses. +However, even if GNU <code>gettext</code> uses this convention internally, +it does not offer it officially. The real, genuine keyword is truly +‘<samp><span class="samp">gettext</span></samp>’ indeed. It is fairly easy for those wanting to use +‘<samp><span class="samp">_</span></samp>’ instead of ‘<samp><span class="samp">gettext</span></samp>’ to declare: + +<pre class="example"> #include <libintl.h> + #define _(String) gettext (String) +</pre> + <p class="noindent">instead of merely using ‘<samp><span class="samp">#include <libintl.h></span></samp>’. + + <p>The marking keywords ‘<samp><span class="samp">gettext</span></samp>’ and ‘<samp><span class="samp">_</span></samp>’ take the translatable +string as sole argument. It is also possible to define marking functions +that take it at another argument position. It is even possible to make +the marked argument position depend on the total number of arguments of +the function call; this is useful in C++. All this is achieved using +<code>xgettext</code>'s ‘<samp><span class="samp">--keyword</span></samp>’ option. How to pass such an option +to <code>xgettext</code>, assuming that <code>gettextize</code> is used, is described +in <a href="#po_002fMakevars">po/Makevars</a> and <a href="#AM_005fXGETTEXT_005fOPTION">AM_XGETTEXT_OPTION</a>. + + <p>Note also that long strings can be split across lines, into multiple +adjacent string tokens. Automatic string concatenation is performed +at compile time according to ISO C and ISO C++; <code>xgettext</code> also +supports this syntax. + + <p>Later on, the maintenance is relatively easy. If, as a programmer, +you add or modify a string, you will have to ask yourself if the +new or altered string requires translation, and include it within +‘<samp><span class="samp">_()</span></samp>’ if you think it should be translated. For example, ‘<samp><span class="samp">"%s"</span></samp>’ +is an example of string <em>not</em> requiring translation. But +‘<samp><span class="samp">"%s: %d"</span></samp>’ <em>does</em> require translation, because in French, unlike +in English, it's customary to put a space before a colon. + +<div class="node"> +<a name="Marking"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#c_002dformat-Flag">c-format Flag</a>, +Previous: <a rel="previous" accesskey="p" href="#Mark-Keywords">Mark Keywords</a>, +Up: <a rel="up" accesskey="u" href="#Sources">Sources</a> + +</div> + +<h3 class="section">4.5 Marking Translatable Strings</h3> + + <p><a name="index-marking-strings-for-translation-145"></a> +In PO mode, one set of features is meant more for the programmer than +for the translator, and allows him to interactively mark which strings, +in a set of program sources, are translatable, and which are not. +Even if it is a fairly easy job for a programmer to find and mark +such strings by other means, using any editor of his choice, PO mode +makes this work more comfortable. Further, this gives translators +who feel a little like programmers, or programmers who feel a little +like translators, a tool letting them work at marking translatable +strings in the program sources, while simultaneously producing a set of +translation in some language, for the package being internationalized. + + <p><a name="index-g_t_0040code_007betags_007d_002c-using-for-marking-strings-146"></a>The set of program sources, targeted by the PO mode commands describe +here, should have an Emacs tags table constructed for your project, +prior to using these PO file commands. This is easy to do. In any +shell window, change the directory to the root of your project, then +execute a command resembling: + +<pre class="example"> etags src/*.[hc] lib/*.[hc] +</pre> + <p class="noindent">presuming here you want to process all <samp><span class="file">.h</span></samp> and <samp><span class="file">.c</span></samp> files +from the <samp><span class="file">src/</span></samp> and <samp><span class="file">lib/</span></samp> directories. This command will +explore all said files and create a <samp><span class="file">TAGS</span></samp> file in your root +directory, somewhat summarizing the contents using a special file +format Emacs can understand. + + <p><a name="index-g_t_0040file_007bTAGS_007d_002c-and-marking-translatable-strings-147"></a>For packages following the GNU coding standards, there is +a make goal <code>tags</code> or <code>TAGS</code> which constructs the tag files in +all directories and for all files containing source code. + + <p>Once your <samp><span class="file">TAGS</span></samp> file is ready, the following commands assist +the programmer at marking translatable strings in his set of sources. +But these commands are necessarily driven from within a PO file +window, and it is likely that you do not even have such a PO file yet. +This is not a problem at all, as you may safely open a new, empty PO +file, mainly for using these commands. This empty PO file will slowly +fill in while you mark strings as translatable in your program sources. + + <dl> +<dt><kbd>,</kbd><dd><a name="index-g_t_002c_0040r_007b_002c-PO-Mode-command_007d-148"></a>Search through program sources for a string which looks like a +candidate for translation (<code>po-tags-search</code>). + + <br><dt><kbd>M-,</kbd><dd><a name="index-M_002d_002c_0040r_007b_002c-PO-Mode-command_007d-149"></a>Mark the last string found with ‘<samp><span class="samp">_()</span></samp>’ (<code>po-mark-translatable</code>). + + <br><dt><kbd>M-.</kbd><dd><a name="index-M_002d_002e_0040r_007b_002c-PO-Mode-command_007d-150"></a>Mark the last string found with a keyword taken from a set of possible +keywords. This command with a prefix allows some management of these +keywords (<code>po-select-mark-and-mark</code>). + + </dl> + + <p><a name="index-po_002dtags_002dsearch_0040r_007b_002c-PO-Mode-command_007d-151"></a>The <kbd>,</kbd> (<code>po-tags-search</code>) command searches for the next +occurrence of a string which looks like a possible candidate for +translation, and displays the program source in another Emacs window, +positioned in such a way that the string is near the top of this other +window. If the string is too big to fit whole in this window, it is +positioned so only its end is shown. In any case, the cursor +is left in the PO file window. If the shown string would be better +presented differently in different native languages, you may mark it +using <kbd>M-,</kbd> or <kbd>M-.</kbd>. Otherwise, you might rather ignore it +and skip to the next string by merely repeating the <kbd>,</kbd> command. + + <p>A string is a good candidate for translation if it contains a sequence +of three or more letters. A string containing at most two letters in +a row will be considered as a candidate if it has more letters than +non-letters. The command disregards strings containing no letters, +or isolated letters only. It also disregards strings within comments, +or strings already marked with some keyword PO mode knows (see below). + + <p>If you have never told Emacs about some <samp><span class="file">TAGS</span></samp> file to use, the +command will request that you specify one from the minibuffer, the +first time you use the command. You may later change your <samp><span class="file">TAGS</span></samp> +file by using the regular Emacs command <kbd>M-x visit-tags-table</kbd><!-- /@w -->, +which will ask you to name the precise <samp><span class="file">TAGS</span></samp> file you want +to use. See <a href="emacs.html#Tags">Tag Tables</a>. + + <p>Each time you use the <kbd>,</kbd> command, the search resumes from where it was +left by the previous search, and goes through all program sources, +obeying the <samp><span class="file">TAGS</span></samp> file, until all sources have been processed. +However, by giving a prefix argument to the command (<kbd>C-u ,</kbd>)<!-- /@w -->, you may request that the search be restarted all over again +from the first program source; but in this case, strings that you +recently marked as translatable will be automatically skipped. + + <p>Using this <kbd>,</kbd> command does not prevent using of other regular +Emacs tags commands. For example, regular <code>tags-search</code> or +<code>tags-query-replace</code> commands may be used without disrupting the +independent <kbd>,</kbd> search sequence. However, as implemented, the +<em>initial</em> <kbd>,</kbd> command (or the <kbd>,</kbd> command is used with a +prefix) might also reinitialize the regular Emacs tags searching to the +first tags file, this reinitialization might be considered spurious. + + <p><a name="index-po_002dmark_002dtranslatable_0040r_007b_002c-PO-Mode-command_007d-152"></a><a name="index-po_002dselect_002dmark_002dand_002dmark_0040r_007b_002c-PO-Mode-command_007d-153"></a>The <kbd>M-,</kbd> (<code>po-mark-translatable</code>) command will mark the +recently found string with the ‘<samp><span class="samp">_</span></samp>’ keyword. The <kbd>M-.</kbd> +(<code>po-select-mark-and-mark</code>) command will request that you type +one keyword from the minibuffer and use that keyword for marking +the string. Both commands will automatically create a new PO file +untranslated entry for the string being marked, and make it the +current entry (making it easy for you to immediately proceed to its +translation, if you feel like doing it right away). It is possible +that the modifications made to the program source by <kbd>M-,</kbd> or +<kbd>M-.</kbd> render some source line longer than 80 columns, forcing you +to break and re-indent this line differently. You may use the <kbd>O</kbd> +command from PO mode, or any other window changing command from +Emacs, to break out into the program source window, and do any +needed adjustments. You will have to use some regular Emacs command +to return the cursor to the PO file window, if you want command +<kbd>,</kbd> for the next string, say. + + <p>The <kbd>M-.</kbd> command has a few built-in speedups, so you do not +have to explicitly type all keywords all the time. The first such +speedup is that you are presented with a <em>preferred</em> keyword, +which you may accept by merely typing <kbd><RET></kbd> at the prompt. +The second speedup is that you may type any non-ambiguous prefix of the +keyword you really mean, and the command will complete it automatically +for you. This also means that PO mode has to <em>know</em> all +your possible keywords, and that it will not accept mistyped keywords. + + <p>If you reply <kbd>?</kbd> to the keyword request, the command gives a +list of all known keywords, from which you may choose. When the +command is prefixed by an argument (<kbd>C-u M-.</kbd>)<!-- /@w -->, it inhibits +updating any program source or PO file buffer, and does some simple +keyword management instead. In this case, the command asks for a +keyword, written in full, which becomes a new allowed keyword for +later <kbd>M-.</kbd> commands. Moreover, this new keyword automatically +becomes the <em>preferred</em> keyword for later commands. By typing +an already known keyword in response to <kbd>C-u M-.</kbd><!-- /@w -->, one merely +changes the <em>preferred</em> keyword and does nothing more. + + <p>All keywords known for <kbd>M-.</kbd> are recognized by the <kbd>,</kbd> command +when scanning for strings, and strings already marked by any of those +known keywords are automatically skipped. If many PO files are opened +simultaneously, each one has its own independent set of known keywords. +There is no provision in PO mode, currently, for deleting a known +keyword, you have to quit the file (maybe using <kbd>q</kbd>) and reopen +it afresh. When a PO file is newly brought up in an Emacs window, only +‘<samp><span class="samp">gettext</span></samp>’ and ‘<samp><span class="samp">_</span></samp>’ are known as keywords, and ‘<samp><span class="samp">gettext</span></samp>’ +is preferred for the <kbd>M-.</kbd> command. In fact, this is not useful to +prefer ‘<samp><span class="samp">_</span></samp>’, as this one is already built in the <kbd>M-,</kbd> command. + +<div class="node"> +<a name="c-format-Flag"></a> +<a name="c_002dformat-Flag"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Special-cases">Special cases</a>, +Previous: <a rel="previous" accesskey="p" href="#Marking">Marking</a>, +Up: <a rel="up" accesskey="u" href="#Sources">Sources</a> + +</div> + +<h3 class="section">4.6 Special Comments preceding Keywords</h3> + +<!-- FIXME document c-format and no-c-format. --> + <p><a name="index-format-strings-154"></a>In C programs strings are often used within calls of functions from the +<code>printf</code> family. The special thing about these format strings is +that they can contain format specifiers introduced with <kbd>%</kbd>. Assume +we have the code + +<pre class="example"> printf (gettext ("String `%s' has %d characters\n"), s, strlen (s)); +</pre> + <p class="noindent">A possible German translation for the above string might be: + +<pre class="example"> "%d Zeichen lang ist die Zeichenkette `%s'" +</pre> + <p>A C programmer, even if he cannot speak German, will recognize that +there is something wrong here. The order of the two format specifiers +is changed but of course the arguments in the <code>printf</code> don't have. +This will most probably lead to problems because now the length of the +string is regarded as the address. + + <p>To prevent errors at runtime caused by translations the <code>msgfmt</code> +tool can check statically whether the arguments in the original and the +translation string match in type and number. If this is not the case +and the ‘<samp><span class="samp">-c</span></samp>’ option has been passed to <code>msgfmt</code>, <code>msgfmt</code> +will give an error and refuse to produce a MO file. Thus consequent +use of ‘<samp><span class="samp">msgfmt -c</span></samp>’ will catch the error, so that it cannot cause +cause problems at runtime. + +<p class="noindent">If the word order in the above German translation would be correct one +would have to write + +<pre class="example"> "%2$d Zeichen lang ist die Zeichenkette `%1$s'" +</pre> + <p class="noindent">The routines in <code>msgfmt</code> know about this special notation. + + <p>Because not all strings in a program must be format strings it is not +useful for <code>msgfmt</code> to test all the strings in the <samp><span class="file">.po</span></samp> file. +This might cause problems because the string might contain what looks +like a format specifier, but the string is not used in <code>printf</code>. + + <p>Therefore the <code>xgettext</code> adds a special tag to those messages it +thinks might be a format string. There is no absolute rule for this, +only a heuristic. In the <samp><span class="file">.po</span></samp> file the entry is marked using the +<code>c-format</code> flag in the <code>#,</code> comment line (see <a href="#PO-Files">PO Files</a>). + + <p><a name="index-c_002dformat_0040r_007b_002c-and-_0040code_007bxgettext_007d_007d-155"></a><a name="index-no_002dc_002dformat_0040r_007b_002c-and-_0040code_007bxgettext_007d_007d-156"></a>The careful reader now might say that this again can cause problems. +The heuristic might guess it wrong. This is true and therefore +<code>xgettext</code> knows about a special kind of comment which lets +the programmer take over the decision. If in the same line as or +the immediately preceding line to the <code>gettext</code> keyword +the <code>xgettext</code> program finds a comment containing the words +<code>xgettext:c-format</code>, it will mark the string in any case with +the <code>c-format</code> flag. This kind of comment should be used when +<code>xgettext</code> does not recognize the string as a format string but +it really is one and it should be tested. Please note that when the +comment is in the same line as the <code>gettext</code> keyword, it must be +before the string to be translated. + + <p>This situation happens quite often. The <code>printf</code> function is often +called with strings which do not contain a format specifier. Of course +one would normally use <code>fputs</code> but it does happen. In this case +<code>xgettext</code> does not recognize this as a format string but what +happens if the translation introduces a valid format specifier? The +<code>printf</code> function will try to access one of the parameters but none +exists because the original code does not pass any parameters. + + <p><code>xgettext</code> of course could make a wrong decision the other way +round, i.e. a string marked as a format string actually is not a format +string. In this case the <code>msgfmt</code> might give too many warnings and +would prevent translating the <samp><span class="file">.po</span></samp> file. The method to prevent +this wrong decision is similar to the one used above, only the comment +to use must contain the string <code>xgettext:no-c-format</code>. + + <p>If a string is marked with <code>c-format</code> and this is not correct the +user can find out who is responsible for the decision. See +<a href="#xgettext-Invocation">xgettext Invocation</a> to see how the <code>--debug</code> option can be +used for solving this problem. + +<div class="node"> +<a name="Special-cases"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Bug-Report-Address">Bug Report Address</a>, +Previous: <a rel="previous" accesskey="p" href="#c_002dformat-Flag">c-format Flag</a>, +Up: <a rel="up" accesskey="u" href="#Sources">Sources</a> + +</div> + +<h3 class="section">4.7 Special Cases of Translatable Strings</h3> + + <p><a name="index-marking-string-initializers-157"></a>The attentive reader might now point out that it is not always possible +to mark translatable string with <code>gettext</code> or something like this. +Consider the following case: + +<pre class="example"> { + static const char *messages[] = { + "some very meaningful message", + "and another one" + }; + const char *string; + ... + string + = index > 1 ? "a default message" : messages[index]; + + fputs (string); + ... + } +</pre> + <p>While it is no problem to mark the string <code>"a default message"</code> it +is not possible to mark the string initializers for <code>messages</code>. +What is to be done? We have to fulfill two tasks. First we have to mark the +strings so that the <code>xgettext</code> program (see <a href="#xgettext-Invocation">xgettext Invocation</a>) +can find them, and second we have to translate the string at runtime +before printing them. + + <p>The first task can be fulfilled by creating a new keyword, which names a +no-op. For the second we have to mark all access points to a string +from the array. So one solution can look like this: + +<pre class="example"> #define gettext_noop(String) String + + { + static const char *messages[] = { + gettext_noop ("some very meaningful message"), + gettext_noop ("and another one") + }; + const char *string; + ... + string + = index > 1 ? gettext ("a default message") : gettext (messages[index]); + + fputs (string); + ... + } +</pre> + <p>Please convince yourself that the string which is written by +<code>fputs</code> is translated in any case. How to get <code>xgettext</code> know +the additional keyword <code>gettext_noop</code> is explained in <a href="#xgettext-Invocation">xgettext Invocation</a>. + + <p>The above is of course not the only solution. You could also come along +with the following one: + +<pre class="example"> #define gettext_noop(String) String + + { + static const char *messages[] = { + gettext_noop ("some very meaningful message", + gettext_noop ("and another one") + }; + const char *string; + ... + string + = index > 1 ? gettext_noop ("a default message") : messages[index]; + + fputs (gettext (string)); + ... + } +</pre> + <p>But this has a drawback. The programmer has to take care that +he uses <code>gettext_noop</code> for the string <code>"a default message"</code>. +A use of <code>gettext</code> could have in rare cases unpredictable results. + + <p>One advantage is that you need not make control flow analysis to make +sure the output is really translated in any case. But this analysis is +generally not very difficult. If it should be in any situation you can +use this second method in this situation. + +<div class="node"> +<a name="Bug-Report-Address"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Names">Names</a>, +Previous: <a rel="previous" accesskey="p" href="#Special-cases">Special cases</a>, +Up: <a rel="up" accesskey="u" href="#Sources">Sources</a> + +</div> + +<h3 class="section">4.8 Letting Users Report Translation Bugs</h3> + + <p>Code sometimes has bugs, but translations sometimes have bugs too. The +users need to be able to report them. Reporting translation bugs to the +programmer or maintainer of a package is not very useful, since the +maintainer must never change a translation, except on behalf of the +translator. Hence the translation bugs must be reported to the +translators. + + <p>Here is a way to organize this so that the maintainer does not need to +forward translation bug reports, nor even keep a list of the addresses of +the translators or their translation teams. + + <p>Every program has a place where is shows the bug report address. For +GNU programs, it is the code which handles the “–help” option, +typically in a function called “usage”. In this place, instruct the +translator to add her own bug reporting address. For example, if that +code has a statement + +<pre class="example"> printf (_("Report bugs to <%s>.\n"), PACKAGE_BUGREPORT); +</pre> + <p>you can add some translator instructions like this: + +<pre class="example"> /* TRANSLATORS: The placeholder indicates the bug-reporting address + for this package. Please add _another line_ saying + "Report translation bugs to <...>\n" with the address for translation + bugs (typically your translation team's web or email address). */ + printf (_("Report bugs to <%s>.\n"), PACKAGE_BUGREPORT); +</pre> + <p>These will be extracted by ‘<samp><span class="samp">xgettext</span></samp>’, leading to a .pot file that +contains this: + +<pre class="example"> #. TRANSLATORS: The placeholder indicates the bug-reporting address + #. for this package. Please add _another line_ saying + #. "Report translation bugs to <...>\n" with the address for translation + #. bugs (typically your translation team's web or email address). + #: src/hello.c:178 + #, c-format + msgid "Report bugs to <%s>.\n" + msgstr "" +</pre> + <div class="node"> +<a name="Names"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Libraries">Libraries</a>, +Previous: <a rel="previous" accesskey="p" href="#Bug-Report-Address">Bug Report Address</a>, +Up: <a rel="up" accesskey="u" href="#Sources">Sources</a> + +</div> + +<h3 class="section">4.9 Marking Proper Names for Translation</h3> + + <p>Should names of persons, cities, locations etc. be marked for translation +or not? People who only know languages that can be written with Latin +letters (English, Spanish, French, German, etc.) are tempted to say “no”, +because names usually do not change when transported between these languages. +However, in general when translating from one script to another, names +are translated too, usually phonetically or by transliteration. For +example, Russian or Greek names are converted to the Latin alphabet when +being translated to English, and English or French names are converted +to the Katakana script when being translated to Japanese. This is +necessary because the speakers of the target language in general cannot +read the script the name is originally written in. + + <p>As a programmer, you should therefore make sure that names are marked +for translation, with a special comment telling the translators that it +is a proper name and how to pronounce it. In its simple form, it looks +like this: + +<pre class="example"> printf (_("Written by %s.\n"), + /* TRANSLATORS: This is a proper name. See the gettext + manual, section Names. Note this is actually a non-ASCII + name: The first name is (with Unicode escapes) + "Fran\u00e7ois" or (with HTML entities) "Fran&ccedil;ois". + Pronunciation is like "fraa-swa pee-nar". */ + _("Francois Pinard")); +</pre> + <p class="noindent">The GNU gnulib library offers a module ‘<samp><span class="samp">propername</span></samp>’ +(<a href="http://www.gnu.org/software/gnulib/MODULES.html#module=propername">http://www.gnu.org/software/gnulib/MODULES.html#module=propername</a>) +which takes care to automatically append the original name, in parentheses, +to the translated name. For names that cannot be written in ASCII, it +also frees the translator from the task of entering the appropriate non-ASCII +characters if no script change is needed. In this more comfortable form, +it looks like this: + +<pre class="example"> printf (_("Written by %s and %s.\n"), + proper_name ("Ulrich Drepper"), + /* TRANSLATORS: This is a proper name. See the gettext + manual, section Names. Note this is actually a non-ASCII + name: The first name is (with Unicode escapes) + "Fran\u00e7ois" or (with HTML entities) "Fran&ccedil;ois". + Pronunciation is like "fraa-swa pee-nar". */ + proper_name_utf8 ("Francois Pinard", "Fran\303\247ois Pinard")); +</pre> + <p class="noindent">You can also write the original name directly in Unicode (rather than with +Unicode escapes or HTML entities) and denote the pronunciation using the +International Phonetic Alphabet (see +<a href="http://www.wikipedia.org/wiki/International_Phonetic_Alphabet">http://www.wikipedia.org/wiki/International_Phonetic_Alphabet</a>). + + <p>As a translator, you should use some care when translating names, because +it is frustrating if people see their names mutilated or distorted. + + <p>If your language uses the Latin script, all you need to do is to reproduce +the name as perfectly as you can within the usual character set of your +language. In this particular case, this means to provide a translation +containing the c-cedilla character. If your language uses a different +script and the people speaking it don't usually read Latin words, it means +transliteration. If the programmer used the simple case, you should still +give, in parentheses, the original writing of the name – for the sake of +the people that do read the Latin script. If the programmer used the +‘<samp><span class="samp">propername</span></samp>’ module mentioned above, you don't need to give the original +writing of the name in parentheses, because the program will already do so. +Here is an example, using Greek as the target script: + +<pre class="example"> #. This is a proper name. See the gettext + #. manual, section Names. Note this is actually a non-ASCII + #. name: The first name is (with Unicode escapes) + #. "Fran\u00e7ois" or (with HTML entities) "Fran&ccedil;ois". + #. Pronunciation is like "fraa-swa pee-nar". + msgid "Francois Pinard" + msgstr "\phi\rho\alpha\sigma\omicron\alpha \pi\iota\nu\alpha\rho" + " (Francois Pinard)" +</pre> + <p>Because translation of names is such a sensitive domain, it is a good +idea to test your translation before submitting it. + +<div class="node"> +<a name="Libraries"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Names">Names</a>, +Up: <a rel="up" accesskey="u" href="#Sources">Sources</a> + +</div> + +<h3 class="section">4.10 Preparing Library Sources</h3> + + <p>When you are preparing a library, not a program, for the use of +<code>gettext</code>, only a few details are different. Here we assume that +the library has a translation domain and a POT file of its own. (If +it uses the translation domain and POT file of the main program, then +the previous sections apply without changes.) + + <ol type=1 start=1> +<li>The library code doesn't call <code>setlocale (LC_ALL, "")</code>. It's the +responsibility of the main program to set the locale. The library's +documentation should mention this fact, so that developers of programs +using the library are aware of it. + + <li>The library code doesn't call <code>textdomain (PACKAGE)</code>, because it +would interfere with the text domain set by the main program. + + <li>The initialization code for a program was + + <pre class="smallexample"> setlocale (LC_ALL, ""); + bindtextdomain (PACKAGE, LOCALEDIR); + textdomain (PACKAGE); +</pre> + <p class="noindent">For a library it is reduced to + + <pre class="smallexample"> bindtextdomain (PACKAGE, LOCALEDIR); +</pre> + <p class="noindent">If your library's API doesn't already have an initialization function, +you need to create one, containing at least the <code>bindtextdomain</code> +invocation. However, you usually don't need to export and document this +initialization function: It is sufficient that all entry points of the +library call the initialization function if it hasn't been called before. +The typical idiom used to achieve this is a static boolean variable that +indicates whether the initialization function has been called. Like this: + + <pre class="example"> static bool libfoo_initialized; + + static void + libfoo_initialize (void) + { + bindtextdomain (PACKAGE, LOCALEDIR); + libfoo_initialized = true; + } + + /* This function is part of the exported API. */ + struct foo * + create_foo (...) + { + /* Must ensure the initialization is performed. */ + if (!libfoo_initialized) + libfoo_initialize (); + ... + } + + /* This function is part of the exported API. The argument must be + non-NULL and have been created through create_foo(). */ + int + foo_refcount (struct foo *argument) + { + /* No need to invoke the initialization function here, because + create_foo() must already have been called before. */ + ... + } +</pre> + <li>The usual declaration of the ‘<samp><span class="samp">_</span></samp>’ macro in each source file was + + <pre class="smallexample"> #include <libintl.h> + #define _(String) gettext (String) +</pre> + <p class="noindent">for a program. For a library, which has its own translation domain, +it reads like this: + + <pre class="smallexample"> #include <libintl.h> + #define _(String) dgettext (PACKAGE, String) +</pre> + <p>In other words, <code>dgettext</code> is used instead of <code>gettext</code>. +Similarly, the <code>dngettext</code> function should be used in place of the +<code>ngettext</code> function. + </ol> + +<div class="node"> +<a name="Template"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Creating">Creating</a>, +Previous: <a rel="previous" accesskey="p" href="#Sources">Sources</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">5 Making the PO Template File</h2> + + <p><a name="index-PO-template-file-158"></a> +After preparing the sources, the programmer creates a PO template file. +This section explains how to use <code>xgettext</code> for this purpose. + + <p><code>xgettext</code> creates a file named <samp><var>domainname</var><span class="file">.po</span></samp>. You +should then rename it to <samp><var>domainname</var><span class="file">.pot</span></samp>. (Why doesn't +<code>xgettext</code> create it under the name <samp><var>domainname</var><span class="file">.pot</span></samp> +right away? The answer is: for historical reasons. When <code>xgettext</code> +was specified, the distinction between a PO file and PO file template +was fuzzy, and the suffix ‘<samp><span class="samp">.pot</span></samp>’ wasn't in use at that time.) + +<!-- FIXME: Rewrite. --> +<ul class="menu"> +<li><a accesskey="1" href="#xgettext-Invocation">xgettext Invocation</a>: Invoking the <code>xgettext</code> Program +</ul> + +<div class="node"> +<a name="xgettext-Invocation"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Template">Template</a>, +Up: <a rel="up" accesskey="u" href="#Template">Template</a> + +</div> + +<h3 class="section">5.1 Invoking the <code>xgettext</code> Program</h3> + + <p><a name="index-xgettext-159"></a><a name="index-g_t_0040code_007bxgettext_007d-program_002c-usage-160"></a> +<pre class="example"> xgettext [<var>option</var>] [<var>inputfile</var>] ... +</pre> + <p>The <code>xgettext</code> program extracts translatable strings from given +input files. + +<h4 class="subsection">5.1.1 Input file location</h4> + + <dl> +<dt>‘<samp><var>inputfile</var><span class="samp"> ...</span></samp>’<dd>Input files. + + <br><dt>‘<samp><span class="samp">-f </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--files-from=</span><var>file</var></samp>’<dd><a name="index-g_t_002df_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-161"></a><a name="index-g_t_002d_002dfiles_002dfrom_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-162"></a>Read the names of the input files from <var>file</var> instead of getting +them from the command line. + + <br><dt>‘<samp><span class="samp">-D </span><var>directory</var></samp>’<dt>‘<samp><span class="samp">--directory=</span><var>directory</var></samp>’<dd><a name="index-g_t_002dD_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-163"></a><a name="index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-164"></a>Add <var>directory</var> to the list of directories. Source files are +searched relative to this list of directories. The resulting <samp><span class="file">.po</span></samp> +file will be written relative to the current directory, though. + + </dl> + + <p>If <var>inputfile</var> is ‘<samp><span class="samp">-</span></samp>’, standard input is read. + +<h4 class="subsection">5.1.2 Output file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-d </span><var>name</var></samp>’<dt>‘<samp><span class="samp">--default-domain=</span><var>name</var></samp>’<dd><a name="index-g_t_002dd_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-165"></a><a name="index-g_t_002d_002ddefault_002ddomain_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-166"></a>Use <samp><var>name</var><span class="file">.po</span></samp> for output (instead of <samp><span class="file">messages.po</span></samp>). + + <br><dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--output=</span><var>file</var></samp>’<dd><a name="index-g_t_002do_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-167"></a><a name="index-g_t_002d_002doutput_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-168"></a>Write output to specified file (instead of <samp><var>name</var><span class="file">.po</span></samp> or +<samp><span class="file">messages.po</span></samp>). + + <br><dt>‘<samp><span class="samp">-p </span><var>dir</var></samp>’<dt>‘<samp><span class="samp">--output-dir=</span><var>dir</var></samp>’<dd><a name="index-g_t_002dp_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-169"></a><a name="index-g_t_002d_002doutput_002ddir_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-170"></a>Output files will be placed in directory <var>dir</var>. + + </dl> + + <p><a name="index-output-to-stdout_002c-_0040code_007bxgettext_007d-171"></a>If the output <var>file</var> is ‘<samp><span class="samp">-</span></samp>’ or ‘<samp><span class="samp">/dev/stdout</span></samp>’, the output +is written to standard output. + +<h4 class="subsection">5.1.3 Choice of input file language</h4> + + <dl> +<dt>‘<samp><span class="samp">-L </span><var>name</var></samp>’<dt>‘<samp><span class="samp">--language=</span><var>name</var></samp>’<dd><a name="index-g_t_002dL_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-172"></a><a name="index-g_t_002d_002dlanguage_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-173"></a><a name="index-supported-languages_002c-_0040code_007bxgettext_007d-174"></a>Specifies the language of the input files. The supported languages +are <code>C</code>, <code>C++</code>, <code>ObjectiveC</code>, <code>PO</code>, <code>Python</code>, +<code>Lisp</code>, <code>EmacsLisp</code>, <code>librep</code>, <code>Scheme</code>, <code>Smalltalk</code>, +<code>Java</code>, <code>JavaProperties</code>, <code>C#</code>, <code>awk</code>, <code>YCP</code>, +<code>Tcl</code>, <code>Perl</code>, <code>PHP</code>, <code>GCC-source</code>, <code>NXStringTable</code>, +<code>RST</code>, <code>Glade</code>. + + <br><dt>‘<samp><span class="samp">-C</span></samp>’<dt>‘<samp><span class="samp">--c++</span></samp>’<dd><a name="index-g_t_002dC_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-175"></a><a name="index-g_t_002d_002dc_002b_002b_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-176"></a>This is a shorthand for <code>--language=C++</code>. + + </dl> + + <p>By default the language is guessed depending on the input file name +extension. + +<h4 class="subsection">5.1.4 Input file interpretation</h4> + + <dl> +<dt>‘<samp><span class="samp">--from-code=</span><var>name</var></samp>’<dd><a name="index-g_t_002d_002dfrom_002dcode_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-177"></a>Specifies the encoding of the input files. This option is needed only +if some untranslated message strings or their corresponding comments +contain non-ASCII characters. Note that Tcl and Glade input files are +always assumed to be in UTF-8, regardless of this option. + + </dl> + + <p>By default the input files are assumed to be in ASCII. + +<h4 class="subsection">5.1.5 Operation mode</h4> + + <dl> +<dt>‘<samp><span class="samp">-j</span></samp>’<dt>‘<samp><span class="samp">--join-existing</span></samp>’<dd><a name="index-g_t_002dj_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-178"></a><a name="index-g_t_002d_002djoin_002dexisting_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-179"></a>Join messages with existing file. + + <br><dt>‘<samp><span class="samp">-x </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--exclude-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002dx_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-180"></a><a name="index-g_t_002d_002dexclude_002dfile_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-181"></a>Entries from <var>file</var> are not extracted. <var>file</var> should be a PO or +POT file. + + <br><dt>‘<samp><span class="samp">-c[</span><var>tag</var><span class="samp">]</span></samp>’<dt>‘<samp><span class="samp">--add-comments[=</span><var>tag</var><span class="samp">]</span></samp>’<dd><a name="index-g_t_002dc_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-182"></a><a name="index-g_t_002d_002dadd_002dcomments_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-183"></a>Place comment blocks starting with <var>tag</var> and preceding keyword lines +in the output file. Without a <var>tag</var>, the option means to put <em>all</em> +comment blocks preceding keyword lines in the output file. + + </dl> + +<h4 class="subsection">5.1.6 Language specific options</h4> + + <dl> +<dt>‘<samp><span class="samp">-a</span></samp>’<dt>‘<samp><span class="samp">--extract-all</span></samp>’<dd><a name="index-g_t_002da_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-184"></a><a name="index-g_t_002d_002dextract_002dall_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-185"></a>Extract all strings. + + <p>This option has an effect with most languages, namely C, C++, ObjectiveC, +Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP, +GCC-source, Glade. + + <br><dt>‘<samp><span class="samp">-k[</span><var>keywordspec</var><span class="samp">]</span></samp>’<dt>‘<samp><span class="samp">--keyword[=</span><var>keywordspec</var><span class="samp">]</span></samp>’<dd><a name="index-g_t_002dk_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-186"></a><a name="index-g_t_002d_002dkeyword_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-187"></a>Specify <var>keywordspec</var> as an additional keyword to be looked for. +Without a <var>keywordspec</var>, the option means to not use default keywords. + + <p><a name="index-adding-keywords_002c-_0040code_007bxgettext_007d-188"></a><a name="index-context_002c-argument-specification-in-_0040code_007bxgettext_007d-189"></a>If <var>keywordspec</var> is a C identifier <var>id</var>, <code>xgettext</code> looks +for strings in the first argument of each call to the function or macro +<var>id</var>. If <var>keywordspec</var> is of the form +‘<samp><var>id</var><span class="samp">:</span><var>argnum</var></samp>’, <code>xgettext</code> looks for strings in the +<var>argnum</var>th argument of the call. If <var>keywordspec</var> is of the form +‘<samp><var>id</var><span class="samp">:</span><var>argnum1</var><span class="samp">,</span><var>argnum2</var></samp>’, <code>xgettext</code> looks for +strings in the <var>argnum1</var>st argument and in the <var>argnum2</var>nd argument +of the call, and treats them as singular/plural variants for a message +with plural handling. Also, if <var>keywordspec</var> is of the form +‘<samp><var>id</var><span class="samp">:</span><var>contextargnum</var><span class="samp">c,</span><var>argnum</var></samp>’ or +‘<samp><var>id</var><span class="samp">:</span><var>argnum</var><span class="samp">,</span><var>contextargnum</var><span class="samp">c</span></samp>’, <code>xgettext</code> treats +strings in the <var>contextargnum</var>th argument as a context specifier. +And, as a special-purpose support for GNOME, if <var>keywordspec</var> is of the +form ‘<samp><var>id</var><span class="samp">:</span><var>argnum</var><span class="samp">g</span></samp>’, <code>xgettext</code> recognizes the +<var>argnum</var>th argument as a string with context, using the GNOME <code>glib</code> +syntax ‘<samp><span class="samp">"msgctxt|msgid"</span></samp>’. +<br> +Furthermore, if <var>keywordspec</var> is of the form +‘<samp><var>id</var><span class="samp">:...,</span><var>totalnumargs</var><span class="samp">t</span></samp>’, <code>xgettext</code> recognizes this +argument specification only if the number of actual arguments is equal to +<var>totalnumargs</var>. This is useful for disambiguating overloaded function +calls in C++. +<br> +Finally, if <var>keywordspec</var> is of the form +‘<samp><var>id</var><span class="samp">:</span><var>argnum</var><span class="samp">...,"</span><var>xcomment</var><span class="samp">"</span></samp>’, <code>xgettext</code>, when +extracting a message from the specified argument strings, adds an extracted +comment <var>xcomment</var> to the message. Note that when used through a normal +shell command line, the double-quotes around the <var>xcomment</var> need to be +escaped. + + <p>This option has an effect with most languages, namely C, C++, ObjectiveC, +Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP, +GCC-source, Glade. + + <p>The default keyword specifications, which are always looked for if not +explicitly disabled, are language dependent. They are: + + <ul> +<li>For C, C++, and GCC-source: <code>gettext</code>, <code>dgettext:2</code>, +<code>dcgettext:2</code>, <code>ngettext:1,2</code>, <code>dngettext:2,3</code>, +<code>dcngettext:2,3</code>, <code>gettext_noop</code>, and <code>pgettext:1c,2</code>, +<code>dpgettext:2c,3</code>, <code>dcpgettext:2c,3</code>, <code>npgettext:1c,2,3</code>, +<code>dnpgettext:2c,3,4</code>, <code>dcnpgettext:2c,3,4</code>. + + <li>For Objective C: Like for C, and also <code>NSLocalizedString</code>, <code>_</code>, +<code>NSLocalizedStaticString</code>, <code>__</code>. + + <li>For Shell scripts: <code>gettext</code>, <code>ngettext:1,2</code>, <code>eval_gettext</code>, +<code>eval_ngettext:1,2</code>. + + <li>For Python: <code>gettext</code>, <code>ugettext</code>, <code>dgettext:2</code>, +<code>ngettext:1,2</code>, <code>ungettext:1,2</code>, <code>dngettext:2,3</code>, <code>_</code>. + + <li>For Lisp: <code>gettext</code>, <code>ngettext:1,2</code>, <code>gettext-noop</code>. + + <li>For EmacsLisp: <code>_</code>. + + <li>For librep: <code>_</code>. + + <li>For Scheme: <code>gettext</code>, <code>ngettext:1,2</code>, <code>gettext-noop</code>. + + <li>For Java: <code>GettextResource.gettext:2</code>, +<code>GettextResource.ngettext:2,3</code>, <code>GettextResource.pgettext:2c,3</code>, +<code>GettextResource.npgettext:2c,3,4</code>, <code>gettext</code>, <code>ngettext:1,2</code>, +<code>pgettext:1c,2</code>, <code>npgettext:1c,2,3</code>, <code>getString</code>. + + <li>For C#: <code>GetString</code>, <code>GetPluralString:1,2</code>, +<code>GetParticularString:1c,2</code>, <code>GetParticularPluralString:1c,2,3</code>. + + <li>For awk: <code>dcgettext</code>, <code>dcngettext:1,2</code>. + + <li>For Tcl: <code>::msgcat::mc</code>. + + <li>For Perl: <code>gettext</code>, <code>%gettext</code>, <code>$gettext</code>, <code>dgettext:2</code>, +<code>dcgettext:2</code>, <code>ngettext:1,2</code>, <code>dngettext:2,3</code>, +<code>dcngettext:2,3</code>, <code>gettext_noop</code>. + + <li>For PHP: <code>_</code>, <code>gettext</code>, <code>dgettext:2</code>, <code>dcgettext:2</code>, +<code>ngettext:1,2</code>, <code>dngettext:2,3</code>, <code>dcngettext:2,3</code>. + + <li>For Glade 1: <code>label</code>, <code>title</code>, <code>text</code>, <code>format</code>, +<code>copyright</code>, <code>comments</code>, <code>preview_text</code>, <code>tooltip</code>. +</ul> + + <p>To disable the default keyword specifications, the option ‘<samp><span class="samp">-k</span></samp>’ or +‘<samp><span class="samp">--keyword</span></samp>’ or ‘<samp><span class="samp">--keyword=</span></samp>’, without a <var>keywordspec</var>, can be +used. + + <br><dt>‘<samp><span class="samp">--flag=</span><var>word</var><span class="samp">:</span><var>arg</var><span class="samp">:</span><var>flag</var></samp>’<dd><a name="index-g_t_002d_002dflag_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-190"></a>Specifies additional flags for strings occurring as part of the <var>arg</var>th +argument of the function <var>word</var>. The possible flags are the possible +format string indicators, such as ‘<samp><span class="samp">c-format</span></samp>’, and their negations, +such as ‘<samp><span class="samp">no-c-format</span></samp>’, possibly prefixed with ‘<samp><span class="samp">pass-</span></samp>’. +<br> +<a name="index-function-attribute_002c-_005f_005fformat_005f_005f-191"></a>The meaning of <code>--flag=</code><var>function</var><code>:</code><var>arg</var><code>:</code><var>lang</var><code>-format</code> +is that in language <var>lang</var>, the specified <var>function</var> expects as +<var>arg</var>th argument a format string. (For those of you familiar with +GCC function attributes, <code>--flag=</code><var>function</var><code>:</code><var>arg</var><code>:c-format</code> is +roughly equivalent to the declaration +‘<samp><span class="samp">__attribute__ ((__format__ (__printf__, </span><var>arg</var><span class="samp">, ...)))</span></samp>’ attached +to <var>function</var> in a C source file.) +For example, if you use the ‘<samp><span class="samp">error</span></samp>’ function from GNU libc, you can +specify its behaviour through <code>--flag=error:3:c-format</code>. The effect of +this specification is that <code>xgettext</code> will mark as format strings all +<code>gettext</code> invocations that occur as <var>arg</var>th argument of +<var>function</var>. +This is useful when such strings contain no format string directives: +together with the checks done by ‘<samp><span class="samp">msgfmt -c</span></samp>’ it will ensure that +translators cannot accidentally use format string directives that would +lead to a crash at runtime. +<br> +<a name="index-function-attribute_002c-_005f_005fformat_005farg_005f_005f-192"></a>The meaning of <code>--flag=</code><var>function</var><code>:</code><var>arg</var><code>:pass-</code><var>lang</var><code>-format</code> +is that in language <var>lang</var>, if the <var>function</var> call occurs in a +position that must yield a format string, then its <var>arg</var>th argument +must yield a format string of the same type as well. (If you know GCC +function attributes, the <code>--flag=</code><var>function</var><code>:</code><var>arg</var><code>:pass-c-format</code> +option is roughly equivalent to the declaration +‘<samp><span class="samp">__attribute__ ((__format_arg__ (</span><var>arg</var><span class="samp">)))</span></samp>’ attached to <var>function</var> +in a C source file.) +For example, if you use the ‘<samp><span class="samp">_</span></samp>’ shortcut for the <code>gettext</code> function, +you should use <code>--flag=_:1:pass-c-format</code>. The effect of this +specification is that <code>xgettext</code> will propagate a format string +requirement for a <code>_("string")</code> call to its first argument, the literal +<code>"string"</code>, and thus mark it as a format string. +This is useful when such strings contain no format string directives: +together with the checks done by ‘<samp><span class="samp">msgfmt -c</span></samp>’ it will ensure that +translators cannot accidentally use format string directives that would +lead to a crash at runtime. +<br> +This option has an effect with most languages, namely C, C++, ObjectiveC, +Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java, C#, awk, YCP, Tcl, Perl, PHP, +GCC-source. + + <br><dt>‘<samp><span class="samp">-T</span></samp>’<dt>‘<samp><span class="samp">--trigraphs</span></samp>’<dd><a name="index-g_t_002dT_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-193"></a><a name="index-g_t_002d_002dtrigraphs_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-194"></a><a name="index-C-trigraphs-195"></a>Understand ANSI C trigraphs for input. +<br> +This option has an effect only with the languages C, C++, ObjectiveC. + + <br><dt>‘<samp><span class="samp">--qt</span></samp>’<dd><a name="index-g_t_002d_002dqt_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-196"></a><a name="index-Qt-format-strings-197"></a>Recognize Qt format strings. +<br> +This option has an effect only with the language C++. + + <br><dt>‘<samp><span class="samp">--kde</span></samp>’<dd><a name="index-g_t_002d_002dkde_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-198"></a><a name="index-KDE-format-strings-199"></a>Recognize KDE 4 format strings. +<br> +This option has an effect only with the language C++. + + <br><dt>‘<samp><span class="samp">--boost</span></samp>’<dd><a name="index-g_t_002d_002dboost_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-200"></a><a name="index-Boost-format-strings-201"></a>Recognize Boost format strings. +<br> +This option has an effect only with the language C++. + + <br><dt>‘<samp><span class="samp">--debug</span></samp>’<dd><a name="index-g_t_002d_002ddebug_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-202"></a><a name="index-debugging-messages-marked-as-format-strings-203"></a>Use the flags <code>c-format</code> and <code>possible-c-format</code> to show who was +responsible for marking a message as a format string. The latter form is +used if the <code>xgettext</code> program decided, the format form is used if +the programmer prescribed it. + + <p>By default only the <code>c-format</code> form is used. The translator should +not have to care about these details. + + </dl> + + <p>This implementation of <code>xgettext</code> is able to process a few awkward +cases, like strings in preprocessor macros, ANSI concatenation of +adjacent strings, and escaped end of lines for continued strings. + +<h4 class="subsection">5.1.7 Output details</h4> + +<!-- no-escape and -escape omitted on purpose. They are not useful. --> + <dl> +<dt>‘<samp><span class="samp">--color</span></samp>’<dt>‘<samp><span class="samp">--color=</span><var>when</var></samp>’<dd><a name="index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-204"></a>Specify whether or when to use colors and other text attributes. +See <a href="#The-_002d_002dcolor-option">The –color option</a> for details. + + <br><dt>‘<samp><span class="samp">--style=</span><var>style_file</var></samp>’<dd><a name="index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-205"></a>Specify the CSS style rule file to use for <code>--color</code>. +See <a href="#The-_002d_002dstyle-option">The –style option</a> for details. + + <br><dt>‘<samp><span class="samp">--force-po</span></samp>’<dd><a name="index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-206"></a>Always write an output file even if no message is defined. + + <br><dt>‘<samp><span class="samp">-i</span></samp>’<dt>‘<samp><span class="samp">--indent</span></samp>’<dd><a name="index-g_t_002di_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-207"></a><a name="index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-208"></a>Write the .po file using indented style. + + <br><dt>‘<samp><span class="samp">--no-location</span></samp>’<dd><a name="index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-209"></a>Do not write ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines. Note that using +this option makes it harder for technically skilled translators to understand +each message's context. + + <br><dt>‘<samp><span class="samp">-n</span></samp>’<dt>‘<samp><span class="samp">--add-location</span></samp>’<dd><a name="index-g_t_002dn_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-210"></a><a name="index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-211"></a>Generate ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines (default). + + <br><dt>‘<samp><span class="samp">--strict</span></samp>’<dd><a name="index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-212"></a>Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + + <br><dt>‘<samp><span class="samp">--properties-output</span></samp>’<dd><a name="index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-213"></a>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note +that this file format doesn't support plural forms and silently drops +obsolete messages. + + <br><dt>‘<samp><span class="samp">--stringtable-output</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-214"></a>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. +Note that this file format doesn't support plural forms. + + <br><dt>‘<samp><span class="samp">-w </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--width=</span><var>number</var></samp>’<dd><a name="index-g_t_002dw_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-215"></a><a name="index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-216"></a>Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given <var>number</var>. + + <br><dt>‘<samp><span class="samp">--no-wrap</span></samp>’<dd><a name="index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-217"></a>Do not break long message lines. Message lines whose width exceeds the +output page width will not be split into several lines. Only file reference +lines which are wider than the output page width will be split. + + <br><dt>‘<samp><span class="samp">-s</span></samp>’<dt>‘<samp><span class="samp">--sort-output</span></samp>’<dd><a name="index-g_t_002ds_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-218"></a><a name="index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-219"></a><a name="index-sorting-output-of-_0040code_007bxgettext_007d-220"></a>Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + + <br><dt>‘<samp><span class="samp">-F</span></samp>’<dt>‘<samp><span class="samp">--sort-by-file</span></samp>’<dd><a name="index-g_t_002dF_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-221"></a><a name="index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-222"></a>Sort output by file location. + + <br><dt>‘<samp><span class="samp">--omit-header</span></samp>’<dd><a name="index-g_t_002d_002domit_002dheader_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-223"></a>Don't write header with ‘<samp><span class="samp">msgid ""</span></samp>’ entry. + + <p><a name="index-testing-_0040file_007b_002epo_007d-files-for-equivalence-224"></a>This is useful for testing purposes because it eliminates a source +of variance for generated <code>.gmo</code> files. With <code>--omit-header</code>, +two invocations of <code>xgettext</code> on the same files with the same +options at different times are guaranteed to produce the same results. + + <p>Note that using this option will lead to an error if the resulting file +would not entirely be in ASCII. + + <br><dt>‘<samp><span class="samp">--copyright-holder=</span><var>string</var></samp>’<dd><a name="index-g_t_002d_002dcopyright_002dholder_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-225"></a>Set the copyright holder in the output. <var>string</var> should be the +copyright holder of the surrounding package. (Note that the msgstr +strings, extracted from the package's sources, belong to the copyright +holder of the package.) Translators are expected to transfer or disclaim +the copyright for their translations, so that package maintainers can +distribute them without legal risk. If <var>string</var> is empty, the output +files are marked as being in the public domain; in this case, the translators +are expected to disclaim their copyright, again so that package maintainers +can distribute them without legal risk. + + <p>The default value for <var>string</var> is the Free Software Foundation, Inc., +simply because <code>xgettext</code> was first used in the GNU project. + + <br><dt>‘<samp><span class="samp">--foreign-user</span></samp>’<dd><a name="index-g_t_002d_002dforeign_002duser_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-226"></a>Omit FSF copyright in output. This option is equivalent to +‘<samp><span class="samp">--copyright-holder=''</span></samp>’. It can be useful for packages outside the GNU +project that want their translations to be in the public domain. + + <br><dt>‘<samp><span class="samp">--package-name=</span><var>package</var></samp>’<dd><a name="index-g_t_002d_002dpackage_002dname_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-227"></a>Set the package name in the header of the output. + + <br><dt>‘<samp><span class="samp">--package-version=</span><var>version</var></samp>’<dd><a name="index-g_t_002d_002dpackage_002dversion_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-228"></a>Set the package version in the header of the output. This option has an +effect only if the ‘<samp><span class="samp">--package-name</span></samp>’ option is also used. + + <br><dt>‘<samp><span class="samp">--msgid-bugs-address=</span><var>email@address</var></samp>’<dd><a name="index-g_t_002d_002dmsgid_002dbugs_002daddress_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-229"></a>Set the reporting address for msgid bugs. This is the email address or URL +to which the translators shall report bugs in the untranslated strings: + + <ul> +<li>Strings which are not entire sentences, see the maintainer guidelines +in <a href="#Preparing-Strings">Preparing Strings</a>. +<li>Strings which use unclear terms or require additional context to be +understood. +<li>Strings which make invalid assumptions about notation of date, time or +money. +<li>Pluralisation problems. +<li>Incorrect English spelling. +<li>Incorrect formatting. +</ul> + + <p>It can be your email address, or a mailing list address where translators +can write to without being subscribed, or the URL of a web page through +which the translators can contact you. + + <p>The default value is empty, which means that translators will be clueless! +Don't forget to specify this option. + + <br><dt>‘<samp><span class="samp">-m[</span><var>string</var><span class="samp">]</span></samp>’<dt>‘<samp><span class="samp">--msgstr-prefix[=</span><var>string</var><span class="samp">]</span></samp>’<dd><a name="index-g_t_002dm_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-230"></a><a name="index-g_t_002d_002dmsgstr_002dprefix_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-231"></a>Use <var>string</var> (or "" if not specified) as prefix for msgstr values. + + <br><dt>‘<samp><span class="samp">-M[</span><var>string</var><span class="samp">]</span></samp>’<dt>‘<samp><span class="samp">--msgstr-suffix[=</span><var>string</var><span class="samp">]</span></samp>’<dd><a name="index-g_t_002dM_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-232"></a><a name="index-g_t_002d_002dmsgstr_002dsuffix_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-233"></a>Use <var>string</var> (or "" if not specified) as suffix for msgstr values. + + </dl> + +<h4 class="subsection">5.1.8 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-234"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-235"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-236"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-237"></a>Output version information and exit. + + </dl> + +<div class="node"> +<a name="Creating"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Updating">Updating</a>, +Previous: <a rel="previous" accesskey="p" href="#Template">Template</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">6 Creating a New PO File</h2> + + <p><a name="index-creating-a-new-PO-file-238"></a> +When starting a new translation, the translator creates a file called +<samp><var>LANG</var><span class="file">.po</span></samp>, as a copy of the <samp><var>package</var><span class="file">.pot</span></samp> template +file with modifications in the initial comments (at the beginning of the file) +and in the header entry (the first entry, near the beginning of the file). + + <p>The easiest way to do so is by use of the ‘<samp><span class="samp">msginit</span></samp>’ program. +For example: + +<pre class="example"> $ cd <var>PACKAGE</var>-<var>VERSION</var> + $ cd po + $ msginit +</pre> + <p>The alternative way is to do the copy and modifications by hand. +To do so, the translator copies <samp><var>package</var><span class="file">.pot</span></samp> to +<samp><var>LANG</var><span class="file">.po</span></samp>. Then she modifies the initial comments and +the header entry of this file. + +<ul class="menu"> +<li><a accesskey="1" href="#msginit-Invocation">msginit Invocation</a>: Invoking the <code>msginit</code> Program +<li><a accesskey="2" href="#Header-Entry">Header Entry</a>: Filling in the Header Entry +</ul> + +<div class="node"> +<a name="msginit-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Header-Entry">Header Entry</a>, +Previous: <a rel="previous" accesskey="p" href="#Creating">Creating</a>, +Up: <a rel="up" accesskey="u" href="#Creating">Creating</a> + +</div> + +<h3 class="section">6.1 Invoking the <code>msginit</code> Program</h3> + + <p><a name="index-msginit-239"></a><a name="index-g_t_0040code_007bmsginit_007d-program_002c-usage-240"></a> +<pre class="example"> msginit [<var>option</var>] +</pre> + <p><a name="index-create-new-PO-file-241"></a><a name="index-initialize-new-PO-file-242"></a>The <code>msginit</code> program creates a new PO file, initializing the meta +information with values from the user's environment. + +<h4 class="subsection">6.1.1 Input file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-i </span><var>inputfile</var></samp>’<dt>‘<samp><span class="samp">--input=</span><var>inputfile</var></samp>’<dd><a name="index-g_t_002di_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-243"></a><a name="index-g_t_002d_002dinput_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-244"></a>Input POT file. + + </dl> + + <p>If no <var>inputfile</var> is given, the current directory is searched for the +POT file. If it is ‘<samp><span class="samp">-</span></samp>’, standard input is read. + +<h4 class="subsection">6.1.2 Output file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--output-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002do_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-245"></a><a name="index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-246"></a>Write output to specified PO file. + + </dl> + + <p>If no output file is given, it depends on the ‘<samp><span class="samp">--locale</span></samp>’ option or the +user's locale setting. If it is ‘<samp><span class="samp">-</span></samp>’, the results are written to +standard output. + +<h4 class="subsection">6.1.3 Input file syntax</h4> + + <dl> +<dt>‘<samp><span class="samp">-P</span></samp>’<dt>‘<samp><span class="samp">--properties-input</span></samp>’<dd><a name="index-g_t_002dP_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-247"></a><a name="index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-248"></a>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> +syntax, not in PO file syntax. + + <br><dt>‘<samp><span class="samp">--stringtable-input</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-249"></a>Assume the input file is a NeXTstep/GNUstep localized resource file in +<code>.strings</code> syntax, not in PO file syntax. + + </dl> + +<h4 class="subsection">6.1.4 Output details</h4> + + <dl> +<dt>‘<samp><span class="samp">-l </span><var>ll_CC</var></samp>’<dt>‘<samp><span class="samp">--locale=</span><var>ll_CC</var></samp>’<dd><a name="index-g_t_002dl_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-250"></a><a name="index-g_t_002d_002dlocale_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-251"></a>Set target locale. <var>ll</var> should be a language code, and <var>CC</var> should +be a country code. The command ‘<samp><span class="samp">locale -a</span></samp>’ can be used to output a list +of all installed locales. The default is the user's locale setting. + + <br><dt>‘<samp><span class="samp">--no-translator</span></samp>’<dd><a name="index-g_t_002d_002dno_002dtranslator_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-252"></a>Declares that the PO file will not have a human translator and is instead +automatically generated. + + <br><dt>‘<samp><span class="samp">--color</span></samp>’<dt>‘<samp><span class="samp">--color=</span><var>when</var></samp>’<dd><a name="index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-253"></a>Specify whether or when to use colors and other text attributes. +See <a href="#The-_002d_002dcolor-option">The –color option</a> for details. + + <br><dt>‘<samp><span class="samp">--style=</span><var>style_file</var></samp>’<dd><a name="index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-254"></a>Specify the CSS style rule file to use for <code>--color</code>. +See <a href="#The-_002d_002dstyle-option">The –style option</a> for details. + + <br><dt>‘<samp><span class="samp">-p</span></samp>’<dt>‘<samp><span class="samp">--properties-output</span></samp>’<dd><a name="index-g_t_002dp_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-255"></a><a name="index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-256"></a>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note +that this file format doesn't support plural forms and silently drops +obsolete messages. + + <br><dt>‘<samp><span class="samp">--stringtable-output</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-257"></a>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. +Note that this file format doesn't support plural forms. + + <br><dt>‘<samp><span class="samp">-w </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--width=</span><var>number</var></samp>’<dd><a name="index-g_t_002dw_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-258"></a><a name="index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-259"></a>Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given <var>number</var>. + + <br><dt>‘<samp><span class="samp">--no-wrap</span></samp>’<dd><a name="index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-260"></a>Do not break long message lines. Message lines whose width exceeds the +output page width will not be split into several lines. Only file reference +lines which are wider than the output page width will be split. + + </dl> + +<h4 class="subsection">6.1.5 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-261"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-262"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-263"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-264"></a>Output version information and exit. + + </dl> + +<div class="node"> +<a name="Header-Entry"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#msginit-Invocation">msginit Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Creating">Creating</a> + +</div> + +<h3 class="section">6.2 Filling in the Header Entry</h3> + + <p><a name="index-header-entry-of-a-PO-file-265"></a> +The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and +"FIRST AUTHOR <EMAIL@ADDRESS>, YEAR" ought to be replaced by sensible +information. This can be done in any text editor; if Emacs is used +and it switched to PO mode automatically (because it has recognized +the file's suffix), you can disable it by typing <kbd>M-x fundamental-mode</kbd>. + + <p>Modifying the header entry can already be done using PO mode: in Emacs, +type <kbd>M-x po-mode RET</kbd> and then <kbd>RET</kbd> again to start editing the +entry. You should fill in the following fields. + + <dl> +<dt>Project-Id-Version<dd>This is the name and version of the package. Fill it in if it has not +already been filled in by <code>xgettext</code>. + + <br><dt>Report-Msgid-Bugs-To<dd>This has already been filled in by <code>xgettext</code>. It contains an email +address or URL where you can report bugs in the untranslated strings: + + <ul> +<li>Strings which are not entire sentences, see the maintainer guidelines +in <a href="#Preparing-Strings">Preparing Strings</a>. +<li>Strings which use unclear terms or require additional context to be +understood. +<li>Strings which make invalid assumptions about notation of date, time or +money. +<li>Pluralisation problems. +<li>Incorrect English spelling. +<li>Incorrect formatting. +</ul> + + <br><dt>POT-Creation-Date<dd>This has already been filled in by <code>xgettext</code>. + + <br><dt>PO-Revision-Date<dd>You don't need to fill this in. It will be filled by the PO file editor +when you save the file. + + <br><dt>Last-Translator<dd>Fill in your name and email address (without double quotes). + + <br><dt>Language-Team<dd>Fill in the English name of the language, and the email address or +homepage URL of the language team you are part of. + + <p>Before starting a translation, it is a good idea to get in touch with +your translation team, not only to make sure you don't do duplicated work, +but also to coordinate difficult linguistic issues. + + <p><a name="index-list-of-translation-teams_002c-where-to-find-266"></a>In the Free Translation Project, each translation team has its own mailing +list. The up-to-date list of teams can be found at the Free Translation +Project's homepage, <a href="http://translationproject.org/">http://translationproject.org/</a>, in the "Teams" +area. + + <br><dt>Language<dd><!-- The purpose of this field is to make it possible to automatically --> +<!-- convert PO files to translation memory, --> +<!-- initialize a spell checker based on the PO file, --> +<!-- perform language specific checks. --> +Fill in the language code of the language. This can be in one of three +forms: + + <ul> +<li>‘<samp><var>ll</var></samp>’, an ISO 639<!-- /@w --> two-letter language code (lowercase). +See <a href="#Language-Codes">Language Codes</a> for the list of codes. + + <li>‘<samp><var>ll</var><span class="samp">_</span><var>CC</var></samp>’, where ‘<samp><var>ll</var></samp>’ is an ISO 639<!-- /@w --> two-letter +language code (lowercase) and ‘<samp><var>CC</var></samp>’ is an ISO 3166<!-- /@w --> two-letter +country code (uppercase). The country code specification is not redundant: +Some languages have dialects in different countries. For example, +‘<samp><span class="samp">de_AT</span></samp>’ is used for Austria, and ‘<samp><span class="samp">pt_BR</span></samp>’ for Brazil. The country +code serves to distinguish the dialects. See <a href="#Language-Codes">Language Codes</a> and +<a href="#Country-Codes">Country Codes</a> for the lists of codes. + + <li>‘<samp><var>ll</var><span class="samp">_</span><var>CC</var><span class="samp">@</span><var>variant</var></samp>’, where ‘<samp><var>ll</var></samp>’ is an +ISO 639<!-- /@w --> two-letter language code (lowercase), ‘<samp><var>CC</var></samp>’ is an +ISO 3166<!-- /@w --> two-letter country code (uppercase), and ‘<samp><var>variant</var></samp>’ is +a variant designator. The variant designator (lowercase) can be a script +designator, such as ‘<samp><span class="samp">latin</span></samp>’ or ‘<samp><span class="samp">cyrillic</span></samp>’. +</ul> + + <p>The naming convention ‘<samp><var>ll</var><span class="samp">_</span><var>CC</var></samp>’ is also the way locales are +named on systems based on GNU libc. But there are three important differences: + + <ul> +<li>In this PO file field, but not in locale names, ‘<samp><var>ll</var><span class="samp">_</span><var>CC</var></samp>’ +combinations denoting a language's main dialect are abbreviated as +‘<samp><var>ll</var></samp>’. For example, ‘<samp><span class="samp">de</span></samp>’ is equivalent to ‘<samp><span class="samp">de_DE</span></samp>’ +(German as spoken in Germany), and ‘<samp><span class="samp">pt</span></samp>’ to ‘<samp><span class="samp">pt_PT</span></samp>’ (Portuguese as +spoken in Portugal) in this context. + + <li>In this PO file field, suffixes like ‘<samp><span class="samp">.</span><var>encoding</var></samp>’ are not used. + + <li>In this PO file field, variant designators that are not relevant to message +translation, such as ‘<samp><span class="samp">@euro</span></samp>’, are not used. +</ul> + + <p>So, if your locale name is ‘<samp><span class="samp">de_DE.UTF-8</span></samp>’, the language specification in +PO files is just ‘<samp><span class="samp">de</span></samp>’. + + <br><dt>Content-Type<dd><a name="index-encoding-of-PO-files-267"></a><a name="index-charset-of-PO-files-268"></a>Replace ‘<samp><span class="samp">CHARSET</span></samp>’ with the character encoding used for your language, +in your locale, or UTF-8. This field is needed for correct operation of the +<code>msgmerge</code> and <code>msgfmt</code> programs, as well as for users whose +locale's character encoding differs from yours (see <a href="#Charset-conversion">Charset conversion</a>). + + <p><a name="index-g_t_0040code_007blocale_007d-program-269"></a>You get the character encoding of your locale by running the shell command +‘<samp><span class="samp">locale charmap</span></samp>’. If the result is ‘<samp><span class="samp">C</span></samp>’ or ‘<samp><span class="samp">ANSI_X3.4-1968</span></samp>’, +which is equivalent to ‘<samp><span class="samp">ASCII</span></samp>’ (= ‘<samp><span class="samp">US-ASCII</span></samp>’), it means that your +locale is not correctly configured. In this case, ask your translation +team which charset to use. ‘<samp><span class="samp">ASCII</span></samp>’ is not usable for any language +except Latin. + + <p><a name="index-encoding-list-270"></a>Because the PO files must be portable to operating systems with less advanced +internationalization facilities, the character encodings that can be used +are limited to those supported by both GNU <code>libc</code> and GNU +<code>libiconv</code>. These are: +<code>ASCII</code>, <code>ISO-8859-1</code>, <code>ISO-8859-2</code>, <code>ISO-8859-3</code>, +<code>ISO-8859-4</code>, <code>ISO-8859-5</code>, <code>ISO-8859-6</code>, <code>ISO-8859-7</code>, +<code>ISO-8859-8</code>, <code>ISO-8859-9</code>, <code>ISO-8859-13</code>, <code>ISO-8859-14</code>, +<code>ISO-8859-15</code>, +<code>KOI8-R</code>, <code>KOI8-U</code>, <code>KOI8-T</code>, +<code>CP850</code>, <code>CP866</code>, <code>CP874</code>, +<code>CP932</code>, <code>CP949</code>, <code>CP950</code>, <code>CP1250</code>, <code>CP1251</code>, +<code>CP1252</code>, <code>CP1253</code>, <code>CP1254</code>, <code>CP1255</code>, <code>CP1256</code>, +<code>CP1257</code>, <code>GB2312</code>, <code>EUC-JP</code>, <code>EUC-KR</code>, <code>EUC-TW</code>, +<code>BIG5</code>, <code>BIG5-HKSCS</code>, <code>GBK</code>, <code>GB18030</code>, <code>SHIFT_JIS</code>, +<code>JOHAB</code>, <code>TIS-620</code>, <code>VISCII</code>, <code>GEORGIAN-PS</code>, <code>UTF-8</code>. + + <!-- This data is taken from glibc/localedata/SUPPORTED. --> + <p><a name="index-Linux-271"></a>In the GNU system, the following encodings are frequently used for the +corresponding languages. + + <p><a name="index-encoding-for-your-language-272"></a> + <ul> +<li><code>ISO-8859-1</code> for +Afrikaans, Albanian, Basque, Breton, Catalan, Cornish, Danish, Dutch, +English, Estonian, Faroese, Finnish, French, Galician, German, +Greenlandic, Icelandic, Indonesian, Irish, Italian, Malay, Manx, +Norwegian, Occitan, Portuguese, Spanish, Swedish, Tagalog, Uzbek, +Walloon, +<li><code>ISO-8859-2</code> for +Bosnian, Croatian, Czech, Hungarian, Polish, Romanian, Serbian, Slovak, +Slovenian, +<li><code>ISO-8859-3</code> for Maltese, +<li><code>ISO-8859-5</code> for Macedonian, Serbian, +<li><code>ISO-8859-6</code> for Arabic, +<li><code>ISO-8859-7</code> for Greek, +<li><code>ISO-8859-8</code> for Hebrew, +<li><code>ISO-8859-9</code> for Turkish, +<li><code>ISO-8859-13</code> for Latvian, Lithuanian, Maori, +<li><code>ISO-8859-14</code> for Welsh, +<li><code>ISO-8859-15</code> for +Basque, Catalan, Dutch, English, Finnish, French, Galician, German, Irish, +Italian, Portuguese, Spanish, Swedish, Walloon, +<li><code>KOI8-R</code> for Russian, +<li><code>KOI8-U</code> for Ukrainian, +<li><code>KOI8-T</code> for Tajik, +<li><code>CP1251</code> for Bulgarian, Belarusian, +<li><code>GB2312</code>, <code>GBK</code>, <code>GB18030</code> +for simplified writing of Chinese, +<li><code>BIG5</code>, <code>BIG5-HKSCS</code> +for traditional writing of Chinese, +<li><code>EUC-JP</code> for Japanese, +<li><code>EUC-KR</code> for Korean, +<li><code>TIS-620</code> for Thai, +<li><code>GEORGIAN-PS</code> for Georgian, +<li><code>UTF-8</code> for any language, including those listed above. +</ul> + + <p><a name="index-quote-characters_002c-use-in-PO-files-273"></a><a name="index-quotation-marks-274"></a>When single quote characters or double quote characters are used in +translations for your language, and your locale's encoding is one of the +ISO-8859-* charsets, it is best if you create your PO files in UTF-8 +encoding, instead of your locale's encoding. This is because in UTF-8 +the real quote characters can be represented (single quote characters: +U+2018, U+2019, double quote characters: U+201C, U+201D), whereas none of +ISO-8859-* charsets has them all. Users in UTF-8 locales will see the +real quote characters, whereas users in ISO-8859-* locales will see the +vertical apostrophe and the vertical double quote instead (because that's +what the character set conversion will transliterate them to). + + <p><a name="index-g_t_0040code_007bxmodmap_007d-program_002c-and-typing-quotation-marks-275"></a>To enter such quote characters under X11, you can change your keyboard +mapping using the <code>xmodmap</code> program. The X11 names of the quote +characters are "leftsinglequotemark", "rightsinglequotemark", +"leftdoublequotemark", "rightdoublequotemark", "singlelowquotemark", +"doublelowquotemark". + + <p>Note that only recent versions of GNU Emacs support the UTF-8 encoding: +Emacs 20 with Mule-UCS, and Emacs 21. As of January 2001, XEmacs doesn't +support the UTF-8 encoding. + + <p>The character encoding name can be written in either upper or lower case. +Usually upper case is preferred. + + <br><dt>Content-Transfer-Encoding<dd>Set this to <code>8bit</code>. + + <br><dt>Plural-Forms<dd>This field is optional. It is only needed if the PO file has plural forms. +You can find them by searching for the ‘<samp><span class="samp">msgid_plural</span></samp>’ keyword. The +format of the plural forms field is described in <a href="#Plural-forms">Plural forms</a> and +<a href="#Translating-plural-forms">Translating plural forms</a>. +</dl> + +<div class="node"> +<a name="Updating"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Editing">Editing</a>, +Previous: <a rel="previous" accesskey="p" href="#Creating">Creating</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">7 Updating Existing PO Files</h2> + +<ul class="menu"> +<li><a accesskey="1" href="#msgmerge-Invocation">msgmerge Invocation</a>: Invoking the <code>msgmerge</code> Program +</ul> + +<div class="node"> +<a name="msgmerge-Invocation"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Updating">Updating</a>, +Up: <a rel="up" accesskey="u" href="#Updating">Updating</a> + +</div> + +<h3 class="section">7.1 Invoking the <code>msgmerge</code> Program</h3> + + <p><a name="index-msgmerge-276"></a><a name="index-g_t_0040code_007bmsgmerge_007d-program_002c-usage-277"></a> +<pre class="example"> msgmerge [<var>option</var>] <var>def</var>.po <var>ref</var>.pot +</pre> + <p>The <code>msgmerge</code> program merges two Uniforum style .po files together. +The <var>def</var>.po file is an existing PO file with translations which will +be taken over to the newly created file as long as they still match; +comments will be preserved, but extracted comments and file positions will +be discarded. The <var>ref</var>.pot file is the last created PO file with +up-to-date source references but old translations, or a PO Template file +(generally created by <code>xgettext</code>); any translations or comments +in the file will be discarded, however dot comments and file positions +will be preserved. Where an exact match cannot be found, fuzzy matching +is used to produce better results. + +<h4 class="subsection">7.1.1 Input file location</h4> + + <dl> +<dt>‘<samp><var>def</var><span class="samp">.po</span></samp>’<dd>Translations referring to old sources. + + <br><dt>‘<samp><var>ref</var><span class="samp">.pot</span></samp>’<dd>References to the new sources. + + <br><dt>‘<samp><span class="samp">-D </span><var>directory</var></samp>’<dt>‘<samp><span class="samp">--directory=</span><var>directory</var></samp>’<dd><a name="index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-278"></a><a name="index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-279"></a>Add <var>directory</var> to the list of directories. Source files are +searched relative to this list of directories. The resulting <samp><span class="file">.po</span></samp> +file will be written relative to the current directory, though. + + <br><dt>‘<samp><span class="samp">-C </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--compendium=</span><var>file</var></samp>’<dd><a name="index-g_t_002dC_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-280"></a><a name="index-g_t_002d_002dcompendium_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-281"></a>Specify an additional library of message translations. See <a href="#Compendium">Compendium</a>. +This option may be specified more than once. + + </dl> + +<h4 class="subsection">7.1.2 Operation mode</h4> + + <dl> +<dt>‘<samp><span class="samp">-U</span></samp>’<dt>‘<samp><span class="samp">--update</span></samp>’<dd><a name="index-g_t_002dU_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-282"></a><a name="index-g_t_002d_002dupdate_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-283"></a>Update <var>def</var>.po. Do nothing if <var>def</var>.po is already up to date. + + </dl> + +<h4 class="subsection">7.1.3 Output file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--output-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002do_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-284"></a><a name="index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-285"></a>Write output to specified file. + + </dl> + + <p><a name="index-standard-output_002c-and-_0040code_007bmsgmerge_007d-program-286"></a>The results are written to standard output if no output file is specified +or if it is ‘<samp><span class="samp">-</span></samp>’. + +<h4 class="subsection">7.1.4 Output file location in update mode</h4> + + <p>The result is written back to <var>def</var>.po. + + <dl> +<dt>‘<samp><span class="samp">--backup=</span><var>control</var></samp>’<dd><a name="index-g_t_002d_002dbackup_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-287"></a><a name="index-backup-old-file_002c-and-_0040code_007bmsgmerge_007d-program-288"></a>Make a backup of <var>def</var>.po + + <br><dt>‘<samp><span class="samp">--suffix=</span><var>suffix</var></samp>’<dd><a name="index-g_t_002d_002dsuffix_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-289"></a>Override the usual backup suffix. + + </dl> + + <p><a name="index-version-control-for-backup-files_002c-_0040code_007bmsgmerge_007d-290"></a>The version control method may be selected via the <code>--backup</code> option +or through the <code>VERSION_CONTROL</code> environment variable. Here are the +values: + + <dl> +<dt>‘<samp><span class="samp">none</span></samp>’<dt>‘<samp><span class="samp">off</span></samp>’<dd>Never make backups (even if <code>--backup</code> is given). + + <br><dt>‘<samp><span class="samp">numbered</span></samp>’<dt>‘<samp><span class="samp">t</span></samp>’<dd>Make numbered backups. + + <br><dt>‘<samp><span class="samp">existing</span></samp>’<dt>‘<samp><span class="samp">nil</span></samp>’<dd>Make numbered backups if numbered backups for this file already exist, +otherwise make simple backups. + + <br><dt>‘<samp><span class="samp">simple</span></samp>’<dt>‘<samp><span class="samp">never</span></samp>’<dd>Always make simple backups. + + </dl> + + <p>The backup suffix is ‘<samp><span class="samp">~</span></samp>’, unless set with <code>--suffix</code> or the +<code>SIMPLE_BACKUP_SUFFIX</code> environment variable. + +<h4 class="subsection">7.1.5 Operation modifiers</h4> + + <dl> +<dt>‘<samp><span class="samp">-m</span></samp>’<dt>‘<samp><span class="samp">--multi-domain</span></samp>’<dd><a name="index-g_t_002dm_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-291"></a><a name="index-g_t_002d_002dmulti_002ddomain_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-292"></a>Apply <var>ref</var>.pot to each of the domains in <var>def</var>.po. + + <br><dt>‘<samp><span class="samp">-N</span></samp>’<dt>‘<samp><span class="samp">--no-fuzzy-matching</span></samp>’<dd><a name="index-g_t_002dN_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-293"></a><a name="index-g_t_002d_002dno_002dfuzzy_002dmatching_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-294"></a>Do not use fuzzy matching when an exact match is not found. This may speed +up the operation considerably. + + <br><dt>‘<samp><span class="samp">--previous</span></samp>’<dd><a name="index-g_t_002d_002dprevious_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-295"></a>Keep the previous msgids of translated messages, marked with ‘<samp><span class="samp">#|</span></samp>’, when +adding the fuzzy marker to such messages. +</dl> + +<h4 class="subsection">7.1.6 Input file syntax</h4> + + <dl> +<dt>‘<samp><span class="samp">-P</span></samp>’<dt>‘<samp><span class="samp">--properties-input</span></samp>’<dd><a name="index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-296"></a><a name="index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-297"></a>Assume the input files are Java ResourceBundles in Java <code>.properties</code> +syntax, not in PO file syntax. + + <br><dt>‘<samp><span class="samp">--stringtable-input</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-298"></a>Assume the input files are NeXTstep/GNUstep localized resource files in +<code>.strings</code> syntax, not in PO file syntax. + + </dl> + +<h4 class="subsection">7.1.7 Output details</h4> + +<!-- no-escape and -escape omitted on purpose. They are not useful. --> + <dl> +<dt>‘<samp><span class="samp">--lang=</span><var>catalogname</var></samp>’<dd><a name="index-g_t_002d_002dlang_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-299"></a>Specify the ‘<samp><span class="samp">Language</span></samp>’ field to be used in the header entry. See +<a href="#Header-Entry">Header Entry</a> for the meaning of this field. Note: The +‘<samp><span class="samp">Language-Team</span></samp>’ and ‘<samp><span class="samp">Plural-Forms</span></samp>’ fields are left unchanged. +If this option is not specified, the ‘<samp><span class="samp">Language</span></samp>’ field is inferred, as +best as possible, from the ‘<samp><span class="samp">Language-Team</span></samp>’ field. + + <br><dt>‘<samp><span class="samp">--color</span></samp>’<dt>‘<samp><span class="samp">--color=</span><var>when</var></samp>’<dd><a name="index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-300"></a>Specify whether or when to use colors and other text attributes. +See <a href="#The-_002d_002dcolor-option">The –color option</a> for details. + + <br><dt>‘<samp><span class="samp">--style=</span><var>style_file</var></samp>’<dd><a name="index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-301"></a>Specify the CSS style rule file to use for <code>--color</code>. +See <a href="#The-_002d_002dstyle-option">The –style option</a> for details. + + <br><dt>‘<samp><span class="samp">--force-po</span></samp>’<dd><a name="index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-302"></a>Always write an output file even if it contains no message. + + <br><dt>‘<samp><span class="samp">-i</span></samp>’<dt>‘<samp><span class="samp">--indent</span></samp>’<dd><a name="index-g_t_002di_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-303"></a><a name="index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-304"></a>Write the .po file using indented style. + + <br><dt>‘<samp><span class="samp">--no-location</span></samp>’<dd><a name="index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-305"></a>Do not write ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines. + + <br><dt>‘<samp><span class="samp">--add-location</span></samp>’<dd><a name="index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-306"></a>Generate ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines (default). + + <br><dt>‘<samp><span class="samp">--strict</span></samp>’<dd><a name="index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-307"></a>Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + + <br><dt>‘<samp><span class="samp">-p</span></samp>’<dt>‘<samp><span class="samp">--properties-output</span></samp>’<dd><a name="index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-308"></a><a name="index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-309"></a>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note +that this file format doesn't support plural forms and silently drops +obsolete messages. + + <br><dt>‘<samp><span class="samp">--stringtable-output</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-310"></a>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. +Note that this file format doesn't support plural forms. + + <br><dt>‘<samp><span class="samp">-w </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--width=</span><var>number</var></samp>’<dd><a name="index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-311"></a><a name="index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-312"></a>Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given <var>number</var>. + + <br><dt>‘<samp><span class="samp">--no-wrap</span></samp>’<dd><a name="index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-313"></a>Do not break long message lines. Message lines whose width exceeds the +output page width will not be split into several lines. Only file reference +lines which are wider than the output page width will be split. + + <br><dt>‘<samp><span class="samp">-s</span></samp>’<dt>‘<samp><span class="samp">--sort-output</span></samp>’<dd><a name="index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-314"></a><a name="index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-315"></a><a name="index-sorting-_0040code_007bmsgmerge_007d-output-316"></a>Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + + <br><dt>‘<samp><span class="samp">-F</span></samp>’<dt>‘<samp><span class="samp">--sort-by-file</span></samp>’<dd><a name="index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-317"></a><a name="index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-318"></a>Sort output by file location. + + </dl> + +<h4 class="subsection">7.1.8 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-319"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-320"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-321"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-322"></a>Output version information and exit. + + <br><dt>‘<samp><span class="samp">-v</span></samp>’<dt>‘<samp><span class="samp">--verbose</span></samp>’<dd><a name="index-g_t_002dv_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-323"></a><a name="index-g_t_002d_002dverbose_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-324"></a>Increase verbosity level. + + <br><dt>‘<samp><span class="samp">-q</span></samp>’<dt>‘<samp><span class="samp">--quiet</span></samp>’<dt>‘<samp><span class="samp">--silent</span></samp>’<dd><a name="index-g_t_002dq_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-325"></a><a name="index-g_t_002d_002dquiet_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-326"></a><a name="index-g_t_002d_002dsilent_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-327"></a>Suppress progress indicators. + + </dl> + +<div class="node"> +<a name="Editing"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Manipulating">Manipulating</a>, +Previous: <a rel="previous" accesskey="p" href="#Updating">Updating</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">8 Editing PO Files</h2> + + <p><a name="index-Editing-PO-Files-328"></a> + +<ul class="menu"> +<li><a accesskey="1" href="#KBabel">KBabel</a>: KDE's PO File Editor +<li><a accesskey="2" href="#Gtranslator">Gtranslator</a>: GNOME's PO File Editor +<li><a accesskey="3" href="#PO-Mode">PO Mode</a>: Emacs's PO File Editor +<li><a accesskey="4" href="#Compendium">Compendium</a>: Using Translation Compendia +</ul> + +<div class="node"> +<a name="KBabel"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Gtranslator">Gtranslator</a>, +Previous: <a rel="previous" accesskey="p" href="#Editing">Editing</a>, +Up: <a rel="up" accesskey="u" href="#Editing">Editing</a> + +</div> + +<h3 class="section">8.1 KDE's PO File Editor</h3> + + <p><a name="index-KDE-PO-file-editor-329"></a> +<div class="node"> +<a name="Gtranslator"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#PO-Mode">PO Mode</a>, +Previous: <a rel="previous" accesskey="p" href="#KBabel">KBabel</a>, +Up: <a rel="up" accesskey="u" href="#Editing">Editing</a> + +</div> + +<h3 class="section">8.2 GNOME's PO File Editor</h3> + + <p><a name="index-GNOME-PO-file-editor-330"></a> +<div class="node"> +<a name="PO-Mode"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Compendium">Compendium</a>, +Previous: <a rel="previous" accesskey="p" href="#Gtranslator">Gtranslator</a>, +Up: <a rel="up" accesskey="u" href="#Editing">Editing</a> + +</div> + +<h3 class="section">8.3 Emacs's PO File Editor</h3> + + <p><a name="index-Emacs-PO-Mode-331"></a> +<!-- FIXME: Rewrite. --> + + <p>For those of you being +the lucky users of Emacs, PO mode has been specifically created +for providing a cozy environment for editing or modifying PO files. +While editing a PO file, PO mode allows for the easy browsing of +auxiliary and compendium PO files, as well as for following references into +the set of C program sources from which PO files have been derived. +It has a few special features, among which are the interactive marking +of program strings as translatable, and the validation of PO files +with easy repositioning to PO file lines showing errors. + + <p>For the beginning, besides main PO mode commands +(see <a href="#Main-PO-Commands">Main PO Commands</a>), you should know how to move between entries +(see <a href="#Entry-Positioning">Entry Positioning</a>), and how to handle untranslated entries +(see <a href="#Untranslated-Entries">Untranslated Entries</a>). + +<ul class="menu"> +<li><a accesskey="1" href="#Installation">Installation</a>: Completing GNU <code>gettext</code> Installation +<li><a accesskey="2" href="#Main-PO-Commands">Main PO Commands</a>: Main Commands +<li><a accesskey="3" href="#Entry-Positioning">Entry Positioning</a>: Entry Positioning +<li><a accesskey="4" href="#Normalizing">Normalizing</a>: Normalizing Strings in Entries +<li><a accesskey="5" href="#Translated-Entries">Translated Entries</a>: Translated Entries +<li><a accesskey="6" href="#Fuzzy-Entries">Fuzzy Entries</a>: Fuzzy Entries +<li><a accesskey="7" href="#Untranslated-Entries">Untranslated Entries</a>: Untranslated Entries +<li><a accesskey="8" href="#Obsolete-Entries">Obsolete Entries</a>: Obsolete Entries +<li><a accesskey="9" href="#Modifying-Translations">Modifying Translations</a>: Modifying Translations +<li><a href="#Modifying-Comments">Modifying Comments</a>: Modifying Comments +<li><a href="#Subedit">Subedit</a>: Mode for Editing Translations +<li><a href="#C-Sources-Context">C Sources Context</a>: C Sources Context +<li><a href="#Auxiliary">Auxiliary</a>: Consulting Auxiliary PO Files +</ul> + +<div class="node"> +<a name="Installation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Main-PO-Commands">Main PO Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#PO-Mode">PO Mode</a>, +Up: <a rel="up" accesskey="u" href="#PO-Mode">PO Mode</a> + +</div> + +<h4 class="subsection">8.3.1 Completing GNU <code>gettext</code> Installation</h4> + + <p><a name="index-installing-_0040code_007bgettext_007d-332"></a><a name="index-g_t_0040code_007bgettext_007d-installation-333"></a>Once you have received, unpacked, configured and compiled the GNU +<code>gettext</code> distribution, the ‘<samp><span class="samp">make install</span></samp>’ command puts in +place the programs <code>xgettext</code>, <code>msgfmt</code>, <code>gettext</code>, and +<code>msgmerge</code>, as well as their available message catalogs. To +top off a comfortable installation, you might also want to make the +PO mode available to your Emacs users. + + <p><a name="index-g_t_0040file_007b_002eemacs_007d-customizations-334"></a><a name="index-installing-PO-mode-335"></a>During the installation of the PO mode, you might want to modify your +file <samp><span class="file">.emacs</span></samp>, once and for all, so it contains a few lines looking +like: + +<pre class="example"> (setq auto-mode-alist + (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist)) + (autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t) +</pre> + <p>Later, whenever you edit some <samp><span class="file">.po</span></samp> +file, or any file having the string ‘<samp><span class="samp">.po.</span></samp>’ within its name, +Emacs loads <samp><span class="file">po-mode.elc</span></samp> (or <samp><span class="file">po-mode.el</span></samp>) as needed, and +automatically activates PO mode commands for the associated buffer. +The string <em>PO</em> appears in the mode line for any buffer for +which PO mode is active. Many PO files may be active at once in a +single Emacs session. + + <p>If you are using Emacs version 20 or newer, and have already installed +the appropriate international fonts on your system, you may also tell +Emacs how to determine automatically the coding system of every PO file. +This will often (but not always) cause the necessary fonts to be loaded +and used for displaying the translations on your Emacs screen. For this +to happen, add the lines: + +<pre class="example"> (modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\." + 'po-find-file-coding-system) + (autoload 'po-find-file-coding-system "po-mode") +</pre> + <p class="noindent">to your <samp><span class="file">.emacs</span></samp> file. If, with this, you still see boxes instead +of international characters, try a different font set (via Shift Mouse +button 1). + +<div class="node"> +<a name="Main-PO-Commands"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Entry-Positioning">Entry Positioning</a>, +Previous: <a rel="previous" accesskey="p" href="#Installation">Installation</a>, +Up: <a rel="up" accesskey="u" href="#PO-Mode">PO Mode</a> + +</div> + +<h4 class="subsection">8.3.2 Main PO mode Commands</h4> + + <p><a name="index-PO-mode-_0028Emacs_0029-commands-336"></a><a name="index-commands-337"></a>After setting up Emacs with something similar to the lines in +<a href="#Installation">Installation</a>, PO mode is activated for a window when Emacs finds a +PO file in that window. This puts the window read-only and establishes a +po-mode-map, which is a genuine Emacs mode, in a way that is not derived +from text mode in any way. Functions found on <code>po-mode-hook</code>, +if any, will be executed. + + <p>When PO mode is active in a window, the letters ‘<samp><span class="samp">PO</span></samp>’ appear +in the mode line for that window. The mode line also displays how +many entries of each kind are held in the PO file. For example, +the string ‘<samp><span class="samp">132t+3f+10u+2o</span></samp>’ would tell the translator that the +PO mode contains 132 translated entries (see <a href="#Translated-Entries">Translated Entries</a>, +3 fuzzy entries (see <a href="#Fuzzy-Entries">Fuzzy Entries</a>), 10 untranslated entries +(see <a href="#Untranslated-Entries">Untranslated Entries</a>) and 2 obsolete entries (see <a href="#Obsolete-Entries">Obsolete Entries</a>). Zero-coefficients items are not shown. So, in this example, if +the fuzzy entries were unfuzzied, the untranslated entries were translated +and the obsolete entries were deleted, the mode line would merely display +‘<samp><span class="samp">145t</span></samp>’ for the counters. + + <p>The main PO commands are those which do not fit into the other categories of +subsequent sections. These allow for quitting PO mode or for managing windows +in special ways. + + <dl> +<dt><kbd>_</kbd><dd><a name="index-g_t_005f_0040r_007b_002c-PO-Mode-command_007d-338"></a>Undo last modification to the PO file (<code>po-undo</code>). + + <br><dt><kbd>Q</kbd><dd><a name="index-Q_0040r_007b_002c-PO-Mode-command_007d-339"></a>Quit processing and save the PO file (<code>po-quit</code>). + + <br><dt><kbd>q</kbd><dd><a name="index-q_0040r_007b_002c-PO-Mode-command_007d-340"></a>Quit processing, possibly after confirmation (<code>po-confirm-and-quit</code>). + + <br><dt><kbd>0</kbd><dd><a name="index-g_t0_0040r_007b_002c-PO-Mode-command_007d-341"></a>Temporary leave the PO file window (<code>po-other-window</code>). + + <br><dt><kbd>?</kbd><dt><kbd>h</kbd><dd><a name="index-g_t_003f_0040r_007b_002c-PO-Mode-command_007d-342"></a><a name="index-h_0040r_007b_002c-PO-Mode-command_007d-343"></a>Show help about PO mode (<code>po-help</code>). + + <br><dt><kbd>=</kbd><dd><a name="index-g_t_003d_0040r_007b_002c-PO-Mode-command_007d-344"></a>Give some PO file statistics (<code>po-statistics</code>). + + <br><dt><kbd>V</kbd><dd><a name="index-V_0040r_007b_002c-PO-Mode-command_007d-345"></a>Batch validate the format of the whole PO file (<code>po-validate</code>). + + </dl> + + <p><a name="index-g_t_005f_0040r_007b_002c-PO-Mode-command_007d-346"></a><a name="index-po_002dundo_0040r_007b_002c-PO-Mode-command_007d-347"></a>The command <kbd>_</kbd> (<code>po-undo</code>) interfaces to the Emacs +<em>undo</em> facility. See <a href="emacs.html#Undo">Undoing Changes</a>. Each time <kbd>_</kbd> is typed, modifications which the translator +did to the PO file are undone a little more. For the purpose of +undoing, each PO mode command is atomic. This is especially true for +the <kbd><RET></kbd> command: the whole edition made by using a single +use of this command is undone at once, even if the edition itself +implied several actions. However, while in the editing window, one +can undo the edition work quite parsimoniously. + + <p><a name="index-Q_0040r_007b_002c-PO-Mode-command_007d-348"></a><a name="index-q_0040r_007b_002c-PO-Mode-command_007d-349"></a><a name="index-po_002dquit_0040r_007b_002c-PO-Mode-command_007d-350"></a><a name="index-po_002dconfirm_002dand_002dquit_0040r_007b_002c-PO-Mode-command_007d-351"></a>The commands <kbd>Q</kbd> (<code>po-quit</code>) and <kbd>q</kbd> +(<code>po-confirm-and-quit</code>) are used when the translator is done with the +PO file. The former is a bit less verbose than the latter. If the file +has been modified, it is saved to disk first. In both cases, and prior to +all this, the commands check if any untranslated messages remain in the +PO file and, if so, the translator is asked if she really wants to leave +off working with this PO file. This is the preferred way of getting rid +of an Emacs PO file buffer. Merely killing it through the usual command +<kbd>C-x k</kbd><!-- /@w --> (<code>kill-buffer</code>) is not the tidiest way to proceed. + + <p><a name="index-g_t0_0040r_007b_002c-PO-Mode-command_007d-352"></a><a name="index-po_002dother_002dwindow_0040r_007b_002c-PO-Mode-command_007d-353"></a>The command <kbd>0</kbd> (<code>po-other-window</code>) is another, softer way, +to leave PO mode, temporarily. It just moves the cursor to some other +Emacs window, and pops one if necessary. For example, if the translator +just got PO mode to show some source context in some other, she might +discover some apparent bug in the program source that needs correction. +This command allows the translator to change sex, become a programmer, +and have the cursor right into the window containing the program she +(or rather <em>he</em>) wants to modify. By later getting the cursor back +in the PO file window, or by asking Emacs to edit this file once again, +PO mode is then recovered. + + <p><a name="index-g_t_003f_0040r_007b_002c-PO-Mode-command_007d-354"></a><a name="index-h_0040r_007b_002c-PO-Mode-command_007d-355"></a><a name="index-po_002dhelp_0040r_007b_002c-PO-Mode-command_007d-356"></a>The command <kbd>h</kbd> (<code>po-help</code>) displays a summary of all available PO +mode commands. The translator should then type any character to resume +normal PO mode operations. The command <kbd>?</kbd> has the same effect +as <kbd>h</kbd>. + + <p><a name="index-g_t_003d_0040r_007b_002c-PO-Mode-command_007d-357"></a><a name="index-po_002dstatistics_0040r_007b_002c-PO-Mode-command_007d-358"></a>The command <kbd>=</kbd> (<code>po-statistics</code>) computes the total number of +entries in the PO file, the ordinal of the current entry (counted from +1), the number of untranslated entries, the number of obsolete entries, +and displays all these numbers. + + <p><a name="index-V_0040r_007b_002c-PO-Mode-command_007d-359"></a><a name="index-po_002dvalidate_0040r_007b_002c-PO-Mode-command_007d-360"></a>The command <kbd>V</kbd> (<code>po-validate</code>) launches <code>msgfmt</code> in +checking and verbose +mode over the current PO file. This command first offers to save the +current PO file on disk. The <code>msgfmt</code> tool, from GNU <code>gettext</code>, +has the purpose of creating a MO file out of a PO file, and PO mode uses +the features of this program for checking the overall format of a PO file, +as well as all individual entries. + + <p><a name="index-next_002derror_0040r_007b_002c-stepping-through-PO-file-validation-results_007d-361"></a>The program <code>msgfmt</code> runs asynchronously with Emacs, so the +translator regains control immediately while her PO file is being studied. +Error output is collected in the Emacs ‘<samp><span class="samp">*compilation*</span></samp>’ buffer, +displayed in another window. The regular Emacs command <kbd>C-x`</kbd> +(<code>next-error</code>), as well as other usual compile commands, allow the +translator to reposition quickly to the offending parts of the PO file. +Once the cursor is on the line in error, the translator may decide on +any PO mode action which would help correcting the error. + +<div class="node"> +<a name="Entry-Positioning"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Normalizing">Normalizing</a>, +Previous: <a rel="previous" accesskey="p" href="#Main-PO-Commands">Main PO Commands</a>, +Up: <a rel="up" accesskey="u" href="#PO-Mode">PO Mode</a> + +</div> + +<h4 class="subsection">8.3.3 Entry Positioning</h4> + + <p><a name="index-current-entry-of-a-PO-file-362"></a>The cursor in a PO file window is almost always part of +an entry. The only exceptions are the special case when the cursor +is after the last entry in the file, or when the PO file is +empty. The entry where the cursor is found to be is said to be the +current entry. Many PO mode commands operate on the current entry, +so moving the cursor does more than allowing the translator to browse +the PO file, this also selects on which entry commands operate. + + <p><a name="index-moving-through-a-PO-file-363"></a>Some PO mode commands alter the position of the cursor in a specialized +way. A few of those special purpose positioning are described here, +the others are described in following sections (for a complete list try +<kbd>C-h m</kbd>): + + <dl> +<dt><kbd>.</kbd><dd><a name="index-g_t_002e_0040r_007b_002c-PO-Mode-command_007d-364"></a>Redisplay the current entry (<code>po-current-entry</code>). + + <br><dt><kbd>n</kbd><dd><a name="index-n_0040r_007b_002c-PO-Mode-command_007d-365"></a>Select the entry after the current one (<code>po-next-entry</code>). + + <br><dt><kbd>p</kbd><dd><a name="index-p_0040r_007b_002c-PO-Mode-command_007d-366"></a>Select the entry before the current one (<code>po-previous-entry</code>). + + <br><dt><kbd><</kbd><dd><a name="index-g_t_003c_0040r_007b_002c-PO-Mode-command_007d-367"></a>Select the first entry in the PO file (<code>po-first-entry</code>). + + <br><dt><kbd>></kbd><dd><a name="index-g_t_003e_0040r_007b_002c-PO-Mode-command_007d-368"></a>Select the last entry in the PO file (<code>po-last-entry</code>). + + <br><dt><kbd>m</kbd><dd><a name="index-m_0040r_007b_002c-PO-Mode-command_007d-369"></a>Record the location of the current entry for later use +(<code>po-push-location</code>). + + <br><dt><kbd>r</kbd><dd><a name="index-r_0040r_007b_002c-PO-Mode-command_007d-370"></a>Return to a previously saved entry location (<code>po-pop-location</code>). + + <br><dt><kbd>x</kbd><dd><a name="index-x_0040r_007b_002c-PO-Mode-command_007d-371"></a>Exchange the current entry location with the previously saved one +(<code>po-exchange-location</code>). + + </dl> + + <p><a name="index-g_t_002e_0040r_007b_002c-PO-Mode-command_007d-372"></a><a name="index-po_002dcurrent_002dentry_0040r_007b_002c-PO-Mode-command_007d-373"></a>Any Emacs command able to reposition the cursor may be used +to select the current entry in PO mode, including commands which +move by characters, lines, paragraphs, screens or pages, and search +commands. However, there is a kind of standard way to display the +current entry in PO mode, which usual Emacs commands moving +the cursor do not especially try to enforce. The command <kbd>.</kbd> +(<code>po-current-entry</code>) has the sole purpose of redisplaying the +current entry properly, after the current entry has been changed by +means external to PO mode, or the Emacs screen otherwise altered. + + <p>It is yet to be decided if PO mode helps the translator, or otherwise +irritates her, by forcing a rigid window disposition while she +is doing her work. We originally had quite precise ideas about +how windows should behave, but on the other hand, anyone used to +Emacs is often happy to keep full control. Maybe a fixed window +disposition might be offered as a PO mode option that the translator +might activate or deactivate at will, so it could be offered on an +experimental basis. If nobody feels a real need for using it, or +a compulsion for writing it, we should drop this whole idea. +The incentive for doing it should come from translators rather than +programmers, as opinions from an experienced translator are surely +more worth to me than opinions from programmers <em>thinking</em> about +how <em>others</em> should do translation. + + <p><a name="index-n_0040r_007b_002c-PO-Mode-command_007d-374"></a><a name="index-po_002dnext_002dentry_0040r_007b_002c-PO-Mode-command_007d-375"></a><a name="index-p_0040r_007b_002c-PO-Mode-command_007d-376"></a><a name="index-po_002dprevious_002dentry_0040r_007b_002c-PO-Mode-command_007d-377"></a>The commands <kbd>n</kbd> (<code>po-next-entry</code>) and <kbd>p</kbd> +(<code>po-previous-entry</code>) move the cursor the entry following, +or preceding, the current one. If <kbd>n</kbd> is given while the +cursor is on the last entry of the PO file, or if <kbd>p</kbd> +is given while the cursor is on the first entry, no move is done. + + <p><a name="index-g_t_003c_0040r_007b_002c-PO-Mode-command_007d-378"></a><a name="index-po_002dfirst_002dentry_0040r_007b_002c-PO-Mode-command_007d-379"></a><a name="index-g_t_003e_0040r_007b_002c-PO-Mode-command_007d-380"></a><a name="index-po_002dlast_002dentry_0040r_007b_002c-PO-Mode-command_007d-381"></a>The commands <kbd><</kbd> (<code>po-first-entry</code>) and <kbd>></kbd> +(<code>po-last-entry</code>) move the cursor to the first entry, or last +entry, of the PO file. When the cursor is located past the last +entry in a PO file, most PO mode commands will return an error saying +‘<samp><span class="samp">After last entry</span></samp>’. Moreover, the commands <kbd><</kbd> and <kbd>></kbd> +have the special property of being able to work even when the cursor +is not into some PO file entry, and one may use them for nicely +correcting this situation. But even these commands will fail on a +truly empty PO file. There are development plans for the PO mode for it +to interactively fill an empty PO file from sources. See <a href="#Marking">Marking</a>. + + <p>The translator may decide, before working at the translation of +a particular entry, that she needs to browse the remainder of the +PO file, maybe for finding the terminology or phraseology used +in related entries. She can of course use the standard Emacs idioms +for saving the current cursor location in some register, and use that +register for getting back, or else, use the location ring. + + <p><a name="index-m_0040r_007b_002c-PO-Mode-command_007d-382"></a><a name="index-po_002dpush_002dlocation_0040r_007b_002c-PO-Mode-command_007d-383"></a><a name="index-r_0040r_007b_002c-PO-Mode-command_007d-384"></a><a name="index-po_002dpop_002dlocation_0040r_007b_002c-PO-Mode-command_007d-385"></a>PO mode offers another approach, by which cursor locations may be saved +onto a special stack. The command <kbd>m</kbd> (<code>po-push-location</code>) +merely adds the location of current entry to the stack, pushing +the already saved locations under the new one. The command +<kbd>r</kbd> (<code>po-pop-location</code>) consumes the top stack element and +repositions the cursor to the entry associated with that top element. +This position is then lost, for the next <kbd>r</kbd> will move the cursor +to the previously saved location, and so on until no locations remain +on the stack. + + <p>If the translator wants the position to be kept on the location stack, +maybe for taking a look at the entry associated with the top +element, then go elsewhere with the intent of getting back later, she +ought to use <kbd>m</kbd> immediately after <kbd>r</kbd>. + + <p><a name="index-x_0040r_007b_002c-PO-Mode-command_007d-386"></a><a name="index-po_002dexchange_002dlocation_0040r_007b_002c-PO-Mode-command_007d-387"></a>The command <kbd>x</kbd> (<code>po-exchange-location</code>) simultaneously +repositions the cursor to the entry associated with the top element of +the stack of saved locations, and replaces that top element with the +location of the current entry before the move. Consequently, repeating +the <kbd>x</kbd> command toggles alternatively between two entries. +For achieving this, the translator will position the cursor on the +first entry, use <kbd>m</kbd>, then position to the second entry, and +merely use <kbd>x</kbd> for making the switch. + +<div class="node"> +<a name="Normalizing"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Translated-Entries">Translated Entries</a>, +Previous: <a rel="previous" accesskey="p" href="#Entry-Positioning">Entry Positioning</a>, +Up: <a rel="up" accesskey="u" href="#PO-Mode">PO Mode</a> + +</div> + +<h4 class="subsection">8.3.4 Normalizing Strings in Entries</h4> + + <p><a name="index-string-normalization-in-entries-388"></a> +There are many different ways for encoding a particular string into a +PO file entry, because there are so many different ways to split and +quote multi-line strings, and even, to represent special characters +by backslashed escaped sequences. Some features of PO mode rely on +the ability for PO mode to scan an already existing PO file for a +particular string encoded into the <code>msgid</code> field of some entry. +Even if PO mode has internally all the built-in machinery for +implementing this recognition easily, doing it fast is technically +difficult. To facilitate a solution to this efficiency problem, +we decided on a canonical representation for strings. + + <p>A conventional representation of strings in a PO file is currently +under discussion, and PO mode experiments with a canonical representation. +Having both <code>xgettext</code> and PO mode converging towards a uniform +way of representing equivalent strings would be useful, as the internal +normalization needed by PO mode could be automatically satisfied +when using <code>xgettext</code> from GNU <code>gettext</code>. An explicit +PO mode normalization should then be only necessary for PO files +imported from elsewhere, or for when the convention itself evolves. + + <p>So, for achieving normalization of at least the strings of a given +PO file needing a canonical representation, the following PO mode +command is available: + + <p><a name="index-string-normalization-in-entries-389"></a> + <dl> +<dt><kbd>M-x po-normalize</kbd><dd><a name="index-po_002dnormalize_0040r_007b_002c-PO-Mode-command_007d-390"></a>Tidy the whole PO file by making entries more uniform. + + </dl> + + <p>The special command <kbd>M-x po-normalize</kbd>, which has no associated +keys, revises all entries, ensuring that strings of both original +and translated entries use uniform internal quoting in the PO file. +It also removes any crumb after the last entry. This command may be +useful for PO files freshly imported from elsewhere, or if we ever +improve on the canonical quoting format we use. This canonical format +is not only meant for getting cleaner PO files, but also for greatly +speeding up <code>msgid</code> string lookup for some other PO mode commands. + + <p><kbd>M-x po-normalize</kbd> presently makes three passes over the entries. +The first implements heuristics for converting PO files for GNU +<code>gettext</code> 0.6 and earlier, in which <code>msgid</code> and <code>msgstr</code> +fields were using K&R style C string syntax for multi-line strings. +These heuristics may fail for comments not related to obsolete +entries and ending with a backslash; they also depend on subsequent +passes for finalizing the proper commenting of continued lines for +obsolete entries. This first pass might disappear once all oldish PO +files would have been adjusted. The second and third pass normalize +all <code>msgid</code> and <code>msgstr</code> strings respectively. They also +clean out those trailing backslashes used by XView's <code>msgfmt</code> +for continued lines. + + <p><a name="index-importing-PO-files-391"></a>Having such an explicit normalizing command allows for importing PO +files from other sources, but also eases the evolution of the current +convention, evolution driven mostly by aesthetic concerns, as of now. +It is easy to make suggested adjustments at a later time, as the +normalizing command and eventually, other GNU <code>gettext</code> tools +should greatly automate conformance. A description of the canonical +string format is given below, for the particular benefit of those not +having Emacs handy, and who would nevertheless want to handcraft +their PO files in nice ways. + + <p><a name="index-multi_002dline-strings-392"></a>Right now, in PO mode, strings are single line or multi-line. A string +goes multi-line if and only if it has <em>embedded</em> newlines, that +is, if it matches ‘<samp><span class="samp">[^\n]\n+[^\n]</span></samp>’. So, we would have: + +<pre class="example"> msgstr "\n\nHello, world!\n\n\n" +</pre> + <p>but, replacing the space by a newline, this becomes: + +<pre class="example"> msgstr "" + "\n" + "\n" + "Hello,\n" + "world!\n" + "\n" + "\n" +</pre> + <p>We are deliberately using a caricatural example, here, to make the +point clearer. Usually, multi-lines are not that bad looking. +It is probable that we will implement the following suggestion. +We might lump together all initial newlines into the empty string, +and also all newlines introducing empty lines (that is, for <var>n</var> > 1<!-- /@w -->, the <var>n</var>-1'th last newlines would go together on a separate +string), so making the previous example appear: + +<pre class="example"> msgstr "\n\n" + "Hello,\n" + "world!\n" + "\n\n" +</pre> + <p>There are a few yet undecided little points about string normalization, +to be documented in this manual, once these questions settle. + +<div class="node"> +<a name="Translated-Entries"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Fuzzy-Entries">Fuzzy Entries</a>, +Previous: <a rel="previous" accesskey="p" href="#Normalizing">Normalizing</a>, +Up: <a rel="up" accesskey="u" href="#PO-Mode">PO Mode</a> + +</div> + +<h4 class="subsection">8.3.5 Translated Entries</h4> + + <p><a name="index-translated-entries-393"></a> +Each PO file entry for which the <code>msgstr</code> field has been filled with +a translation, and which is not marked as fuzzy (see <a href="#Fuzzy-Entries">Fuzzy Entries</a>), +is said to be a <dfn>translated</dfn> entry. Only translated entries will +later be compiled by GNU <code>msgfmt</code> and become usable in programs. +Other entry types will be excluded; translation will not occur for them. + + <p><a name="index-moving-by-translated-entries-394"></a>Some commands are more specifically related to translated entry processing. + + <dl> +<dt><kbd>t</kbd><dd><a name="index-t_0040r_007b_002c-PO-Mode-command_007d-395"></a>Find the next translated entry (<code>po-next-translated-entry</code>). + + <br><dt><kbd>T</kbd><dd><a name="index-T_0040r_007b_002c-PO-Mode-command_007d-396"></a>Find the previous translated entry (<code>po-previous-translated-entry</code>). + + </dl> + + <p><a name="index-t_0040r_007b_002c-PO-Mode-command_007d-397"></a><a name="index-po_002dnext_002dtranslated_002dentry_0040r_007b_002c-PO-Mode-command_007d-398"></a><a name="index-T_0040r_007b_002c-PO-Mode-command_007d-399"></a><a name="index-po_002dprevious_002dtranslated_002dentry_0040r_007b_002c-PO-Mode-command_007d-400"></a>The commands <kbd>t</kbd> (<code>po-next-translated-entry</code>) and <kbd>T</kbd> +(<code>po-previous-translated-entry</code>) move forwards or backwards, chasing +for an translated entry. If none is found, the search is extended and +wraps around in the PO file buffer. + + <p><a name="index-po_002dauto_002dfuzzy_002don_002dedit_0040r_007b_002c-PO-Mode-variable_007d-401"></a>Translated entries usually result from the translator having edited in +a translation for them, <a href="#Modifying-Translations">Modifying Translations</a>. However, if the +variable <code>po-auto-fuzzy-on-edit</code> is not <code>nil</code>, the entry having +received a new translation first becomes a fuzzy entry, which ought to +be later unfuzzied before becoming an official, genuine translated entry. +See <a href="#Fuzzy-Entries">Fuzzy Entries</a>. + +<div class="node"> +<a name="Fuzzy-Entries"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Untranslated-Entries">Untranslated Entries</a>, +Previous: <a rel="previous" accesskey="p" href="#Translated-Entries">Translated Entries</a>, +Up: <a rel="up" accesskey="u" href="#PO-Mode">PO Mode</a> + +</div> + +<h4 class="subsection">8.3.6 Fuzzy Entries</h4> + + <p><a name="index-fuzzy-entries-402"></a> +<a name="index-attributes-of-a-PO-file-entry-403"></a><a name="index-attribute_002c-fuzzy-404"></a>Each PO file entry may have a set of <dfn>attributes</dfn>, which are +qualities given a name and explicitly associated with the translation, +using a special system comment. One of these attributes +has the name <code>fuzzy</code>, and entries having this attribute are said +to have a fuzzy translation. They are called fuzzy entries, for short. + + <p>Fuzzy entries, even if they account for translated entries for +most other purposes, usually call for revision by the translator. +Those may be produced by applying the program <code>msgmerge</code> to +update an older translated PO files according to a new PO template +file, when this tool hypothesises that some new <code>msgid</code> has +been modified only slightly out of an older one, and chooses to pair +what it thinks to be the old translation for the new modified entry. +The slight alteration in the original string (the <code>msgid</code> string) +should often be reflected in the translated string, and this requires +the intervention of the translator. For this reason, <code>msgmerge</code> +might mark some entries as being fuzzy. + + <p><a name="index-moving-by-fuzzy-entries-405"></a>Also, the translator may decide herself to mark an entry as fuzzy +for her own convenience, when she wants to remember that the entry +has to be later revisited. So, some commands are more specifically +related to fuzzy entry processing. + + <dl> +<dt><kbd>f</kbd><dd><a name="index-f_0040r_007b_002c-PO-Mode-command_007d-406"></a><!-- better append "-entry" all the time. -ke- --> +Find the next fuzzy entry (<code>po-next-fuzzy-entry</code>). + + <br><dt><kbd>F</kbd><dd><a name="index-F_0040r_007b_002c-PO-Mode-command_007d-407"></a>Find the previous fuzzy entry (<code>po-previous-fuzzy-entry</code>). + + <br><dt><kbd><TAB></kbd><dd><a name="index-TAB_0040r_007b_002c-PO-Mode-command_007d-408"></a>Remove the fuzzy attribute of the current entry (<code>po-unfuzzy</code>). + + </dl> + + <p><a name="index-f_0040r_007b_002c-PO-Mode-command_007d-409"></a><a name="index-po_002dnext_002dfuzzy_002dentry_0040r_007b_002c-PO-Mode-command_007d-410"></a><a name="index-F_0040r_007b_002c-PO-Mode-command_007d-411"></a><a name="index-po_002dprevious_002dfuzzy_002dentry_0040r_007b_002c-PO-Mode-command_007d-412"></a>The commands <kbd>f</kbd> (<code>po-next-fuzzy-entry</code>) and <kbd>F</kbd> +(<code>po-previous-fuzzy-entry</code>) move forwards or backwards, chasing for +a fuzzy entry. If none is found, the search is extended and wraps +around in the PO file buffer. + + <p><a name="index-TAB_0040r_007b_002c-PO-Mode-command_007d-413"></a><a name="index-po_002dunfuzzy_0040r_007b_002c-PO-Mode-command_007d-414"></a><a name="index-po_002dauto_002dselect_002don_002dunfuzzy_0040r_007b_002c-PO-Mode-variable_007d-415"></a>The command <kbd><TAB></kbd> (<code>po-unfuzzy</code>) removes the fuzzy +attribute associated with an entry, usually leaving it translated. +Further, if the variable <code>po-auto-select-on-unfuzzy</code> has not +the <code>nil</code> value, the <kbd><TAB></kbd> command will automatically chase +for another interesting entry to work on. The initial value of +<code>po-auto-select-on-unfuzzy</code> is <code>nil</code>. + + <p>The initial value of <code>po-auto-fuzzy-on-edit</code> is <code>nil</code>. However, +if the variable <code>po-auto-fuzzy-on-edit</code> is set to <code>t</code>, any entry +edited through the <kbd><RET></kbd> command is marked fuzzy, as a way to +ensure some kind of double check, later. In this case, the usual paradigm +is that an entry becomes fuzzy (if not already) whenever the translator +modifies it. If she is satisfied with the translation, she then uses +<kbd><TAB></kbd> to pick another entry to work on, clearing the fuzzy attribute +on the same blow. If she is not satisfied yet, she merely uses <kbd><SPC></kbd> +to chase another entry, leaving the entry fuzzy. + + <p><a name="index-DEL_0040r_007b_002c-PO-Mode-command_007d-416"></a><a name="index-po_002dfade_002dout_002dentry_0040r_007b_002c-PO-Mode-command_007d-417"></a>The translator may also use the <kbd><DEL></kbd> command +(<code>po-fade-out-entry</code>) over any translated entry to mark it as being +fuzzy, when she wants to easily leave a trace she wants to later return +working at this entry. + + <p>Also, when time comes to quit working on a PO file buffer with the <kbd>q</kbd> +command, the translator is asked for confirmation, if fuzzy string +still exists. + +<div class="node"> +<a name="Untranslated-Entries"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Obsolete-Entries">Obsolete Entries</a>, +Previous: <a rel="previous" accesskey="p" href="#Fuzzy-Entries">Fuzzy Entries</a>, +Up: <a rel="up" accesskey="u" href="#PO-Mode">PO Mode</a> + +</div> + +<h4 class="subsection">8.3.7 Untranslated Entries</h4> + + <p><a name="index-untranslated-entries-418"></a> +When <code>xgettext</code> originally creates a PO file, unless told +otherwise, it initializes the <code>msgid</code> field with the untranslated +string, and leaves the <code>msgstr</code> string to be empty. Such entries, +having an empty translation, are said to be <dfn>untranslated</dfn> entries. +Later, when the programmer slightly modifies some string right in +the program, this change is later reflected in the PO file +by the appearance of a new untranslated entry for the modified string. + + <p>The usual commands moving from entry to entry consider untranslated +entries on the same level as active entries. Untranslated entries +are easily recognizable by the fact they end with ‘<samp><span class="samp">msgstr ""</span></samp>’<!-- /@w -->. + + <p><a name="index-moving-by-untranslated-entries-419"></a>The work of the translator might be (quite naively) seen as the process +of seeking for an untranslated entry, editing a translation for +it, and repeating these actions until no untranslated entries remain. +Some commands are more specifically related to untranslated entry +processing. + + <dl> +<dt><kbd>u</kbd><dd><a name="index-u_0040r_007b_002c-PO-Mode-command_007d-420"></a>Find the next untranslated entry (<code>po-next-untranslated-entry</code>). + + <br><dt><kbd>U</kbd><dd><a name="index-U_0040r_007b_002c-PO-Mode-command_007d-421"></a>Find the previous untranslated entry (<code>po-previous-untransted-entry</code>). + + <br><dt><kbd>k</kbd><dd><a name="index-k_0040r_007b_002c-PO-Mode-command_007d-422"></a>Turn the current entry into an untranslated one (<code>po-kill-msgstr</code>). + + </dl> + + <p><a name="index-u_0040r_007b_002c-PO-Mode-command_007d-423"></a><a name="index-po_002dnext_002duntranslated_002dentry_0040r_007b_002c-PO-Mode-command_007d-424"></a><a name="index-U_0040r_007b_002c-PO-Mode-command_007d-425"></a><a name="index-po_002dprevious_002duntransted_002dentry_0040r_007b_002c-PO-Mode-command_007d-426"></a>The commands <kbd>u</kbd> (<code>po-next-untranslated-entry</code>) and <kbd>U</kbd> +(<code>po-previous-untransted-entry</code>) move forwards or backwards, +chasing for an untranslated entry. If none is found, the search is +extended and wraps around in the PO file buffer. + + <p><a name="index-k_0040r_007b_002c-PO-Mode-command_007d-427"></a><a name="index-po_002dkill_002dmsgstr_0040r_007b_002c-PO-Mode-command_007d-428"></a>An entry can be turned back into an untranslated entry by +merely emptying its translation, using the command <kbd>k</kbd> +(<code>po-kill-msgstr</code>). See <a href="#Modifying-Translations">Modifying Translations</a>. + + <p>Also, when time comes to quit working on a PO file buffer +with the <kbd>q</kbd> command, the translator is asked for confirmation, +if some untranslated string still exists. + +<div class="node"> +<a name="Obsolete-Entries"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Modifying-Translations">Modifying Translations</a>, +Previous: <a rel="previous" accesskey="p" href="#Untranslated-Entries">Untranslated Entries</a>, +Up: <a rel="up" accesskey="u" href="#PO-Mode">PO Mode</a> + +</div> + +<h4 class="subsection">8.3.8 Obsolete Entries</h4> + + <p><a name="index-obsolete-entries-429"></a> +By <dfn>obsolete</dfn> PO file entries, we mean those entries which are +commented out, usually by <code>msgmerge</code> when it found that the +translation is not needed anymore by the package being localized. + + <p>The usual commands moving from entry to entry consider obsolete +entries on the same level as active entries. Obsolete entries are +easily recognizable by the fact that all their lines start with +<code>#</code>, even those lines containing <code>msgid</code> or <code>msgstr</code>. + + <p>Commands exist for emptying the translation or reinitializing it +to the original untranslated string. Commands interfacing with the +kill ring may force some previously saved text into the translation. +The user may interactively edit the translation. All these commands +may apply to obsolete entries, carefully leaving the entry obsolete +after the fact. + + <p><a name="index-moving-by-obsolete-entries-430"></a>Moreover, some commands are more specifically related to obsolete +entry processing. + + <dl> +<dt><kbd>o</kbd><dd><a name="index-o_0040r_007b_002c-PO-Mode-command_007d-431"></a>Find the next obsolete entry (<code>po-next-obsolete-entry</code>). + + <br><dt><kbd>O</kbd><dd><a name="index-O_0040r_007b_002c-PO-Mode-command_007d-432"></a>Find the previous obsolete entry (<code>po-previous-obsolete-entry</code>). + + <br><dt><kbd><DEL></kbd><dd><a name="index-DEL_0040r_007b_002c-PO-Mode-command_007d-433"></a>Make an active entry obsolete, or zap out an obsolete entry +(<code>po-fade-out-entry</code>). + + </dl> + + <p><a name="index-o_0040r_007b_002c-PO-Mode-command_007d-434"></a><a name="index-po_002dnext_002dobsolete_002dentry_0040r_007b_002c-PO-Mode-command_007d-435"></a><a name="index-O_0040r_007b_002c-PO-Mode-command_007d-436"></a><a name="index-po_002dprevious_002dobsolete_002dentry_0040r_007b_002c-PO-Mode-command_007d-437"></a>The commands <kbd>o</kbd> (<code>po-next-obsolete-entry</code>) and <kbd>O</kbd> +(<code>po-previous-obsolete-entry</code>) move forwards or backwards, +chasing for an obsolete entry. If none is found, the search is +extended and wraps around in the PO file buffer. + + <p>PO mode does not provide ways for un-commenting an obsolete entry +and making it active, because this would reintroduce an original +untranslated string which does not correspond to any marked string +in the program sources. This goes with the philosophy of never +introducing useless <code>msgid</code> values. + + <p><a name="index-DEL_0040r_007b_002c-PO-Mode-command_007d-438"></a><a name="index-po_002dfade_002dout_002dentry_0040r_007b_002c-PO-Mode-command_007d-439"></a><a name="index-obsolete-active-entry-440"></a><a name="index-comment-out-PO-file-entry-441"></a>However, it is possible to comment out an active entry, so making +it obsolete. GNU <code>gettext</code> utilities will later react to the +disappearance of a translation by using the untranslated string. +The command <kbd><DEL></kbd> (<code>po-fade-out-entry</code>) pushes the current entry +a little further towards annihilation. If the entry is active (it is a +translated entry), then it is first made fuzzy. If it is already fuzzy, +then the entry is merely commented out, with confirmation. If the entry +is already obsolete, then it is completely deleted from the PO file. +It is easy to recycle the translation so deleted into some other PO file +entry, usually one which is untranslated. See <a href="#Modifying-Translations">Modifying Translations</a>. + + <p>Here is a quite interesting problem to solve for later development of +PO mode, for those nights you are not sleepy. The idea would be that +PO mode might become bright enough, one of these days, to make good +guesses at retrieving the most probable candidate, among all obsolete +entries, for initializing the translation of a newly appeared string. +I think it might be a quite hard problem to do this algorithmically, as +we have to develop good and efficient measures of string similarity. +Right now, PO mode completely lets the decision to the translator, +when the time comes to find the adequate obsolete translation, it +merely tries to provide handy tools for helping her to do so. + +<div class="node"> +<a name="Modifying-Translations"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Modifying-Comments">Modifying Comments</a>, +Previous: <a rel="previous" accesskey="p" href="#Obsolete-Entries">Obsolete Entries</a>, +Up: <a rel="up" accesskey="u" href="#PO-Mode">PO Mode</a> + +</div> + +<h4 class="subsection">8.3.9 Modifying Translations</h4> + + <p><a name="index-editing-translations-442"></a><a name="index-editing-translations-443"></a> +PO mode prevents direct modification of the PO file, by the usual +means Emacs gives for altering a buffer's contents. By doing so, +it pretends helping the translator to avoid little clerical errors +about the overall file format, or the proper quoting of strings, +as those errors would be easily made. Other kinds of errors are +still possible, but some may be caught and diagnosed by the batch +validation process, which the translator may always trigger by the +<kbd>V</kbd> command. For all other errors, the translator has to rely on +her own judgment, and also on the linguistic reports submitted to her +by the users of the translated package, having the same mother tongue. + + <p>When the time comes to create a translation, correct an error diagnosed +mechanically or reported by a user, the translators have to resort to +using the following commands for modifying the translations. + + <dl> +<dt><kbd><RET></kbd><dd><a name="index-RET_0040r_007b_002c-PO-Mode-command_007d-444"></a>Interactively edit the translation (<code>po-edit-msgstr</code>). + + <br><dt><kbd><LFD></kbd><dt><kbd>C-j</kbd><dd><a name="index-LFD_0040r_007b_002c-PO-Mode-command_007d-445"></a><a name="index-C_002dj_0040r_007b_002c-PO-Mode-command_007d-446"></a>Reinitialize the translation with the original, untranslated string +(<code>po-msgid-to-msgstr</code>). + + <br><dt><kbd>k</kbd><dd><a name="index-k_0040r_007b_002c-PO-Mode-command_007d-447"></a>Save the translation on the kill ring, and delete it (<code>po-kill-msgstr</code>). + + <br><dt><kbd>w</kbd><dd><a name="index-w_0040r_007b_002c-PO-Mode-command_007d-448"></a>Save the translation on the kill ring, without deleting it +(<code>po-kill-ring-save-msgstr</code>). + + <br><dt><kbd>y</kbd><dd><a name="index-y_0040r_007b_002c-PO-Mode-command_007d-449"></a>Replace the translation, taking the new from the kill ring +(<code>po-yank-msgstr</code>). + + </dl> + + <p><a name="index-RET_0040r_007b_002c-PO-Mode-command_007d-450"></a><a name="index-po_002dedit_002dmsgstr_0040r_007b_002c-PO-Mode-command_007d-451"></a>The command <kbd><RET></kbd> (<code>po-edit-msgstr</code>) opens a new Emacs +window meant to edit in a new translation, or to modify an already existing +translation. The new window contains a copy of the translation taken from +the current PO file entry, all ready for edition, expunged of all quoting +marks, fully modifiable and with the complete extent of Emacs modifying +commands. When the translator is done with her modifications, she may use +<kbd>C-c C-c</kbd><!-- /@w --> to close the subedit window with the automatically requoted +results, or <kbd>C-c C-k</kbd><!-- /@w --> to abort her modifications. See <a href="#Subedit">Subedit</a>, +for more information. + + <p><a name="index-LFD_0040r_007b_002c-PO-Mode-command_007d-452"></a><a name="index-C_002dj_0040r_007b_002c-PO-Mode-command_007d-453"></a><a name="index-po_002dmsgid_002dto_002dmsgstr_0040r_007b_002c-PO-Mode-command_007d-454"></a>The command <kbd><LFD></kbd> (<code>po-msgid-to-msgstr</code>) initializes, or +reinitializes the translation with the original string. This command is +normally used when the translator wants to redo a fresh translation of +the original string, disregarding any previous work. + + <p><a name="index-po_002dauto_002dedit_002dwith_002dmsgid_0040r_007b_002c-PO-Mode-variable_007d-455"></a>It is possible to arrange so, whenever editing an untranslated +entry, the <kbd><LFD></kbd> command be automatically executed. If you set +<code>po-auto-edit-with-msgid</code> to <code>t</code>, the translation gets +initialised with the original string, in case none exists already. +The default value for <code>po-auto-edit-with-msgid</code> is <code>nil</code>. + + <p><a name="index-starting-a-string-translation-456"></a>In fact, whether it is best to start a translation with an empty +string, or rather with a copy of the original string, is a matter of +taste or habit. Sometimes, the source language and the +target language are so different that is simply best to start writing +on an empty page. At other times, the source and target languages +are so close that it would be a waste to retype a number of words +already being written in the original string. A translator may also +like having the original string right under her eyes, as she will +progressively overwrite the original text with the translation, even +if this requires some extra editing work to get rid of the original. + + <p><a name="index-cut-and-paste-for-translated-strings-457"></a><a name="index-k_0040r_007b_002c-PO-Mode-command_007d-458"></a><a name="index-po_002dkill_002dmsgstr_0040r_007b_002c-PO-Mode-command_007d-459"></a><a name="index-w_0040r_007b_002c-PO-Mode-command_007d-460"></a><a name="index-po_002dkill_002dring_002dsave_002dmsgstr_0040r_007b_002c-PO-Mode-command_007d-461"></a>The command <kbd>k</kbd> (<code>po-kill-msgstr</code>) merely empties the +translation string, so turning the entry into an untranslated +one. But while doing so, its previous contents is put apart in +a special place, known as the kill ring. The command <kbd>w</kbd> +(<code>po-kill-ring-save-msgstr</code>) has also the effect of taking a +copy of the translation onto the kill ring, but it otherwise leaves +the entry alone, and does <em>not</em> remove the translation from the +entry. Both commands use exactly the Emacs kill ring, which is shared +between buffers, and which is well known already to Emacs lovers. + + <p>The translator may use <kbd>k</kbd> or <kbd>w</kbd> many times in the course +of her work, as the kill ring may hold several saved translations. +From the kill ring, strings may later be reinserted in various +Emacs buffers. In particular, the kill ring may be used for moving +translation strings between different entries of a single PO file +buffer, or if the translator is handling many such buffers at once, +even between PO files. + + <p>To facilitate exchanges with buffers which are not in PO mode, the +translation string put on the kill ring by the <kbd>k</kbd> command is fully +unquoted before being saved: external quotes are removed, multi-line +strings are concatenated, and backslash escaped sequences are turned +into their corresponding characters. In the special case of obsolete +entries, the translation is also uncommented prior to saving. + + <p><a name="index-y_0040r_007b_002c-PO-Mode-command_007d-462"></a><a name="index-po_002dyank_002dmsgstr_0040r_007b_002c-PO-Mode-command_007d-463"></a>The command <kbd>y</kbd> (<code>po-yank-msgstr</code>) completely replaces the +translation of the current entry by a string taken from the kill ring. +Following Emacs terminology, we then say that the replacement +string is <dfn>yanked</dfn> into the PO file buffer. +See <a href="emacs.html#Yanking">Yanking</a>. +The first time <kbd>y</kbd> is used, the translation receives the value of +the most recent addition to the kill ring. If <kbd>y</kbd> is typed once +again, immediately, without intervening keystrokes, the translation +just inserted is taken away and replaced by the second most recent +addition to the kill ring. By repeating <kbd>y</kbd> many times in a row, +the translator may travel along the kill ring for saved strings, +until she finds the string she really wanted. + + <p>When a string is yanked into a PO file entry, it is fully and +automatically requoted for complying with the format PO files should +have. Further, if the entry is obsolete, PO mode then appropriately +push the inserted string inside comments. Once again, translators +should not burden themselves with quoting considerations besides, of +course, the necessity of the translated string itself respective to +the program using it. + + <p>Note that <kbd>k</kbd> or <kbd>w</kbd> are not the only commands pushing strings +on the kill ring, as almost any PO mode command replacing translation +strings (or the translator comments) automatically saves the old string +on the kill ring. The main exceptions to this general rule are the +yanking commands themselves. + + <p><a name="index-using-obsolete-translations-to-make-new-entries-464"></a>To better illustrate the operation of killing and yanking, let's +use an actual example, taken from a common situation. When the +programmer slightly modifies some string right in the program, his +change is later reflected in the PO file by the appearance +of a new untranslated entry for the modified string, and the fact +that the entry translating the original or unmodified string becomes +obsolete. In many cases, the translator might spare herself some work +by retrieving the unmodified translation from the obsolete entry, +then initializing the untranslated entry <code>msgstr</code> field with +this retrieved translation. Once this done, the obsolete entry is +not wanted anymore, and may be safely deleted. + + <p>When the translator finds an untranslated entry and suspects that a +slight variant of the translation exists, she immediately uses <kbd>m</kbd> +to mark the current entry location, then starts chasing obsolete +entries with <kbd>o</kbd>, hoping to find some translation corresponding +to the unmodified string. Once found, she uses the <kbd><DEL></kbd> command +for deleting the obsolete entry, knowing that <kbd><DEL></kbd> also <em>kills</em> +the translation, that is, pushes the translation on the kill ring. +Then, <kbd>r</kbd> returns to the initial untranslated entry, and <kbd>y</kbd> +then <em>yanks</em> the saved translation right into the <code>msgstr</code> +field. The translator is then free to use <kbd><RET></kbd> for fine +tuning the translation contents, and maybe to later use <kbd>u</kbd>, +then <kbd>m</kbd> again, for going on with the next untranslated string. + + <p>When some sequence of keys has to be typed over and over again, the +translator may find it useful to become better acquainted with the Emacs +capability of learning these sequences and playing them back under request. +See <a href="emacs.html#Keyboard-Macros">Keyboard Macros</a>. + +<div class="node"> +<a name="Modifying-Comments"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Subedit">Subedit</a>, +Previous: <a rel="previous" accesskey="p" href="#Modifying-Translations">Modifying Translations</a>, +Up: <a rel="up" accesskey="u" href="#PO-Mode">PO Mode</a> + +</div> + +<h4 class="subsection">8.3.10 Modifying Comments</h4> + + <p><a name="index-editing-comments-in-PO-files-465"></a><a name="index-editing-comments-466"></a> +Any translation work done seriously will raise many linguistic +difficulties, for which decisions have to be made, and the choices +further documented. These documents may be saved within the +PO file in form of translator comments, which the translator +is free to create, delete, or modify at will. These comments may +be useful to herself when she returns to this PO file after a while. + + <p>Comments not having whitespace after the initial ‘<samp><span class="samp">#</span></samp>’, for example, +those beginning with ‘<samp><span class="samp">#.</span></samp>’ or ‘<samp><span class="samp">#:</span></samp>’, are <em>not</em> translator +comments, they are exclusively created by other <code>gettext</code> tools. +So, the commands below will never alter such system added comments, +they are not meant for the translator to modify. See <a href="#PO-Files">PO Files</a>. + + <p>The following commands are somewhat similar to those modifying translations, +so the general indications given for those apply here. See <a href="#Modifying-Translations">Modifying Translations</a>. + + <dl> +<dt><kbd>#</kbd><dd><a name="index-g_t_0023_0040r_007b_002c-PO-Mode-command_007d-467"></a>Interactively edit the translator comments (<code>po-edit-comment</code>). + + <br><dt><kbd>K</kbd><dd><a name="index-K_0040r_007b_002c-PO-Mode-command_007d-468"></a>Save the translator comments on the kill ring, and delete it +(<code>po-kill-comment</code>). + + <br><dt><kbd>W</kbd><dd><a name="index-W_0040r_007b_002c-PO-Mode-command_007d-469"></a>Save the translator comments on the kill ring, without deleting it +(<code>po-kill-ring-save-comment</code>). + + <br><dt><kbd>Y</kbd><dd><a name="index-Y_0040r_007b_002c-PO-Mode-command_007d-470"></a>Replace the translator comments, taking the new from the kill ring +(<code>po-yank-comment</code>). + + </dl> + + <p>These commands parallel PO mode commands for modifying the translation +strings, and behave much the same way as they do, except that they handle +this part of PO file comments meant for translator usage, rather +than the translation strings. So, if the descriptions given below are +slightly succinct, it is because the full details have already been given. +See <a href="#Modifying-Translations">Modifying Translations</a>. + + <p><a name="index-g_t_0023_0040r_007b_002c-PO-Mode-command_007d-471"></a><a name="index-po_002dedit_002dcomment_0040r_007b_002c-PO-Mode-command_007d-472"></a>The command <kbd>#</kbd> (<code>po-edit-comment</code>) opens a new Emacs window +containing a copy of the translator comments on the current PO file entry. +If there are no such comments, PO mode understands that the translator wants +to add a comment to the entry, and she is presented with an empty screen. +Comment marks (<code>#</code>) and the space following them are automatically +removed before edition, and reinstated after. For translator comments +pertaining to obsolete entries, the uncommenting and recommenting operations +are done twice. Once in the editing window, the keys <kbd>C-c C-c</kbd><!-- /@w --> +allow the translator to tell she is finished with editing the comment. +See <a href="#Subedit">Subedit</a>, for further details. + + <p><a name="index-po_002dsubedit_002dmode_002dhook_0040r_007b_002c-PO-Mode-variable_007d-473"></a>Functions found on <code>po-subedit-mode-hook</code>, if any, are executed after +the string has been inserted in the edit buffer. + + <p><a name="index-K_0040r_007b_002c-PO-Mode-command_007d-474"></a><a name="index-po_002dkill_002dcomment_0040r_007b_002c-PO-Mode-command_007d-475"></a><a name="index-W_0040r_007b_002c-PO-Mode-command_007d-476"></a><a name="index-po_002dkill_002dring_002dsave_002dcomment_0040r_007b_002c-PO-Mode-command_007d-477"></a><a name="index-Y_0040r_007b_002c-PO-Mode-command_007d-478"></a><a name="index-po_002dyank_002dcomment_0040r_007b_002c-PO-Mode-command_007d-479"></a>The command <kbd>K</kbd> (<code>po-kill-comment</code>) gets rid of all +translator comments, while saving those comments on the kill ring. +The command <kbd>W</kbd> (<code>po-kill-ring-save-comment</code>) takes +a copy of the translator comments on the kill ring, but leaves +them undisturbed in the current entry. The command <kbd>Y</kbd> +(<code>po-yank-comment</code>) completely replaces the translator comments +by a string taken at the front of the kill ring. When this command +is immediately repeated, the comments just inserted are withdrawn, +and replaced by other strings taken along the kill ring. + + <p>On the kill ring, all strings have the same nature. There is no +distinction between <em>translation</em> strings and <em>translator +comments</em> strings. So, for example, let's presume the translator +has just finished editing a translation, and wants to create a new +translator comment to document why the previous translation was +not good, just to remember what was the problem. Foreseeing that she +will do that in her documentation, the translator may want to quote +the previous translation in her translator comments. To do so, she +may initialize the translator comments with the previous translation, +still at the head of the kill ring. Because editing already pushed the +previous translation on the kill ring, she merely has to type <kbd>M-w</kbd> +prior to <kbd>#</kbd>, and the previous translation will be right there, +all ready for being introduced by some explanatory text. + + <p>On the other hand, presume there are some translator comments already +and that the translator wants to add to those comments, instead +of wholly replacing them. Then, she should edit the comment right +away with <kbd>#</kbd>. Once inside the editing window, she can use the +regular Emacs commands <kbd>C-y</kbd> (<code>yank</code>) and <kbd>M-y</kbd> +(<code>yank-pop</code>) to get the previous translation where she likes. + +<div class="node"> +<a name="Subedit"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#C-Sources-Context">C Sources Context</a>, +Previous: <a rel="previous" accesskey="p" href="#Modifying-Comments">Modifying Comments</a>, +Up: <a rel="up" accesskey="u" href="#PO-Mode">PO Mode</a> + +</div> + +<h4 class="subsection">8.3.11 Details of Sub Edition</h4> + + <p><a name="index-subedit-minor-mode-480"></a> +The PO subedit minor mode has a few peculiarities worth being described +in fuller detail. It installs a few commands over the usual editing set +of Emacs, which are described below. + + <dl> +<dt><kbd>C-c C-c</kbd><dd><a name="index-C_002dc-C_002dc_0040r_007b_002c-PO-Mode-command_007d-481"></a>Complete edition (<code>po-subedit-exit</code>). + + <br><dt><kbd>C-c C-k</kbd><dd><a name="index-C_002dc-C_002dk_0040r_007b_002c-PO-Mode-command_007d-482"></a>Abort edition (<code>po-subedit-abort</code>). + + <br><dt><kbd>C-c C-a</kbd><dd><a name="index-C_002dc-C_002da_0040r_007b_002c-PO-Mode-command_007d-483"></a>Consult auxiliary PO files (<code>po-subedit-cycle-auxiliary</code>). + + </dl> + + <p><a name="index-exiting-PO-subedit-484"></a><a name="index-C_002dc-C_002dc_0040r_007b_002c-PO-Mode-command_007d-485"></a><a name="index-po_002dsubedit_002dexit_0040r_007b_002c-PO-Mode-command_007d-486"></a>The window's contents represents a translation for a given message, +or a translator comment. The translator may modify this window to +her heart's content. Once this is done, the command <kbd>C-c C-c</kbd><!-- /@w --> +(<code>po-subedit-exit</code>) may be used to return the edited translation into +the PO file, replacing the original translation, even if it moved out of +sight or if buffers were switched. + + <p><a name="index-C_002dc-C_002dk_0040r_007b_002c-PO-Mode-command_007d-487"></a><a name="index-po_002dsubedit_002dabort_0040r_007b_002c-PO-Mode-command_007d-488"></a>If the translator becomes unsatisfied with her translation or comment, +to the extent she prefers keeping what was existent prior to the +<kbd><RET></kbd> or <kbd>#</kbd> command, she may use the command <kbd>C-c C-k</kbd><!-- /@w --> +(<code>po-subedit-abort</code>) to merely get rid of edition, while preserving +the original translation or comment. Another way would be for her to exit +normally with <kbd>C-c C-c</kbd><!-- /@w -->, then type <code>U</code> once for undoing the +whole effect of last edition. + + <p><a name="index-C_002dc-C_002da_0040r_007b_002c-PO-Mode-command_007d-489"></a><a name="index-po_002dsubedit_002dcycle_002dauxiliary_0040r_007b_002c-PO-Mode-command_007d-490"></a>The command <kbd>C-c C-a</kbd><!-- /@w --> (<code>po-subedit-cycle-auxiliary</code>) +allows for glancing through translations +already achieved in other languages, directly while editing the current +translation. This may be quite convenient when the translator is fluent +at many languages, but of course, only makes sense when such completed +auxiliary PO files are already available to her (see <a href="#Auxiliary">Auxiliary</a>). + + <p>Functions found on <code>po-subedit-mode-hook</code>, if any, are executed after +the string has been inserted in the edit buffer. + + <p>While editing her translation, the translator should pay attention to not +inserting unwanted <kbd><RET></kbd> (newline) characters at the end of +the translated string if those are not meant to be there, or to removing +such characters when they are required. Since these characters are not +visible in the editing buffer, they are easily introduced by mistake. +To help her, <kbd><RET></kbd> automatically puts the character <code><</code> +at the end of the string being edited, but this <code><</code> is not really +part of the string. On exiting the editing window with <kbd>C-c C-c</kbd><!-- /@w -->, +PO mode automatically removes such <kbd><</kbd> and all whitespace added after +it. If the translator adds characters after the terminating <code><</code>, it +looses its delimiting property and integrally becomes part of the string. +If she removes the delimiting <code><</code>, then the edited string is taken +<em>as is</em>, with all trailing newlines, even if invisible. Also, if +the translated string ought to end itself with a genuine <code><</code>, then +the delimiting <code><</code> may not be removed; so the string should appear, +in the editing window, as ending with two <code><</code> in a row. + + <p><a name="index-editing-multiple-entries-491"></a>When a translation (or a comment) is being edited, the translator may move +the cursor back into the PO file buffer and freely move to other entries, +browsing at will. If, with an edition pending, the translator wanders in the +PO file buffer, she may decide to start modifying another entry. Each entry +being edited has its own subedit buffer. It is possible to simultaneously +edit the translation <em>and</em> the comment of a single entry, or to +edit entries in different PO files, all at once. Typing <kbd><RET></kbd> +on a field already being edited merely resumes that particular edit. Yet, +the translator should better be comfortable at handling many Emacs windows! + + <p><a name="index-pending-subedits-492"></a>Pending subedits may be completed or aborted in any order, regardless +of how or when they were started. When many subedits are pending and the +translator asks for quitting the PO file (with the <kbd>q</kbd> command), subedits +are automatically resumed one at a time, so she may decide for each of them. + +<div class="node"> +<a name="C-Sources-Context"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Auxiliary">Auxiliary</a>, +Previous: <a rel="previous" accesskey="p" href="#Subedit">Subedit</a>, +Up: <a rel="up" accesskey="u" href="#PO-Mode">PO Mode</a> + +</div> + +<h4 class="subsection">8.3.12 C Sources Context</h4> + + <p><a name="index-consulting-program-sources-493"></a><a name="index-looking-at-the-source-to-aid-translation-494"></a><a name="index-use-the-source_002c-Luke-495"></a> +PO mode is particularly powerful when used with PO files +created through GNU <code>gettext</code> utilities, as those utilities +insert special comments in the PO files they generate. +Some of these special comments relate the PO file entry to +exactly where the untranslated string appears in the program sources. + + <p>When the translator gets to an untranslated entry, she is fairly +often faced with an original string which is not as informative as +it normally should be, being succinct, cryptic, or otherwise ambiguous. +Before choosing how to translate the string, she needs to understand +better what the string really means and how tight the translation has +to be. Most of the time, when problems arise, the only way left to make +her judgment is looking at the true program sources from where this +string originated, searching for surrounding comments the programmer +might have put in there, and looking around for helping clues of +<em>any</em> kind. + + <p>Surely, when looking at program sources, the translator will receive +more help if she is a fluent programmer. However, even if she is +not versed in programming and feels a little lost in C code, the +translator should not be shy at taking a look, once in a while. +It is most probable that she will still be able to find some of the +hints she needs. She will learn quickly to not feel uncomfortable +in program code, paying more attention to programmer's comments, +variable and function names (if he dared choosing them well), and +overall organization, than to the program code itself. + + <p><a name="index-find-source-fragment-for-a-PO-file-entry-496"></a>The following commands are meant to help the translator at getting +program source context for a PO file entry. + + <dl> +<dt><kbd>s</kbd><dd><a name="index-s_0040r_007b_002c-PO-Mode-command_007d-497"></a>Resume the display of a program source context, or cycle through them +(<code>po-cycle-source-reference</code>). + + <br><dt><kbd>M-s</kbd><dd><a name="index-M_002ds_0040r_007b_002c-PO-Mode-command_007d-498"></a>Display of a program source context selected by menu +(<code>po-select-source-reference</code>). + + <br><dt><kbd>S</kbd><dd><a name="index-S_0040r_007b_002c-PO-Mode-command_007d-499"></a>Add a directory to the search path for source files +(<code>po-consider-source-path</code>). + + <br><dt><kbd>M-S</kbd><dd><a name="index-M_002dS_0040r_007b_002c-PO-Mode-command_007d-500"></a>Delete a directory from the search path for source files +(<code>po-ignore-source-path</code>). + + </dl> + + <p><a name="index-s_0040r_007b_002c-PO-Mode-command_007d-501"></a><a name="index-po_002dcycle_002dsource_002dreference_0040r_007b_002c-PO-Mode-command_007d-502"></a><a name="index-M_002ds_0040r_007b_002c-PO-Mode-command_007d-503"></a><a name="index-po_002dselect_002dsource_002dreference_0040r_007b_002c-PO-Mode-command_007d-504"></a>The commands <kbd>s</kbd> (<code>po-cycle-source-reference</code>) and <kbd>M-s</kbd> +(<code>po-select-source-reference</code>) both open another window displaying +some source program file, and already positioned in such a way that +it shows an actual use of the string to be translated. By doing +so, the command gives source program context for the string. But if +the entry has no source context references, or if all references +are unresolved along the search path for program sources, then the +command diagnoses this as an error. + + <p>Even if <kbd>s</kbd> (or <kbd>M-s</kbd>) opens a new window, the cursor stays +in the PO file window. If the translator really wants to +get into the program source window, she ought to do it explicitly, +maybe by using command <kbd>O</kbd>. + + <p>When <kbd>s</kbd> is typed for the first time, or for a PO file entry which +is different of the last one used for getting source context, then the +command reacts by giving the first context available for this entry, +if any. If some context has already been recently displayed for the +current PO file entry, and the translator wandered off to do other +things, typing <kbd>s</kbd> again will merely resume, in another window, +the context last displayed. In particular, if the translator moved +the cursor away from the context in the source file, the command will +bring the cursor back to the context. By using <kbd>s</kbd> many times +in a row, with no other commands intervening, PO mode will cycle to +the next available contexts for this particular entry, getting back +to the first context once the last has been shown. + + <p>The command <kbd>M-s</kbd> behaves differently. Instead of cycling through +references, it lets the translator choose a particular reference among +many, and displays that reference. It is best used with completion, +if the translator types <kbd><TAB></kbd> immediately after <kbd>M-s</kbd>, in +response to the question, she will be offered a menu of all possible +references, as a reminder of which are the acceptable answers. +This command is useful only where there are really many contexts +available for a single string to translate. + + <p><a name="index-S_0040r_007b_002c-PO-Mode-command_007d-505"></a><a name="index-po_002dconsider_002dsource_002dpath_0040r_007b_002c-PO-Mode-command_007d-506"></a><a name="index-M_002dS_0040r_007b_002c-PO-Mode-command_007d-507"></a><a name="index-po_002dignore_002dsource_002dpath_0040r_007b_002c-PO-Mode-command_007d-508"></a>Program source files are usually found relative to where the PO +file stands. As a special provision, when this fails, the file is +also looked for, but relative to the directory immediately above it. +Those two cases take proper care of most PO files. However, it might +happen that a PO file has been moved, or is edited in a different +place than its normal location. When this happens, the translator +should tell PO mode in which directory normally sits the genuine PO +file. Many such directories may be specified, and all together, they +constitute what is called the <dfn>search path</dfn> for program sources. +The command <kbd>S</kbd> (<code>po-consider-source-path</code>) is used to interactively +enter a new directory at the front of the search path, and the command +<kbd>M-S</kbd> (<code>po-ignore-source-path</code>) is used to select, with completion, +one of the directories she does not want anymore on the search path. + +<div class="node"> +<a name="Auxiliary"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#C-Sources-Context">C Sources Context</a>, +Up: <a rel="up" accesskey="u" href="#PO-Mode">PO Mode</a> + +</div> + +<h4 class="subsection">8.3.13 Consulting Auxiliary PO Files</h4> + + <p><a name="index-consulting-translations-to-other-languages-509"></a> +PO mode is able to help the knowledgeable translator, being fluent in +many languages, at taking advantage of translations already achieved +in other languages she just happens to know. It provides these other +language translations as additional context for her own work. Moreover, +it has features to ease the production of translations for many languages +at once, for translators preferring to work in this way. + + <p><a name="index-auxiliary-PO-file-510"></a><a name="index-auxiliary-PO-file-511"></a>An <dfn>auxiliary</dfn> PO file is an existing PO file meant for the same +package the translator is working on, but targeted to a different mother +tongue language. Commands exist for declaring and handling auxiliary +PO files, and also for showing contexts for the entry under work. + + <p>Here are the auxiliary file commands available in PO mode. + + <dl> +<dt><kbd>a</kbd><dd><a name="index-a_0040r_007b_002c-PO-Mode-command_007d-512"></a>Seek auxiliary files for another translation for the same entry +(<code>po-cycle-auxiliary</code>). + + <br><dt><kbd>C-c C-a</kbd><dd><a name="index-C_002dc-C_002da_0040r_007b_002c-PO-Mode-command_007d-513"></a>Switch to a particular auxiliary file (<code>po-select-auxiliary</code>). + + <br><dt><kbd>A</kbd><dd><a name="index-A_0040r_007b_002c-PO-Mode-command_007d-514"></a>Declare this PO file as an auxiliary file (<code>po-consider-as-auxiliary</code>). + + <br><dt><kbd>M-A</kbd><dd><a name="index-M_002dA_0040r_007b_002c-PO-Mode-command_007d-515"></a>Remove this PO file from the list of auxiliary files +(<code>po-ignore-as-auxiliary</code>). + + </dl> + + <p><a name="index-A_0040r_007b_002c-PO-Mode-command_007d-516"></a><a name="index-po_002dconsider_002das_002dauxiliary_0040r_007b_002c-PO-Mode-command_007d-517"></a><a name="index-M_002dA_0040r_007b_002c-PO-Mode-command_007d-518"></a><a name="index-po_002dignore_002das_002dauxiliary_0040r_007b_002c-PO-Mode-command_007d-519"></a>Command <kbd>A</kbd> (<code>po-consider-as-auxiliary</code>) adds the current +PO file to the list of auxiliary files, while command <kbd>M-A</kbd> +(<code>po-ignore-as-auxiliary</code> just removes it. + + <p><a name="index-a_0040r_007b_002c-PO-Mode-command_007d-520"></a><a name="index-po_002dcycle_002dauxiliary_0040r_007b_002c-PO-Mode-command_007d-521"></a>The command <kbd>a</kbd> (<code>po-cycle-auxiliary</code>) seeks all auxiliary PO +files, round-robin, searching for a translated entry in some other language +having an <code>msgid</code> field identical as the one for the current entry. +The found PO file, if any, takes the place of the current PO file in +the display (its window gets on top). Before doing so, the current PO +file is also made into an auxiliary file, if not already. So, <kbd>a</kbd> +in this newly displayed PO file will seek another PO file, and so on, +so repeating <kbd>a</kbd> will eventually yield back the original PO file. + + <p><a name="index-C_002dc-C_002da_0040r_007b_002c-PO-Mode-command_007d-522"></a><a name="index-po_002dselect_002dauxiliary_0040r_007b_002c-PO-Mode-command_007d-523"></a>The command <kbd>C-c C-a</kbd> (<code>po-select-auxiliary</code>) asks the translator +for her choice of a particular auxiliary file, with completion, and +then switches to that selected PO file. The command also checks if +the selected file has an <code>msgid</code> field identical as the one for +the current entry, and if yes, this entry becomes current. Otherwise, +the cursor of the selected file is left undisturbed. + + <p>For all this to work fully, auxiliary PO files will have to be normalized, +in that way that <code>msgid</code> fields should be written <em>exactly</em> +the same way. It is possible to write <code>msgid</code> fields in various +ways for representing the same string, different writing would break the +proper behaviour of the auxiliary file commands of PO mode. This is not +expected to be much a problem in practice, as most existing PO files have +their <code>msgid</code> entries written by the same GNU <code>gettext</code> tools. + + <p><a name="index-normalize_0040r_007b_002c-PO-Mode-command_007d-524"></a>However, PO files initially created by PO mode itself, while marking +strings in source files, are normalised differently. So are PO +files resulting of the ‘<samp><span class="samp">M-x normalize</span></samp>’ command. Until these +discrepancies between PO mode and other GNU <code>gettext</code> tools get +fully resolved, the translator should stay aware of normalisation issues. + +<div class="node"> +<a name="Compendium"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#PO-Mode">PO Mode</a>, +Up: <a rel="up" accesskey="u" href="#Editing">Editing</a> + +</div> + +<h3 class="section">8.4 Using Translation Compendia</h3> + + <p><a name="index-using-translation-compendia-525"></a> +<a name="index-compendium-526"></a>A <dfn>compendium</dfn> is a special PO file containing a set of +translations recurring in many different packages. The translator can +use gettext tools to build a new compendium, to add entries to her +compendium, and to initialize untranslated entries, or to update +already translated entries, from translations kept in the compendium. + +<ul class="menu"> +<li><a accesskey="1" href="#Creating-Compendia">Creating Compendia</a>: Merging translations for later use +<li><a accesskey="2" href="#Using-Compendia">Using Compendia</a>: Using older translations if they fit +</ul> + +<div class="node"> +<a name="Creating-Compendia"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Using-Compendia">Using Compendia</a>, +Previous: <a rel="previous" accesskey="p" href="#Compendium">Compendium</a>, +Up: <a rel="up" accesskey="u" href="#Compendium">Compendium</a> + +</div> + +<h4 class="subsection">8.4.1 Creating Compendia</h4> + + <p><a name="index-creating-compendia-527"></a><a name="index-compendium_002c-creating-528"></a> +Basically every PO file consisting of translated entries only can be +declared as a valid compendium. Often the translator wants to have +special compendia; let's consider two cases: <cite>concatenating PO +files</cite> and <cite>extracting a message subset from a PO file</cite>. + +<h5 class="subsubsection">8.4.1.1 Concatenate PO Files</h5> + + <p><a name="index-concatenating-PO-files-into-a-compendium-529"></a><a name="index-accumulating-translations-530"></a>To concatenate several valid PO files into one compendium file you can +use ‘<samp><span class="samp">msgcomm</span></samp>’ or ‘<samp><span class="samp">msgcat</span></samp>’ (the latter preferred): + +<pre class="example"> msgcat -o compendium.po file1.po file2.po +</pre> + <p>By default, <code>msgcat</code> will accumulate divergent translations +for the same string. Those occurrences will be marked as <code>fuzzy</code> +and highly visible decorated; calling <code>msgcat</code> on +<samp><span class="file">file1.po</span></samp>: + +<pre class="example"> #: src/hello.c:200 + #, c-format + msgid "Report bugs to <%s>.\n" + msgstr "Comunicar `bugs' a <%s>.\n" +</pre> + <p class="noindent">and <samp><span class="file">file2.po</span></samp>: + +<pre class="example"> #: src/bye.c:100 + #, c-format + msgid "Report bugs to <%s>.\n" + msgstr "Comunicar \"bugs\" a <%s>.\n" +</pre> + <p class="noindent">will result in: + +<pre class="example"> #: src/hello.c:200 src/bye.c:100 + #, fuzzy, c-format + msgid "Report bugs to <%s>.\n" + msgstr "" + "#-#-#-#-# file1.po #-#-#-#-#\n" + "Comunicar `bugs' a <%s>.\n" + "#-#-#-#-# file2.po #-#-#-#-#\n" + "Comunicar \"bugs\" a <%s>.\n" +</pre> + <p class="noindent">The translator will have to resolve this “conflict” manually; she +has to decide whether the first or the second version is appropriate +(or provide a new translation), to delete the “marker lines”, and +finally to remove the <code>fuzzy</code> mark. + + <p>If the translator knows in advance the first found translation of a +message is always the best translation she can make use to the +‘<samp><span class="samp">--use-first</span></samp>’ switch: + +<pre class="example"> msgcat --use-first -o compendium.po file1.po file2.po +</pre> + <p>A good compendium file must not contain <code>fuzzy</code> or untranslated +entries. If input files are “dirty” you must preprocess the input +files or postprocess the result using ‘<samp><span class="samp">msgattrib --translated --no-fuzzy</span></samp>’. + +<h5 class="subsubsection">8.4.1.2 Extract a Message Subset from a PO File</h5> + + <p><a name="index-extracting-parts-of-a-PO-file-into-a-compendium-531"></a> +Nobody wants to translate the same messages again and again; thus you +may wish to have a compendium file containing <samp><span class="file">getopt.c</span></samp> messages. + + <p>To extract a message subset (e.g., all <samp><span class="file">getopt.c</span></samp> messages) from an +existing PO file into one compendium file you can use ‘<samp><span class="samp">msggrep</span></samp>’: + +<pre class="example"> msggrep --location src/getopt.c -o compendium.po file.po +</pre> + <div class="node"> +<a name="Using-Compendia"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Creating-Compendia">Creating Compendia</a>, +Up: <a rel="up" accesskey="u" href="#Compendium">Compendium</a> + +</div> + +<h4 class="subsection">8.4.2 Using Compendia</h4> + + <p>You can use a compendium file to initialize a translation from scratch +or to update an already existing translation. + +<h5 class="subsubsection">8.4.2.1 Initialize a New Translation File</h5> + + <p><a name="index-initialize-translations-from-a-compendium-532"></a> +Since a PO file with translations does not exist the translator can +merely use <samp><span class="file">/dev/null</span></samp> to fake the “old” translation file. + +<pre class="example"> msgmerge --compendium compendium.po -o file.po /dev/null file.pot +</pre> + <h5 class="subsubsection">8.4.2.2 Update an Existing Translation File</h5> + + <p><a name="index-update-translations-from-a-compendium-533"></a> +Concatenate the compendium file(s) and the existing PO, merge the +result with the POT file and remove the obsolete entries (optional, +here done using ‘<samp><span class="samp">sed</span></samp>’): + +<pre class="example"> msgcat --use-first -o update.po compendium1.po compendium2.po file.po + msgmerge update.po file.pot | msgattrib --no-obsolete > file.po +</pre> + <div class="node"> +<a name="Manipulating"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Binaries">Binaries</a>, +Previous: <a rel="previous" accesskey="p" href="#Editing">Editing</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">9 Manipulating PO Files</h2> + + <p><a name="index-manipulating-PO-files-534"></a> +Sometimes it is necessary to manipulate PO files in a way that is better +performed automatically than by hand. GNU <code>gettext</code> includes a +complete set of tools for this purpose. + + <p><a name="index-merging-two-PO-files-535"></a>When merging two packages into a single package, the resulting POT file +will be the concatenation of the two packages' POT files. Thus the +maintainer must concatenate the two existing package translations into +a single translation catalog, for each language. This is best performed +using ‘<samp><span class="samp">msgcat</span></samp>’. It is then the translators' duty to deal with any +possible conflicts that arose during the merge. + + <p><a name="index-encoding-conversion-536"></a>When a translator takes over the translation job from another translator, +but she uses a different character encoding in her locale, she will +convert the catalog to her character encoding. This is best done through +the ‘<samp><span class="samp">msgconv</span></samp>’ program. + + <p>When a maintainer takes a source file with tagged messages from another +package, he should also take the existing translations for this source +file (and not let the translators do the same job twice). One way to do +this is through ‘<samp><span class="samp">msggrep</span></samp>’, another is to create a POT file for +that source file and use ‘<samp><span class="samp">msgmerge</span></samp>’. + + <p><a name="index-dialect-537"></a><a name="index-orthography-538"></a>When a translator wants to adjust some translation catalog for a special +dialect or orthography — for example, German as written in Switzerland +versus German as written in Germany — she needs to apply some text +processing to every message in the catalog. The tool for doing this is +‘<samp><span class="samp">msgfilter</span></samp>’. + + <p>Another use of <code>msgfilter</code> is to produce approximately the POT file for +which a given PO file was made. This can be done through a filter command +like ‘<samp><span class="samp">msgfilter sed -e d | sed -e '/^# /d'</span></samp>’. Note that the original +POT file may have had different comments and different plural message counts, +that's why it's better to use the original POT file if available. + + <p><a name="index-checking-of-translations-539"></a>When a translator wants to check her translations, for example according +to orthography rules or using a non-interactive spell checker, she can do +so using the ‘<samp><span class="samp">msgexec</span></samp>’ program. + + <p><a name="index-duplicate-elimination-540"></a>When third party tools create PO or POT files, sometimes duplicates cannot +be avoided. But the GNU <code>gettext</code> tools give an error when they +encounter duplicate msgids in the same file and in the same domain. +To merge duplicates, the ‘<samp><span class="samp">msguniq</span></samp>’ program can be used. + + <p>‘<samp><span class="samp">msgcomm</span></samp>’ is a more general tool for keeping or throwing away +duplicates, occurring in different files. + + <p>‘<samp><span class="samp">msgcmp</span></samp>’ can be used to check whether a translation catalog is +completely translated. + + <p><a name="index-attributes_002c-manipulating-541"></a>‘<samp><span class="samp">msgattrib</span></samp>’ can be used to select and extract only the fuzzy +or untranslated messages of a translation catalog. + + <p>‘<samp><span class="samp">msgen</span></samp>’ is useful as a first step for preparing English translation +catalogs. It copies each message's msgid to its msgstr. + + <p>Finally, for those applications where all these various programs are not +sufficient, a library ‘<samp><span class="samp">libgettextpo</span></samp>’ is provided that can be used to +write other specialized programs that process PO files. + +<ul class="menu"> +<li><a accesskey="1" href="#msgcat-Invocation">msgcat Invocation</a>: Invoking the <code>msgcat</code> Program +<li><a accesskey="2" href="#msgconv-Invocation">msgconv Invocation</a>: Invoking the <code>msgconv</code> Program +<li><a accesskey="3" href="#msggrep-Invocation">msggrep Invocation</a>: Invoking the <code>msggrep</code> Program +<li><a accesskey="4" href="#msgfilter-Invocation">msgfilter Invocation</a>: Invoking the <code>msgfilter</code> Program +<li><a accesskey="5" href="#msguniq-Invocation">msguniq Invocation</a>: Invoking the <code>msguniq</code> Program +<li><a accesskey="6" href="#msgcomm-Invocation">msgcomm Invocation</a>: Invoking the <code>msgcomm</code> Program +<li><a accesskey="7" href="#msgcmp-Invocation">msgcmp Invocation</a>: Invoking the <code>msgcmp</code> Program +<li><a accesskey="8" href="#msgattrib-Invocation">msgattrib Invocation</a>: Invoking the <code>msgattrib</code> Program +<li><a accesskey="9" href="#msgen-Invocation">msgen Invocation</a>: Invoking the <code>msgen</code> Program +<li><a href="#msgexec-Invocation">msgexec Invocation</a>: Invoking the <code>msgexec</code> Program +<li><a href="#Colorizing">Colorizing</a>: Highlighting parts of PO files +<li><a href="#libgettextpo">libgettextpo</a>: Writing your own programs that process PO files +</ul> + +<div class="node"> +<a name="msgcat-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#msgconv-Invocation">msgconv Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#Manipulating">Manipulating</a>, +Up: <a rel="up" accesskey="u" href="#Manipulating">Manipulating</a> + +</div> + +<h3 class="section">9.1 Invoking the <code>msgcat</code> Program</h3> + + <p><a name="index-msgcat-542"></a><a name="index-g_t_0040code_007bmsgcat_007d-program_002c-usage-543"></a> +<pre class="example"> msgcat [<var>option</var>] [<var>inputfile</var>]... +</pre> + <p><a name="index-concatenate-PO-files-544"></a><a name="index-merge-PO-files-545"></a>The <code>msgcat</code> program concatenates and merges the specified PO files. +It finds messages which are common to two or more of the specified PO files. +By using the <code>--more-than</code> option, greater commonality may be requested +before messages are printed. Conversely, the <code>--less-than</code> option may be +used to specify less commonality before messages are printed (i.e. +‘<samp><span class="samp">--less-than=2</span></samp>’ will only print the unique messages). Translations, +comments and extract comments will be cumulated, except that if +<code>--use-first</code> is specified, they will be taken from the first PO file +to define them. File positions from all PO files will be cumulated. + +<h4 class="subsection">9.1.1 Input file location</h4> + + <dl> +<dt>‘<samp><var>inputfile</var><span class="samp"> ...</span></samp>’<dd>Input files. + + <br><dt>‘<samp><span class="samp">-f </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--files-from=</span><var>file</var></samp>’<dd><a name="index-g_t_002df_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-546"></a><a name="index-g_t_002d_002dfiles_002dfrom_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-547"></a>Read the names of the input files from <var>file</var> instead of getting +them from the command line. + + <br><dt>‘<samp><span class="samp">-D </span><var>directory</var></samp>’<dt>‘<samp><span class="samp">--directory=</span><var>directory</var></samp>’<dd><a name="index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-548"></a><a name="index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-549"></a>Add <var>directory</var> to the list of directories. Source files are +searched relative to this list of directories. The resulting <samp><span class="file">.po</span></samp> +file will be written relative to the current directory, though. + + </dl> + + <p>If <var>inputfile</var> is ‘<samp><span class="samp">-</span></samp>’, standard input is read. + +<h4 class="subsection">9.1.2 Output file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--output-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002do_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-550"></a><a name="index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-551"></a>Write output to specified file. + + </dl> + + <p><a name="index-standard-output_002c-and-_0040code_007bmsgcat_007d-552"></a>The results are written to standard output if no output file is specified +or if it is ‘<samp><span class="samp">-</span></samp>’. + +<h4 class="subsection">9.1.3 Message selection</h4> + + <dl> +<dt>‘<samp><span class="samp">-< </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--less-than=</span><var>number</var></samp>’<dd><a name="index-g_t_002d_003c_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-553"></a><a name="index-g_t_002d_002dless_002dthan_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-554"></a>Print messages with less than <var>number</var> definitions, defaults to infinite +if not set. + + <br><dt>‘<samp><span class="samp">-> </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--more-than=</span><var>number</var></samp>’<dd><a name="index-g_t_002d_003e_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-555"></a><a name="index-g_t_002d_002dmore_002dthan_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-556"></a>Print messages with more than <var>number</var> definitions, defaults to 0 if not +set. + + <br><dt>‘<samp><span class="samp">-u</span></samp>’<dt>‘<samp><span class="samp">--unique</span></samp>’<dd><a name="index-g_t_002du_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-557"></a><a name="index-g_t_002d_002dunique_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-558"></a>Shorthand for ‘<samp><span class="samp">--less-than=2</span></samp>’. Requests that only unique messages be +printed. + + </dl> + +<h4 class="subsection">9.1.4 Input file syntax</h4> + + <dl> +<dt>‘<samp><span class="samp">-P</span></samp>’<dt>‘<samp><span class="samp">--properties-input</span></samp>’<dd><a name="index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-559"></a><a name="index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-560"></a>Assume the input files are Java ResourceBundles in Java <code>.properties</code> +syntax, not in PO file syntax. + + <br><dt>‘<samp><span class="samp">--stringtable-input</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-561"></a>Assume the input files are NeXTstep/GNUstep localized resource files in +<code>.strings</code> syntax, not in PO file syntax. + + </dl> + +<h4 class="subsection">9.1.5 Output details</h4> + +<!-- no-escape and -escape omitted on purpose. They are not useful. --> + <dl> +<dt>‘<samp><span class="samp">-t</span></samp>’<dt>‘<samp><span class="samp">--to-code=</span><var>name</var></samp>’<dd><a name="index-g_t_002dt_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-562"></a><a name="index-g_t_002d_002dto_002dcode_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-563"></a>Specify encoding for output. + + <br><dt>‘<samp><span class="samp">--use-first</span></samp>’<dd><a name="index-g_t_002d_002duse_002dfirst_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-564"></a>Use first available translation for each message. Don't merge several +translations into one. + + <br><dt>‘<samp><span class="samp">--lang=</span><var>catalogname</var></samp>’<dd><a name="index-g_t_002d_002dlang_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-565"></a>Specify the ‘<samp><span class="samp">Language</span></samp>’ field to be used in the header entry. See +<a href="#Header-Entry">Header Entry</a> for the meaning of this field. Note: The +‘<samp><span class="samp">Language-Team</span></samp>’ and ‘<samp><span class="samp">Plural-Forms</span></samp>’ fields are left unchanged. + + <br><dt>‘<samp><span class="samp">--color</span></samp>’<dt>‘<samp><span class="samp">--color=</span><var>when</var></samp>’<dd><a name="index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-566"></a>Specify whether or when to use colors and other text attributes. +See <a href="#The-_002d_002dcolor-option">The –color option</a> for details. + + <br><dt>‘<samp><span class="samp">--style=</span><var>style_file</var></samp>’<dd><a name="index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-567"></a>Specify the CSS style rule file to use for <code>--color</code>. +See <a href="#The-_002d_002dstyle-option">The –style option</a> for details. + + <br><dt>‘<samp><span class="samp">--force-po</span></samp>’<dd><a name="index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-568"></a>Always write an output file even if it contains no message. + + <br><dt>‘<samp><span class="samp">-i</span></samp>’<dt>‘<samp><span class="samp">--indent</span></samp>’<dd><a name="index-g_t_002di_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-569"></a><a name="index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-570"></a>Write the .po file using indented style. + + <br><dt>‘<samp><span class="samp">--no-location</span></samp>’<dd><a name="index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-571"></a>Do not write ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines. + + <br><dt>‘<samp><span class="samp">-n</span></samp>’<dt>‘<samp><span class="samp">--add-location</span></samp>’<dd><a name="index-g_t_002dn_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-572"></a><a name="index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-573"></a>Generate ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines (default). + + <br><dt>‘<samp><span class="samp">--strict</span></samp>’<dd><a name="index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-574"></a>Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + + <br><dt>‘<samp><span class="samp">-p</span></samp>’<dt>‘<samp><span class="samp">--properties-output</span></samp>’<dd><a name="index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-575"></a><a name="index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-576"></a>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note +that this file format doesn't support plural forms and silently drops +obsolete messages. + + <br><dt>‘<samp><span class="samp">--stringtable-output</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-577"></a>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. +Note that this file format doesn't support plural forms. + + <br><dt>‘<samp><span class="samp">-w </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--width=</span><var>number</var></samp>’<dd><a name="index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-578"></a><a name="index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-579"></a>Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given <var>number</var>. + + <br><dt>‘<samp><span class="samp">--no-wrap</span></samp>’<dd><a name="index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-580"></a>Do not break long message lines. Message lines whose width exceeds the +output page width will not be split into several lines. Only file reference +lines which are wider than the output page width will be split. + + <br><dt>‘<samp><span class="samp">-s</span></samp>’<dt>‘<samp><span class="samp">--sort-output</span></samp>’<dd><a name="index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-581"></a><a name="index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-582"></a><a name="index-sorting-_0040code_007bmsgcat_007d-output-583"></a>Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + + <br><dt>‘<samp><span class="samp">-F</span></samp>’<dt>‘<samp><span class="samp">--sort-by-file</span></samp>’<dd><a name="index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-584"></a><a name="index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-585"></a>Sort output by file location. + + </dl> + +<h4 class="subsection">9.1.6 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-586"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-587"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-588"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-589"></a>Output version information and exit. + + </dl> + +<div class="node"> +<a name="msgconv-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#msggrep-Invocation">msggrep Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#msgcat-Invocation">msgcat Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Manipulating">Manipulating</a> + +</div> + +<h3 class="section">9.2 Invoking the <code>msgconv</code> Program</h3> + + <p><a name="index-msgconv-590"></a><a name="index-g_t_0040code_007bmsgconv_007d-program_002c-usage-591"></a> +<pre class="example"> msgconv [<var>option</var>] [<var>inputfile</var>] +</pre> + <p><a name="index-convert-translations-to-a-different-encoding-592"></a>The <code>msgconv</code> program converts a translation catalog to a different +character encoding. + +<h4 class="subsection">9.2.1 Input file location</h4> + + <dl> +<dt>‘<samp><var>inputfile</var></samp>’<dd>Input PO file. + + <br><dt>‘<samp><span class="samp">-D </span><var>directory</var></samp>’<dt>‘<samp><span class="samp">--directory=</span><var>directory</var></samp>’<dd><a name="index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-593"></a><a name="index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-594"></a>Add <var>directory</var> to the list of directories. Source files are +searched relative to this list of directories. The resulting <samp><span class="file">.po</span></samp> +file will be written relative to the current directory, though. + + </dl> + + <p>If no <var>inputfile</var> is given or if it is ‘<samp><span class="samp">-</span></samp>’, standard input is read. + +<h4 class="subsection">9.2.2 Output file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--output-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002do_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-595"></a><a name="index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-596"></a>Write output to specified file. + + </dl> + + <p>The results are written to standard output if no output file is specified +or if it is ‘<samp><span class="samp">-</span></samp>’. + +<h4 class="subsection">9.2.3 Conversion target</h4> + + <dl> +<dt>‘<samp><span class="samp">-t</span></samp>’<dt>‘<samp><span class="samp">--to-code=</span><var>name</var></samp>’<dd><a name="index-g_t_002dt_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-597"></a><a name="index-g_t_002d_002dto_002dcode_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-598"></a>Specify encoding for output. + + </dl> + + <p>The default encoding is the current locale's encoding. + +<h4 class="subsection">9.2.4 Input file syntax</h4> + + <dl> +<dt>‘<samp><span class="samp">-P</span></samp>’<dt>‘<samp><span class="samp">--properties-input</span></samp>’<dd><a name="index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-599"></a><a name="index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-600"></a>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> +syntax, not in PO file syntax. + + <br><dt>‘<samp><span class="samp">--stringtable-input</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgonv_007d-option_007d-601"></a>Assume the input file is a NeXTstep/GNUstep localized resource file in +<code>.strings</code> syntax, not in PO file syntax. + + </dl> + +<h4 class="subsection">9.2.5 Output details</h4> + +<!-- no-escape and -escape omitted on purpose. They are not useful. --> + <dl> +<dt>‘<samp><span class="samp">--color</span></samp>’<dt>‘<samp><span class="samp">--color=</span><var>when</var></samp>’<dd><a name="index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-602"></a>Specify whether or when to use colors and other text attributes. +See <a href="#The-_002d_002dcolor-option">The –color option</a> for details. + + <br><dt>‘<samp><span class="samp">--style=</span><var>style_file</var></samp>’<dd><a name="index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-603"></a>Specify the CSS style rule file to use for <code>--color</code>. +See <a href="#The-_002d_002dstyle-option">The –style option</a> for details. + + <br><dt>‘<samp><span class="samp">--force-po</span></samp>’<dd><a name="index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-604"></a>Always write an output file even if it contains no message. + + <br><dt>‘<samp><span class="samp">-i</span></samp>’<dt>‘<samp><span class="samp">--indent</span></samp>’<dd><a name="index-g_t_002di_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-605"></a><a name="index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-606"></a>Write the .po file using indented style. + + <br><dt>‘<samp><span class="samp">--no-location</span></samp>’<dd><a name="index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-607"></a>Do not write ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines. + + <br><dt>‘<samp><span class="samp">--add-location</span></samp>’<dd><a name="index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-608"></a>Generate ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines (default). + + <br><dt>‘<samp><span class="samp">--strict</span></samp>’<dd><a name="index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-609"></a>Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + + <br><dt>‘<samp><span class="samp">-p</span></samp>’<dt>‘<samp><span class="samp">--properties-output</span></samp>’<dd><a name="index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-610"></a><a name="index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-611"></a>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note +that this file format doesn't support plural forms and silently drops +obsolete messages. + + <br><dt>‘<samp><span class="samp">--stringtable-output</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-612"></a>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. +Note that this file format doesn't support plural forms. + + <br><dt>‘<samp><span class="samp">-w </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--width=</span><var>number</var></samp>’<dd><a name="index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-613"></a><a name="index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-614"></a>Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given <var>number</var>. + + <br><dt>‘<samp><span class="samp">--no-wrap</span></samp>’<dd><a name="index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-615"></a>Do not break long message lines. Message lines whose width exceeds the +output page width will not be split into several lines. Only file reference +lines which are wider than the output page width will be split. + + <br><dt>‘<samp><span class="samp">-s</span></samp>’<dt>‘<samp><span class="samp">--sort-output</span></samp>’<dd><a name="index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-616"></a><a name="index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-617"></a>Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + + <br><dt>‘<samp><span class="samp">-F</span></samp>’<dt>‘<samp><span class="samp">--sort-by-file</span></samp>’<dd><a name="index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-618"></a><a name="index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-619"></a>Sort output by file location. + + </dl> + +<h4 class="subsection">9.2.6 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-620"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-621"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-622"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-623"></a>Output version information and exit. + + </dl> + +<div class="node"> +<a name="msggrep-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#msgfilter-Invocation">msgfilter Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#msgconv-Invocation">msgconv Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Manipulating">Manipulating</a> + +</div> + +<h3 class="section">9.3 Invoking the <code>msggrep</code> Program</h3> + + <p><a name="index-msggrep-624"></a><a name="index-g_t_0040code_007bmsggrep_007d-program_002c-usage-625"></a> +<pre class="example"> msggrep [<var>option</var>] [<var>inputfile</var>] +</pre> + <p><a name="index-search-messages-in-a-catalog-626"></a>The <code>msggrep</code> program extracts all messages of a translation catalog +that match a given pattern or belong to some given source files. + +<h4 class="subsection">9.3.1 Input file location</h4> + + <dl> +<dt>‘<samp><var>inputfile</var></samp>’<dd>Input PO file. + + <br><dt>‘<samp><span class="samp">-D </span><var>directory</var></samp>’<dt>‘<samp><span class="samp">--directory=</span><var>directory</var></samp>’<dd><a name="index-g_t_002dD_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-627"></a><a name="index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-628"></a>Add <var>directory</var> to the list of directories. Source files are +searched relative to this list of directories. The resulting <samp><span class="file">.po</span></samp> +file will be written relative to the current directory, though. + + </dl> + + <p>If no <var>inputfile</var> is given or if it is ‘<samp><span class="samp">-</span></samp>’, standard input is read. + +<h4 class="subsection">9.3.2 Output file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--output-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002do_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-629"></a><a name="index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-630"></a>Write output to specified file. + + </dl> + + <p>The results are written to standard output if no output file is specified +or if it is ‘<samp><span class="samp">-</span></samp>’. + +<h4 class="subsection">9.3.3 Message selection</h4> + +<pre class="example"> [-N <var>sourcefile</var>]... [-M <var>domainname</var>]... + [-J <var>msgctxt-pattern</var>] [-K <var>msgid-pattern</var>] [-T <var>msgstr-pattern</var>] + [-C <var>comment-pattern</var>] +</pre> + <p>A message is selected if + <ul> +<li>it comes from one of the specified source files, +<li>or if it comes from one of the specified domains, +<li>or if ‘<samp><span class="samp">-J</span></samp>’ is given and its context (msgctxt) matches +<var>msgctxt-pattern</var>, +<li>or if ‘<samp><span class="samp">-K</span></samp>’ is given and its key (msgid or msgid_plural) matches +<var>msgid-pattern</var>, +<li>or if ‘<samp><span class="samp">-T</span></samp>’ is given and its translation (msgstr) matches +<var>msgstr-pattern</var>, +<li>or if ‘<samp><span class="samp">-C</span></samp>’ is given and the translator's comment matches +<var>comment-pattern</var>. +</ul> + + <p>When more than one selection criterion is specified, the set of selected +messages is the union of the selected messages of each criterion. + + <p><var>msgctxt-pattern</var> or <var>msgid-pattern</var> or <var>msgstr-pattern</var> syntax: +<pre class="example"> [-E | -F] [-e <var>pattern</var> | -f <var>file</var>]... +</pre> + <p><var>pattern</var>s are basic regular expressions by default, or extended regular +expressions if -E is given, or fixed strings if -F is given. + + <dl> +<dt>‘<samp><span class="samp">-N </span><var>sourcefile</var></samp>’<dt>‘<samp><span class="samp">--location=</span><var>sourcefile</var></samp>’<dd><a name="index-g_t_002dN_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-631"></a><a name="index-g_t_002d_002dlocation_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-632"></a>Select messages extracted from <var>sourcefile</var>. <var>sourcefile</var> can be +either a literal file name or a wildcard pattern. + + <br><dt>‘<samp><span class="samp">-M </span><var>domainname</var></samp>’<dt>‘<samp><span class="samp">--domain=</span><var>domainname</var></samp>’<dd><a name="index-g_t_002dM_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-633"></a><a name="index-g_t_002d_002ddomain_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-634"></a>Select messages belonging to domain <var>domainname</var>. + + <br><dt>‘<samp><span class="samp">-J</span></samp>’<dt>‘<samp><span class="samp">--msgctxt</span></samp>’<dd><a name="index-g_t_002dJ_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-635"></a><a name="index-g_t_002d_002dmsgctxt_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-636"></a>Start of patterns for the msgctxt. + + <br><dt>‘<samp><span class="samp">-K</span></samp>’<dt>‘<samp><span class="samp">--msgid</span></samp>’<dd><a name="index-g_t_002dK_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-637"></a><a name="index-g_t_002d_002dmsgid_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-638"></a>Start of patterns for the msgid. + + <br><dt>‘<samp><span class="samp">-T</span></samp>’<dt>‘<samp><span class="samp">--msgstr</span></samp>’<dd><a name="index-g_t_002dT_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-639"></a><a name="index-g_t_002d_002dmsgstr_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-640"></a>Start of patterns for the msgstr. + + <br><dt>‘<samp><span class="samp">-C</span></samp>’<dt>‘<samp><span class="samp">--comment</span></samp>’<dd><a name="index-g_t_002dC_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-641"></a><a name="index-g_t_002d_002dcomment_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-642"></a>Start of patterns for the translator's comment. + + <br><dt>‘<samp><span class="samp">-X</span></samp>’<dt>‘<samp><span class="samp">--extracted-comment</span></samp>’<dd><a name="index-g_t_002dX_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-643"></a><a name="index-g_t_002d_002dextracted_002dcomment_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-644"></a>Start of patterns for the extracted comments. + + <br><dt>‘<samp><span class="samp">-E</span></samp>’<dt>‘<samp><span class="samp">--extended-regexp</span></samp>’<dd><a name="index-g_t_002dE_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-645"></a><a name="index-g_t_002d_002dextended_002dregexp_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-646"></a>Specify that <var>pattern</var> is an extended regular expression. + + <br><dt>‘<samp><span class="samp">-F</span></samp>’<dt>‘<samp><span class="samp">--fixed-strings</span></samp>’<dd><a name="index-g_t_002dF_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-647"></a><a name="index-g_t_002d_002dfixed_002dstrings_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-648"></a>Specify that <var>pattern</var> is a set of newline-separated strings. + + <br><dt>‘<samp><span class="samp">-e </span><var>pattern</var></samp>’<dt>‘<samp><span class="samp">--regexp=</span><var>pattern</var></samp>’<dd><a name="index-g_t_002de_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-649"></a><a name="index-g_t_002d_002dregexp_003d_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-650"></a>Use <var>pattern</var> as a regular expression. + + <br><dt>‘<samp><span class="samp">-f </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--file=</span><var>file</var></samp>’<dd><a name="index-g_t_002df_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-651"></a><a name="index-g_t_002d_002dfile_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-652"></a>Obtain <var>pattern</var> from <var>file</var>. + + <br><dt>‘<samp><span class="samp">-i</span></samp>’<dt>‘<samp><span class="samp">--ignore-case</span></samp>’<dd><a name="index-g_t_002di_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-653"></a><a name="index-g_t_002d_002dignore_002dcase_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-654"></a>Ignore case distinctions. + + <br><dt>‘<samp><span class="samp">-v</span></samp>’<dt>‘<samp><span class="samp">--invert-match</span></samp>’<dd><a name="index-g_t_002dv_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-655"></a><a name="index-g_t_002d_002dinvert_002dmatch_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-656"></a>Output only the messages that do not match any selection criterion, instead +of the messages that match a selection criterion. + + </dl> + +<h4 class="subsection">9.3.4 Input file syntax</h4> + + <dl> +<dt>‘<samp><span class="samp">-P</span></samp>’<dt>‘<samp><span class="samp">--properties-input</span></samp>’<dd><a name="index-g_t_002dP_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-657"></a><a name="index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-658"></a>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> +syntax, not in PO file syntax. + + <br><dt>‘<samp><span class="samp">--stringtable-input</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-659"></a>Assume the input file is a NeXTstep/GNUstep localized resource file in +<code>.strings</code> syntax, not in PO file syntax. + + </dl> + +<h4 class="subsection">9.3.5 Output details</h4> + +<!-- no-escape and -escape omitted on purpose. They are not useful. --> + <dl> +<dt>‘<samp><span class="samp">--color</span></samp>’<dt>‘<samp><span class="samp">--color=</span><var>when</var></samp>’<dd><a name="index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-660"></a>Specify whether or when to use colors and other text attributes. +See <a href="#The-_002d_002dcolor-option">The –color option</a> for details. + + <br><dt>‘<samp><span class="samp">--style=</span><var>style_file</var></samp>’<dd><a name="index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-661"></a>Specify the CSS style rule file to use for <code>--color</code>. +See <a href="#The-_002d_002dstyle-option">The –style option</a> for details. + + <br><dt>‘<samp><span class="samp">--force-po</span></samp>’<dd><a name="index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-662"></a>Always write an output file even if it contains no message. + + <br><dt>‘<samp><span class="samp">--indent</span></samp>’<dd><a name="index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-663"></a>Write the .po file using indented style. + + <br><dt>‘<samp><span class="samp">--no-location</span></samp>’<dd><a name="index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-664"></a>Do not write ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines. + + <br><dt>‘<samp><span class="samp">--add-location</span></samp>’<dd><a name="index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-665"></a>Generate ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines (default). + + <br><dt>‘<samp><span class="samp">--strict</span></samp>’<dd><a name="index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-666"></a>Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + + <br><dt>‘<samp><span class="samp">-p</span></samp>’<dt>‘<samp><span class="samp">--properties-output</span></samp>’<dd><a name="index-g_t_002dp_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-667"></a><a name="index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-668"></a>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note +that this file format doesn't support plural forms and silently drops +obsolete messages. + + <br><dt>‘<samp><span class="samp">--stringtable-output</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-669"></a>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. +Note that this file format doesn't support plural forms. + + <br><dt>‘<samp><span class="samp">-w </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--width=</span><var>number</var></samp>’<dd><a name="index-g_t_002dw_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-670"></a><a name="index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-671"></a>Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given <var>number</var>. + + <br><dt>‘<samp><span class="samp">--no-wrap</span></samp>’<dd><a name="index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-672"></a>Do not break long message lines. Message lines whose width exceeds the +output page width will not be split into several lines. Only file reference +lines which are wider than the output page width will be split. + + <br><dt>‘<samp><span class="samp">--sort-output</span></samp>’<dd><a name="index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-673"></a>Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + + <br><dt>‘<samp><span class="samp">--sort-by-file</span></samp>’<dd><a name="index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-674"></a>Sort output by file location. + + </dl> + +<h4 class="subsection">9.3.6 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-675"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-676"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-677"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-678"></a>Output version information and exit. + + </dl> + +<h4 class="subsection">9.3.7 Examples</h4> + + <p>To extract the messages that come from the source files +<code>gnulib-lib/error.c</code> and <code>gnulib-lib/getopt.c</code>: + +<pre class="smallexample"> msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po +</pre> + <p>To extract the messages that contain the string “Please specify” in the +original string: + +<pre class="smallexample"> msggrep --msgid -F -e 'Please specify' input.po +</pre> + <p>To extract the messages that have a context specifier of either “Menu>File” +or “Menu>Edit” or a submenu of them: + +<pre class="smallexample"> msggrep --msgctxt -E -e '^Menu>(File|Edit)' input.po +</pre> + <p>To extract the messages whose translation contains one of the strings in the +file <code>wordlist.txt</code>: + +<pre class="smallexample"> msggrep --msgstr -F -f wordlist.txt input.po +</pre> + <div class="node"> +<a name="msgfilter-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#msguniq-Invocation">msguniq Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#msggrep-Invocation">msggrep Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Manipulating">Manipulating</a> + +</div> + +<h3 class="section">9.4 Invoking the <code>msgfilter</code> Program</h3> + + <p><a name="index-msgfilter-679"></a><a name="index-g_t_0040code_007bmsgfilter_007d-program_002c-usage-680"></a> +<pre class="example"> msgfilter [<var>option</var>] <var>filter</var> [<var>filter-option</var>] +</pre> + <p><a name="index-apply-a-filter-to-translations-681"></a>The <code>msgfilter</code> program applies a filter to all translations of a +translation catalog. + + <p><a name="index-MSGFILTER_005fMSGCTXT_0040r_007b_002c-environment-variable_007d-682"></a><a name="index-MSGFILTER_005fMSGID_0040r_007b_002c-environment-variable_007d-683"></a><a name="index-MSGFILTER_005fLOCATION_0040r_007b_002c-environment-variable_007d-684"></a>During each <var>filter</var> invocation, the environment variable +<code>MSGFILTER_MSGID</code> is bound to the message's msgid, and the environment +variable <code>MSGFILTER_LOCATION</code> is bound to the location in the PO file +of the message. If the message has a context, the environment variable +<code>MSGFILTER_MSGCTXT</code> is bound to the message's msgctxt, otherwise it is +unbound. + +<h4 class="subsection">9.4.1 Input file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-i </span><var>inputfile</var></samp>’<dt>‘<samp><span class="samp">--input=</span><var>inputfile</var></samp>’<dd><a name="index-g_t_002di_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-685"></a><a name="index-g_t_002d_002dinput_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-686"></a>Input PO file. + + <br><dt>‘<samp><span class="samp">-D </span><var>directory</var></samp>’<dt>‘<samp><span class="samp">--directory=</span><var>directory</var></samp>’<dd><a name="index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-687"></a><a name="index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-688"></a>Add <var>directory</var> to the list of directories. Source files are +searched relative to this list of directories. The resulting <samp><span class="file">.po</span></samp> +file will be written relative to the current directory, though. + + </dl> + + <p>If no <var>inputfile</var> is given or if it is ‘<samp><span class="samp">-</span></samp>’, standard input is read. + +<h4 class="subsection">9.4.2 Output file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--output-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002do_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-689"></a><a name="index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-690"></a>Write output to specified file. + + </dl> + + <p>The results are written to standard output if no output file is specified +or if it is ‘<samp><span class="samp">-</span></samp>’. + +<h4 class="subsection">9.4.3 The filter</h4> + + <p>The <var>filter</var> can be any program that reads a translation from standard +input and writes a modified translation to standard output. A frequently +used filter is ‘<samp><span class="samp">sed</span></samp>’. A few particular built-in filters are also +recognized. + + <p><a name="index-g_t_0040code_007bmsgfilter_007d-filter-and-catalog-encoding-691"></a>Note: If the filter is not a built-in filter, you have to care about encodings: +It is your responsibility to ensure that the <var>filter</var> can cope +with input encoded in the translation catalog's encoding. If the +<var>filter</var> wants input in a particular encoding, you can in a first step +convert the translation catalog to that encoding using the ‘<samp><span class="samp">msgconv</span></samp>’ +program, before invoking ‘<samp><span class="samp">msgfilter</span></samp>’. If the <var>filter</var> wants input +in the locale's encoding, but you want to avoid the locale's encoding, then +you can first convert the translation catalog to UTF-8 using the +‘<samp><span class="samp">msgconv</span></samp>’ program and then make ‘<samp><span class="samp">msgfilter</span></samp>’ work in an UTF-8 +locale, by using the <code>LC_ALL</code> environment variable. + + <p><a name="index-portability-problems-with-_0040code_007bsed_007d-692"></a>Note: Most translations in a translation catalog don't end with a newline +character. For this reason, it is important that the <var>filter</var> +recognizes its last input line even if it ends without a newline, and that +it doesn't add an undesired trailing newline at the end. The ‘<samp><span class="samp">sed</span></samp>’ +program on some platforms is known to ignore the last line of input if it +is not terminated with a newline. You can use GNU <code>sed</code> instead; it +does not have this limitation. + +<h4 class="subsection">9.4.4 Useful <var>filter-option</var>s when the <var>filter</var> is ‘<samp><span class="samp">sed</span></samp>’</h4> + + <dl> +<dt>‘<samp><span class="samp">-e </span><var>script</var></samp>’<dt>‘<samp><span class="samp">--expression=</span><var>script</var></samp>’<dd><a name="index-g_t_002de_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-693"></a><a name="index-g_t_002d_002dexpression_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-694"></a>Add <var>script</var> to the commands to be executed. + + <br><dt>‘<samp><span class="samp">-f </span><var>scriptfile</var></samp>’<dt>‘<samp><span class="samp">--file=</span><var>scriptfile</var></samp>’<dd><a name="index-g_t_002df_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-695"></a><a name="index-g_t_002d_002dfile_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-696"></a>Add the contents of <var>scriptfile</var> to the commands to be executed. + + <br><dt>‘<samp><span class="samp">-n</span></samp>’<dt>‘<samp><span class="samp">--quiet</span></samp>’<dt>‘<samp><span class="samp">--silent</span></samp>’<dd><a name="index-g_t_002dn_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-697"></a><a name="index-g_t_002d_002dquiet_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-698"></a><a name="index-g_t_002d_002dsilent_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-699"></a>Suppress automatic printing of pattern space. + + </dl> + +<h4 class="subsection">9.4.5 Built-in <var>filter</var>s</h4> + + <p><a name="index-recode_002dsr_002dlatin-700"></a><a name="index-g_t_0040code_007brecode_002dsr_002dlatin_007d-program-701"></a>The filter ‘<samp><span class="samp">recode-sr-latin</span></samp>’ is recognized as a built-in filter. +The command ‘<samp><span class="samp">recode-sr-latin</span></samp>’ converts Serbian text, written in the +Cyrillic script, to the Latin script. +The command ‘<samp><span class="samp">msgfilter recode-sr-latin</span></samp>’ applies this conversion to the +translations of a PO file. Thus, it can be used to convert an <samp><span class="file">sr.po</span></samp> +file to an <samp><span class="file">sr@latin.po</span></samp> file. + + <p>The use of built-in filters is not sensitive to the current locale's encoding. +Moreover, when used with a built-in filter, ‘<samp><span class="samp">msgfilter</span></samp>’ can automatically +convert the message catalog to the UTF-8 encoding when needed. + +<h4 class="subsection">9.4.6 Input file syntax</h4> + + <dl> +<dt>‘<samp><span class="samp">-P</span></samp>’<dt>‘<samp><span class="samp">--properties-input</span></samp>’<dd><a name="index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-702"></a><a name="index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-703"></a>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> +syntax, not in PO file syntax. + + <br><dt>‘<samp><span class="samp">--stringtable-input</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-704"></a>Assume the input file is a NeXTstep/GNUstep localized resource file in +<code>.strings</code> syntax, not in PO file syntax. + + </dl> + +<h4 class="subsection">9.4.7 Output details</h4> + +<!-- no-escape and -escape omitted on purpose. They are not useful. --> + <dl> +<dt>‘<samp><span class="samp">--color</span></samp>’<dt>‘<samp><span class="samp">--color=</span><var>when</var></samp>’<dd><a name="index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-705"></a>Specify whether or when to use colors and other text attributes. +See <a href="#The-_002d_002dcolor-option">The –color option</a> for details. + + <br><dt>‘<samp><span class="samp">--style=</span><var>style_file</var></samp>’<dd><a name="index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-706"></a>Specify the CSS style rule file to use for <code>--color</code>. +See <a href="#The-_002d_002dstyle-option">The –style option</a> for details. + + <br><dt>‘<samp><span class="samp">--force-po</span></samp>’<dd><a name="index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-707"></a>Always write an output file even if it contains no message. + + <br><dt>‘<samp><span class="samp">--indent</span></samp>’<dd><a name="index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-708"></a>Write the .po file using indented style. + + <br><dt>‘<samp><span class="samp">--keep-header</span></samp>’<dd><a name="index-g_t_002d_002dkeep_002dheader_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-709"></a>Keep the header entry, i.e. the message with ‘<samp><span class="samp">msgid ""</span></samp>’, unmodified, +instead of filtering it. By default, the header entry is subject to +filtering like any other message. + + <br><dt>‘<samp><span class="samp">--no-location</span></samp>’<dd><a name="index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-710"></a>Do not write ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines. + + <br><dt>‘<samp><span class="samp">--add-location</span></samp>’<dd><a name="index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-711"></a>Generate ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines (default). + + <br><dt>‘<samp><span class="samp">--strict</span></samp>’<dd><a name="index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-712"></a>Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + + <br><dt>‘<samp><span class="samp">-p</span></samp>’<dt>‘<samp><span class="samp">--properties-output</span></samp>’<dd><a name="index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-713"></a><a name="index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-714"></a>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note +that this file format doesn't support plural forms and silently drops +obsolete messages. + + <br><dt>‘<samp><span class="samp">--stringtable-output</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-715"></a>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. +Note that this file format doesn't support plural forms. + + <br><dt>‘<samp><span class="samp">-w </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--width=</span><var>number</var></samp>’<dd><a name="index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-716"></a><a name="index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-717"></a>Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given <var>number</var>. + + <br><dt>‘<samp><span class="samp">--no-wrap</span></samp>’<dd><a name="index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-718"></a>Do not break long message lines. Message lines whose width exceeds the +output page width will not be split into several lines. Only file reference +lines which are wider than the output page width will be split. + + <br><dt>‘<samp><span class="samp">-s</span></samp>’<dt>‘<samp><span class="samp">--sort-output</span></samp>’<dd><a name="index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-719"></a><a name="index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-720"></a>Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + + <br><dt>‘<samp><span class="samp">-F</span></samp>’<dt>‘<samp><span class="samp">--sort-by-file</span></samp>’<dd><a name="index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-721"></a><a name="index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-722"></a>Sort output by file location. + + </dl> + +<h4 class="subsection">9.4.8 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-723"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-724"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-725"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-726"></a>Output version information and exit. + + </dl> + +<h4 class="subsection">9.4.9 Examples</h4> + + <p>To convert German translations to Swiss orthography (in an UTF-8 locale): + +<pre class="smallexample"> msgconv -t UTF-8 de.po | msgfilter sed -e 's/ß/ss/g' +</pre> + <p>To convert Serbian translations in Cyrillic script to Latin script: + +<pre class="smallexample"> msgfilter recode-sr-latin < sr.po +</pre> + <div class="node"> +<a name="msguniq-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#msgcomm-Invocation">msgcomm Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#msgfilter-Invocation">msgfilter Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Manipulating">Manipulating</a> + +</div> + +<h3 class="section">9.5 Invoking the <code>msguniq</code> Program</h3> + + <p><a name="index-msguniq-727"></a><a name="index-g_t_0040code_007bmsguniq_007d-program_002c-usage-728"></a> +<pre class="example"> msguniq [<var>option</var>] [<var>inputfile</var>] +</pre> + <p><a name="index-unify-duplicate-translations-729"></a><a name="index-duplicate-removal-730"></a>The <code>msguniq</code> program unifies duplicate translations in a translation +catalog. It finds duplicate translations of the same message ID. Such +duplicates are invalid input for other programs like <code>msgfmt</code>, +<code>msgmerge</code> or <code>msgcat</code>. By default, duplicates are merged +together. When using the ‘<samp><span class="samp">--repeated</span></samp>’ option, only duplicates are +output, and all other messages are discarded. Comments and extracted +comments will be cumulated, except that if ‘<samp><span class="samp">--use-first</span></samp>’ is +specified, they will be taken from the first translation. File positions +will be cumulated. When using the ‘<samp><span class="samp">--unique</span></samp>’ option, duplicates are +discarded. + +<h4 class="subsection">9.5.1 Input file location</h4> + + <dl> +<dt>‘<samp><var>inputfile</var></samp>’<dd>Input PO file. + + <br><dt>‘<samp><span class="samp">-D </span><var>directory</var></samp>’<dt>‘<samp><span class="samp">--directory=</span><var>directory</var></samp>’<dd><a name="index-g_t_002dD_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-731"></a><a name="index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-732"></a>Add <var>directory</var> to the list of directories. Source files are +searched relative to this list of directories. The resulting <samp><span class="file">.po</span></samp> +file will be written relative to the current directory, though. + + </dl> + + <p>If no <var>inputfile</var> is given or if it is ‘<samp><span class="samp">-</span></samp>’, standard input is read. + +<h4 class="subsection">9.5.2 Output file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--output-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002do_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-733"></a><a name="index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-734"></a>Write output to specified file. + + </dl> + + <p>The results are written to standard output if no output file is specified +or if it is ‘<samp><span class="samp">-</span></samp>’. + +<h4 class="subsection">9.5.3 Message selection</h4> + + <dl> +<dt>‘<samp><span class="samp">-d</span></samp>’<dt>‘<samp><span class="samp">--repeated</span></samp>’<dd><a name="index-g_t_002dd_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-735"></a><a name="index-g_t_002d_002drepeated_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-736"></a>Print only duplicates. + + <br><dt>‘<samp><span class="samp">-u</span></samp>’<dt>‘<samp><span class="samp">--unique</span></samp>’<dd><a name="index-g_t_002du_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-737"></a><a name="index-g_t_002d_002dunique_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-738"></a>Print only unique messages, discard duplicates. + + </dl> + +<h4 class="subsection">9.5.4 Input file syntax</h4> + + <dl> +<dt>‘<samp><span class="samp">-P</span></samp>’<dt>‘<samp><span class="samp">--properties-input</span></samp>’<dd><a name="index-g_t_002dP_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-739"></a><a name="index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-740"></a>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> +syntax, not in PO file syntax. + + <br><dt>‘<samp><span class="samp">--stringtable-input</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-741"></a>Assume the input file is a NeXTstep/GNUstep localized resource file in +<code>.strings</code> syntax, not in PO file syntax. + + </dl> + +<h4 class="subsection">9.5.5 Output details</h4> + +<!-- no-escape and -escape omitted on purpose. They are not useful. --> + <dl> +<dt>‘<samp><span class="samp">-t</span></samp>’<dt>‘<samp><span class="samp">--to-code=</span><var>name</var></samp>’<dd><a name="index-g_t_002dt_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-742"></a><a name="index-g_t_002d_002dto_002dcode_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-743"></a>Specify encoding for output. + + <br><dt>‘<samp><span class="samp">--use-first</span></samp>’<dd><a name="index-g_t_002d_002duse_002dfirst_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-744"></a>Use first available translation for each message. Don't merge several +translations into one. + + <br><dt>‘<samp><span class="samp">--color</span></samp>’<dt>‘<samp><span class="samp">--color=</span><var>when</var></samp>’<dd><a name="index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-745"></a>Specify whether or when to use colors and other text attributes. +See <a href="#The-_002d_002dcolor-option">The –color option</a> for details. + + <br><dt>‘<samp><span class="samp">--style=</span><var>style_file</var></samp>’<dd><a name="index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-746"></a>Specify the CSS style rule file to use for <code>--color</code>. +See <a href="#The-_002d_002dstyle-option">The –style option</a> for details. + + <br><dt>‘<samp><span class="samp">--force-po</span></samp>’<dd><a name="index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-747"></a>Always write an output file even if it contains no message. + + <br><dt>‘<samp><span class="samp">-i</span></samp>’<dt>‘<samp><span class="samp">--indent</span></samp>’<dd><a name="index-g_t_002di_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-748"></a><a name="index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-749"></a>Write the .po file using indented style. + + <br><dt>‘<samp><span class="samp">--no-location</span></samp>’<dd><a name="index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-750"></a>Do not write ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines. + + <br><dt>‘<samp><span class="samp">-n</span></samp>’<dt>‘<samp><span class="samp">--add-location</span></samp>’<dd><a name="index-g_t_002dn_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-751"></a><a name="index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-752"></a>Generate ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines (default). + + <br><dt>‘<samp><span class="samp">--strict</span></samp>’<dd><a name="index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-753"></a>Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + + <br><dt>‘<samp><span class="samp">-p</span></samp>’<dt>‘<samp><span class="samp">--properties-output</span></samp>’<dd><a name="index-g_t_002dp_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-754"></a><a name="index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-755"></a>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note +that this file format doesn't support plural forms and silently drops +obsolete messages. + + <br><dt>‘<samp><span class="samp">--stringtable-output</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-756"></a>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. +Note that this file format doesn't support plural forms. + + <br><dt>‘<samp><span class="samp">-w </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--width=</span><var>number</var></samp>’<dd><a name="index-g_t_002dw_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-757"></a><a name="index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-758"></a>Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given <var>number</var>. + + <br><dt>‘<samp><span class="samp">--no-wrap</span></samp>’<dd><a name="index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-759"></a>Do not break long message lines. Message lines whose width exceeds the +output page width will not be split into several lines. Only file reference +lines which are wider than the output page width will be split. + + <br><dt>‘<samp><span class="samp">-s</span></samp>’<dt>‘<samp><span class="samp">--sort-output</span></samp>’<dd><a name="index-g_t_002ds_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-760"></a><a name="index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-761"></a>Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + + <br><dt>‘<samp><span class="samp">-F</span></samp>’<dt>‘<samp><span class="samp">--sort-by-file</span></samp>’<dd><a name="index-g_t_002dF_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-762"></a><a name="index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-763"></a>Sort output by file location. + + </dl> + +<h4 class="subsection">9.5.6 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-764"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-765"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-766"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-767"></a>Output version information and exit. + + </dl> + +<div class="node"> +<a name="msgcomm-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#msgcmp-Invocation">msgcmp Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#msguniq-Invocation">msguniq Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Manipulating">Manipulating</a> + +</div> + +<h3 class="section">9.6 Invoking the <code>msgcomm</code> Program</h3> + + <p><a name="index-msgcomm-768"></a><a name="index-g_t_0040code_007bmsgcomm_007d-program_002c-usage-769"></a> +<pre class="example"> msgcomm [<var>option</var>] [<var>inputfile</var>]... +</pre> + <p><a name="index-find-common-messages-770"></a>The <code>msgcomm</code> program finds messages which are common to two or more +of the specified PO files. +By using the <code>--more-than</code> option, greater commonality may be requested +before messages are printed. Conversely, the <code>--less-than</code> option may be +used to specify less commonality before messages are printed (i.e. +‘<samp><span class="samp">--less-than=2</span></samp>’ will only print the unique messages). Translations, +comments and extract comments will be preserved, but only from the first +PO file to define them. File positions from all PO files will be +cumulated. + +<h4 class="subsection">9.6.1 Input file location</h4> + + <dl> +<dt>‘<samp><var>inputfile</var><span class="samp"> ...</span></samp>’<dd>Input files. + + <br><dt>‘<samp><span class="samp">-f </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--files-from=</span><var>file</var></samp>’<dd><a name="index-g_t_002df_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-771"></a><a name="index-g_t_002d_002dfiles_002dfrom_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-772"></a>Read the names of the input files from <var>file</var> instead of getting +them from the command line. + + <br><dt>‘<samp><span class="samp">-D </span><var>directory</var></samp>’<dt>‘<samp><span class="samp">--directory=</span><var>directory</var></samp>’<dd><a name="index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-773"></a><a name="index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-774"></a>Add <var>directory</var> to the list of directories. Source files are +searched relative to this list of directories. The resulting <samp><span class="file">.po</span></samp> +file will be written relative to the current directory, though. + + </dl> + + <p>If <var>inputfile</var> is ‘<samp><span class="samp">-</span></samp>’, standard input is read. + +<h4 class="subsection">9.6.2 Output file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--output-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002do_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-775"></a><a name="index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-776"></a>Write output to specified file. + + </dl> + + <p>The results are written to standard output if no output file is specified +or if it is ‘<samp><span class="samp">-</span></samp>’. + +<h4 class="subsection">9.6.3 Message selection</h4> + + <dl> +<dt>‘<samp><span class="samp">-< </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--less-than=</span><var>number</var></samp>’<dd><a name="index-g_t_002d_003c_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-777"></a><a name="index-g_t_002d_002dless_002dthan_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-778"></a>Print messages with less than <var>number</var> definitions, defaults to infinite +if not set. + + <br><dt>‘<samp><span class="samp">-> </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--more-than=</span><var>number</var></samp>’<dd><a name="index-g_t_002d_003e_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-779"></a><a name="index-g_t_002d_002dmore_002dthan_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-780"></a>Print messages with more than <var>number</var> definitions, defaults to 1 if not +set. + + <br><dt>‘<samp><span class="samp">-u</span></samp>’<dt>‘<samp><span class="samp">--unique</span></samp>’<dd><a name="index-g_t_002du_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-781"></a><a name="index-g_t_002d_002dunique_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-782"></a>Shorthand for ‘<samp><span class="samp">--less-than=2</span></samp>’. Requests that only unique messages be +printed. + + </dl> + +<h4 class="subsection">9.6.4 Input file syntax</h4> + + <dl> +<dt>‘<samp><span class="samp">-P</span></samp>’<dt>‘<samp><span class="samp">--properties-input</span></samp>’<dd><a name="index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-783"></a><a name="index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-784"></a>Assume the input files are Java ResourceBundles in Java <code>.properties</code> +syntax, not in PO file syntax. + + <br><dt>‘<samp><span class="samp">--stringtable-input</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-785"></a>Assume the input files are NeXTstep/GNUstep localized resource files in +<code>.strings</code> syntax, not in PO file syntax. + + </dl> + +<h4 class="subsection">9.6.5 Output details</h4> + +<!-- no-escape and -escape omitted on purpose. They are not useful. --> + <dl> +<dt>‘<samp><span class="samp">--color</span></samp>’<dt>‘<samp><span class="samp">--color=</span><var>when</var></samp>’<dd><a name="index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-786"></a>Specify whether or when to use colors and other text attributes. +See <a href="#The-_002d_002dcolor-option">The –color option</a> for details. + + <br><dt>‘<samp><span class="samp">--style=</span><var>style_file</var></samp>’<dd><a name="index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-787"></a>Specify the CSS style rule file to use for <code>--color</code>. +See <a href="#The-_002d_002dstyle-option">The –style option</a> for details. + + <br><dt>‘<samp><span class="samp">--force-po</span></samp>’<dd><a name="index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-788"></a>Always write an output file even if it contains no message. + + <br><dt>‘<samp><span class="samp">-i</span></samp>’<dt>‘<samp><span class="samp">--indent</span></samp>’<dd><a name="index-g_t_002di_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-789"></a><a name="index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-790"></a>Write the .po file using indented style. + + <br><dt>‘<samp><span class="samp">--no-location</span></samp>’<dd><a name="index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-791"></a>Do not write ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines. + + <br><dt>‘<samp><span class="samp">-n</span></samp>’<dt>‘<samp><span class="samp">--add-location</span></samp>’<dd><a name="index-g_t_002dn_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-792"></a><a name="index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-793"></a>Generate ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines (default). + + <br><dt>‘<samp><span class="samp">--strict</span></samp>’<dd><a name="index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-794"></a>Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + + <br><dt>‘<samp><span class="samp">-p</span></samp>’<dt>‘<samp><span class="samp">--properties-output</span></samp>’<dd><a name="index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-795"></a><a name="index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-796"></a>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note +that this file format doesn't support plural forms and silently drops +obsolete messages. + + <br><dt>‘<samp><span class="samp">--stringtable-output</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-797"></a>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. +Note that this file format doesn't support plural forms. + + <br><dt>‘<samp><span class="samp">-w </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--width=</span><var>number</var></samp>’<dd><a name="index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-798"></a><a name="index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-799"></a>Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given <var>number</var>. + + <br><dt>‘<samp><span class="samp">--no-wrap</span></samp>’<dd><a name="index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-800"></a>Do not break long message lines. Message lines whose width exceeds the +output page width will not be split into several lines. Only file reference +lines which are wider than the output page width will be split. + + <br><dt>‘<samp><span class="samp">-s</span></samp>’<dt>‘<samp><span class="samp">--sort-output</span></samp>’<dd><a name="index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-801"></a><a name="index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-802"></a>Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + + <br><dt>‘<samp><span class="samp">-F</span></samp>’<dt>‘<samp><span class="samp">--sort-by-file</span></samp>’<dd><a name="index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-803"></a><a name="index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-804"></a>Sort output by file location. + + <br><dt>‘<samp><span class="samp">--omit-header</span></samp>’<dd><a name="index-g_t_002d_002domit_002dheader_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-805"></a>Don't write header with ‘<samp><span class="samp">msgid ""</span></samp>’ entry. + + </dl> + +<h4 class="subsection">9.6.6 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-806"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-807"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-808"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-809"></a>Output version information and exit. + + </dl> + +<div class="node"> +<a name="msgcmp-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#msgattrib-Invocation">msgattrib Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#msgcomm-Invocation">msgcomm Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Manipulating">Manipulating</a> + +</div> + +<h3 class="section">9.7 Invoking the <code>msgcmp</code> Program</h3> + + <p><a name="index-msgcmp-810"></a><a name="index-g_t_0040code_007bmsgcmp_007d-program_002c-usage-811"></a> +<pre class="example"> msgcmp [<var>option</var>] <var>def</var>.po <var>ref</var>.pot +</pre> + <p><a name="index-compare-PO-files-812"></a>The <code>msgcmp</code> program compares two Uniforum style .po files to check that +both contain the same set of msgid strings. The <var>def</var>.po file is an +existing PO file with the translations. The <var>ref</var>.pot file is the last +created PO file, or a PO Template file (generally created by <code>xgettext</code>). +This is useful for checking that you have translated each and every message +in your program. Where an exact match cannot be found, fuzzy matching is +used to produce better diagnostics. + +<h4 class="subsection">9.7.1 Input file location</h4> + + <dl> +<dt>‘<samp><var>def</var><span class="samp">.po</span></samp>’<dd>Translations. + + <br><dt>‘<samp><var>ref</var><span class="samp">.pot</span></samp>’<dd>References to the sources. + + <br><dt>‘<samp><span class="samp">-D </span><var>directory</var></samp>’<dt>‘<samp><span class="samp">--directory=</span><var>directory</var></samp>’<dd><a name="index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-813"></a><a name="index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-814"></a>Add <var>directory</var> to the list of directories. Source files are +searched relative to this list of directories. + + </dl> + +<h4 class="subsection">9.7.2 Operation modifiers</h4> + + <dl> +<dt>‘<samp><span class="samp">-m</span></samp>’<dt>‘<samp><span class="samp">--multi-domain</span></samp>’<dd><a name="index-g_t_002dm_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-815"></a><a name="index-g_t_002d_002dmulti_002ddomain_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-816"></a>Apply <var>ref</var>.pot to each of the domains in <var>def</var>.po. + + <br><dt>‘<samp><span class="samp">-N</span></samp>’<dt>‘<samp><span class="samp">--no-fuzzy-matching</span></samp>’<dd><a name="index-g_t_002dN_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-817"></a><a name="index-g_t_002d_002dno_002dfuzzy_002dmatching_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-818"></a>Do not use fuzzy matching when an exact match is not found. This may speed +up the operation considerably. + + <br><dt>‘<samp><span class="samp">--use-fuzzy</span></samp>’<dd><a name="index-g_t_002d_002duse_002dfuzzy_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-819"></a>Consider fuzzy messages in the <var>def</var>.po file like translated messages. +Note that using this option is usually wrong, because fuzzy messages are +exactly those which have not been validated by a human translator. + + <br><dt>‘<samp><span class="samp">--use-untranslated</span></samp>’<dd><a name="index-g_t_002d_002duse_002duntranslated_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-820"></a>Consider untranslated messages in the <var>def</var>.po file like translated +messages. Note that using this option is usually wrong. + + </dl> + +<h4 class="subsection">9.7.3 Input file syntax</h4> + + <dl> +<dt>‘<samp><span class="samp">-P</span></samp>’<dt>‘<samp><span class="samp">--properties-input</span></samp>’<dd><a name="index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-821"></a><a name="index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-822"></a>Assume the input files are Java ResourceBundles in Java <code>.properties</code> +syntax, not in PO file syntax. + + <br><dt>‘<samp><span class="samp">--stringtable-input</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-823"></a>Assume the input files are NeXTstep/GNUstep localized resource files in +<code>.strings</code> syntax, not in PO file syntax. + + </dl> + +<h4 class="subsection">9.7.4 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-824"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-825"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-826"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-827"></a>Output version information and exit. + + </dl> + +<div class="node"> +<a name="msgattrib-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#msgen-Invocation">msgen Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#msgcmp-Invocation">msgcmp Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Manipulating">Manipulating</a> + +</div> + +<h3 class="section">9.8 Invoking the <code>msgattrib</code> Program</h3> + + <p><a name="index-msgattrib-828"></a><a name="index-g_t_0040code_007bmsgattrib_007d-program_002c-usage-829"></a> +<pre class="example"> msgattrib [<var>option</var>] [<var>inputfile</var>] +</pre> + <p><a name="index-filter-messages-according-to-attributes-830"></a><a name="index-attribute-manipulation-831"></a>The <code>msgattrib</code> program filters the messages of a translation catalog +according to their attributes, and manipulates the attributes. + +<h4 class="subsection">9.8.1 Input file location</h4> + + <dl> +<dt>‘<samp><var>inputfile</var></samp>’<dd>Input PO file. + + <br><dt>‘<samp><span class="samp">-D </span><var>directory</var></samp>’<dt>‘<samp><span class="samp">--directory=</span><var>directory</var></samp>’<dd><a name="index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-832"></a><a name="index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-833"></a>Add <var>directory</var> to the list of directories. Source files are +searched relative to this list of directories. The resulting <samp><span class="file">.po</span></samp> +file will be written relative to the current directory, though. + + </dl> + + <p>If no <var>inputfile</var> is given or if it is ‘<samp><span class="samp">-</span></samp>’, standard input is read. + +<h4 class="subsection">9.8.2 Output file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--output-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002do_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-834"></a><a name="index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-835"></a>Write output to specified file. + + </dl> + + <p>The results are written to standard output if no output file is specified +or if it is ‘<samp><span class="samp">-</span></samp>’. + +<h4 class="subsection">9.8.3 Message selection</h4> + + <dl> +<dt>‘<samp><span class="samp">--translated</span></samp>’<dd><a name="index-g_t_002d_002dtranslated_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-836"></a>Keep translated messages, remove untranslated messages. + + <br><dt>‘<samp><span class="samp">--untranslated</span></samp>’<dd><a name="index-g_t_002d_002duntranslated_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-837"></a>Keep untranslated messages, remove translated messages. + + <br><dt>‘<samp><span class="samp">--no-fuzzy</span></samp>’<dd><a name="index-g_t_002d_002dno_002dfuzzy_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-838"></a>Remove +‘fuzzy’ +marked messages. + + <br><dt>‘<samp><span class="samp">--only-fuzzy</span></samp>’<dd><a name="index-g_t_002d_002donly_002dfuzzy_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-839"></a>Keep +‘fuzzy’ +marked messages, remove all other messages. + + <br><dt>‘<samp><span class="samp">--no-obsolete</span></samp>’<dd><a name="index-g_t_002d_002dno_002dobsolete_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-840"></a>Remove obsolete #~ messages. + + <br><dt>‘<samp><span class="samp">--only-obsolete</span></samp>’<dd><a name="index-g_t_002d_002donly_002dobsolete_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-841"></a>Keep obsolete #~ messages, remove all other messages. + + </dl> + +<h4 class="subsection">9.8.4 Attribute manipulation</h4> + + <p><a name="index-modify-message-attributes-842"></a>Attributes are modified after the message selection/removal has been +performed. If the ‘<samp><span class="samp">--only-file</span></samp>’ or ‘<samp><span class="samp">--ignore-file</span></samp>’ option is +specified, the attribute modification is applied only to those messages +that are listed in the <var>only-file</var> and not listed in the +<var>ignore-file</var>. + + <dl> +<dt>‘<samp><span class="samp">--set-fuzzy</span></samp>’<dd><a name="index-g_t_002d_002dset_002dfuzzy_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-843"></a>Set all messages +‘fuzzy’. + + <br><dt>‘<samp><span class="samp">--clear-fuzzy</span></samp>’<dd><a name="index-g_t_002d_002dclear_002dfuzzy_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-844"></a>Set all messages +non-‘fuzzy’. + + <br><dt>‘<samp><span class="samp">--set-obsolete</span></samp>’<dd><a name="index-g_t_002d_002dset_002dobsolete_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-845"></a>Set all messages obsolete. + + <br><dt>‘<samp><span class="samp">--clear-obsolete</span></samp>’<dd><a name="index-g_t_002d_002dclear_002dobsolete_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-846"></a>Set all messages non-obsolete. + + <br><dt>‘<samp><span class="samp">--clear-previous</span></samp>’<dd><a name="index-g_t_002d_002dclear_002dprevious_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-847"></a>Remove the “previous msgid” (‘<samp><span class="samp">#|</span></samp>’) comments from all messages. + + <br><dt>‘<samp><span class="samp">--only-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002d_002donly_002dfile_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-848"></a>Limit the attribute changes to entries that are listed in <var>file</var>. +<var>file</var> should be a PO or POT file. + + <br><dt>‘<samp><span class="samp">--ignore-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002d_002dignore_002dfile_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-849"></a>Limit the attribute changes to entries that are not listed in <var>file</var>. +<var>file</var> should be a PO or POT file. + + <br><dt>‘<samp><span class="samp">--fuzzy</span></samp>’<dd><a name="index-g_t_002d_002dfuzzy_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-850"></a>Synonym for ‘<samp><span class="samp">--only-fuzzy --clear-fuzzy</span></samp>’: It keeps only the fuzzy +messages and removes their +‘fuzzy’ +mark. + + <br><dt>‘<samp><span class="samp">--obsolete</span></samp>’<dd><a name="index-g_t_002d_002dobsolete_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-851"></a>Synonym for ‘<samp><span class="samp">--only-obsolete --clear-obsolete</span></samp>’: It keeps only the +obsolete messages and makes them non-obsolete. + + </dl> + +<h4 class="subsection">9.8.5 Input file syntax</h4> + + <dl> +<dt>‘<samp><span class="samp">-P</span></samp>’<dt>‘<samp><span class="samp">--properties-input</span></samp>’<dd><a name="index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-852"></a><a name="index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-853"></a>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> +syntax, not in PO file syntax. + + <br><dt>‘<samp><span class="samp">--stringtable-input</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-854"></a>Assume the input file is a NeXTstep/GNUstep localized resource file in +<code>.strings</code> syntax, not in PO file syntax. + + </dl> + +<h4 class="subsection">9.8.6 Output details</h4> + +<!-- no-escape and -escape omitted on purpose. They are not useful. --> + <dl> +<dt>‘<samp><span class="samp">--color</span></samp>’<dt>‘<samp><span class="samp">--color=</span><var>when</var></samp>’<dd><a name="index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-855"></a>Specify whether or when to use colors and other text attributes. +See <a href="#The-_002d_002dcolor-option">The –color option</a> for details. + + <br><dt>‘<samp><span class="samp">--style=</span><var>style_file</var></samp>’<dd><a name="index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-856"></a>Specify the CSS style rule file to use for <code>--color</code>. +See <a href="#The-_002d_002dstyle-option">The –style option</a> for details. + + <br><dt>‘<samp><span class="samp">--force-po</span></samp>’<dd><a name="index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-857"></a>Always write an output file even if it contains no message. + + <br><dt>‘<samp><span class="samp">-i</span></samp>’<dt>‘<samp><span class="samp">--indent</span></samp>’<dd><a name="index-g_t_002di_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-858"></a><a name="index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-859"></a>Write the .po file using indented style. + + <br><dt>‘<samp><span class="samp">--no-location</span></samp>’<dd><a name="index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-860"></a>Do not write ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines. + + <br><dt>‘<samp><span class="samp">-n</span></samp>’<dt>‘<samp><span class="samp">--add-location</span></samp>’<dd><a name="index-g_t_002dn_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-861"></a><a name="index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-862"></a>Generate ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines (default). + + <br><dt>‘<samp><span class="samp">--strict</span></samp>’<dd><a name="index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-863"></a>Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + + <br><dt>‘<samp><span class="samp">-p</span></samp>’<dt>‘<samp><span class="samp">--properties-output</span></samp>’<dd><a name="index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-864"></a><a name="index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-865"></a>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note +that this file format doesn't support plural forms and silently drops +obsolete messages. + + <br><dt>‘<samp><span class="samp">--stringtable-output</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-866"></a>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. +Note that this file format doesn't support plural forms. + + <br><dt>‘<samp><span class="samp">-w </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--width=</span><var>number</var></samp>’<dd><a name="index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-867"></a><a name="index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-868"></a>Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given <var>number</var>. + + <br><dt>‘<samp><span class="samp">--no-wrap</span></samp>’<dd><a name="index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-869"></a>Do not break long message lines. Message lines whose width exceeds the +output page width will not be split into several lines. Only file reference +lines which are wider than the output page width will be split. + + <br><dt>‘<samp><span class="samp">-s</span></samp>’<dt>‘<samp><span class="samp">--sort-output</span></samp>’<dd><a name="index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-870"></a><a name="index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-871"></a>Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + + <br><dt>‘<samp><span class="samp">-F</span></samp>’<dt>‘<samp><span class="samp">--sort-by-file</span></samp>’<dd><a name="index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-872"></a><a name="index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-873"></a>Sort output by file location. + + </dl> + +<h4 class="subsection">9.8.7 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-874"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-875"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-876"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-877"></a>Output version information and exit. + + </dl> + +<div class="node"> +<a name="msgen-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#msgexec-Invocation">msgexec Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#msgattrib-Invocation">msgattrib Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Manipulating">Manipulating</a> + +</div> + +<h3 class="section">9.9 Invoking the <code>msgen</code> Program</h3> + + <p><a name="index-msgen-878"></a><a name="index-g_t_0040code_007bmsgen_007d-program_002c-usage-879"></a> +<pre class="example"> msgen [<var>option</var>] <var>inputfile</var> +</pre> + <p><a name="index-generate-translation-catalog-in-English-880"></a>The <code>msgen</code> program creates an English translation catalog. The +input file is the last created English PO file, or a PO Template file +(generally created by xgettext). Untranslated entries are assigned a +translation that is identical to the msgid. + + <p>Note: ‘<samp><span class="samp">msginit --no-translator --locale=en</span></samp>’ performs a very similar +task. The main difference is that <code>msginit</code> cares specially about +the header entry, whereas <code>msgen</code> doesn't. + +<h4 class="subsection">9.9.1 Input file location</h4> + + <dl> +<dt>‘<samp><var>inputfile</var></samp>’<dd>Input PO or POT file. + + <br><dt>‘<samp><span class="samp">-D </span><var>directory</var></samp>’<dt>‘<samp><span class="samp">--directory=</span><var>directory</var></samp>’<dd><a name="index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-881"></a><a name="index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-882"></a>Add <var>directory</var> to the list of directories. Source files are +searched relative to this list of directories. The resulting <samp><span class="file">.po</span></samp> +file will be written relative to the current directory, though. + + </dl> + + <p>If <var>inputfile</var> is ‘<samp><span class="samp">-</span></samp>’, standard input is read. + +<h4 class="subsection">9.9.2 Output file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--output-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002do_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-883"></a><a name="index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-884"></a>Write output to specified file. + + </dl> + + <p>The results are written to standard output if no output file is specified +or if it is ‘<samp><span class="samp">-</span></samp>’. + +<h4 class="subsection">9.9.3 Input file syntax</h4> + + <dl> +<dt>‘<samp><span class="samp">-P</span></samp>’<dt>‘<samp><span class="samp">--properties-input</span></samp>’<dd><a name="index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-885"></a><a name="index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-886"></a>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> +syntax, not in PO file syntax. + + <br><dt>‘<samp><span class="samp">--stringtable-input</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-887"></a>Assume the input file is a NeXTstep/GNUstep localized resource file in +<code>.strings</code> syntax, not in PO file syntax. + + </dl> + +<h4 class="subsection">9.9.4 Output details</h4> + +<!-- no-escape and -escape omitted on purpose. They are not useful. --> + <dl> +<dt>‘<samp><span class="samp">--lang=</span><var>catalogname</var></samp>’<dd><a name="index-g_t_002d_002dlang_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-888"></a>Specify the ‘<samp><span class="samp">Language</span></samp>’ field to be used in the header entry. See +<a href="#Header-Entry">Header Entry</a> for the meaning of this field. Note: The +‘<samp><span class="samp">Language-Team</span></samp>’ and ‘<samp><span class="samp">Plural-Forms</span></samp>’ fields are not set by this +option. + + <br><dt>‘<samp><span class="samp">--color</span></samp>’<dt>‘<samp><span class="samp">--color=</span><var>when</var></samp>’<dd><a name="index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-889"></a>Specify whether or when to use colors and other text attributes. +See <a href="#The-_002d_002dcolor-option">The –color option</a> for details. + + <br><dt>‘<samp><span class="samp">--style=</span><var>style_file</var></samp>’<dd><a name="index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-890"></a>Specify the CSS style rule file to use for <code>--color</code>. +See <a href="#The-_002d_002dstyle-option">The –style option</a> for details. + + <br><dt>‘<samp><span class="samp">--force-po</span></samp>’<dd><a name="index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-891"></a>Always write an output file even if it contains no message. + + <br><dt>‘<samp><span class="samp">-i</span></samp>’<dt>‘<samp><span class="samp">--indent</span></samp>’<dd><a name="index-g_t_002di_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-892"></a><a name="index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-893"></a>Write the .po file using indented style. + + <br><dt>‘<samp><span class="samp">--no-location</span></samp>’<dd><a name="index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-894"></a>Do not write ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines. + + <br><dt>‘<samp><span class="samp">--add-location</span></samp>’<dd><a name="index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-895"></a>Generate ‘<samp><span class="samp">#: </span><var>filename</var><span class="samp">:</span><var>line</var></samp>’ lines (default). + + <br><dt>‘<samp><span class="samp">--strict</span></samp>’<dd><a name="index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-896"></a>Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + + <br><dt>‘<samp><span class="samp">-p</span></samp>’<dt>‘<samp><span class="samp">--properties-output</span></samp>’<dd><a name="index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-897"></a><a name="index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-898"></a>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note +that this file format doesn't support plural forms and silently drops +obsolete messages. + + <br><dt>‘<samp><span class="samp">--stringtable-output</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-899"></a>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. +Note that this file format doesn't support plural forms. + + <br><dt>‘<samp><span class="samp">-w </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--width=</span><var>number</var></samp>’<dd><a name="index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-900"></a><a name="index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-901"></a>Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given <var>number</var>. + + <br><dt>‘<samp><span class="samp">--no-wrap</span></samp>’<dd><a name="index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-902"></a>Do not break long message lines. Message lines whose width exceeds the +output page width will not be split into several lines. Only file reference +lines which are wider than the output page width will be split. + + <br><dt>‘<samp><span class="samp">-s</span></samp>’<dt>‘<samp><span class="samp">--sort-output</span></samp>’<dd><a name="index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-903"></a><a name="index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-904"></a>Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + + <br><dt>‘<samp><span class="samp">-F</span></samp>’<dt>‘<samp><span class="samp">--sort-by-file</span></samp>’<dd><a name="index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-905"></a><a name="index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-906"></a>Sort output by file location. + + </dl> + +<h4 class="subsection">9.9.5 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-907"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-908"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-909"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-910"></a>Output version information and exit. + + </dl> + +<div class="node"> +<a name="msgexec-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Colorizing">Colorizing</a>, +Previous: <a rel="previous" accesskey="p" href="#msgen-Invocation">msgen Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Manipulating">Manipulating</a> + +</div> + +<h3 class="section">9.10 Invoking the <code>msgexec</code> Program</h3> + + <p><a name="index-msgexec-911"></a><a name="index-g_t_0040code_007bmsgexec_007d-program_002c-usage-912"></a> +<pre class="example"> msgexec [<var>option</var>] <var>command</var> [<var>command-option</var>] +</pre> + <p><a name="index-apply-command-to-all-translations-in-a-catalog-913"></a>The <code>msgexec</code> program applies a command to all translations of a +translation catalog. +The <var>command</var> can be any program that reads a translation from standard +input. It is invoked once for each translation. Its output becomes +msgexec's output. <code>msgexec</code>'s return code is the maximum return code +across all invocations. + + <p><a name="index-g_t_0040code_007bxargs_007d_002c-and-output-from-_0040code_007bmsgexec_007d-914"></a>A special builtin command called ‘<samp><span class="samp">0</span></samp>’ outputs the translation, followed +by a null byte. The output of ‘<samp><span class="samp">msgexec 0</span></samp>’ is suitable as input for +‘<samp><span class="samp">xargs -0</span></samp>’. + + <p><a name="index-MSGEXEC_005fMSGCTXT_0040r_007b_002c-environment-variable_007d-915"></a><a name="index-MSGEXEC_005fMSGID_0040r_007b_002c-environment-variable_007d-916"></a><a name="index-MSGEXEC_005fLOCATION_0040r_007b_002c-environment-variable_007d-917"></a>During each <var>command</var> invocation, the environment variable +<code>MSGEXEC_MSGID</code> is bound to the message's msgid, and the environment +variable <code>MSGEXEC_LOCATION</code> is bound to the location in the PO file +of the message. If the message has a context, the environment variable +<code>MSGEXEC_MSGCTXT</code> is bound to the message's msgctxt, otherwise it is +unbound. + + <p><a name="index-catalog-encoding-and-_0040code_007bmsgexec_007d-output-918"></a>Note: It is your responsibility to ensure that the <var>command</var> can cope +with input encoded in the translation catalog's encoding. If the +<var>command</var> wants input in a particular encoding, you can in a first step +convert the translation catalog to that encoding using the ‘<samp><span class="samp">msgconv</span></samp>’ +program, before invoking ‘<samp><span class="samp">msgexec</span></samp>’. If the <var>command</var> wants input +in the locale's encoding, but you want to avoid the locale's encoding, then +you can first convert the translation catalog to UTF-8 using the +‘<samp><span class="samp">msgconv</span></samp>’ program and then make ‘<samp><span class="samp">msgexec</span></samp>’ work in an UTF-8 +locale, by using the <code>LC_ALL</code> environment variable. + +<h4 class="subsection">9.10.1 Input file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-i </span><var>inputfile</var></samp>’<dt>‘<samp><span class="samp">--input=</span><var>inputfile</var></samp>’<dd><a name="index-g_t_002di_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-919"></a><a name="index-g_t_002d_002dinput_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-920"></a>Input PO file. + + <br><dt>‘<samp><span class="samp">-D </span><var>directory</var></samp>’<dt>‘<samp><span class="samp">--directory=</span><var>directory</var></samp>’<dd><a name="index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-921"></a><a name="index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-922"></a>Add <var>directory</var> to the list of directories. Source files are +searched relative to this list of directories. The resulting <samp><span class="file">.po</span></samp> +file will be written relative to the current directory, though. + + </dl> + + <p>If no <var>inputfile</var> is given or if it is ‘<samp><span class="samp">-</span></samp>’, standard input is read. + +<h4 class="subsection">9.10.2 Input file syntax</h4> + + <dl> +<dt>‘<samp><span class="samp">-P</span></samp>’<dt>‘<samp><span class="samp">--properties-input</span></samp>’<dd><a name="index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-923"></a><a name="index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-924"></a>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> +syntax, not in PO file syntax. + + <br><dt>‘<samp><span class="samp">--stringtable-input</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-925"></a>Assume the input file is a NeXTstep/GNUstep localized resource file in +<code>.strings</code> syntax, not in PO file syntax. + + </dl> + +<h4 class="subsection">9.10.3 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-926"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-927"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-928"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-929"></a>Output version information and exit. + + </dl> + +<div class="node"> +<a name="Colorizing"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#libgettextpo">libgettextpo</a>, +Previous: <a rel="previous" accesskey="p" href="#msgexec-Invocation">msgexec Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Manipulating">Manipulating</a> + +</div> + +<h3 class="section">9.11 Highlighting parts of PO files</h3> + + <p>Translators are usually only interested in seeing the untranslated and +fuzzy messages of a PO file. Also, when a message is set fuzzy because +the msgid changed, they want to see the differences between the previous +msgid and the current one (especially if the msgid is long and only few +words in it have changed). Finally, it's always welcome to highlight the +different sections of a message in a PO file (comments, msgid, msgstr, etc.). + + <p>Such highlighting is possible through the <code>msgcat</code> options +‘<samp><span class="samp">--color</span></samp>’ and ‘<samp><span class="samp">--style</span></samp>’. + +<ul class="menu"> +<li><a accesskey="1" href="#The-_002d_002dcolor-option">The --color option</a>: Triggering colorized output +<li><a accesskey="2" href="#The-TERM-variable">The TERM variable</a>: The environment variable <code>TERM</code> +<li><a accesskey="3" href="#The-_002d_002dstyle-option">The --style option</a>: The <code>--style</code> option +<li><a accesskey="4" href="#Style-rules">Style rules</a>: Style rules for PO files +<li><a accesskey="5" href="#Customizing-less">Customizing less</a>: Customizing <code>less</code> for viewing PO files +</ul> + +<div class="node"> +<a name="The---color-option"></a> +<a name="The-_002d_002dcolor-option"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#The-TERM-variable">The TERM variable</a>, +Up: <a rel="up" accesskey="u" href="#Colorizing">Colorizing</a> + +</div> + +<h4 class="subsection">9.11.1 The <code>--color</code> option</h4> + + <p><a name="index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-930"></a>The ‘<samp><span class="samp">--color=</span><var>when</var></samp>’ option specifies under which conditions +colorized output should be generated. The <var>when</var> part can be one of +the following: + + <dl> +<dt><code>always</code><dt><code>yes</code><dd>The output will be colorized. + + <br><dt><code>never</code><dt><code>no</code><dd>The output will not be colorized. + + <br><dt><code>auto</code><dt><code>tty</code><dd>The output will be colorized if the output device is a tty, i.e. when the +output goes directly to a text screen or terminal emulator window. + + <br><dt><code>html</code><dd>The output will be colorized and be in HTML format. +</dl> + +<p class="noindent">‘<samp><span class="samp">--color</span></samp>’ is equivalent to ‘<samp><span class="samp">--color=yes</span></samp>’. The default is +‘<samp><span class="samp">--color=auto</span></samp>’. + + <p>Thus, a command like ‘<samp><span class="samp">msgcat vi.po</span></samp>’ will produce colorized output +when called by itself in a command window. Whereas in a pipe, such as +‘<samp><span class="samp">msgcat vi.po | less -R</span></samp>’, it will not produce colorized output. To +get colorized output in this situation nevertheless, use the command +‘<samp><span class="samp">msgcat --color vi.po | less -R</span></samp>’. + + <p>The ‘<samp><span class="samp">--color=html</span></samp>’ option will produce output that can be viewed in +a browser. This can be useful, for example, for Indic languages, +because the renderic of Indic scripts in browser is usually better than +in terminal emulators. + + <p>Note that the output produced with the <code>--color</code> option is <em>not</em> +a valid PO file in itself. It contains additional terminal-specific escape +sequences or HTML tags. A PO file reader will give a syntax error when +confronted with such content. Except for the ‘<samp><span class="samp">--color=html</span></samp>’ case, +you therefore normally don't need to save output produced with the +<code>--color</code> option in a file. + +<div class="node"> +<a name="The-TERM-variable"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#The-_002d_002dstyle-option">The --style option</a>, +Previous: <a rel="previous" accesskey="p" href="#The-_002d_002dcolor-option">The --color option</a>, +Up: <a rel="up" accesskey="u" href="#Colorizing">Colorizing</a> + +</div> + +<h4 class="subsection">9.11.2 The environment variable <code>TERM</code></h4> + + <p><a name="index-TERM_0040r_007b_002c-environment-variable_007d-931"></a>The environment variable <code>TERM</code> contains a identifier for the text +window's capabilities. You can get a detailed list of these cababilities +by using the ‘<samp><span class="samp">infocmp</span></samp>’ command, using ‘<samp><span class="samp">man 5 terminfo</span></samp>’ as a +reference. + + <p>When producing text with embedded color directives, <code>msgcat</code> looks +at the <code>TERM</code> variable. Text windows today typically support at least +8 colors. Often, however, the text window supports 16 or more colors, +even though the <code>TERM</code> variable is set to a identifier denoting only +8 supported colors. It can be worth setting the <code>TERM</code> variable to +a different value in these cases: + + <dl> +<dt><code>xterm</code><dd><code>xterm</code> is in most cases built with support for 16 colors. It can also +be built with support for 88 or 256 colors (but not both). You can try to +set <code>TERM</code> to either <code>xterm-16color</code>, <code>xterm-88color</code>, or +<code>xterm-256color</code>. + + <br><dt><code>rxvt</code><dd><code>rxvt</code> is often built with support for 16 colors. You can try to set +<code>TERM</code> to <code>rxvt-16color</code>. + + <br><dt><code>konsole</code><dd><code>konsole</code> too is often built with support for 16 colors. You can try to +set <code>TERM</code> to <code>konsole-16color</code> or <code>xterm-16color</code>. +</dl> + + <p>After setting <code>TERM</code>, you can verify it by invoking +‘<samp><span class="samp">msgcat --color=test</span></samp>’ and seeing whether the output looks like a +reasonable color map. + +<div class="node"> +<a name="The---style-option"></a> +<a name="The-_002d_002dstyle-option"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Style-rules">Style rules</a>, +Previous: <a rel="previous" accesskey="p" href="#The-TERM-variable">The TERM variable</a>, +Up: <a rel="up" accesskey="u" href="#Colorizing">Colorizing</a> + +</div> + +<h4 class="subsection">9.11.3 The <code>--style</code> option</h4> + + <p><a name="index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-932"></a>The ‘<samp><span class="samp">--style=</span><var>style_file</var></samp>’ option specifies the style file to use +when colorizing. It has an effect only when the <code>--color</code> option is +effective. + + <p><a name="index-PO_005fSTYLE_0040r_007b_002c-environment-variable_007d-933"></a>If the <code>--style</code> option is not specified, the environment variable +<code>PO_STYLE</code> is considered. It is meant to point to the user's +preferred style for PO files. + + <p>The default style file is <samp><span class="file">$prefix/share/gettext/styles/po-default.css</span></samp>, +where <code>$prefix</code> is the installation location. + + <p>A few style files are predefined: + <dl> +<dt><samp><span class="file">po-vim.css</span></samp><dd>This style imitates the look used by vim 7. + + <br><dt><samp><span class="file">po-emacs-x.css</span></samp><dd>This style imitates the look used by GNU Emacs 21 and 22 in an X11 window. + + <br><dt><samp><span class="file">po-emacs-xterm.css</span></samp><dt><samp><span class="file">po-emacs-xterm16.css</span></samp><dt><samp><span class="file">po-emacs-xterm256.css</span></samp><dd>This style imitates the look used by GNU Emacs 22 in a terminal of type +‘<samp><span class="samp">xterm</span></samp>’ (8 colors) or ‘<samp><span class="samp">xterm-16color</span></samp>’ (16 colors) or +‘<samp><span class="samp">xterm-256color</span></samp>’ (256 colors), respectively. +</dl> + +<p class="noindent">You can use these styles without specifying a directory. They are actually +located in <samp><span class="file">$prefix/share/gettext/styles/</span></samp>, where <code>$prefix</code> is the +installation location. + + <p>You can also design your own styles. This is described in the next section. + +<div class="node"> +<a name="Style-rules"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Customizing-less">Customizing less</a>, +Previous: <a rel="previous" accesskey="p" href="#The-_002d_002dstyle-option">The --style option</a>, +Up: <a rel="up" accesskey="u" href="#Colorizing">Colorizing</a> + +</div> + +<h4 class="subsection">9.11.4 Style rules for PO files</h4> + + <p>The same style file can be used for styling of a PO file, for terminal +output and for HTML output. It is written in CSS (Cascading Style Sheet) +syntax. See <a href="http://www.w3.org/TR/css2/cover.html">http://www.w3.org/TR/css2/cover.html</a> for a formal +definition of CSS. Many HTML authoring tutorials also contain explanations +of CSS. + + <p>In the case of HTML output, the style file is embedded in the HTML output. +In the case of text output, the style file is interpreted by the +<code>msgcat</code> program. This means, in particular, that when +<code>@import</code> is used with relative file names, the file names are + + <ul> +<li>relative to the resulting HTML file, in the case of HTML output, + + <li>relative to the style sheet containing the <code>@import</code>, in the case of +text output. (Actually, <code>@import</code>s are not yet supported in this case, +due to a limitation in <code>libcroco</code>.) +</ul> + + <p>CSS rules are built up from selectors and declarations. The declarations +specify graphical properties; the selectors specify specify when they apply. + + <p>In PO files, the following simple selectors (based on "CSS classes", see +the CSS2 spec, section 5.8.3) are supported. + + <ul> +<li>Selectors that apply to entire messages: + + <dl> +<dt><code>.header</code><dd>This matches the header entry of a PO file. + + <br><dt><code>.translated</code><dd>This matches a translated message. + + <br><dt><code>.untranslated</code><dd>This matches an untranslated message (i.e. a message with empty translation). + + <br><dt><code>.fuzzy</code><dd>This matches a fuzzy message (i.e. a message which has a translation that +needs review by the translator). + + <br><dt><code>.obsolete</code><dd>This matches an obsolete message (i.e. a message that was translated but is +not needed by the current POT file any more). +</dl> + + <li>Selectors that apply to parts of a message in PO syntax. Recall the general +structure of a message in PO syntax: + + <pre class="example"> <var>white-space</var> + # <var>translator-comments</var> + #. <var>extracted-comments</var> + #: <var>reference</var>... + #, <var>flag</var>... + #| msgid <var>previous-untranslated-string</var> + msgid <var>untranslated-string</var> + msgstr <var>translated-string</var> +</pre> + <dl> +<dt><code>.comment</code><dd>This matches all comments (translator comments, extracted comments, +source file reference comments, flag comments, previous message comments, +as well as the entire obsolete messages). + + <br><dt><code>.translator-comment</code><dd>This matches the translator comments. + + <br><dt><code>.extracted-comment</code><dd>This matches the extracted comments, i.e. the comments placed by the +programmer at the attention of the translator. + + <br><dt><code>.reference-comment</code><dd>This matches the source file reference comments (entire lines). + + <br><dt><code>.reference</code><dd>This matches the individual source file references inside the source file +reference comment lines. + + <br><dt><code>.flag-comment</code><dd>This matches the flag comment lines (entire lines). + + <br><dt><code>.flag</code><dd>This matches the individual flags inside flag comment lines. + + <br><dt><code>.fuzzy-flag</code><dd>This matches the `fuzzy' flag inside flag comment lines. + + <br><dt><code>.previous-comment</code><dd>This matches the comments containing the previous untranslated string (entire +lines). + + <br><dt><code>.previous</code><dd>This matches the previous untranslated string including the string delimiters, +the associated keywords (<code>msgid</code> etc.) and the spaces between them. + + <br><dt><code>.msgid</code><dd>This matches the untranslated string including the string delimiters, +the associated keywords (<code>msgid</code> etc.) and the spaces between them. + + <br><dt><code>.msgstr</code><dd>This matches the translated string including the string delimiters, +the associated keywords (<code>msgstr</code> etc.) and the spaces between them. + + <br><dt><code>.keyword</code><dd>This matches the keywords (<code>msgid</code>, <code>msgstr</code>, etc.). + + <br><dt><code>.string</code><dd>This matches strings, including the string delimiters (double quotes). +</dl> + + <li>Selectors that apply to parts of strings: + + <dl> +<dt><code>.text</code><dd>This matches the entire contents of a string (excluding the string delimiters, +i.e. the double quotes). + + <br><dt><code>.escape-sequence</code><dd>This matches an escape sequence (starting with a backslash). + + <br><dt><code>.format-directive</code><dd>This matches a format string directive (starting with a ‘<samp><span class="samp">%</span></samp>’ sign in the +case of most programming languages, with a ‘<samp><span class="samp">{</span></samp>’ in the case of +<code>java-format</code> and <code>csharp-format</code>, with a ‘<samp><span class="samp">~</span></samp>’ in the case of +<code>lisp-format</code> and <code>scheme-format</code>, or with ‘<samp><span class="samp">$</span></samp>’ in the case of +<code>sh-format</code>). + + <br><dt><code>.invalid-format-directive</code><dd>This matches an invalid format string directive. + + <br><dt><code>.added</code><dd>In an untranslated string, this matches a part of the string that was not +present in the previous untranslated string. (Not yet implemented in this +release.) + + <br><dt><code>.changed</code><dd>In an untranslated string or in a previous untranslated string, this matches +a part of the string that is changed or replaced. (Not yet implemented in +this release.) + + <br><dt><code>.removed</code><dd>In a previous untranslated string, this matches a part of the string that +is not present in the current untranslated string. (Not yet implemented in +this release.) +</dl> + </ul> + + <p>These selectors can be combined to hierarchical selectors. For example, + +<pre class="smallexample"> .msgstr .invalid-format-directive { color: red; } +</pre> + <p class="noindent">will highlight the invalid format directives in the translated strings. + + <p>In text mode, pseudo-classes (CSS2 spec, section 5.11) and pseudo-elements +(CSS2 spec, section 5.12) are not supported. + + <p>The declarations in HTML mode are not limited; any graphical attribute +supported by the browsers can be used. + + <p>The declarations in text mode are limited to the following properties. Other +properties will be silently ignored. + + <dl> +<dt><code>color</code> (CSS2 spec, section 14.1)<dt><code>background-color</code> (CSS2 spec, section 14.2.1)<dd>These properties is supported. Colors will be adjusted to match the terminal's +capabilities. Note that many terminals support only 8 colors. + + <br><dt><code>font-weight</code> (CSS2 spec, section 15.2.3)<dd>This property is supported, but most terminals can only render two different +weights: <code>normal</code> and <code>bold</code>. Values >= 600 are rendered as +<code>bold</code>. + + <br><dt><code>font-style</code> (CSS2 spec, section 15.2.3)<dd>This property is supported. The values <code>italic</code> and <code>oblique</code> are +rendered the same way. + + <br><dt><code>text-decoration</code> (CSS2 spec, section 16.3.1)<dd>This property is supported, limited to the values <code>none</code> and +<code>underline</code>. +</dl> + +<div class="node"> +<a name="Customizing-less"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Style-rules">Style rules</a>, +Up: <a rel="up" accesskey="u" href="#Colorizing">Colorizing</a> + +</div> + +<h4 class="subsection">9.11.5 Customizing <code>less</code> for viewing PO files</h4> + + <p>The ‘<samp><span class="samp">less</span></samp>’ program is a popular text file browser for use in a text +screen or terminal emulator. It also supports text with embedded escape +sequences for colors and text decorations. + + <p>You can use <code>less</code> to view a PO file like this (assuming an UTF-8 +environment): + +<pre class="smallexample"> msgcat --to-code=UTF-8 --color xyz.po | less -R +</pre> + <p>You can simplify this to this simple command: + +<pre class="smallexample"> less xyz.po +</pre> + <p class="noindent">after these three preparations: + + <ol type=1 start=1> +<li>Add the options ‘<samp><span class="samp">-R</span></samp>’ and ‘<samp><span class="samp">-f</span></samp>’ to the <code>LESS</code> environment +variable. In sh shells: + <pre class="smallexample"> $ LESS="$LESS -R -f" + $ export LESS +</pre> + <li>If your system does not already have the <samp><span class="file">lessopen.sh</span></samp> and +<samp><span class="file">lessclose.sh</span></samp> scripts, create them and set the <code>LESSOPEN</code> and +<code>LESSCLOSE</code> environment variables, as indicated in the manual page +(‘<samp><span class="samp">man less</span></samp>’). + + <li>Add to <samp><span class="file">lessopen.sh</span></samp> a piece of script that recognizes PO files +through their file extension and invokes <code>msgcat</code> on them, producing +a temporary file. Like this: + + <pre class="smallexample"> case "$1" in + *.po) + tmpfile=`mktemp "${TMPDIR-/tmp}/less.XXXXXX"` + msgcat --to-code=UTF-8 --color "$1" > "$tmpfile" + echo "$tmpfile" + exit 0 + ;; + esac +</pre> + </ol> + +<div class="node"> +<a name="libgettextpo"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Colorizing">Colorizing</a>, +Up: <a rel="up" accesskey="u" href="#Manipulating">Manipulating</a> + +</div> + +<h3 class="section">9.12 Writing your own programs that process PO files</h3> + + <p>For the tasks for which a combination of ‘<samp><span class="samp">msgattrib</span></samp>’, ‘<samp><span class="samp">msgcat</span></samp>’ etc. +is not sufficient, a set of C functions is provided in a library, to make it +possible to process PO files in your own programs. When you use this library, +you don't need to write routines to parse the PO file; instead, you retrieve +a pointer in memory to each of messages contained in the PO file. Functions +for writing PO files are not provided at this time. + + <p>The functions are declared in the header file ‘<samp><span class="samp"><gettext-po.h></span></samp>’, and are +defined in a library called ‘<samp><span class="samp">libgettextpo</span></samp>’. + +<div class="defun"> +— Data Type: <b>po_file_t</b><var><a name="index-po_005ffile_005ft-934"></a></var><br> +<blockquote><p>This is a pointer type that refers to the contents of a PO file, after it has +been read into memory. +</p></blockquote></div> + +<div class="defun"> +— Data Type: <b>po_message_iterator_t</b><var><a name="index-po_005fmessage_005fiterator_005ft-935"></a></var><br> +<blockquote><p>This is a pointer type that refers to an iterator that produces a sequence of +messages. +</p></blockquote></div> + +<div class="defun"> +— Data Type: <b>po_message_t</b><var><a name="index-po_005fmessage_005ft-936"></a></var><br> +<blockquote><p>This is a pointer type that refers to a message of a PO file, including its +translation. +</p></blockquote></div> + +<div class="defun"> +— Function: po_file_t <b>po_file_read</b> (<var>const char *filename</var>)<var><a name="index-po_005ffile_005fread-937"></a></var><br> +<blockquote><p>The <code>po_file_read</code> function reads a PO file into memory. The file name +is given as argument. The return value is a handle to the PO file's contents, +valid until <code>po_file_free</code> is called on it. In case of error, the return +value is <code>NULL</code>, and <code>errno</code> is set. +</p></blockquote></div> + +<div class="defun"> +— Function: void <b>po_file_free</b> (<var>po_file_t file</var>)<var><a name="index-po_005ffile_005ffree-938"></a></var><br> +<blockquote><p>The <code>po_file_free</code> function frees a PO file's contents from memory, +including all messages that are only implicitly accessible through iterators. +</p></blockquote></div> + +<div class="defun"> +— Function: const char * const * <b>po_file_domains</b> (<var>po_file_t file</var>)<var><a name="index-po_005ffile_005fdomains-939"></a></var><br> +<blockquote><p>The <code>po_file_domains</code> function returns the domains for which the given +PO file has messages. The return value is a <code>NULL</code> terminated array +which is valid as long as the <var>file</var> handle is valid. For PO files which +contain no ‘<samp><span class="samp">domain</span></samp>’ directive, the return value contains only one domain, +namely the default domain <code>"messages"</code>. +</p></blockquote></div> + +<div class="defun"> +— Function: po_message_iterator_t <b>po_message_iterator</b> (<var>po_file_t file, const char *domain</var>)<var><a name="index-po_005fmessage_005fiterator-940"></a></var><br> +<blockquote><p>The <code>po_message_iterator</code> returns an iterator that will produce the +messages of <var>file</var> that belong to the given <var>domain</var>. If <var>domain</var> +is <code>NULL</code>, the default domain is used instead. To list the messages, +use the function <code>po_next_message</code> repeatedly. +</p></blockquote></div> + +<div class="defun"> +— Function: void <b>po_message_iterator_free</b> (<var>po_message_iterator_t iterator</var>)<var><a name="index-po_005fmessage_005fiterator_005ffree-941"></a></var><br> +<blockquote><p>The <code>po_message_iterator_free</code> function frees an iterator previously +allocated through the <code>po_message_iterator</code> function. +</p></blockquote></div> + +<div class="defun"> +— Function: po_message_t <b>po_next_message</b> (<var>po_message_iterator_t iterator</var>)<var><a name="index-po_005fnext_005fmessage-942"></a></var><br> +<blockquote><p>The <code>po_next_message</code> function returns the next message from +<var>iterator</var> and advances the iterator. It returns <code>NULL</code> when the +iterator has reached the end of its message list. +</p></blockquote></div> + + <p>The following functions returns details of a <code>po_message_t</code>. Recall +that the results are valid as long as the <var>file</var> handle is valid. + +<div class="defun"> +— Function: const char * <b>po_message_msgid</b> (<var>po_message_t message</var>)<var><a name="index-po_005fmessage_005fmsgid-943"></a></var><br> +<blockquote><p>The <code>po_message_msgid</code> function returns the <code>msgid</code> (untranslated +English string) of a message. This is guaranteed to be non-<code>NULL</code>. +</p></blockquote></div> + +<div class="defun"> +— Function: const char * <b>po_message_msgid_plural</b> (<var>po_message_t message</var>)<var><a name="index-po_005fmessage_005fmsgid_005fplural-944"></a></var><br> +<blockquote><p>The <code>po_message_msgid_plural</code> function returns the <code>msgid_plural</code> +(untranslated English plural string) of a message with plurals, or <code>NULL</code> +for a message without plural. +</p></blockquote></div> + +<div class="defun"> +— Function: const char * <b>po_message_msgstr</b> (<var>po_message_t message</var>)<var><a name="index-po_005fmessage_005fmsgstr-945"></a></var><br> +<blockquote><p>The <code>po_message_msgstr</code> function returns the <code>msgstr</code> (translation) +of a message. For an untranslated message, the return value is an empty +string. +</p></blockquote></div> + +<div class="defun"> +— Function: const char * <b>po_message_msgstr_plural</b> (<var>po_message_t message, int index</var>)<var><a name="index-po_005fmessage_005fmsgstr_005fplural-946"></a></var><br> +<blockquote><p>The <code>po_message_msgstr_plural</code> function returns the +<code>msgstr[</code><var>index</var><code>]</code> of a message with plurals, or <code>NULL</code> when +the <var>index</var> is out of range or for a message without plural. +</p></blockquote></div> + + <p>Here is an example code how these functions can be used. + +<pre class="example"> const char *filename = ...; + po_file_t file = po_file_read (filename); + + if (file == NULL) + error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename); + { + const char * const *domains = po_file_domains (file); + const char * const *domainp; + + for (domainp = domains; *domainp; domainp++) + { + const char *domain = *domainp; + po_message_iterator_t iterator = po_message_iterator (file, domain); + + for (;;) + { + po_message_t *message = po_next_message (iterator); + + if (message == NULL) + break; + { + const char *msgid = po_message_msgid (message); + const char *msgstr = po_message_msgstr (message); + + ... + } + } + po_message_iterator_free (iterator); + } + } + po_file_free (file); +</pre> + <div class="node"> +<a name="Binaries"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Programmers">Programmers</a>, +Previous: <a rel="previous" accesskey="p" href="#Manipulating">Manipulating</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">10 Producing Binary MO Files</h2> + +<!-- FIXME: Rewrite. --> +<ul class="menu"> +<li><a accesskey="1" href="#msgfmt-Invocation">msgfmt Invocation</a>: Invoking the <code>msgfmt</code> Program +<li><a accesskey="2" href="#msgunfmt-Invocation">msgunfmt Invocation</a>: Invoking the <code>msgunfmt</code> Program +<li><a accesskey="3" href="#MO-Files">MO Files</a>: The Format of GNU MO Files +</ul> + +<div class="node"> +<a name="msgfmt-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#msgunfmt-Invocation">msgunfmt Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#Binaries">Binaries</a>, +Up: <a rel="up" accesskey="u" href="#Binaries">Binaries</a> + +</div> + +<h3 class="section">10.1 Invoking the <code>msgfmt</code> Program</h3> + + <p><a name="index-msgfmt-947"></a><a name="index-g_t_0040code_007bmsgfmt_007d-program_002c-usage-948"></a> +<pre class="example"> msgfmt [<var>option</var>] <var>filename</var>.po ... +</pre> + <p><a name="index-generate-binary-message-catalog-from-PO-file-949"></a>The <code>msgfmt</code> programs generates a binary message catalog from a textual +translation description. + +<h4 class="subsection">10.1.1 Input file location</h4> + + <dl> +<dt>‘<samp><var>filename</var><span class="samp">.po ...</span></samp>’ +<br><dt>‘<samp><span class="samp">-D </span><var>directory</var></samp>’<dt>‘<samp><span class="samp">--directory=</span><var>directory</var></samp>’<dd><a name="index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-950"></a><a name="index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-951"></a>Add <var>directory</var> to the list of directories. Source files are +searched relative to this list of directories. The resulting <samp><span class="file">.po</span></samp> +file will be written relative to the current directory, though. + + </dl> + + <p>If an input file is ‘<samp><span class="samp">-</span></samp>’, standard input is read. + +<h4 class="subsection">10.1.2 Operation mode</h4> + + <dl> +<dt>‘<samp><span class="samp">-j</span></samp>’<dt>‘<samp><span class="samp">--java</span></samp>’<dd><a name="index-g_t_002dj_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-952"></a><a name="index-g_t_002d_002djava_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-953"></a><a name="index-Java-mode_002c-and-_0040code_007bmsgfmt_007d-program-954"></a>Java mode: generate a Java <code>ResourceBundle</code> class. + + <br><dt>‘<samp><span class="samp">--java2</span></samp>’<dd><a name="index-g_t_002d_002djava2_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-955"></a>Like –java, and assume Java2 (JDK 1.2 or higher). + + <br><dt>‘<samp><span class="samp">--csharp</span></samp>’<dd><a name="index-g_t_002d_002dcsharp_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-956"></a><a name="index-C_0023-mode_002c-and-_0040code_007bmsgfmt_007d-program-957"></a>C# mode: generate a .NET .dll file containing a subclass of +<code>GettextResourceSet</code>. + + <br><dt>‘<samp><span class="samp">--csharp-resources</span></samp>’<dd><a name="index-g_t_002d_002dcsharp_002dresources_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-958"></a><a name="index-C_0023-resources-mode_002c-and-_0040code_007bmsgfmt_007d-program-959"></a>C# resources mode: generate a .NET <samp><span class="file">.resources</span></samp> file. + + <br><dt>‘<samp><span class="samp">--tcl</span></samp>’<dd><a name="index-g_t_002d_002dtcl_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-960"></a><a name="index-Tcl-mode_002c-and-_0040code_007bmsgfmt_007d-program-961"></a>Tcl mode: generate a tcl/msgcat <samp><span class="file">.msg</span></samp> file. + + <br><dt>‘<samp><span class="samp">--qt</span></samp>’<dd><a name="index-g_t_002d_002dqt_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-962"></a><a name="index-Qt-mode_002c-and-_0040code_007bmsgfmt_007d-program-963"></a>Qt mode: generate a Qt <samp><span class="file">.qm</span></samp> file. + + </dl> + +<h4 class="subsection">10.1.3 Output file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--output-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002do_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-964"></a><a name="index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-965"></a>Write output to specified file. + + <br><dt>‘<samp><span class="samp">--strict</span></samp>’<dd><a name="index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-966"></a>Direct the program to work strictly following the Uniforum/Sun +implementation. Currently this only affects the naming of the output +file. If this option is not given the name of the output file is the +same as the domain name. If the strict Uniforum mode is enabled the +suffix <samp><span class="file">.mo</span></samp> is added to the file name if it is not already +present. + + <p>We find this behaviour of Sun's implementation rather silly and so by +default this mode is <em>not</em> selected. + + </dl> + + <p>If the output <var>file</var> is ‘<samp><span class="samp">-</span></samp>’, output is written to standard output. + +<h4 class="subsection">10.1.4 Output file location in Java mode</h4> + + <dl> +<dt>‘<samp><span class="samp">-r </span><var>resource</var></samp>’<dt>‘<samp><span class="samp">--resource=</span><var>resource</var></samp>’<dd><a name="index-g_t_002dr_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-967"></a><a name="index-g_t_002d_002dresource_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-968"></a>Specify the resource name. + + <br><dt>‘<samp><span class="samp">-l </span><var>locale</var></samp>’<dt>‘<samp><span class="samp">--locale=</span><var>locale</var></samp>’<dd><a name="index-g_t_002dl_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-969"></a><a name="index-g_t_002d_002dlocale_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-970"></a>Specify the locale name, either a language specification of the form <var>ll</var> +or a combined language and country specification of the form <var>ll_CC</var>. + + <br><dt>‘<samp><span class="samp">-d </span><var>directory</var></samp>’<dd><a name="index-g_t_002dd_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-971"></a>Specify the base directory of classes directory hierarchy. + + </dl> + + <p>The class name is determined by appending the locale name to the resource name, +separated with an underscore. The ‘<samp><span class="samp">-d</span></samp>’ option is mandatory. The class +is written under the specified directory. + +<h4 class="subsection">10.1.5 Output file location in C# mode</h4> + + <dl> +<dt>‘<samp><span class="samp">-r </span><var>resource</var></samp>’<dt>‘<samp><span class="samp">--resource=</span><var>resource</var></samp>’<dd><a name="index-g_t_002dr_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-972"></a><a name="index-g_t_002d_002dresource_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-973"></a>Specify the resource name. + + <br><dt>‘<samp><span class="samp">-l </span><var>locale</var></samp>’<dt>‘<samp><span class="samp">--locale=</span><var>locale</var></samp>’<dd><a name="index-g_t_002dl_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-974"></a><a name="index-g_t_002d_002dlocale_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-975"></a>Specify the locale name, either a language specification of the form <var>ll</var> +or a combined language and country specification of the form <var>ll_CC</var>. + + <br><dt>‘<samp><span class="samp">-d </span><var>directory</var></samp>’<dd><a name="index-g_t_002dd_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-976"></a>Specify the base directory for locale dependent <samp><span class="file">.dll</span></samp> files. + + </dl> + + <p>The ‘<samp><span class="samp">-l</span></samp>’ and ‘<samp><span class="samp">-d</span></samp>’ options are mandatory. The <samp><span class="file">.dll</span></samp> file is +written in a subdirectory of the specified directory whose name depends on the +locale. + +<h4 class="subsection">10.1.6 Output file location in Tcl mode</h4> + + <dl> +<dt>‘<samp><span class="samp">-l </span><var>locale</var></samp>’<dt>‘<samp><span class="samp">--locale=</span><var>locale</var></samp>’<dd><a name="index-g_t_002dl_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-977"></a><a name="index-g_t_002d_002dlocale_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-978"></a>Specify the locale name, either a language specification of the form <var>ll</var> +or a combined language and country specification of the form <var>ll_CC</var>. + + <br><dt>‘<samp><span class="samp">-d </span><var>directory</var></samp>’<dd><a name="index-g_t_002dd_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-979"></a>Specify the base directory of <samp><span class="file">.msg</span></samp> message catalogs. + + </dl> + + <p>The ‘<samp><span class="samp">-l</span></samp>’ and ‘<samp><span class="samp">-d</span></samp>’ options are mandatory. The <samp><span class="file">.msg</span></samp> file is +written in the specified directory. + +<h4 class="subsection">10.1.7 Input file syntax</h4> + + <dl> +<dt>‘<samp><span class="samp">-P</span></samp>’<dt>‘<samp><span class="samp">--properties-input</span></samp>’<dd><a name="index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-980"></a><a name="index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-981"></a>Assume the input files are Java ResourceBundles in Java <code>.properties</code> +syntax, not in PO file syntax. + + <br><dt>‘<samp><span class="samp">--stringtable-input</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-982"></a>Assume the input files are NeXTstep/GNUstep localized resource files in +<code>.strings</code> syntax, not in PO file syntax. + + </dl> + +<h4 class="subsection">10.1.8 Input file interpretation</h4> + + <dl> +<dt>‘<samp><span class="samp">-c</span></samp>’<dt>‘<samp><span class="samp">--check</span></samp>’<dd><a name="index-g_t_002dc_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-983"></a><a name="index-g_t_002d_002dcheck_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-984"></a>Perform all the checks implied by <code>--check-format</code>, <code>--check-header</code>, +<code>--check-domain</code>. + + <br><dt>‘<samp><span class="samp">--check-format</span></samp>’<dd><a name="index-g_t_002d_002dcheck_002dformat_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-985"></a><a name="index-check-format-strings-986"></a>Check language dependent format strings. + + <p>If the string represents a format string used in a +<code>printf</code>-like function both strings should have the same number of +‘<samp><span class="samp">%</span></samp>’ format specifiers, with matching types. If the flag +<code>c-format</code> or <code>possible-c-format</code> appears in the special +comment <#,> for this entry a check is performed. For example, the +check will diagnose using ‘<samp><span class="samp">%.*s</span></samp>’ against ‘<samp><span class="samp">%s</span></samp>’, or ‘<samp><span class="samp">%d</span></samp>’ +against ‘<samp><span class="samp">%s</span></samp>’, or ‘<samp><span class="samp">%d</span></samp>’ against ‘<samp><span class="samp">%x</span></samp>’. It can even handle +positional parameters. + + <p>Normally the <code>xgettext</code> program automatically decides whether a +string is a format string or not. This algorithm is not perfect, +though. It might regard a string as a format string though it is not +used in a <code>printf</code>-like function and so <code>msgfmt</code> might report +errors where there are none. + + <p>To solve this problem the programmer can dictate the decision to the +<code>xgettext</code> program (see <a href="#c_002dformat">c-format</a>). The translator should not +consider removing the flag from the <#,> line. This "fix" would be +reversed again as soon as <code>msgmerge</code> is called the next time. + + <br><dt>‘<samp><span class="samp">--check-header</span></samp>’<dd><a name="index-g_t_002d_002dcheck_002dheader_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-987"></a>Verify presence and contents of the header entry. See <a href="#Header-Entry">Header Entry</a>, +for a description of the various fields in the header entry. + + <br><dt>‘<samp><span class="samp">--check-domain</span></samp>’<dd><a name="index-g_t_002d_002dcheck_002ddomain_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-988"></a>Check for conflicts between domain directives and the <code>--output-file</code> +option + + <br><dt>‘<samp><span class="samp">-C</span></samp>’<dt>‘<samp><span class="samp">--check-compatibility</span></samp>’<dd><a name="index-g_t_002dC_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-989"></a><a name="index-g_t_002d_002dcheck_002dcompatibility_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-990"></a><a name="index-compatibility-with-X_002fOpen-_0040code_007bmsgfmt_007d-991"></a>Check that GNU msgfmt behaves like X/Open msgfmt. This will give an error +when attempting to use the GNU extensions. + + <br><dt>‘<samp><span class="samp">--check-accelerators[=</span><var>char</var><span class="samp">]</span></samp>’<dd><a name="index-g_t_002d_002dcheck_002daccelerators_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-992"></a><a name="index-keyboard-accelerator-checking-993"></a><a name="index-menu_002c-keyboard-accelerator-support-994"></a><a name="index-mnemonics-of-menu-entries-995"></a>Check presence of keyboard accelerators for menu items. This is based on +the convention used in some GUIs that a keyboard accelerator in a menu +item string is designated by an immediately preceding ‘<samp><span class="samp">&</span></samp>’ character. +Sometimes a keyboard accelerator is also called "keyboard mnemonic". +This check verifies that if the untranslated string has exactly one +‘<samp><span class="samp">&</span></samp>’ character, the translated string has exactly one ‘<samp><span class="samp">&</span></samp>’ as well. +If this option is given with a <var>char</var> argument, this <var>char</var> should +be a non-alphanumeric character and is used as keyboard accelerator mark +instead of ‘<samp><span class="samp">&</span></samp>’. + + <br><dt>‘<samp><span class="samp">-f</span></samp>’<dt>‘<samp><span class="samp">--use-fuzzy</span></samp>’<dd><a name="index-g_t_002df_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-996"></a><a name="index-g_t_002d_002duse_002dfuzzy_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-997"></a><a name="index-force-use-of-fuzzy-entries-998"></a>Use fuzzy entries in output. Note that using this option is usually wrong, +because fuzzy messages are exactly those which have not been validated by +a human translator. + + </dl> + +<h4 class="subsection">10.1.9 Output details</h4> + + <dl> +<dt>‘<samp><span class="samp">-a </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--alignment=</span><var>number</var></samp>’<dd><a name="index-g_t_002da_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-999"></a><a name="index-g_t_002d_002dalignment_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1000"></a>Align strings to <var>number</var> bytes (default: 1). +<!-- Currently the README mentions that this constant could be changed by --> +<!-- the installer by changing the value in config.h. Should this go away? --> + + <br><dt>‘<samp><span class="samp">--no-hash</span></samp>’<dd><a name="index-g_t_002d_002dno_002dhash_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1001"></a>Don't include a hash table in the binary file. Lookup will be more expensive +at run time (binary search instead of hash table lookup). + + </dl> + +<h4 class="subsection">10.1.10 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1002"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1003"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1004"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1005"></a>Output version information and exit. + + <br><dt>‘<samp><span class="samp">--statistics</span></samp>’<dd><a name="index-g_t_002d_002dstatistics_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1006"></a>Print statistics about translations. When the option <code>--verbose</code> is used +in combination with <code>--statistics</code>, the input file name is printed in +front of the statistics line. + + <br><dt>‘<samp><span class="samp">-v</span></samp>’<dt>‘<samp><span class="samp">--verbose</span></samp>’<dd><a name="index-g_t_002dv_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1007"></a><a name="index-g_t_002d_002dverbose_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1008"></a>Increase verbosity level. + + </dl> + +<div class="node"> +<a name="msgunfmt-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#MO-Files">MO Files</a>, +Previous: <a rel="previous" accesskey="p" href="#msgfmt-Invocation">msgfmt Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Binaries">Binaries</a> + +</div> + +<h3 class="section">10.2 Invoking the <code>msgunfmt</code> Program</h3> + + <p><a name="index-msgunfmt-1009"></a><a name="index-g_t_0040code_007bmsgunfmt_007d-program_002c-usage-1010"></a> +<pre class="example"> msgunfmt [<var>option</var>] [<var>file</var>]... +</pre> + <p><a name="index-convert-binary-message-catalog-into-PO-file-1011"></a>The <code>msgunfmt</code> program converts a binary message catalog to a +Uniforum style .po file. + +<h4 class="subsection">10.2.1 Operation mode</h4> + + <dl> +<dt>‘<samp><span class="samp">-j</span></samp>’<dt>‘<samp><span class="samp">--java</span></samp>’<dd><a name="index-g_t_002dj_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1012"></a><a name="index-g_t_002d_002djava_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1013"></a><a name="index-Java-mode_002c-and-_0040code_007bmsgunfmt_007d-program-1014"></a>Java mode: input is a Java <code>ResourceBundle</code> class. + + <br><dt>‘<samp><span class="samp">--csharp</span></samp>’<dd><a name="index-g_t_002d_002dcsharp_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1015"></a><a name="index-C_0023-mode_002c-and-_0040code_007bmsgunfmt_007d-program-1016"></a>C# mode: input is a .NET .dll file containing a subclass of +<code>GettextResourceSet</code>. + + <br><dt>‘<samp><span class="samp">--csharp-resources</span></samp>’<dd><a name="index-g_t_002d_002dcsharp_002dresources_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1017"></a><a name="index-C_0023-resources-mode_002c-and-_0040code_007bmsgunfmt_007d-program-1018"></a>C# resources mode: input is a .NET <samp><span class="file">.resources</span></samp> file. + + <br><dt>‘<samp><span class="samp">--tcl</span></samp>’<dd><a name="index-g_t_002d_002dtcl_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1019"></a><a name="index-Tcl-mode_002c-and-_0040code_007bmsgunfmt_007d-program-1020"></a>Tcl mode: input is a tcl/msgcat <samp><span class="file">.msg</span></samp> file. + + </dl> + +<h4 class="subsection">10.2.2 Input file location</h4> + + <dl> +<dt>‘<samp><var>file</var><span class="samp"> ...</span></samp>’<dd>Input .mo files. + + </dl> + + <p>If no input <var>file</var> is given or if it is ‘<samp><span class="samp">-</span></samp>’, standard input is read. + +<h4 class="subsection">10.2.3 Input file location in Java mode</h4> + + <dl> +<dt>‘<samp><span class="samp">-r </span><var>resource</var></samp>’<dt>‘<samp><span class="samp">--resource=</span><var>resource</var></samp>’<dd><a name="index-g_t_002dr_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1021"></a><a name="index-g_t_002d_002dresource_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1022"></a>Specify the resource name. + + <br><dt>‘<samp><span class="samp">-l </span><var>locale</var></samp>’<dt>‘<samp><span class="samp">--locale=</span><var>locale</var></samp>’<dd><a name="index-g_t_002dl_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1023"></a><a name="index-g_t_002d_002dlocale_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1024"></a>Specify the locale name, either a language specification of the form <var>ll</var> +or a combined language and country specification of the form <var>ll_CC</var>. + + </dl> + + <p>The class name is determined by appending the locale name to the resource name, +separated with an underscore. The class is located using the <code>CLASSPATH</code>. + +<h4 class="subsection">10.2.4 Input file location in C# mode</h4> + + <dl> +<dt>‘<samp><span class="samp">-r </span><var>resource</var></samp>’<dt>‘<samp><span class="samp">--resource=</span><var>resource</var></samp>’<dd><a name="index-g_t_002dr_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1025"></a><a name="index-g_t_002d_002dresource_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1026"></a>Specify the resource name. + + <br><dt>‘<samp><span class="samp">-l </span><var>locale</var></samp>’<dt>‘<samp><span class="samp">--locale=</span><var>locale</var></samp>’<dd><a name="index-g_t_002dl_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1027"></a><a name="index-g_t_002d_002dlocale_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1028"></a>Specify the locale name, either a language specification of the form <var>ll</var> +or a combined language and country specification of the form <var>ll_CC</var>. + + <br><dt>‘<samp><span class="samp">-d </span><var>directory</var></samp>’<dd><a name="index-g_t_002dd_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1029"></a>Specify the base directory for locale dependent <samp><span class="file">.dll</span></samp> files. + + </dl> + + <p>The ‘<samp><span class="samp">-l</span></samp>’ and ‘<samp><span class="samp">-d</span></samp>’ options are mandatory. The <samp><span class="file">.msg</span></samp> file is +located in a subdirectory of the specified directory whose name depends on the +locale. + +<h4 class="subsection">10.2.5 Input file location in Tcl mode</h4> + + <dl> +<dt>‘<samp><span class="samp">-l </span><var>locale</var></samp>’<dt>‘<samp><span class="samp">--locale=</span><var>locale</var></samp>’<dd><a name="index-g_t_002dl_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1030"></a><a name="index-g_t_002d_002dlocale_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1031"></a>Specify the locale name, either a language specification of the form <var>ll</var> +or a combined language and country specification of the form <var>ll_CC</var>. + + <br><dt>‘<samp><span class="samp">-d </span><var>directory</var></samp>’<dd><a name="index-g_t_002dd_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1032"></a>Specify the base directory of <samp><span class="file">.msg</span></samp> message catalogs. + + </dl> + + <p>The ‘<samp><span class="samp">-l</span></samp>’ and ‘<samp><span class="samp">-d</span></samp>’ options are mandatory. The <samp><span class="file">.msg</span></samp> file is +located in the specified directory. + +<h4 class="subsection">10.2.6 Output file location</h4> + + <dl> +<dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’<dt>‘<samp><span class="samp">--output-file=</span><var>file</var></samp>’<dd><a name="index-g_t_002do_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1033"></a><a name="index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1034"></a>Write output to specified file. + + </dl> + + <p>The results are written to standard output if no output file is specified +or if it is ‘<samp><span class="samp">-</span></samp>’. + +<h4 class="subsection">10.2.7 Output details</h4> + +<!-- no-escape and -escape omitted on purpose. They are not useful. --> + <dl> +<dt>‘<samp><span class="samp">--color</span></samp>’<dt>‘<samp><span class="samp">--color=</span><var>when</var></samp>’<dd><a name="index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1035"></a>Specify whether or when to use colors and other text attributes. +See <a href="#The-_002d_002dcolor-option">The –color option</a> for details. + + <br><dt>‘<samp><span class="samp">--style=</span><var>style_file</var></samp>’<dd><a name="index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1036"></a>Specify the CSS style rule file to use for <code>--color</code>. +See <a href="#The-_002d_002dstyle-option">The –style option</a> for details. + + <br><dt>‘<samp><span class="samp">--force-po</span></samp>’<dd><a name="index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1037"></a>Always write an output file even if it contains no message. + + <br><dt>‘<samp><span class="samp">-i</span></samp>’<dt>‘<samp><span class="samp">--indent</span></samp>’<dd><a name="index-g_t_002di_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1038"></a><a name="index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1039"></a>Write the .po file using indented style. + + <br><dt>‘<samp><span class="samp">--strict</span></samp>’<dd><a name="index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1040"></a>Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + + <br><dt>‘<samp><span class="samp">-p</span></samp>’<dt>‘<samp><span class="samp">--properties-output</span></samp>’<dd><a name="index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1041"></a><a name="index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1042"></a>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note +that this file format doesn't support plural forms and silently drops +obsolete messages. + + <br><dt>‘<samp><span class="samp">--stringtable-output</span></samp>’<dd><a name="index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1043"></a>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. +Note that this file format doesn't support plural forms. + + <br><dt>‘<samp><span class="samp">-w </span><var>number</var></samp>’<dt>‘<samp><span class="samp">--width=</span><var>number</var></samp>’<dd><a name="index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1044"></a><a name="index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1045"></a>Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given <var>number</var>. + + <br><dt>‘<samp><span class="samp">--no-wrap</span></samp>’<dd><a name="index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1046"></a>Do not break long message lines. Message lines whose width exceeds the +output page width will not be split into several lines. Only file reference +lines which are wider than the output page width will be split. + + <br><dt>‘<samp><span class="samp">-s</span></samp>’<dt>‘<samp><span class="samp">--sort-output</span></samp>’<dd><a name="index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1047"></a><a name="index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1048"></a><a name="index-sorting-_0040code_007bmsgunfmt_007d-output-1049"></a>Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + + </dl> + +<h4 class="subsection">10.2.8 Informative output</h4> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1050"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1051"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1052"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1053"></a>Output version information and exit. + + <br><dt>‘<samp><span class="samp">-v</span></samp>’<dt>‘<samp><span class="samp">--verbose</span></samp>’<dd><a name="index-g_t_002dv_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1054"></a><a name="index-g_t_002d_002dverbose_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1055"></a>Increase verbosity level. + + </dl> + +<div class="node"> +<a name="MO-Files"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#msgunfmt-Invocation">msgunfmt Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Binaries">Binaries</a> + +</div> + +<h3 class="section">10.3 The Format of GNU MO Files</h3> + + <p><a name="index-MO-file_0027s-format-1056"></a><a name="index-file-format_002c-_0040file_007b_002emo_007d-1057"></a> +The format of the generated MO files is best described by a picture, +which appears below. + + <p><a name="index-magic-signature-of-MO-files-1058"></a>The first two words serve the identification of the file. The magic +number will always signal GNU MO files. The number is stored in the +byte order of the generating machine, so the magic number really is +two numbers: <code>0x950412de</code> and <code>0xde120495</code>. + + <p>The second word describes the current revision of the file format, +composed of a major and a minor revision number. The revision numbers +ensure that the readers of MO files can distinguish new formats from +old ones and handle their contents, as far as possible. For now the +major revision is 0 or 1, and the minor revision is also 0 or 1. More +revisions might be added in the future. A program seeing an unexpected +major revision number should stop reading the MO file entirely; whereas +an unexpected minor revision number means that the file can be read but +will not reveal its full contents, when parsed by a program that +supports only smaller minor revision numbers. + + <p>The version is kept +separate from the magic number, instead of using different magic +numbers for different formats, mainly because <samp><span class="file">/etc/magic</span></samp> is +not updated often. + + <p>Follow a number of pointers to later tables in the file, allowing +for the extension of the prefix part of MO files without having to +recompile programs reading them. This might become useful for later +inserting a few flag bits, indication about the charset used, new +tables, or other things. + + <p>Then, at offset <var>O</var> and offset <var>T</var> in the picture, two tables +of string descriptors can be found. In both tables, each string +descriptor uses two 32 bits integers, one for the string length, +another for the offset of the string in the MO file, counting in bytes +from the start of the file. The first table contains descriptors +for the original strings, and is sorted so the original strings +are in increasing lexicographical order. The second table contains +descriptors for the translated strings, and is parallel to the first +table: to find the corresponding translation one has to access the +array slot in the second array with the same index. + + <p>Having the original strings sorted enables the use of simple binary +search, for when the MO file does not contain an hashing table, or +for when it is not practical to use the hashing table provided in +the MO file. This also has another advantage, as the empty string +in a PO file GNU <code>gettext</code> is usually <em>translated</em> into +some system information attached to that particular MO file, and the +empty string necessarily becomes the first in both the original and +translated tables, making the system information very easy to find. + + <p><a name="index-hash-table_002c-inside-MO-files-1059"></a>The size <var>S</var> of the hash table can be zero. In this case, the +hash table itself is not contained in the MO file. Some people might +prefer this because a precomputed hashing table takes disk space, and +does not win <em>that</em> much speed. The hash table contains indices +to the sorted array of strings in the MO file. Conflict resolution is +done by double hashing. The precise hashing algorithm used is fairly +dependent on GNU <code>gettext</code> code, and is not documented here. + + <p>As for the strings themselves, they follow the hash file, and each +is terminated with a <NUL>, and this <NUL> is not counted in +the length which appears in the string descriptor. The <code>msgfmt</code> +program has an option selecting the alignment for MO file strings. +With this option, each string is separately aligned so it starts at +an offset which is a multiple of the alignment value. On some RISC +machines, a correct alignment will speed things up. + + <p><a name="index-context_002c-in-MO-files-1060"></a>Contexts are stored by storing the concatenation of the context, a +<EOT> byte, and the original string, instead of the original string. + + <p><a name="index-plural-forms_002c-in-MO-files-1061"></a>Plural forms are stored by letting the plural of the original string +follow the singular of the original string, separated through a +<NUL> byte. The length which appears in the string descriptor +includes both. However, only the singular of the original string +takes part in the hash table lookup. The plural variants of the +translation are all stored consecutively, separated through a +<NUL> byte. Here also, the length in the string descriptor +includes all of them. + + <p>Nothing prevents a MO file from having embedded <NUL>s in strings. +However, the program interface currently used already presumes +that strings are <NUL> terminated, so embedded <NUL>s are +somewhat useless. But the MO file format is general enough so other +interfaces would be later possible, if for example, we ever want to +implement wide characters right in MO files, where <NUL> bytes may +accidentally appear. (No, we don't want to have wide characters in MO +files. They would make the file unnecessarily large, and the +‘<samp><span class="samp">wchar_t</span></samp>’ type being platform dependent, MO files would be +platform dependent as well.) + + <p>This particular issue has been strongly debated in the GNU +<code>gettext</code> development forum, and it is expectable that MO file +format will evolve or change over time. It is even possible that many +formats may later be supported concurrently. But surely, we have to +start somewhere, and the MO file format described here is a good start. +Nothing is cast in concrete, and the format may later evolve fairly +easily, so we should feel comfortable with the current approach. + +<pre class="example"> byte + +------------------------------------------+ + 0 | magic number = 0x950412de | + | | + 4 | file format revision = 0 | + | | + 8 | number of strings | == N + | | + 12 | offset of table with original strings | == O + | | + 16 | offset of table with translation strings | == T + | | + 20 | size of hashing table | == S + | | + 24 | offset of hashing table | == H + | | + . . + . (possibly more entries later) . + . . + | | + O | length & offset 0th string ----------------. + O + 8 | length & offset 1st string ------------------. + ... ... | | + O + ((N-1)*8)| length & offset (N-1)th string | | | + | | | | + T | length & offset 0th translation ---------------. + T + 8 | length & offset 1st translation -----------------. + ... ... | | | | + T + ((N-1)*8)| length & offset (N-1)th translation | | | | | + | | | | | | + H | start hash table | | | | | + ... ... | | | | + H + S * 4 | end hash table | | | | | + | | | | | | + | NUL terminated 0th string <----------------' | | | + | | | | | + | NUL terminated 1st string <------------------' | | + | | | | + ... ... | | + | | | | + | NUL terminated 0th translation <---------------' | + | | | + | NUL terminated 1st translation <-----------------' + | | + ... ... + | | + +------------------------------------------+ +</pre> + <div class="node"> +<a name="Programmers"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Translators">Translators</a>, +Previous: <a rel="previous" accesskey="p" href="#Binaries">Binaries</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">11 The Programmer's View</h2> + +<!-- FIXME: Reorganize whole chapter. --> + <p>One aim of the current message catalog implementation provided by +GNU <code>gettext</code> was to use the system's message catalog handling, if the +installer wishes to do so. So we perhaps should first take a look at +the solutions we know about. The people in the POSIX committee did not +manage to agree on one of the semi-official standards which we'll +describe below. In fact they couldn't agree on anything, so they decided +only to include an example of an interface. The major Unix vendors +are split in the usage of the two most important specifications: X/Open's +catgets vs. Uniforum's gettext interface. We'll describe them both and +later explain our solution of this dilemma. + +<ul class="menu"> +<li><a accesskey="1" href="#catgets">catgets</a>: About <code>catgets</code> +<li><a accesskey="2" href="#gettext">gettext</a>: About <code>gettext</code> +<li><a accesskey="3" href="#Comparison">Comparison</a>: Comparing the two interfaces +<li><a accesskey="4" href="#Using-libintl_002ea">Using libintl.a</a>: Using libintl.a in own programs +<li><a accesskey="5" href="#gettext-grok">gettext grok</a>: Being a <code>gettext</code> grok +<li><a accesskey="6" href="#Temp-Programmers">Temp Programmers</a>: Temporary Notes for the Programmers Chapter +</ul> + +<div class="node"> +<a name="catgets"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#gettext">gettext</a>, +Previous: <a rel="previous" accesskey="p" href="#Programmers">Programmers</a>, +Up: <a rel="up" accesskey="u" href="#Programmers">Programmers</a> + +</div> + +<h3 class="section">11.1 About <code>catgets</code></h3> + + <p><a name="index-g_t_0040code_007bcatgets_007d_002c-X_002fOpen-specification-1062"></a> +The <code>catgets</code> implementation is defined in the X/Open Portability +Guide, Volume 3, XSI Supplementary Definitions, Chapter 5. But the +process of creating this standard seemed to be too slow for some of +the Unix vendors so they created their implementations on preliminary +versions of the standard. Of course this leads again to problems while +writing platform independent programs: even the usage of <code>catgets</code> +does not guarantee a unique interface. + + <p>Another, personal comment on this that only a bunch of committee members +could have made this interface. They never really tried to program +using this interface. It is a fast, memory-saving implementation, an +user can happily live with it. But programmers hate it (at least I and +some others do<small class="dots">...</small>) + + <p>But we must not forget one point: after all the trouble with transferring +the rights on Unix(tm) they at last came to X/Open, the very same who +published this specification. This leads me to making the prediction +that this interface will be in future Unix standards (e.g. Spec1170) and +therefore part of all Unix implementation (implementations, which are +<em>allowed</em> to wear this name). + +<ul class="menu"> +<li><a accesskey="1" href="#Interface-to-catgets">Interface to catgets</a>: The interface +<li><a accesskey="2" href="#Problems-with-catgets">Problems with catgets</a>: Problems with the <code>catgets</code> interface?! +</ul> + +<div class="node"> +<a name="Interface-to-catgets"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Problems-with-catgets">Problems with catgets</a>, +Previous: <a rel="previous" accesskey="p" href="#catgets">catgets</a>, +Up: <a rel="up" accesskey="u" href="#catgets">catgets</a> + +</div> + +<h4 class="subsection">11.1.1 The Interface</h4> + + <p><a name="index-interface-to-_0040code_007bcatgets_007d-1063"></a> +The interface to the <code>catgets</code> implementation consists of three +functions which correspond to those used in file access: <code>catopen</code> +to open the catalog for using, <code>catgets</code> for accessing the message +tables, and <code>catclose</code> for closing after work is done. Prototypes +for the functions and the needed definitions are in the +<code><nl_types.h></code> header file. + + <p><a name="index-g_t_0040code_007bcatopen_007d_002c-a-_0040code_007bcatgets_007d-function-1064"></a><code>catopen</code> is used like in this: + +<pre class="example"> nl_catd catd = catopen ("catalog_name", 0); +</pre> + <p>The function takes as the argument the name of the catalog. This usual +refers to the name of the program or the package. The second parameter +is not further specified in the standard. I don't even know whether it +is implemented consistently among various systems. So the common advice +is to use <code>0</code> as the value. The return value is a handle to the +message catalog, equivalent to handles to file returned by <code>open</code>. + + <p><a name="index-g_t_0040code_007bcatgets_007d_002c-a-_0040code_007bcatgets_007d-function-1065"></a>This handle is of course used in the <code>catgets</code> function which can +be used like this: + +<pre class="example"> char *translation = catgets (catd, set_no, msg_id, "original string"); +</pre> + <p>The first parameter is this catalog descriptor. The second parameter +specifies the set of messages in this catalog, in which the message +described by <code>msg_id</code> is obtained. <code>catgets</code> therefore uses a +three-stage addressing: + +<pre class="display"> catalog name ⇒ set number ⇒ message ID ⇒ translation +</pre> + <!-- Anybody else loving Haskell??? :-) - Uli --> + <p>The fourth argument is not used to address the translation. It is given +as a default value in case when one of the addressing stages fail. One +important thing to remember is that although the return type of catgets +is <code>char *</code> the resulting string <em>must not</em> be changed. It +should better be <code>const char *</code>, but the standard is published in +1988, one year before ANSI C. + +<p class="noindent"><a name="index-g_t_0040code_007bcatclose_007d_002c-a-_0040code_007bcatgets_007d-function-1066"></a>The last of these functions is used and behaves as expected: + +<pre class="example"> catclose (catd); +</pre> + <p>After this no <code>catgets</code> call using the descriptor is legal anymore. + +<div class="node"> +<a name="Problems-with-catgets"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Interface-to-catgets">Interface to catgets</a>, +Up: <a rel="up" accesskey="u" href="#catgets">catgets</a> + +</div> + +<h4 class="subsection">11.1.2 Problems with the <code>catgets</code> Interface?!</h4> + + <p><a name="index-problems-with-_0040code_007bcatgets_007d-interface-1067"></a> +Now that this description seemed to be really easy — where are the +problems we speak of? In fact the interface could be used in a +reasonable way, but constructing the message catalogs is a pain. The +reason for this lies in the third argument of <code>catgets</code>: the unique +message ID. This has to be a numeric value for all messages in a single +set. Perhaps you could imagine the problems keeping such a list while +changing the source code. Add a new message here, remove one there. Of +course there have been developed a lot of tools helping to organize this +chaos but one as the other fails in one aspect or the other. We don't +want to say that the other approach has no problems but they are far +more easy to manage. + +<div class="node"> +<a name="gettext"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Comparison">Comparison</a>, +Previous: <a rel="previous" accesskey="p" href="#catgets">catgets</a>, +Up: <a rel="up" accesskey="u" href="#Programmers">Programmers</a> + +</div> + +<h3 class="section">11.2 About <code>gettext</code></h3> + + <p><a name="index-g_t_0040code_007bgettext_007d_002c-a-programmer_0027s-view-1068"></a> +The definition of the <code>gettext</code> interface comes from a Uniforum +proposal. It was submitted there by Sun, who had implemented the +<code>gettext</code> function in SunOS 4, around 1990. Nowadays, the +<code>gettext</code> interface is specified by the OpenI18N standard. + + <p>The main point about this solution is that it does not follow the +method of normal file handling (open-use-close) and that it does not +burden the programmer with so many tasks, especially the unique key handling. +Of course here also a unique key is needed, but this key is the message +itself (how long or short it is). See <a href="#Comparison">Comparison</a> for a more +detailed comparison of the two methods. + + <p>The following section contains a rather detailed description of the +interface. We make it that detailed because this is the interface +we chose for the GNU <code>gettext</code> Library. Programmers interested +in using this library will be interested in this description. + +<ul class="menu"> +<li><a accesskey="1" href="#Interface-to-gettext">Interface to gettext</a>: The interface +<li><a accesskey="2" href="#Ambiguities">Ambiguities</a>: Solving ambiguities +<li><a accesskey="3" href="#Locating-Catalogs">Locating Catalogs</a>: Locating message catalog files +<li><a accesskey="4" href="#Charset-conversion">Charset conversion</a>: How to request conversion to Unicode +<li><a accesskey="5" href="#Contexts">Contexts</a>: Solving ambiguities in GUI programs +<li><a accesskey="6" href="#Plural-forms">Plural forms</a>: Additional functions for handling plurals +<li><a accesskey="7" href="#Optimized-gettext">Optimized gettext</a>: Optimization of the *gettext functions +</ul> + +<div class="node"> +<a name="Interface-to-gettext"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Ambiguities">Ambiguities</a>, +Previous: <a rel="previous" accesskey="p" href="#gettext">gettext</a>, +Up: <a rel="up" accesskey="u" href="#gettext">gettext</a> + +</div> + +<h4 class="subsection">11.2.1 The Interface</h4> + + <p><a name="index-g_t_0040code_007bgettext_007d-interface-1069"></a> +The minimal functionality an interface must have is a) to select a +domain the strings are coming from (a single domain for all programs is +not reasonable because its construction and maintenance is difficult, +perhaps impossible) and b) to access a string in a selected domain. + + <p>This is principally the description of the <code>gettext</code> interface. It +has a global domain which unqualified usages reference. Of course this +domain is selectable by the user. + +<pre class="example"> char *textdomain (const char *domain_name); +</pre> + <p>This provides the possibility to change or query the current status of +the current global domain of the <code>LC_MESSAGE</code> category. The +argument is a null-terminated string, whose characters must be legal in +the use in filenames. If the <var>domain_name</var> argument is <code>NULL</code>, +the function returns the current value. If no value has been set +before, the name of the default domain is returned: <em>messages</em>. +Please note that although the return value of <code>textdomain</code> is of +type <code>char *</code> no changing is allowed. It is also important to know +that no checks of the availability are made. If the name is not +available you will see this by the fact that no translations are provided. + +<p class="noindent">To use a domain set by <code>textdomain</code> the function + +<pre class="example"> char *gettext (const char *msgid); +</pre> + <p class="noindent">is to be used. This is the simplest reasonable form one can imagine. +The translation of the string <var>msgid</var> is returned if it is available +in the current domain. If it is not available, the argument itself is +returned. If the argument is <code>NULL</code> the result is undefined. + + <p>One thing which should come into mind is that no explicit dependency to +the used domain is given. The current value of the domain is used. +If this changes between two +executions of the same <code>gettext</code> call in the program, both calls +reference a different message catalog. + + <p>For the easiest case, which is normally used in internationalized +packages, once at the beginning of execution a call to <code>textdomain</code> +is issued, setting the domain to a unique name, normally the package +name. In the following code all strings which have to be translated are +filtered through the gettext function. That's all, the package speaks +your language. + +<div class="node"> +<a name="Ambiguities"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Locating-Catalogs">Locating Catalogs</a>, +Previous: <a rel="previous" accesskey="p" href="#Interface-to-gettext">Interface to gettext</a>, +Up: <a rel="up" accesskey="u" href="#gettext">gettext</a> + +</div> + +<h4 class="subsection">11.2.2 Solving Ambiguities</h4> + + <p><a name="index-several-domains-1070"></a><a name="index-domain-ambiguities-1071"></a><a name="index-large-package-1072"></a> +While this single name domain works well for most applications there +might be the need to get translations from more than one domain. Of +course one could switch between different domains with calls to +<code>textdomain</code>, but this is really not convenient nor is it fast. A +possible situation could be one case subject to discussion during this +writing: all +error messages of functions in the set of common used functions should +go into a separate domain <code>error</code>. By this mean we would only need +to translate them once. +Another case are messages from a library, as these <em>have</em> to be +independent of the current domain set by the application. + +<p class="noindent">For this reasons there are two more functions to retrieve strings: + +<pre class="example"> char *dgettext (const char *domain_name, const char *msgid); + char *dcgettext (const char *domain_name, const char *msgid, + int category); +</pre> + <p>Both take an additional argument at the first place, which corresponds +to the argument of <code>textdomain</code>. The third argument of +<code>dcgettext</code> allows to use another locale category but <code>LC_MESSAGES</code>. +But I really don't know where this can be useful. If the +<var>domain_name</var> is <code>NULL</code> or <var>category</var> has an value beside +the known ones, the result is undefined. It should also be noted that +this function is not part of the second known implementation of this +function family, the one found in Solaris. + + <p>A second ambiguity can arise by the fact, that perhaps more than one +domain has the same name. This can be solved by specifying where the +needed message catalog files can be found. + +<pre class="example"> char *bindtextdomain (const char *domain_name, + const char *dir_name); +</pre> + <p>Calling this function binds the given domain to a file in the specified +directory (how this file is determined follows below). Especially a +file in the systems default place is not favored against the specified +file anymore (as it would be by solely using <code>textdomain</code>). A +<code>NULL</code> pointer for the <var>dir_name</var> parameter returns the binding +associated with <var>domain_name</var>. If <var>domain_name</var> itself is +<code>NULL</code> nothing happens and a <code>NULL</code> pointer is returned. Here +again as for all the other functions is true that none of the return +value must be changed! + + <p>It is important to remember that relative path names for the +<var>dir_name</var> parameter can be trouble. Since the path is always +computed relative to the current directory different results will be +achieved when the program executes a <code>chdir</code> command. Relative +paths should always be avoided to avoid dependencies and +unreliabilities. + +<div class="node"> +<a name="Locating-Catalogs"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Charset-conversion">Charset conversion</a>, +Previous: <a rel="previous" accesskey="p" href="#Ambiguities">Ambiguities</a>, +Up: <a rel="up" accesskey="u" href="#gettext">gettext</a> + +</div> + +<h4 class="subsection">11.2.3 Locating Message Catalog Files</h4> + + <p><a name="index-message-catalog-files-location-1073"></a> +Because many different languages for many different packages have to be +stored we need some way to add these information to file message catalog +files. The way usually used in Unix environments is have this encoding +in the file name. This is also done here. The directory name given in +<code>bindtextdomain</code>s second argument (or the default directory), +followed by the name of the locale, the locale category, and the domain name +are concatenated: + +<pre class="example"> <var>dir_name</var>/<var>locale</var>/LC_<var>category</var>/<var>domain_name</var>.mo +</pre> + <p>The default value for <var>dir_name</var> is system specific. For the GNU +library, and for packages adhering to its conventions, it's: +<pre class="example"> /usr/local/share/locale +</pre> + <p class="noindent"><var>locale</var> is the name of the locale category which is designated by +<code>LC_</code><var>category</var>. For <code>gettext</code> and <code>dgettext</code> this +<code>LC_</code><var>category</var> is always <code>LC_MESSAGES</code>.<a rel="footnote" href="#fn-3" name="fnd-3"><sup>3</sup></a> +The name of the locale category is determined through +<code>setlocale (LC_</code><var>category</var><code>, NULL)</code>. +<a rel="footnote" href="#fn-4" name="fnd-4"><sup>4</sup></a> +When using the function <code>dcgettext</code>, you can specify the locale category +through the third argument. + +<div class="node"> +<a name="Charset-conversion"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Contexts">Contexts</a>, +Previous: <a rel="previous" accesskey="p" href="#Locating-Catalogs">Locating Catalogs</a>, +Up: <a rel="up" accesskey="u" href="#gettext">gettext</a> + +</div> + +<h4 class="subsection">11.2.4 How to specify the output character set <code>gettext</code> uses</h4> + + <p><a name="index-charset-conversion-at-runtime-1074"></a><a name="index-encoding-conversion-at-runtime-1075"></a> +<code>gettext</code> not only looks up a translation in a message catalog. It +also converts the translation on the fly to the desired output character +set. This is useful if the user is working in a different character set +than the translator who created the message catalog, because it avoids +distributing variants of message catalogs which differ only in the +character set. + + <p>The output character set is, by default, the value of <code>nl_langinfo +(CODESET)</code>, which depends on the <code>LC_CTYPE</code> part of the current +locale. But programs which store strings in a locale independent way +(e.g. UTF-8) can request that <code>gettext</code> and related functions +return the translations in that encoding, by use of the +<code>bind_textdomain_codeset</code> function. + + <p>Note that the <var>msgid</var> argument to <code>gettext</code> is not subject to +character set conversion. Also, when <code>gettext</code> does not find a +translation for <var>msgid</var>, it returns <var>msgid</var> unchanged – +independently of the current output character set. It is therefore +recommended that all <var>msgid</var>s be US-ASCII strings. + +<div class="defun"> +— Function: char * <b>bind_textdomain_codeset</b> (<var>const char *domainname, const char *codeset</var>)<var><a name="index-bind_005ftextdomain_005fcodeset-1076"></a></var><br> +<blockquote><p>The <code>bind_textdomain_codeset</code> function can be used to specify the +output character set for message catalogs for domain <var>domainname</var>. +The <var>codeset</var> argument must be a valid codeset name which can be used +for the <code>iconv_open</code> function, or a null pointer. + + <p>If the <var>codeset</var> parameter is the null pointer, +<code>bind_textdomain_codeset</code> returns the currently selected codeset +for the domain with the name <var>domainname</var>. It returns <code>NULL</code> if +no codeset has yet been selected. + + <p>The <code>bind_textdomain_codeset</code> function can be used several times. +If used multiple times with the same <var>domainname</var> argument, the +later call overrides the settings made by the earlier one. + + <p>The <code>bind_textdomain_codeset</code> function returns a pointer to a +string containing the name of the selected codeset. The string is +allocated internally in the function and must not be changed by the +user. If the system went out of core during the execution of +<code>bind_textdomain_codeset</code>, the return value is <code>NULL</code> and the +global variable <var>errno</var> is set accordingly. +</p></blockquote></div> + +<div class="node"> +<a name="Contexts"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Plural-forms">Plural forms</a>, +Previous: <a rel="previous" accesskey="p" href="#Charset-conversion">Charset conversion</a>, +Up: <a rel="up" accesskey="u" href="#gettext">gettext</a> + +</div> + +<h4 class="subsection">11.2.5 Using contexts for solving ambiguities</h4> + + <p><a name="index-context-1077"></a><a name="index-GUI-programs-1078"></a><a name="index-translating-menu-entries-1079"></a><a name="index-menu-entries-1080"></a> +One place where the <code>gettext</code> functions, if used normally, have big +problems is within programs with graphical user interfaces (GUIs). The +problem is that many of the strings which have to be translated are very +short. They have to appear in pull-down menus which restricts the +length. But strings which are not containing entire sentences or at +least large fragments of a sentence may appear in more than one +situation in the program but might have different translations. This is +especially true for the one-word strings which are frequently used in +GUI programs. + + <p>As a consequence many people say that the <code>gettext</code> approach is +wrong and instead <code>catgets</code> should be used which indeed does not +have this problem. But there is a very simple and powerful method to +handle this kind of problems with the <code>gettext</code> functions. + + <p>Contexts can be added to strings to be translated. A context dependent +translation lookup is when a translation for a given string is searched, +that is limited to a given context. The translation for the same string +in a different context can be different. The different translations of +the same string in different contexts can be stored in the in the same +MO file, and can be edited by the translator in the same PO file. + + <p>The <samp><span class="file">gettext.h</span></samp> include file contains the lookup macros for strings +with contexts. They are implemented as thin macros and inline functions +over the functions from <code><libintl.h></code>. + + <p><a name="index-pgettext-1081"></a> +<pre class="example"> const char *pgettext (const char *msgctxt, const char *msgid); +</pre> + <p>In a call of this macro, <var>msgctxt</var> and <var>msgid</var> must be string +literals. The macro returns the translation of <var>msgid</var>, restricted +to the context given by <var>msgctxt</var>. + + <p>The <var>msgctxt</var> string is visible in the PO file to the translator. +You should try to make it somehow canonical and never changing. Because +every time you change an <var>msgctxt</var>, the translator will have to review +the translation of <var>msgid</var>. + + <p>Finding a canonical <var>msgctxt</var> string that doesn't change over time can +be hard. But you shouldn't use the file name or class name containing the +<code>pgettext</code> call – because it is a common development task to rename +a file or a class, and it shouldn't cause translator work. Also you shouldn't +use a comment in the form of a complete English sentence as <var>msgctxt</var> – +because orthography or grammar changes are often applied to such sentences, +and again, it shouldn't force the translator to do a review. + + <p>The ‘<samp><span class="samp">p</span></samp>’ in ‘<samp><span class="samp">pgettext</span></samp>’ stands for “particular”: <code>pgettext</code> +fetches a particular translation of the <var>msgid</var>. + + <p><a name="index-dpgettext-1082"></a><a name="index-dcpgettext-1083"></a> +<pre class="example"> const char *dpgettext (const char *domain_name, + const char *msgctxt, const char *msgid); + const char *dcpgettext (const char *domain_name, + const char *msgctxt, const char *msgid, + int category); +</pre> + <p>These are generalizations of <code>pgettext</code>. They behave similarly to +<code>dgettext</code> and <code>dcgettext</code>, respectively. The <var>domain_name</var> +argument defines the translation domain. The <var>category</var> argument +allows to use another locale category than <code>LC_MESSAGES</code>. + + <p>As as example consider the following fictional situation. A GUI program +has a menu bar with the following entries: + +<pre class="smallexample"> +------------+------------+--------------------------------------+ + | File | Printer | | + +------------+------------+--------------------------------------+ + | Open | | Select | + | New | | Open | + +----------+ | Connect | + +----------+ +</pre> + <p>To have the strings <code>File</code>, <code>Printer</code>, <code>Open</code>, +<code>New</code>, <code>Select</code>, and <code>Connect</code> translated there has to be +at some point in the code a call to a function of the <code>gettext</code> +family. But in two places the string passed into the function would be +<code>Open</code>. The translations might not be the same and therefore we +are in the dilemma described above. + + <p>What distinguishes the two places is the menu path from the menu root to +the particular menu entries: + +<pre class="smallexample"> Menu|File + Menu|Printer + Menu|File|Open + Menu|File|New + Menu|Printer|Select + Menu|Printer|Open + Menu|Printer|Connect +</pre> + <p>The context is thus the menu path without its last part. So, the calls +look like this: + +<pre class="smallexample"> pgettext ("Menu|", "File") + pgettext ("Menu|", "Printer") + pgettext ("Menu|File|", "Open") + pgettext ("Menu|File|", "New") + pgettext ("Menu|Printer|", "Select") + pgettext ("Menu|Printer|", "Open") + pgettext ("Menu|Printer|", "Connect") +</pre> + <p>Whether or not to use the ‘<samp><span class="samp">|</span></samp>’ character at the end of the context is a +matter of style. + + <p>For more complex cases, where the <var>msgctxt</var> or <var>msgid</var> are not +string literals, more general macros are available: + + <p><a name="index-pgettext_005fexpr-1084"></a><a name="index-dpgettext_005fexpr-1085"></a><a name="index-dcpgettext_005fexpr-1086"></a> +<pre class="example"> const char *pgettext_expr (const char *msgctxt, const char *msgid); + const char *dpgettext_expr (const char *domain_name, + const char *msgctxt, const char *msgid); + const char *dcpgettext_expr (const char *domain_name, + const char *msgctxt, const char *msgid, + int category); +</pre> + <p>Here <var>msgctxt</var> and <var>msgid</var> can be arbitrary string-valued expressions. +These macros are more general. But in the case that both argument expressions +are string literals, the macros without the ‘<samp><span class="samp">_expr</span></samp>’ suffix are more +efficient. + +<div class="node"> +<a name="Plural-forms"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Optimized-gettext">Optimized gettext</a>, +Previous: <a rel="previous" accesskey="p" href="#Contexts">Contexts</a>, +Up: <a rel="up" accesskey="u" href="#gettext">gettext</a> + +</div> + +<h4 class="subsection">11.2.6 Additional functions for plural forms</h4> + + <p><a name="index-plural-forms-1087"></a> +The functions of the <code>gettext</code> family described so far (and all the +<code>catgets</code> functions as well) have one problem in the real world +which have been neglected completely in all existing approaches. What +is meant here is the handling of plural forms. + + <p>Looking through Unix source code before the time anybody thought about +internationalization (and, sadly, even afterwards) one can often find +code similar to the following: + +<pre class="smallexample"> printf ("%d file%s deleted", n, n == 1 ? "" : "s"); +</pre> + <p class="noindent">After the first complaints from people internationalizing the code people +either completely avoided formulations like this or used strings like +<code>"file(s)"</code>. Both look unnatural and should be avoided. First +tries to solve the problem correctly looked like this: + +<pre class="smallexample"> if (n == 1) + printf ("%d file deleted", n); + else + printf ("%d files deleted", n); +</pre> + <p>But this does not solve the problem. It helps languages where the +plural form of a noun is not simply constructed by adding an +‘s’ +but that is all. Once again people fell into the trap of believing the +rules their language is using are universal. But the handling of plural +forms differs widely between the language families. For example, +Rafal Maszkowski <code><rzm@mat.uni.torun.pl></code> reports: + + <blockquote> +In Polish we use e.g. plik (file) this way: +<pre class="example"> 1 plik + 2,3,4 pliki + 5-21 pliko'w + 22-24 pliki + 25-31 pliko'w +</pre> + <p>and so on (o' means 8859-2 oacute which should be rather okreska, +similar to aogonek). +</blockquote> + + <p>There are two things which can differ between languages (and even inside +language families); + + <ul> +<li>The form how plural forms are built differs. This is a problem with +languages which have many irregularities. German, for instance, is a +drastic case. Though English and German are part of the same language +family (Germanic), the almost regular forming of plural noun forms +(appending an +‘s’) +is hardly found in German. + + <li>The number of plural forms differ. This is somewhat surprising for +those who only have experiences with Romanic and Germanic languages +since here the number is the same (there are two). + + <p>But other language families have only one form or many forms. More +information on this in an extra section. +</ul> + + <p>The consequence of this is that application writers should not try to +solve the problem in their code. This would be localization since it is +only usable for certain, hardcoded language environments. Instead the +extended <code>gettext</code> interface should be used. + + <p>These extra functions are taking instead of the one key string two +strings and a numerical argument. The idea behind this is that using +the numerical argument and the first string as a key, the implementation +can select using rules specified by the translator the right plural +form. The two string arguments then will be used to provide a return +value in case no message catalog is found (similar to the normal +<code>gettext</code> behavior). In this case the rules for Germanic language +is used and it is assumed that the first string argument is the singular +form, the second the plural form. + + <p>This has the consequence that programs without language catalogs can +display the correct strings only if the program itself is written using +a Germanic language. This is a limitation but since the GNU C library +(as well as the GNU <code>gettext</code> package) are written as part of the +GNU package and the coding standards for the GNU project require program +being written in English, this solution nevertheless fulfills its +purpose. + +<div class="defun"> +— Function: char * <b>ngettext</b> (<var>const char *msgid1, const char *msgid2, unsigned long int n</var>)<var><a name="index-ngettext-1088"></a></var><br> +<blockquote><p>The <code>ngettext</code> function is similar to the <code>gettext</code> function +as it finds the message catalogs in the same way. But it takes two +extra arguments. The <var>msgid1</var> parameter must contain the singular +form of the string to be converted. It is also used as the key for the +search in the catalog. The <var>msgid2</var> parameter is the plural form. +The parameter <var>n</var> is used to determine the plural form. If no +message catalog is found <var>msgid1</var> is returned if <code>n == 1</code>, +otherwise <code>msgid2</code>. + + <p>An example for the use of this function is: + + <pre class="smallexample"> printf (ngettext ("%d file removed", "%d files removed", n), n); +</pre> + <p>Please note that the numeric value <var>n</var> has to be passed to the +<code>printf</code> function as well. It is not sufficient to pass it only to +<code>ngettext</code>. + + <p>In the English singular case, the number – always 1 – can be replaced with +"one": + + <pre class="smallexample"> printf (ngettext ("One file removed", "%d files removed", n), n); +</pre> + <p class="noindent">This works because the ‘<samp><span class="samp">printf</span></samp>’ function discards excess arguments that +are not consumed by the format string. + + <p>If this function is meant to yield a format string that takes two or more +arguments, you can not use it like this: + + <pre class="smallexample"> printf (ngettext ("%d file removed from directory %s", + "%d files removed from directory %s", + n, dir), + n); +</pre> + <p class="noindent">because in many languages the translators want to replace the ‘<samp><span class="samp">%d</span></samp>’ +with an explicit word in the singular case, just like “one” in English, +and C format strings cannot consume the second argument but skip the first +argument. Instead, you have to reorder the arguments so that ‘<samp><span class="samp">n</span></samp>’ +comes last: + + <pre class="smallexample"> printf (ngettext ("%$2d file removed from directory %$1s", + "%$2d files removed from directory %$1s", + dir, n), + n); +</pre> + <p class="noindent">See <a href="#c_002dformat">c-format</a> for details about this argument reordering syntax. + + <p>When you know that the value of <code>n</code> is within a given range, you can +specify it as a comment directed to the <code>xgettext</code> tool. This +information may help translators to use more adequate translations. Like +this: + + <pre class="smallexample"> if (days > 7 && days < 14) + /* xgettext: range: 1..6 */ + printf (ngettext ("one week and one day", "one week and %d days", + days - 7), + days - 7); +</pre> + <p>It is also possible to use this function when the strings don't contain a +cardinal number: + + <pre class="smallexample"> puts (ngettext ("Delete the selected file?", + "Delete the selected files?", + n)); +</pre> + <p>In this case the number <var>n</var> is only used to choose the plural form. +</p></blockquote></div> + +<div class="defun"> +— Function: char * <b>dngettext</b> (<var>const char *domain, const char *msgid1, const char *msgid2, unsigned long int n</var>)<var><a name="index-dngettext-1089"></a></var><br> +<blockquote><p>The <code>dngettext</code> is similar to the <code>dgettext</code> function in the +way the message catalog is selected. The difference is that it takes +two extra parameter to provide the correct plural form. These two +parameters are handled in the same way <code>ngettext</code> handles them. +</p></blockquote></div> + +<div class="defun"> +— Function: char * <b>dcngettext</b> (<var>const char *domain, const char *msgid1, const char *msgid2, unsigned long int n, int category</var>)<var><a name="index-dcngettext-1090"></a></var><br> +<blockquote><p>The <code>dcngettext</code> is similar to the <code>dcgettext</code> function in the +way the message catalog is selected. The difference is that it takes +two extra parameter to provide the correct plural form. These two +parameters are handled in the same way <code>ngettext</code> handles them. +</p></blockquote></div> + + <p>Now, how do these functions solve the problem of the plural forms? +Without the input of linguists (which was not available) it was not +possible to determine whether there are only a few different forms in +which plural forms are formed or whether the number can increase with +every new supported language. + + <p>Therefore the solution implemented is to allow the translator to specify +the rules of how to select the plural form. Since the formula varies +with every language this is the only viable solution except for +hardcoding the information in the code (which still would require the +possibility of extensions to not prevent the use of new languages). + + <p><a name="index-specifying-plural-form-in-a-PO-file-1091"></a><a name="index-nplurals_0040r_007b_002c-in-a-PO-file-header_007d-1092"></a><a name="index-plural_0040r_007b_002c-in-a-PO-file-header_007d-1093"></a>The information about the plural form selection has to be stored in the +header entry of the PO file (the one with the empty <code>msgid</code> string). +The plural form information looks like this: + +<pre class="smallexample"> Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1; +</pre> + <p>The <code>nplurals</code> value must be a decimal number which specifies how +many different plural forms exist for this language. The string +following <code>plural</code> is an expression which is using the C language +syntax. Exceptions are that no negative numbers are allowed, numbers +must be decimal, and the only variable allowed is <code>n</code>. Spaces are +allowed in the expression, but backslash-newlines are not; in the +examples below the backslash-newlines are present for formatting purposes +only. This expression will be evaluated whenever one of the functions +<code>ngettext</code>, <code>dngettext</code>, or <code>dcngettext</code> is called. The +numeric value passed to these functions is then substituted for all uses +of the variable <code>n</code> in the expression. The resulting value then +must be greater or equal to zero and smaller than the value given as the +value of <code>nplurals</code>. + +<p class="noindent"><a name="index-plural-form-formulas-1094"></a>The following rules are known at this point. The language with families +are listed. But this does not necessarily mean the information can be +generalized for the whole family (as can be easily seen in the table +below).<a rel="footnote" href="#fn-5" name="fnd-5"><sup>5</sup></a> + + <dl> +<dt>Only one form:<dd>Some languages only require one single form. There is no distinction +between the singular and plural form. An appropriate header entry +would look like this: + + <pre class="smallexample"> Plural-Forms: nplurals=1; plural=0; +</pre> + <p class="noindent">Languages with this property include: + + <dl> +<dt>Asian family<dd>Japanese, <!-- 122.1 million speakers --> +Vietnamese, <!-- 68.6 million speakers --> +Korean <!-- 66.3 million speakers --> +</dl> + + <br><dt>Two forms, singular used for one only<dd>This is the form used in most existing programs since it is what English +is using. A header entry would look like this: + + <pre class="smallexample"> Plural-Forms: nplurals=2; plural=n != 1; +</pre> + <p>(Note: this uses the feature of C expressions that boolean expressions +have to value zero or one.) + + <p class="noindent">Languages with this property include: + + <dl> +<dt>Germanic family<dd>English, <!-- 328.0 million speakers --> +German, <!-- 96.9 million speakers --> +Dutch, <!-- 21.7 million speakers --> +Swedish, <!-- 8.3 million speakers --> +Danish, <!-- 5.6 million speakers --> +Norwegian, <!-- 4.6 million speakers --> +Faroese <!-- 0.05 million speakers --> +<br><dt>Romanic family<dd>Spanish, <!-- 328.5 million speakers --> +Portuguese, <!-- 178.0 million speakers - 163 million Brazilian Portuguese --> +Italian, <!-- 61.7 million speakers --> +Bulgarian <!-- 9.1 million speakers --> +<br><dt>Latin/Greek family<dd>Greek <!-- 13.1 million speakers --> +<br><dt>Finno-Ugric family<dd>Finnish, <!-- 5.0 million speakers --> +Estonian <!-- 1.0 million speakers --> +<br><dt>Semitic family<dd>Hebrew <!-- 5.3 million speakers --> +<br><dt>Artificial<dd>Esperanto <!-- 2 million speakers --> +</dl> + + <p class="noindent">Other languages using the same header entry are: + + <dl> +<dt>Finno-Ugric family<dd>Hungarian <!-- 12.5 million speakers --> +<br><dt>Turkic/Altaic family<dd>Turkish <!-- 50.8 million speakers --> +</dl> + + <p>Hungarian does not appear to have a plural if you look at sentences involving +cardinal numbers. For example, “1 apple” is “1 alma”, and “123 apples” is +“123 alma”. But when the number is not explicit, the distinction between +singular and plural exists: “the apple” is “az alma”, and “the apples” is +“az almák”. Since <code>ngettext</code> has to support both types of sentences, +it is classified here, under “two forms”. + + <p>The same holds for Turkish: “1 apple” is “1 elma”, and “123 apples” is +“123 elma”. But when the number is omitted, the distinction between singular +and plural exists: “the apple” is “elma”, and “the apples” is +“elmalar”. + + <br><dt>Two forms, singular used for zero and one<dd>Exceptional case in the language family. The header entry would be: + + <pre class="smallexample"> Plural-Forms: nplurals=2; plural=n>1; +</pre> + <p class="noindent">Languages with this property include: + + <dl> +<dt>Romanic family<dd>Brazilian Portuguese, <!-- 163 million speakers --> +French <!-- 67.8 million speakers --> +</dl> + + <br><dt>Three forms, special case for zero<dd>The header entry would be: + + <pre class="smallexample"> Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2; +</pre> + <p class="noindent">Languages with this property include: + + <dl> +<dt>Baltic family<dd>Latvian <!-- 1.5 million speakers --> +</dl> + + <br><dt>Three forms, special cases for one and two<dd>The header entry would be: + + <pre class="smallexample"> Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2; +</pre> + <p class="noindent">Languages with this property include: + + <dl> +<dt>Celtic<dd>Gaeilge (Irish) <!-- 0.4 million speakers --> +</dl> + + <br><dt>Three forms, special case for numbers ending in 00 or [2-9][0-9]<dd>The header entry would be: + + <pre class="smallexample"> Plural-Forms: nplurals=3; \ + plural=n==1 ? 0 : (n==0 || (n%100 > 0 && n%100 < 20)) ? 1 : 2; +</pre> + <p class="noindent">Languages with this property include: + + <dl> +<dt>Romanic family<dd>Romanian <!-- 23.4 million speakers --> +</dl> + + <br><dt>Three forms, special case for numbers ending in 1[2-9]<dd>The header entry would look like this: + + <pre class="smallexample"> Plural-Forms: nplurals=3; \ + plural=n%10==1 && n%100!=11 ? 0 : \ + n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2; +</pre> + <p class="noindent">Languages with this property include: + + <dl> +<dt>Baltic family<dd>Lithuanian <!-- 3.2 million speakers --> +</dl> + + <br><dt>Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]<dd>The header entry would look like this: + + <pre class="smallexample"> Plural-Forms: nplurals=3; \ + plural=n%10==1 && n%100!=11 ? 0 : \ + n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2; +</pre> + <p class="noindent">Languages with this property include: + + <dl> +<dt>Slavic family<dd>Russian, <!-- 143.6 million speakers --> +Ukrainian, <!-- 37.0 million speakers --> +Serbian, <!-- 7.0 million speakers --> +Croatian <!-- 5.5 million speakers --> +</dl> + + <br><dt>Three forms, special cases for 1 and 2, 3, 4<dd>The header entry would look like this: + + <pre class="smallexample"> Plural-Forms: nplurals=3; \ + plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2; +</pre> + <p class="noindent">Languages with this property include: + + <dl> +<dt>Slavic family<dd>Czech, <!-- 9.5 million speakers --> +Slovak <!-- 5.0 million speakers --> +</dl> + + <br><dt>Three forms, special case for one and some numbers ending in 2, 3, or 4<dd>The header entry would look like this: + + <pre class="smallexample"> Plural-Forms: nplurals=3; \ + plural=n==1 ? 0 : \ + n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2; +</pre> + <p class="noindent">Languages with this property include: + + <dl> +<dt>Slavic family<dd>Polish <!-- 40.0 million speakers --> +</dl> + + <br><dt>Four forms, special case for one and all numbers ending in 02, 03, or 04<dd>The header entry would look like this: + + <pre class="smallexample"> Plural-Forms: nplurals=4; \ + plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3; +</pre> + <p class="noindent">Languages with this property include: + + <dl> +<dt>Slavic family<dd>Slovenian <!-- 1.9 million speakers --> +</dl> + </dl> + + <p>You might now ask, <code>ngettext</code> handles only numbers <var>n</var> of type +‘<samp><span class="samp">unsigned long</span></samp>’. What about larger integer types? What about negative +numbers? What about floating-point numbers? + + <p>About larger integer types, such as ‘<samp><span class="samp">uintmax_t</span></samp>’ or +‘<samp><span class="samp">unsigned long long</span></samp>’: they can be handled by reducing the value to a +range that fits in an ‘<samp><span class="samp">unsigned long</span></samp>’. Simply casting the value to +‘<samp><span class="samp">unsigned long</span></samp>’ would not do the right thing, since it would treat +<code>ULONG_MAX + 1</code> like zero, <code>ULONG_MAX + 2</code> like singular, and +the like. Here you can exploit the fact that all mentioned plural form +formulas eventually become periodic, with a period that is a divisor of 100 +(or 1000 or 1000000). So, when you reduce a large value to another one in +the range [1000000, 1999999] that ends in the same 6 decimal digits, you +can assume that it will lead to the same plural form selection. This code +does this: + +<pre class="smallexample"> #include <inttypes.h> + uintmax_t nbytes = ...; + printf (ngettext ("The file has %"PRIuMAX" byte.", + "The file has %"PRIuMAX" bytes.", + (nbytes > ULONG_MAX + ? (nbytes % 1000000) + 1000000 + : nbytes)), + nbytes); +</pre> + <p>Negative and floating-point values usually represent physical entities for +which singular and plural don't clearly apply. In such cases, there is no +need to use <code>ngettext</code>; a simple <code>gettext</code> call with a form suitable +for all values will do. For example: + +<pre class="smallexample"> printf (gettext ("Time elapsed: %.3f seconds"), + num_milliseconds * 0.001); +</pre> + <p class="noindent">Even if <var>num_milliseconds</var> happens to be a multiple of 1000, the output +<pre class="smallexample"> Time elapsed: 1.000 seconds +</pre> + <p class="noindent">is acceptable in English, and similarly for other languages. + + <p>The translators' perspective regarding plural forms is explained in +<a href="#Translating-plural-forms">Translating plural forms</a>. + +<div class="node"> +<a name="Optimized-gettext"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Plural-forms">Plural forms</a>, +Up: <a rel="up" accesskey="u" href="#gettext">gettext</a> + +</div> + +<h4 class="subsection">11.2.7 Optimization of the *gettext functions</h4> + + <p><a name="index-optimization-of-_0040code_007bgettext_007d-functions-1095"></a> +At this point of the discussion we should talk about an advantage of the +GNU <code>gettext</code> implementation. Some readers might have pointed out +that an internationalized program might have a poor performance if some +string has to be translated in an inner loop. While this is unavoidable +when the string varies from one run of the loop to the other it is +simply a waste of time when the string is always the same. Take the +following example: + +<pre class="example"> { + while (...) + { + puts (gettext ("Hello world")); + } + } +</pre> + <p class="noindent">When the locale selection does not change between two runs the resulting +string is always the same. One way to use this is: + +<pre class="example"> { + str = gettext ("Hello world"); + while (...) + { + puts (str); + } + } +</pre> + <p class="noindent">But this solution is not usable in all situation (e.g. when the locale +selection changes) nor does it lead to legible code. + + <p>For this reason, GNU <code>gettext</code> caches previous translation results. +When the same translation is requested twice, with no new message +catalogs being loaded in between, <code>gettext</code> will, the second time, +find the result through a single cache lookup. + +<div class="node"> +<a name="Comparison"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Using-libintl_002ea">Using libintl.a</a>, +Previous: <a rel="previous" accesskey="p" href="#gettext">gettext</a>, +Up: <a rel="up" accesskey="u" href="#Programmers">Programmers</a> + +</div> + +<h3 class="section">11.3 Comparing the Two Interfaces</h3> + + <p><a name="index-g_t_0040code_007bgettext_007d-vs-_0040code_007bcatgets_007d-1096"></a><a name="index-comparison-of-interfaces-1097"></a> +<!-- FIXME: arguments to catgets vs. gettext --> +<!-- Partly done 950718 - drepper --> + + <p>The following discussion is perhaps a little bit colored. As said +above we implemented GNU <code>gettext</code> following the Uniforum +proposal and this surely has its reasons. But it should show how we +came to this decision. + + <p>First we take a look at the developing process. When we write an +application using NLS provided by <code>gettext</code> we proceed as always. +Only when we come to a string which might be seen by the users and thus +has to be translated we use <code>gettext("...")</code> instead of +<code>"..."</code>. At the beginning of each source file (or in a central +header file) we define + +<pre class="example"> #define gettext(String) (String) +</pre> + <p>Even this definition can be avoided when the system supports the +<code>gettext</code> function in its C library. When we compile this code the +result is the same as if no NLS code is used. When you take a look at +the GNU <code>gettext</code> code you will see that we use <code>_("...")</code> +instead of <code>gettext("...")</code>. This reduces the number of +additional characters per translatable string to <em>3</em> (in words: +three). + + <p>When now a production version of the program is needed we simply replace +the definition + +<pre class="example"> #define _(String) (String) +</pre> + <p class="noindent">by + + <p><a name="index-include-file-_0040file_007blibintl_002eh_007d-1098"></a> +<pre class="example"> #include <libintl.h> + #define _(String) gettext (String) +</pre> + <p class="noindent">Additionally we run the program <samp><span class="file">xgettext</span></samp> on all source code file +which contain translatable strings and that's it: we have a running +program which does not depend on translations to be available, but which +can use any that becomes available. + + <p><a name="index-g_t_0040code_007bN_005f_007d_002c-a-convenience-macro-1099"></a>The same procedure can be done for the <code>gettext_noop</code> invocations +(see <a href="#Special-cases">Special cases</a>). One usually defines <code>gettext_noop</code> as a +no-op macro. So you should consider the following code for your project: + +<pre class="example"> #define gettext_noop(String) String + #define N_(String) gettext_noop (String) +</pre> + <p><code>N_</code> is a short form similar to <code>_</code>. The <samp><span class="file">Makefile</span></samp> in +the <samp><span class="file">po/</span></samp> directory of GNU <code>gettext</code> knows by default both of the +mentioned short forms so you are invited to follow this proposal for +your own ease. + + <p>Now to <code>catgets</code>. The main problem is the work for the +programmer. Every time he comes to a translatable string he has to +define a number (or a symbolic constant) which has also be defined in +the message catalog file. He also has to take care for duplicate +entries, duplicate message IDs etc. If he wants to have the same +quality in the message catalog as the GNU <code>gettext</code> program +provides he also has to put the descriptive comments for the strings and +the location in all source code files in the message catalog. This is +nearly a Mission: Impossible. + + <p>But there are also some points people might call advantages speaking for +<code>catgets</code>. If you have a single word in a string and this string +is used in different contexts it is likely that in one or the other +language the word has different translations. Example: + +<pre class="example"> printf ("%s: %d", gettext ("number"), number_of_errors) + + printf ("you should see %d %s", number_count, + number_count == 1 ? gettext ("number") : gettext ("numbers")) +</pre> + <p>Here we have to translate two times the string <code>"number"</code>. Even +if you do not speak a language beside English it might be possible to +recognize that the two words have a different meaning. In German the +first appearance has to be translated to <code>"Anzahl"</code> and the second +to <code>"Zahl"</code>. + + <p>Now you can say that this example is really esoteric. And you are +right! This is exactly how we felt about this problem and decide that +it does not weight that much. The solution for the above problem could +be very easy: + +<pre class="example"> printf ("%s %d", gettext ("number:"), number_of_errors) + + printf (number_count == 1 ? gettext ("you should see %d number") + : gettext ("you should see %d numbers"), + number_count) +</pre> + <p>We believe that we can solve all conflicts with this method. If it is +difficult one can also consider changing one of the conflicting string a +little bit. But it is not impossible to overcome. + + <p><code>catgets</code> allows same original entry to have different translations, +but <code>gettext</code> has another, scalable approach for solving ambiguities +of this kind: See <a href="#Ambiguities">Ambiguities</a>. + +<div class="node"> +<a name="Using-libintl.a"></a> +<a name="Using-libintl_002ea"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#gettext-grok">gettext grok</a>, +Previous: <a rel="previous" accesskey="p" href="#Comparison">Comparison</a>, +Up: <a rel="up" accesskey="u" href="#Programmers">Programmers</a> + +</div> + +<h3 class="section">11.4 Using libintl.a in own programs</h3> + + <p>Starting with version 0.9.4 the library <code>libintl.h</code> should be +self-contained. I.e., you can use it in your own programs without +providing additional functions. The <samp><span class="file">Makefile</span></samp> will put the header +and the library in directories selected using the <code>$(prefix)</code>. + +<div class="node"> +<a name="gettext-grok"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Temp-Programmers">Temp Programmers</a>, +Previous: <a rel="previous" accesskey="p" href="#Using-libintl_002ea">Using libintl.a</a>, +Up: <a rel="up" accesskey="u" href="#Programmers">Programmers</a> + +</div> + +<h3 class="section">11.5 Being a <code>gettext</code> grok</h3> + + <p><strong> NOTE: </strong> This documentation section is outdated and needs to be +revised. + + <p>To fully exploit the functionality of the GNU <code>gettext</code> library it +is surely helpful to read the source code. But for those who don't want +to spend that much time in reading the (sometimes complicated) code here +is a list comments: + + <ul> +<li>Changing the language at runtime +<a name="index-language-selection-at-runtime-1100"></a> +For interactive programs it might be useful to offer a selection of the +used language at runtime. To understand how to do this one need to know +how the used language is determined while executing the <code>gettext</code> +function. The method which is presented here only works correctly +with the GNU implementation of the <code>gettext</code> functions. + + <p>In the function <code>dcgettext</code> at every call the current setting of +the highest priority environment variable is determined and used. +Highest priority means here the following list with decreasing +priority: + + <ol type=1 start=1> +<a name="index-LANGUAGE_0040r_007b_002c-environment-variable_007d-1101"></a><li><code>LANGUAGE</code> +<a name="index-LC_005fALL_0040r_007b_002c-environment-variable_007d-1102"></a><li><code>LC_ALL</code> +<a name="index-LC_005fCTYPE_0040r_007b_002c-environment-variable_007d-1103"></a><a name="index-LC_005fNUMERIC_0040r_007b_002c-environment-variable_007d-1104"></a><a name="index-LC_005fTIME_0040r_007b_002c-environment-variable_007d-1105"></a><a name="index-LC_005fCOLLATE_0040r_007b_002c-environment-variable_007d-1106"></a><a name="index-LC_005fMONETARY_0040r_007b_002c-environment-variable_007d-1107"></a><a name="index-LC_005fMESSAGES_0040r_007b_002c-environment-variable_007d-1108"></a><li><code>LC_xxx</code>, according to selected locale category +<a name="index-LANG_0040r_007b_002c-environment-variable_007d-1109"></a><li><code>LANG</code> + </ol> + + <p>Afterwards the path is constructed using the found value and the +translation file is loaded if available. + + <p>What happens now when the value for, say, <code>LANGUAGE</code> changes? According +to the process explained above the new value of this variable is found +as soon as the <code>dcgettext</code> function is called. But this also means +the (perhaps) different message catalog file is loaded. In other +words: the used language is changed. + + <p>But there is one little hook. The code for gcc-2.7.0 and up provides +some optimization. This optimization normally prevents the calling of +the <code>dcgettext</code> function as long as no new catalog is loaded. But +if <code>dcgettext</code> is not called the program also cannot find the +<code>LANGUAGE</code> variable be changed (see <a href="#Optimized-gettext">Optimized gettext</a>). A +solution for this is very easy. Include the following code in the +language switching function. + + <pre class="example"> /* Change language. */ + setenv ("LANGUAGE", "fr", 1); + + /* Make change known. */ + { + extern int _nl_msg_cat_cntr; + ++_nl_msg_cat_cntr; + } +</pre> + <p><a name="index-g_t_0040code_007b_005fnl_005fmsg_005fcat_005fcntr_007d-1110"></a>The variable <code>_nl_msg_cat_cntr</code> is defined in <samp><span class="file">loadmsgcat.c</span></samp>. +You don't need to know what this is for. But it can be used to detect +whether a <code>gettext</code> implementation is GNU gettext and not non-GNU +system's native gettext implementation. + + </ul> + +<div class="node"> +<a name="Temp-Programmers"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#gettext-grok">gettext grok</a>, +Up: <a rel="up" accesskey="u" href="#Programmers">Programmers</a> + +</div> + +<h3 class="section">11.6 Temporary Notes for the Programmers Chapter</h3> + + <p><strong> NOTE: </strong> This documentation section is outdated and needs to be +revised. + +<ul class="menu"> +<li><a accesskey="1" href="#Temp-Implementations">Temp Implementations</a>: Temporary - Two Possible Implementations +<li><a accesskey="2" href="#Temp-catgets">Temp catgets</a>: Temporary - About <code>catgets</code> +<li><a accesskey="3" href="#Temp-WSI">Temp WSI</a>: Temporary - Why a single implementation +<li><a accesskey="4" href="#Temp-Notes">Temp Notes</a>: Temporary - Notes +</ul> + +<div class="node"> +<a name="Temp-Implementations"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Temp-catgets">Temp catgets</a>, +Previous: <a rel="previous" accesskey="p" href="#Temp-Programmers">Temp Programmers</a>, +Up: <a rel="up" accesskey="u" href="#Temp-Programmers">Temp Programmers</a> + +</div> + +<h4 class="subsection">11.6.1 Temporary - Two Possible Implementations</h4> + + <p>There are two competing methods for language independent messages: +the X/Open <code>catgets</code> method, and the Uniforum <code>gettext</code> +method. The <code>catgets</code> method indexes messages by integers; the +<code>gettext</code> method indexes them by their English translations. +The <code>catgets</code> method has been around longer and is supported +by more vendors. The <code>gettext</code> method is supported by Sun, +and it has been heard that the COSE multi-vendor initiative is +supporting it. Neither method is a POSIX standard; the POSIX.1 +committee had a lot of disagreement in this area. + + <p>Neither one is in the POSIX standard. There was much disagreement +in the POSIX.1 committee about using the <code>gettext</code> routines +vs. <code>catgets</code> (XPG). In the end the committee couldn't +agree on anything, so no messaging system was included as part +of the standard. I believe the informative annex of the standard +includes the XPG3 messaging interfaces, “<small class="dots">...</small>as an example of +a messaging system that has been implemented<small class="dots">...</small>” + + <p>They were very careful not to say anywhere that you should use one +set of interfaces over the other. For more on this topic please +see the Programming for Internationalization FAQ. + +<div class="node"> +<a name="Temp-catgets"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Temp-WSI">Temp WSI</a>, +Previous: <a rel="previous" accesskey="p" href="#Temp-Implementations">Temp Implementations</a>, +Up: <a rel="up" accesskey="u" href="#Temp-Programmers">Temp Programmers</a> + +</div> + +<h4 class="subsection">11.6.2 Temporary - About <code>catgets</code></h4> + + <p>There have been a few discussions of late on the use of +<code>catgets</code> as a base. I think it important to present both +sides of the argument and hence am opting to play devil's advocate +for a little bit. + + <p>I'll not deny the fact that <code>catgets</code> could have been designed +a lot better. It currently has quite a number of limitations and +these have already been pointed out. + + <p>However there is a great deal to be said for consistency and +standardization. A common recurring problem when writing Unix +software is the myriad portability problems across Unix platforms. +It seems as if every Unix vendor had a look at the operating system +and found parts they could improve upon. Undoubtedly, these +modifications are probably innovative and solve real problems. +However, software developers have a hard time keeping up with all +these changes across so many platforms. + + <p>And this has prompted the Unix vendors to begin to standardize their +systems. Hence the impetus for Spec1170. Every major Unix vendor +has committed to supporting this standard and every Unix software +developer waits with glee the day they can write software to this +standard and simply recompile (without having to use autoconf) +across different platforms. + + <p>As I understand it, Spec1170 is roughly based upon version 4 of the +X/Open Portability Guidelines (XPG4). Because <code>catgets</code> and +friends are defined in XPG4, I'm led to believe that <code>catgets</code> +is a part of Spec1170 and hence will become a standardized component +of all Unix systems. + +<div class="node"> +<a name="Temp-WSI"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Temp-Notes">Temp Notes</a>, +Previous: <a rel="previous" accesskey="p" href="#Temp-catgets">Temp catgets</a>, +Up: <a rel="up" accesskey="u" href="#Temp-Programmers">Temp Programmers</a> + +</div> + +<h4 class="subsection">11.6.3 Temporary - Why a single implementation</h4> + + <p>Now it seems kind of wasteful to me to have two different systems +installed for accessing message catalogs. If we do want to remedy +<code>catgets</code> deficiencies why don't we try to expand <code>catgets</code> +(in a compatible manner) rather than implement an entirely new system. +Otherwise, we'll end up with two message catalog access systems installed +with an operating system - one set of routines for packages using GNU +<code>gettext</code> for their internationalization, and another set of routines +(catgets) for all other software. Bloated? + + <p>Supposing another catalog access system is implemented. Which do +we recommend? At least for Linux, we need to attract as many +software developers as possible. Hence we need to make it as easy +for them to port their software as possible. Which means supporting +<code>catgets</code>. We will be implementing the <code>libintl</code> code +within our <code>libc</code>, but does this mean we also have to incorporate +another message catalog access scheme within our <code>libc</code> as well? +And what about people who are going to be using the <code>libintl</code> ++ non-<code>catgets</code> routines. When they port their software to +other platforms, they're now going to have to include the front-end +(<code>libintl</code>) code plus the back-end code (the non-<code>catgets</code> +access routines) with their software instead of just including the +<code>libintl</code> code with their software. + + <p>Message catalog support is however only the tip of the iceberg. +What about the data for the other locale categories? They also have +a number of deficiencies. Are we going to abandon them as well and +develop another duplicate set of routines (should <code>libintl</code> +expand beyond message catalog support)? + + <p>Like many parts of Unix that can be improved upon, we're stuck with balancing +compatibility with the past with useful improvements and innovations for +the future. + +<div class="node"> +<a name="Temp-Notes"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Temp-WSI">Temp WSI</a>, +Up: <a rel="up" accesskey="u" href="#Temp-Programmers">Temp Programmers</a> + +</div> + +<h4 class="subsection">11.6.4 Temporary - Notes</h4> + + <p>X/Open agreed very late on the standard form so that many +implementations differ from the final form. Both of my system (old +Linux catgets and Ultrix-4) have a strange variation. + + <p>OK. After incorporating the last changes I have to spend some time on +making the GNU/Linux <code>libc</code> <code>gettext</code> functions. So in future +Solaris is not the only system having <code>gettext</code>. + +<div class="node"> +<a name="Translators"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Maintainers">Maintainers</a>, +Previous: <a rel="previous" accesskey="p" href="#Programmers">Programmers</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">12 The Translator's View</h2> + +<!-- FIXME: Reorganize whole chapter. --> +<ul class="menu"> +<li><a accesskey="1" href="#Trans-Intro-0">Trans Intro 0</a>: Introduction 0 +<li><a accesskey="2" href="#Trans-Intro-1">Trans Intro 1</a>: Introduction 1 +<li><a accesskey="3" href="#Discussions">Discussions</a>: Discussions +<li><a accesskey="4" href="#Organization">Organization</a>: Organization +<li><a accesskey="5" href="#Information-Flow">Information Flow</a>: Information Flow +<li><a accesskey="6" href="#Translating-plural-forms">Translating plural forms</a>: How to fill in <code>msgstr[0]</code>, <code>msgstr[1]</code> +<li><a accesskey="7" href="#Prioritizing-messages">Prioritizing messages</a>: How to find which messages to translate first +</ul> + +<div class="node"> +<a name="Trans-Intro-0"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Trans-Intro-1">Trans Intro 1</a>, +Previous: <a rel="previous" accesskey="p" href="#Translators">Translators</a>, +Up: <a rel="up" accesskey="u" href="#Translators">Translators</a> + +</div> + +<h3 class="section">12.1 Introduction 0</h3> + + <p><strong> NOTE: </strong> This documentation section is outdated and needs to be +revised. + + <p>Free software is going international! The Translation Project is a way +to get maintainers, translators and users all together, so free software +will gradually become able to speak many native languages. + + <p>The GNU <code>gettext</code> tool set contains <em>everything</em> maintainers +need for internationalizing their packages for messages. It also +contains quite useful tools for helping translators at localizing +messages to their native language, once a package has already been +internationalized. + + <p>To achieve the Translation Project, we need many interested +people who like their own language and write it well, and who are also +able to synergize with other translators speaking the same language. +If you'd like to volunteer to <em>work</em> at translating messages, +please send mail to your translating team. + + <p>Each team has its own mailing list, courtesy of Linux +International. You may reach your translating team at the address +<samp><var>ll</var><span class="file">@li.org</span></samp>, replacing <var>ll</var> by the two-letter ISO 639<!-- /@w --> +code for your language. Language codes are <em>not</em> the same as +country codes given in ISO 3166<!-- /@w -->. The following translating teams +exist: + + <blockquote> +Chinese <code>zh</code>, Czech <code>cs</code>, Danish <code>da</code>, Dutch <code>nl</code>, +Esperanto <code>eo</code>, Finnish <code>fi</code>, French <code>fr</code>, Irish +<code>ga</code>, German <code>de</code>, Greek <code>el</code>, Italian <code>it</code>, +Japanese <code>ja</code>, Indonesian <code>in</code>, Norwegian <code>no</code>, Polish +<code>pl</code>, Portuguese <code>pt</code>, Russian <code>ru</code>, Spanish <code>es</code>, +Swedish <code>sv</code> and Turkish <code>tr</code>. +</blockquote> + +<p class="noindent">For example, you may reach the Chinese translating team by writing to +<samp><span class="file">zh@li.org</span></samp>. When you become a member of the translating team +for your own language, you may subscribe to its list. For example, +Swedish people can send a message to <samp><span class="file">sv-request@li.org</span></samp><!-- /@w -->, +having this message body: + +<pre class="example"> subscribe +</pre> + <p>Keep in mind that team members should be interested in <em>working</em> +at translations, or at solving translational difficulties, rather than +merely lurking around. If your team does not exist yet and you want to +start one, please write to <samp><span class="file">coordinator@translationproject.org</span></samp><!-- /@w -->; +you will then reach the coordinator for all translator teams. + + <p>A handful of GNU packages have already been adapted and provided +with message translations for several languages. Translation +teams have begun to organize, using these packages as a starting +point. But there are many more packages and many languages for +which we have no volunteer translators. If you would like to +volunteer to work at translating messages, please send mail to +<samp><span class="file">coordinator@translationproject.org</span></samp> indicating what language(s) +you can work on. + +<div class="node"> +<a name="Trans-Intro-1"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Discussions">Discussions</a>, +Previous: <a rel="previous" accesskey="p" href="#Trans-Intro-0">Trans Intro 0</a>, +Up: <a rel="up" accesskey="u" href="#Translators">Translators</a> + +</div> + +<h3 class="section">12.2 Introduction 1</h3> + + <p><strong> NOTE: </strong> This documentation section is outdated and needs to be +revised. + + <p>This is now official, GNU is going international! Here is the +announcement submitted for the January 1995 GNU Bulletin: + + <blockquote> +A handful of GNU packages have already been adapted and provided +with message translations for several languages. Translation +teams have begun to organize, using these packages as a starting +point. But there are many more packages and many languages +for which we have no volunteer translators. If you'd like to +volunteer to work at translating messages, please send mail to +‘<samp><span class="samp">coordinator@translationproject.org</span></samp>’ indicating what language(s) +you can work on. +</blockquote> + + <p>This document should answer many questions for those who are curious about +the process or would like to contribute. Please at least skim over it, +hoping to cut down a little of the high volume of e-mail generated by this +collective effort towards internationalization of free software. + + <p>Most free programming which is widely shared is done in English, and +currently, English is used as the main communicating language between +national communities collaborating to free software. This very document +is written in English. This will not change in the foreseeable future. + + <p>However, there is a strong appetite from national communities for +having more software able to write using national language and habits, +and there is an on-going effort to modify free software in such a way +that it becomes able to do so. The experiments driven so far raised +an enthusiastic response from pretesters, so we believe that +internationalization of free software is dedicated to succeed. + + <p>For suggestion clarifications, additions or corrections to this +document, please e-mail to <samp><span class="file">coordinator@translationproject.org</span></samp>. + +<div class="node"> +<a name="Discussions"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Organization">Organization</a>, +Previous: <a rel="previous" accesskey="p" href="#Trans-Intro-1">Trans Intro 1</a>, +Up: <a rel="up" accesskey="u" href="#Translators">Translators</a> + +</div> + +<h3 class="section">12.3 Discussions</h3> + + <p><strong> NOTE: </strong> This documentation section is outdated and needs to be +revised. + + <p>Facing this internationalization effort, a few users expressed their +concerns. Some of these doubts are presented and discussed, here. + + <ul> +<li>Smaller groups + + <p>Some languages are not spoken by a very large number of people, so people +speaking them sometimes consider that there may not be all that much +demand such versions of free software packages. Moreover, many people +being <em>into computers</em>, in some countries, generally seem to prefer +English versions of their software. + + <p>On the other end, people might enjoy their own language a lot, and be +very motivated at providing to themselves the pleasure of having their +beloved free software speaking their mother tongue. They do themselves +a personal favor, and do not pay that much attention to the number of +people benefiting of their work. + + <li>Misinterpretation + + <p>Other users are shy to push forward their own language, seeing in this +some kind of misplaced propaganda. Someone thought there must be some +users of the language over the networks pestering other people with it. + + <p>But any spoken language is worth localization, because there are +people behind the language for whom the language is important and +dear to their hearts. + + <li>Odd translations + + <p>The biggest problem is to find the right translations so that +everybody can understand the messages. Translations are usually a +little odd. Some people get used to English, to the extent they may +find translations into their own language “rather pushy, obnoxious +and sometimes even hilarious.” As a French speaking man, I have +the experience of those instruction manuals for goods, so poorly +translated in French in Korea or Taiwan<small class="dots">...</small> + + <p>The fact is that we sometimes have to create a kind of national +computer culture, and this is not easy without the collaboration of +many people liking their mother tongue. This is why translations are +better achieved by people knowing and loving their own language, and +ready to work together at improving the results they obtain. + + <li>Dependencies over the GPL or LGPL + + <p>Some people wonder if using GNU <code>gettext</code> necessarily brings their +package under the protective wing of the GNU General Public License or +the GNU Library General Public License, when they do not want to make +their program free, or want other kinds of freedom. The simplest +answer is “normally not”. + + <p>The <code>gettext-runtime</code> part of GNU <code>gettext</code>, i.e. the +contents of <code>libintl</code>, is covered by the GNU Library General Public +License. The <code>gettext-tools</code> part of GNU <code>gettext</code>, i.e. the +rest of the GNU <code>gettext</code> package, is covered by the GNU General +Public License. + + <p>The mere marking of localizable strings in a package, or conditional +inclusion of a few lines for initialization, is not really including +GPL'ed or LGPL'ed code. However, since the localization routines in +<code>libintl</code> are under the LGPL, the LGPL needs to be considered. +It gives the right to distribute the complete unmodified source of +<code>libintl</code> even with non-free programs. It also gives the right +to use <code>libintl</code> as a shared library, even for non-free programs. +But it gives the right to use <code>libintl</code> as a static library or +to incorporate <code>libintl</code> into another library only to free +software. + + </ul> + +<div class="node"> +<a name="Organization"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Information-Flow">Information Flow</a>, +Previous: <a rel="previous" accesskey="p" href="#Discussions">Discussions</a>, +Up: <a rel="up" accesskey="u" href="#Translators">Translators</a> + +</div> + +<h3 class="section">12.4 Organization</h3> + + <p><strong> NOTE: </strong> This documentation section is outdated and needs to be +revised. + + <p>On a larger scale, the true solution would be to organize some kind of +fairly precise set up in which volunteers could participate. I gave +some thought to this idea lately, and realize there will be some +touchy points. I thought of writing to Richard Stallman to launch +such a project, but feel it might be good to shake out the ideas +between ourselves first. Most probably that Linux International has +some experience in the field already, or would like to orchestrate +the volunteer work, maybe. Food for thought, in any case! + + <p>I guess we have to setup something early, somehow, that will help +many possible contributors of the same language to interlock and avoid +work duplication, and further be put in contact for solving together +problems particular to their tongue (in most languages, there are many +difficulties peculiar to translating technical English). My Swedish +contributor acknowledged these difficulties, and I'm well aware of +them for French. + + <p>This is surely not a technical issue, but we should manage so the +effort of locale contributors be maximally useful, despite the national +team layer interface between contributors and maintainers. + + <p>The Translation Project needs some setup for coordinating language +coordinators. Localizing evolving programs will surely +become a permanent and continuous activity in the free software community, +once well started. +The setup should be minimally completed and tested before GNU +<code>gettext</code> becomes an official reality. The e-mail address +<samp><span class="file">coordinator@translationproject.org</span></samp> has been set up for receiving +offers from volunteers and general e-mail on these topics. This address +reaches the Translation Project coordinator. + +<ul class="menu"> +<li><a accesskey="1" href="#Central-Coordination">Central Coordination</a>: Central Coordination +<li><a accesskey="2" href="#National-Teams">National Teams</a>: National Teams +<li><a accesskey="3" href="#Mailing-Lists">Mailing Lists</a>: Mailing Lists +</ul> + +<div class="node"> +<a name="Central-Coordination"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#National-Teams">National Teams</a>, +Previous: <a rel="previous" accesskey="p" href="#Organization">Organization</a>, +Up: <a rel="up" accesskey="u" href="#Organization">Organization</a> + +</div> + +<h4 class="subsection">12.4.1 Central Coordination</h4> + + <p>I also think GNU will need sooner than it thinks, that someone set up +a way to organize and coordinate these groups. Some kind of group +of groups. My opinion is that it would be good that GNU delegates +this task to a small group of collaborating volunteers, shortly. +Perhaps in <samp><span class="file">gnu.announce</span></samp> a list of this national committee's +can be published. + + <p>My role as coordinator would simply be to refer to Ulrich any German +speaking volunteer interested to localization of free software packages, and +maybe helping national groups to initially organize, while maintaining +national registries for until national groups are ready to take over. +In fact, the coordinator should ease volunteers to get in contact with +one another for creating national teams, which should then select +one coordinator per language, or country (regionalized language). +If well done, the coordination should be useful without being an +overwhelming task, the time to put delegations in place. + +<div class="node"> +<a name="National-Teams"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Mailing-Lists">Mailing Lists</a>, +Previous: <a rel="previous" accesskey="p" href="#Central-Coordination">Central Coordination</a>, +Up: <a rel="up" accesskey="u" href="#Organization">Organization</a> + +</div> + +<h4 class="subsection">12.4.2 National Teams</h4> + + <p>I suggest we look for volunteer coordinators/editors for individual +languages. These people will scan contributions of translation files +for various programs, for their own languages, and will ensure high +and uniform standards of diction. + + <p>From my current experience with other people in these days, those who +provide localizations are very enthusiastic about the process, and are +more interested in the localization process than in the program they +localize, and want to do many programs, not just one. This seems +to confirm that having a coordinator/editor for each language is a +good idea. + + <p>We need to choose someone who is good at writing clear and concise +prose in the language in question. That is hard—we can't check +it ourselves. So we need to ask a few people to judge each others' +writing and select the one who is best. + + <p>I announce my prerelease to a few dozen people, and you would not +believe all the discussions it generated already. I shudder to think +what will happen when this will be launched, for true, officially, +world wide. Who am I to arbitrate between two Czekolsovak users +contradicting each other, for example? + + <p>I assume that your German is not much better than my French so that +I would not be able to judge about these formulations. What I would +suggest is that for each language there is a group for people who +maintain the PO files and judge about changes. I suspect there will +be cultural differences between how such groups of people will behave. +Some will have relaxed ways, reach consensus easily, and have anyone +of the group relate to the maintainers, while others will fight to +death, organize heavy administrations up to national standards, and +use strict channels. + + <p>The German team is putting out a good example. Right now, they are +maybe half a dozen people revising translations of each other and +discussing the linguistic issues. I do not even have all the names. +Ulrich Drepper is taking care of coordinating the German team. +He subscribed to all my pretest lists, so I do not even have to warn +him specifically of incoming releases. + + <p>I'm sure, that is a good idea to get teams for each language working +on translations. That will make the translations better and more +consistent. + +<ul class="menu"> +<li><a accesskey="1" href="#Sub_002dCultures">Sub-Cultures</a>: Sub-Cultures +<li><a accesskey="2" href="#Organizational-Ideas">Organizational Ideas</a>: Organizational Ideas +</ul> + +<div class="node"> +<a name="Sub-Cultures"></a> +<a name="Sub_002dCultures"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Organizational-Ideas">Organizational Ideas</a>, +Previous: <a rel="previous" accesskey="p" href="#National-Teams">National Teams</a>, +Up: <a rel="up" accesskey="u" href="#National-Teams">National Teams</a> + +</div> + +<h5 class="subsubsection">12.4.2.1 Sub-Cultures</h5> + + <p>Taking French for example, there are a few sub-cultures around computers +which developed diverging vocabularies. Picking volunteers here and +there without addressing this problem in an organized way, soon in the +project, might produce a distasteful mix of internationalized programs, +and possibly trigger endless quarrels among those who really care. + + <p>Keeping some kind of unity in the way French localization of +internationalized programs is achieved is a difficult (and delicate) job. +Knowing the latin character of French people (:-), if we take this +the wrong way, we could end up nowhere, or spoil a lot of energies. +Maybe we should begin to address this problem seriously <em>before</em> +GNU <code>gettext</code> become officially published. And I suspect that this +means soon! + +<div class="node"> +<a name="Organizational-Ideas"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Sub_002dCultures">Sub-Cultures</a>, +Up: <a rel="up" accesskey="u" href="#National-Teams">National Teams</a> + +</div> + +<h5 class="subsubsection">12.4.2.2 Organizational Ideas</h5> + + <p>I expect the next big changes after the official release. Please note +that I use the German translation of the short GPL message. We need +to set a few good examples before the localization goes out for true +in the free software community. Here are a few points to discuss: + + <ul> +<li>Each group should have one FTP server (at least one master). + + <li>The files on the server should reflect the latest version (of +course!) and it should also contain a RCS directory with the +corresponding archives (I don't have this now). + + <li>There should also be a ChangeLog file (this is more useful than the +RCS archive but can be generated automatically from the later by +Emacs). + + <li>A <dfn>core group</dfn> should judge about questionable changes (for now +this group consists solely by me but I ask some others occasionally; +this also seems to work). + + </ul> + +<div class="node"> +<a name="Mailing-Lists"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#National-Teams">National Teams</a>, +Up: <a rel="up" accesskey="u" href="#Organization">Organization</a> + +</div> + +<h4 class="subsection">12.4.3 Mailing Lists</h4> + + <p>If we get any inquiries about GNU <code>gettext</code>, send them on to: + +<pre class="example"> <samp><span class="file">coordinator@translationproject.org</span></samp> +</pre> + <p>The <samp><span class="file">*-pretest</span></samp> lists are quite useful to me, maybe the idea could +be generalized to many GNU, and non-GNU packages. But each maintainer +his/her way! + + <p>François, we have a mechanism in place here at +<samp><span class="file">gnu.ai.mit.edu</span></samp> to track teams, support mailing lists for +them and log members. We have a slight preference that you use it. +If this is OK with you, I can get you clued in. + + <p>Things are changing! A few years ago, when Daniel Fekete and I +asked for a mailing list for GNU localization, nested at the FSF, we +were politely invited to organize it anywhere else, and so did we. +For communicating with my pretesters, I later made a handful of +mailing lists located at iro.umontreal.ca and administrated by +<code>majordomo</code>. These lists have been <em>very</em> dependable +so far<small class="dots">...</small> + + <p>I suspect that the German team will organize itself a mailing list +located in Germany, and so forth for other countries. But before they +organize for true, it could surely be useful to offer mailing lists +located at the FSF to each national team. So yes, please explain me +how I should proceed to create and handle them. + + <p>We should create temporary mailing lists, one per country, to help +people organize. Temporary, because once regrouped and structured, it +would be fair the volunteers from country bring back <em>their</em> list +in there and manage it as they want. My feeling is that, in the long +run, each team should run its own list, from within their country. +There also should be some central list to which all teams could +subscribe as they see fit, as long as each team is represented in it. + +<div class="node"> +<a name="Information-Flow"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Translating-plural-forms">Translating plural forms</a>, +Previous: <a rel="previous" accesskey="p" href="#Organization">Organization</a>, +Up: <a rel="up" accesskey="u" href="#Translators">Translators</a> + +</div> + +<h3 class="section">12.5 Information Flow</h3> + + <p><strong> NOTE: </strong> This documentation section is outdated and needs to be +revised. + + <p>There will surely be some discussion about this messages after the +packages are finally released. If people now send you some proposals +for better messages, how do you proceed? Jim, please note that +right now, as I put forward nearly a dozen of localizable programs, I +receive both the translations and the coordination concerns about them. + + <p>If I put one of my things to pretest, Ulrich receives the announcement +and passes it on to the German team, who make last minute revisions. +Then he submits the translation files to me <em>as the maintainer</em>. +For free packages I do not maintain, I would not even hear about it. +This scheme could be made to work for the whole Translation Project, +I think. For security reasons, maybe Ulrich (national coordinators, +in fact) should update central registry kept at the Translation Project +(Jim, me, or Len's recruits) once in a while. + + <p>In December/January, I was aggressively ready to internationalize +all of GNU, giving myself the duty of one small GNU package per week +or so, taking many weeks or months for bigger packages. But it does +not work this way. I first did all the things I'm responsible for. +I've nothing against some missionary work on other maintainers, but +I'm also loosing a lot of energy over it—same debates over again. + + <p>And when the first localized packages are released we'll get a lot of +responses about ugly translations :-). Surely, and we need to have +beforehand a fairly good idea about how to handle the information +flow between the national teams and the package maintainers. + + <p>Please start saving somewhere a quick history of each PO file. I know +for sure that the file format will change, allowing for comments. +It would be nice that each file has a kind of log, and references for +those who want to submit comments or gripes, or otherwise contribute. +I sent a proposal for a fast and flexible format, but it is not +receiving acceptance yet by the GNU deciders. I'll tell you when I +have more information about this. + +<div class="node"> +<a name="Translating-plural-forms"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Prioritizing-messages">Prioritizing messages</a>, +Previous: <a rel="previous" accesskey="p" href="#Information-Flow">Information Flow</a>, +Up: <a rel="up" accesskey="u" href="#Translators">Translators</a> + +</div> + +<h3 class="section">12.6 Translating plural forms</h3> + + <p><a name="index-plural-forms_002c-translating-1111"></a>Suppose you are translating a PO file, and it contains an entry like this: + +<pre class="smallexample"> #, c-format + msgid "One file removed" + msgid_plural "%d files removed" + msgstr[0] "" + msgstr[1] "" +</pre> + <p class="noindent">What does this mean? How do you fill it in? + + <p>Such an entry denotes a message with plural forms, that is, a message where +the text depends on a cardinal number. The general form of the message, +in English, is the <code>msgid_plural</code> line. The <code>msgid</code> line is the +English singular form, that is, the form for when the number is equal to 1. +More details about plural forms are explained in <a href="#Plural-forms">Plural forms</a>. + + <p>The first thing you need to look at is the <code>Plural-Forms</code> line in the +header entry of the PO file. It contains the number of plural forms and a +formula. If the PO file does not yet have such a line, you have to add it. +It only depends on the language into which you are translating. You can +get this info by using the <code>msginit</code> command (see <a href="#Creating">Creating</a>) – +it contains a database of known plural formulas – or by asking other +members of your translation team. + + <p>Suppose the line looks as follows: + +<pre class="smallexample"> "Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && n" + "%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" +</pre> + <p>It's logically one line; recall that the PO file formatting is allowed to +break long lines so that each physical line fits in 80 monospaced columns. + + <p>The value of <code>nplurals</code> here tells you that there are three plural +forms. The first thing you need to do is to ensure that the entry contains +an <code>msgstr</code> line for each of the forms: + +<pre class="smallexample"> #, c-format + msgid "One file removed" + msgid_plural "%d files removed" + msgstr[0] "" + msgstr[1] "" + msgstr[2] "" +</pre> + <p>Then translate the <code>msgid_plural</code> line and fill it in into each +<code>msgstr</code> line: + +<pre class="smallexample"> #, c-format + msgid "One file removed" + msgid_plural "%d files removed" + msgstr[0] "%d slika uklonjenih" + msgstr[1] "%d slika uklonjenih" + msgstr[2] "%d slika uklonjenih" +</pre> + <p>Now you can refine the translation so that it matches the plural form. +According to the formula above, <code>msgstr[0]</code> is used when the number +ends in 1 but does not end in 11; <code>msgstr[1]</code> is used when the number +ends in 2, 3, 4, but not in 12, 13, 14; and <code>msgstr[2]</code> is used in +all other cases. With this knowledge, you can refine the translations: + +<pre class="smallexample"> #, c-format + msgid "One file removed" + msgid_plural "%d files removed" + msgstr[0] "%d slika je uklonjena" + msgstr[1] "%d datoteke uklonjenih" + msgstr[2] "%d slika uklonjenih" +</pre> + <p>You noticed that in the English singular form (<code>msgid</code>) the number +placeholder could be omitted and replaced by the numeral word “one”. +Can you do this in your translation as well? + +<pre class="smallexample"> msgstr[0] "jednom datotekom je uklonjen" +</pre> + <p class="noindent">Well, it depends on whether <code>msgstr[0]</code> applies only to the number 1, +or to other numbers as well. If, according to the plural formula, +<code>msgstr[0]</code> applies only to <code>n == 1</code>, then you can use the +specialized translation without the number placeholder. In our case, +however, <code>msgstr[0]</code> also applies to the numbers 21, 31, 41, etc., +and therefore you cannot omit the placeholder. + +<div class="node"> +<a name="Prioritizing-messages"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Translating-plural-forms">Translating plural forms</a>, +Up: <a rel="up" accesskey="u" href="#Translators">Translators</a> + +</div> + +<h3 class="section">12.7 Prioritizing messages: How to determine which messages to translate first</h3> + + <p>A translator sometimes has only a limited amount of time per week to +spend on a package, and some packages have quite large message catalogs +(over 1000 messages). Therefore she wishes to translate the messages +first that are the most visible to the user, or that occur most frequently. +This section describes how to determine these "most urgent" messages. +It also applies to determine the "next most urgent" messages after the +message catalog has already been partially translated. + + <p>In a first step, she uses the programs like a user would do. While she +does this, the GNU <code>gettext</code> library logs into a file the not yet +translated messages for which a translation was requested from the program. + + <p>In a second step, she uses the PO mode to translate precisely this set +of messages. + + <p><a name="index-GETTEXT_005fLOG_005fUNTRANSLATED_0040r_007b_002c-environment-variable_007d-1112"></a>Here a more details. The GNU <code>libintl</code> library (but not the +corresponding functions in GNU <code>libc</code>) supports an environment variable +<code>GETTEXT_LOG_UNTRANSLATED</code>. The GNU <code>libintl</code> library will +log into this file the messages for which <code>gettext()</code> and related +functions couldn't find the translation. If the file doesn't exist, it +will be created as needed. On systems with GNU <code>libc</code> a shared library +‘<samp><span class="samp">preloadable_libintl.so</span></samp>’ is provided that can be used with the ELF +‘<samp><span class="samp">LD_PRELOAD</span></samp>’ mechanism. + + <p>So, in the first step, the translator uses these commands on systems with +GNU <code>libc</code>: + +<pre class="smallexample"> $ LD_PRELOAD=/usr/local/lib/preloadable_libintl.so + $ export LD_PRELOAD + $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused + $ export GETTEXT_LOG_UNTRANSLATED +</pre> + <p class="noindent">and these commands on other systems: + +<pre class="smallexample"> $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused + $ export GETTEXT_LOG_UNTRANSLATED +</pre> + <p>Then she uses and peruses the programs. (It is a good and recommended +practice to use the programs for which you provide translations: it +gives you the needed context.) When done, she removes the environment +variables: + +<pre class="smallexample"> $ unset LD_PRELOAD + $ unset GETTEXT_LOG_UNTRANSLATED +</pre> + <p>The second step starts with removing duplicates: + +<pre class="smallexample"> $ msguniq $HOME/gettextlogused > missing.po +</pre> + <p>The result is a PO file, but needs some preprocessing before a PO file editor +can be used with it. First, it is a multi-domain PO file, containing +messages from many translation domains. Second, it lacks all translator +comments and source references. Here is how to get a list of the affected +translation domains: + +<pre class="smallexample"> $ sed -n -e 's,^domain "\(.*\)"$,\1,p' < missing.po | sort | uniq +</pre> + <p>Then the translator can handle the domains one by one. For simplicity, +let's use environment variables to denote the language, domain and source +package. + +<pre class="smallexample"> $ lang=nl # your language + $ domain=coreutils # the name of the domain to be handled + $ package=/usr/src/gnu/coreutils-4.5.4 # the package where it comes from +</pre> + <p>She takes the latest copy of <samp><span class="file">$lang.po</span></samp> from the Translation Project, +or from the package (in most cases, <samp><span class="file">$package/po/$lang.po</span></samp>), or +creates a fresh one if she's the first translator (see <a href="#Creating">Creating</a>). +She then uses the following commands to mark the not urgent messages as +"obsolete". (This doesn't mean that these messages - translated and +untranslated ones - will go away. It simply means that the PO file editor +will ignore them in the following editing session.) + +<pre class="smallexample"> $ msggrep --domain=$domain missing.po | grep -v '^domain' \ + > $domain-missing.po + $ msgattrib --set-obsolete --ignore-file $domain-missing.po $domain.$lang.po \ + > $domain.$lang-urgent.po +</pre> + <p>The she translates <samp><span class="file">$domain.$lang-urgent.po</span></samp> by use of a PO file editor +(see <a href="#Editing">Editing</a>). +(FIXME: I don't know whether <code>KBabel</code> and <code>gtranslator</code> also +preserve obsolete messages, as they should.) +Finally she restores the not urgent messages (with their earlier +translations, for those which were already translated) through this command: + +<pre class="smallexample"> $ msgmerge --no-fuzzy-matching $domain.$lang-urgent.po $package/po/$domain.pot \ + > $domain.$lang.po +</pre> + <p>Then she can submit <samp><span class="file">$domain.$lang.po</span></samp> and proceed to the next domain. + +<div class="node"> +<a name="Maintainers"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Installers">Installers</a>, +Previous: <a rel="previous" accesskey="p" href="#Translators">Translators</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">13 The Maintainer's View</h2> + + <p><a name="index-package-maintainer_0027s-view-of-_0040code_007bgettext_007d-1113"></a> +The maintainer of a package has many responsibilities. One of them +is ensuring that the package will install easily on many platforms, +and that the magic we described earlier (see <a href="#Users">Users</a>) will work +for installers and end users. + + <p>Of course, there are many possible ways by which GNU <code>gettext</code> +might be integrated in a distribution, and this chapter does not cover +them in all generality. Instead, it details one possible approach which +is especially adequate for many free software distributions following GNU +standards, or even better, Gnits standards, because GNU <code>gettext</code> +is purposely for helping the internationalization of the whole GNU +project, and as many other good free packages as possible. So, the +maintainer's view presented here presumes that the package already has +a <samp><span class="file">configure.ac</span></samp> file and uses GNU Autoconf. + + <p>Nevertheless, GNU <code>gettext</code> may surely be useful for free packages +not following GNU standards and conventions, but the maintainers of such +packages might have to show imagination and initiative in organizing +their distributions so <code>gettext</code> work for them in all situations. +There are surely many, out there. + + <p>Even if <code>gettext</code> methods are now stabilizing, slight adjustments +might be needed between successive <code>gettext</code> versions, so you +should ideally revise this chapter in subsequent releases, looking +for changes. + +<ul class="menu"> +<li><a accesskey="1" href="#Flat-and-Non_002dFlat">Flat and Non-Flat</a>: Flat or Non-Flat Directory Structures +<li><a accesskey="2" href="#Prerequisites">Prerequisites</a>: Prerequisite Works +<li><a accesskey="3" href="#gettextize-Invocation">gettextize Invocation</a>: Invoking the <code>gettextize</code> Program +<li><a accesskey="4" href="#Adjusting-Files">Adjusting Files</a>: Files You Must Create or Alter +<li><a accesskey="5" href="#autoconf-macros">autoconf macros</a>: Autoconf macros for use in <samp><span class="file">configure.ac</span></samp> +<li><a accesskey="6" href="#CVS-Issues">CVS Issues</a>: Integrating with CVS +<li><a accesskey="7" href="#Release-Management">Release Management</a>: Creating a Distribution Tarball +</ul> + +<div class="node"> +<a name="Flat-and-Non-Flat"></a> +<a name="Flat-and-Non_002dFlat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Prerequisites">Prerequisites</a>, +Previous: <a rel="previous" accesskey="p" href="#Maintainers">Maintainers</a>, +Up: <a rel="up" accesskey="u" href="#Maintainers">Maintainers</a> + +</div> + +<h3 class="section">13.1 Flat or Non-Flat Directory Structures</h3> + + <p>Some free software packages are distributed as <code>tar</code> files which unpack +in a single directory, these are said to be <dfn>flat</dfn> distributions. +Other free software packages have a one level hierarchy of subdirectories, using +for example a subdirectory named <samp><span class="file">doc/</span></samp> for the Texinfo manual and +man pages, another called <samp><span class="file">lib/</span></samp> for holding functions meant to +replace or complement C libraries, and a subdirectory <samp><span class="file">src/</span></samp> for +holding the proper sources for the package. These other distributions +are said to be <dfn>non-flat</dfn>. + + <p>We cannot say much about flat distributions. A flat +directory structure has the disadvantage of increasing the difficulty +of updating to a new version of GNU <code>gettext</code>. Also, if you have +many PO files, this could somewhat pollute your single directory. +Also, GNU <code>gettext</code>'s libintl sources consist of C sources, shell +scripts, <code>sed</code> scripts and complicated Makefile rules, which don't +fit well into an existing flat structure. For these reasons, we +recommend to use non-flat approach in this case as well. + + <p>Maybe because GNU <code>gettext</code> itself has a non-flat structure, +we have more experience with this approach, and this is what will be +described in the remaining of this chapter. Some maintainers might +use this as an opportunity to unflatten their package structure. + +<div class="node"> +<a name="Prerequisites"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#gettextize-Invocation">gettextize Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#Flat-and-Non_002dFlat">Flat and Non-Flat</a>, +Up: <a rel="up" accesskey="u" href="#Maintainers">Maintainers</a> + +</div> + +<h3 class="section">13.2 Prerequisite Works</h3> + + <p><a name="index-converting-a-package-to-use-_0040code_007bgettext_007d-1114"></a><a name="index-migration-from-earlier-versions-of-_0040code_007bgettext_007d-1115"></a><a name="index-upgrading-to-new-versions-of-_0040code_007bgettext_007d-1116"></a> +There are some works which are required for using GNU <code>gettext</code> +in one of your package. These works have some kind of generality +that escape the point by point descriptions used in the remainder +of this chapter. So, we describe them here. + + <ul> +<li>Before attempting to use <code>gettextize</code> you should install some +other packages first. +Ensure that recent versions of GNU <code>m4</code>, GNU Autoconf and GNU +<code>gettext</code> are already installed at your site, and if not, proceed +to do this first. If you get to install these things, beware that +GNU <code>m4</code> must be fully installed before GNU Autoconf is even +<em>configured</em>. + + <p>To further ease the task of a package maintainer the <code>automake</code> +package was designed and implemented. GNU <code>gettext</code> now uses this +tool and the <samp><span class="file">Makefile</span></samp>s in the <samp><span class="file">intl/</span></samp> and <samp><span class="file">po/</span></samp> +therefore know about all the goals necessary for using <code>automake</code> +and <samp><span class="file">libintl</span></samp> in one project. + + <p>Those four packages are only needed by you, as a maintainer; the +installers of your own package and end users do not really need any of +GNU <code>m4</code>, GNU Autoconf, GNU <code>gettext</code>, or GNU <code>automake</code> +for successfully installing and running your package, with messages +properly translated. But this is not completely true if you provide +internationalized shell scripts within your own package: GNU +<code>gettext</code> shall then be installed at the user site if the end users +want to see the translation of shell script messages. + + <li>Your package should use Autoconf and have a <samp><span class="file">configure.ac</span></samp> or +<samp><span class="file">configure.in</span></samp> file. +If it does not, you have to learn how. The Autoconf documentation +is quite well written, it is a good idea that you print it and get +familiar with it. + + <li>Your C sources should have already been modified according to +instructions given earlier in this manual. See <a href="#Sources">Sources</a>. + + <li>Your <samp><span class="file">po/</span></samp> directory should receive all PO files submitted to you +by the translator teams, each having <samp><var>ll</var><span class="file">.po</span></samp> as a name. +This is not usually easy to get translation +work done before your package gets internationalized and available! +Since the cycle has to start somewhere, the easiest for the maintainer +is to start with absolutely no PO files, and wait until various +translator teams get interested in your package, and submit PO files. + + </ul> + + <p>It is worth adding here a few words about how the maintainer should +ideally behave with PO files submissions. As a maintainer, your role is +to authenticate the origin of the submission as being the representative +of the appropriate translating teams of the Translation Project (forward +the submission to <samp><span class="file">coordinator@translationproject.org</span></samp> in case of doubt), +to ensure that the PO file format is not severely broken and does not +prevent successful installation, and for the rest, to merely put these +PO files in <samp><span class="file">po/</span></samp> for distribution. + + <p>As a maintainer, you do not have to take on your shoulders the +responsibility of checking if the translations are adequate or +complete, and should avoid diving into linguistic matters. Translation +teams drive themselves and are fully responsible of their linguistic +choices for the Translation Project. Keep in mind that translator teams are <em>not</em> +driven by maintainers. You can help by carefully redirecting all +communications and reports from users about linguistic matters to the +appropriate translation team, or explain users how to reach or join +their team. The simplest might be to send them the <samp><span class="file">ABOUT-NLS</span></samp> file. + + <p>Maintainers should <em>never ever</em> apply PO file bug reports +themselves, short-cutting translation teams. If some translator has +difficulty to get some of her points through her team, it should not be +an option for her to directly negotiate translations with maintainers. +Teams ought to settle their problems themselves, if any. If you, as +a maintainer, ever think there is a real problem with a team, please +never try to <em>solve</em> a team's problem on your own. + +<div class="node"> +<a name="gettextize-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Adjusting-Files">Adjusting Files</a>, +Previous: <a rel="previous" accesskey="p" href="#Prerequisites">Prerequisites</a>, +Up: <a rel="up" accesskey="u" href="#Maintainers">Maintainers</a> + +</div> + +<h3 class="section">13.3 Invoking the <code>gettextize</code> Program</h3> + + <p>The <code>gettextize</code> program is an interactive tool that helps the +maintainer of a package internationalized through GNU <code>gettext</code>. +It is used for two purposes: + + <ul> +<li>As a wizard, when a package is modified to use GNU <code>gettext</code> for +the first time. + + <li>As a migration tool, for upgrading the GNU <code>gettext</code> support in +a package from a previous to a newer version of GNU <code>gettext</code>. +</ul> + + <p>This program performs the following tasks: + + <ul> +<li>It copies into the package some files that are consistently and +identically needed in every package internationalized through +GNU <code>gettext</code>. + + <li>It performs as many of the tasks mentioned in the next section +<a href="#Adjusting-Files">Adjusting Files</a> as can be performed automatically. + + <li>It removes obsolete files and idioms used for previous GNU +<code>gettext</code> versions to the form recommended for the current GNU +<code>gettext</code> version. + + <li>It prints a summary of the tasks that ought to be done manually +and could not be done automatically by <code>gettextize</code>. +</ul> + + <p>It can be invoked as follows: + + <p><a name="index-gettextize-1117"></a><a name="index-g_t_0040code_007bgettextize_007d-program_002c-usage-1118"></a> +<pre class="example"> gettextize [ <var>option</var>... ] [ <var>directory</var> ] +</pre> + <p class="noindent">and accepts the following options: + + <dl> +<dt>‘<samp><span class="samp">-f</span></samp>’<dt>‘<samp><span class="samp">--force</span></samp>’<dd><a name="index-g_t_002df_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1119"></a><a name="index-g_t_002d_002dforce_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1120"></a>Force replacement of files which already exist. + + <br><dt>‘<samp><span class="samp">--intl</span></samp>’<dd><a name="index-g_t_002d_002dintl_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1121"></a>Install the libintl sources in a subdirectory named <samp><span class="file">intl/</span></samp>. +This libintl will be used to provide internationalization on systems +that don't have GNU libintl installed. If this option is omitted, +the call to <code>AM_GNU_GETTEXT</code> in <samp><span class="file">configure.ac</span></samp> should read: +‘<samp><span class="samp">AM_GNU_GETTEXT([external])</span></samp>’, and internationalization will not +be enabled on systems lacking GNU gettext. + + <br><dt>‘<samp><span class="samp">--po-dir=</span><var>dir</var></samp>’<dd><a name="index-g_t_002d_002dpo_002ddir_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1122"></a>Specify a directory containing PO files. Such a directory contains the +translations into various languages of a particular POT file. This +option can be specified multiple times, once for each translation domain. +If it is not specified, the directory named <samp><span class="file">po/</span></samp> is updated. + + <br><dt>‘<samp><span class="samp">--no-changelog</span></samp>’<dd><a name="index-g_t_002d_002dno_002dchangelog_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1123"></a>Don't update or create ChangeLog files. By default, <code>gettextize</code> +logs all changes (file additions, modifications and removals) in a +file called ‘<samp><span class="samp">ChangeLog</span></samp>’ in each affected directory. + + <br><dt>‘<samp><span class="samp">--symlink</span></samp>’<dd><a name="index-g_t_002d_002dsymlink_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1124"></a>Make symbolic links instead of copying the needed files. This can be +useful to save a few kilobytes of disk space, but it requires extra +effort to create self-contained tarballs, it may disturb some mechanism +the maintainer applies to the sources, and it is likely to introduce +bugs when a newer version of <code>gettext</code> is installed on the system. + + <br><dt>‘<samp><span class="samp">-n</span></samp>’<dt>‘<samp><span class="samp">--dry-run</span></samp>’<dd><a name="index-g_t_002dd_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1125"></a><a name="index-g_t_002d_002ddry_002drun_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1126"></a>Print modifications but don't perform them. All actions that +<code>gettextize</code> would normally execute are inhibited and instead only +listed on standard output. + + <br><dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1127"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1128"></a>Output version information and exit. + + </dl> + + <p>If <var>directory</var> is given, this is the top level directory of a +package to prepare for using GNU <code>gettext</code>. If not given, it +is assumed that the current directory is the top level directory of +such a package. + + <p>The program <code>gettextize</code> provides the following files. However, +no existing file will be replaced unless the option <code>--force</code> +(<code>-f</code>) is specified. + + <ol type=1 start=1> +<li>The <samp><span class="file">ABOUT-NLS</span></samp> file is copied in the main directory of your package, +the one being at the top level. This file gives the main indications +about how to install and use the Native Language Support features +of your program. You might elect to use a more recent copy of this +<samp><span class="file">ABOUT-NLS</span></samp> file than the one provided through <code>gettextize</code>, +if you have one handy. You may also fetch a more recent copy of file +<samp><span class="file">ABOUT-NLS</span></samp> from Translation Project sites, and from most GNU +archive sites. + + <li>A <samp><span class="file">po/</span></samp> directory is created for eventually holding +all translation files, but initially only containing the file +<samp><span class="file">po/Makefile.in.in</span></samp> from the GNU <code>gettext</code> distribution +(beware the double ‘<samp><span class="samp">.in</span></samp>’ in the file name) and a few auxiliary +files. If the <samp><span class="file">po/</span></samp> directory already exists, it will be preserved +along with the files it contains, and only <samp><span class="file">Makefile.in.in</span></samp> and +the auxiliary files will be overwritten. + + <p>If ‘<samp><span class="samp">--po-dir</span></samp>’ has been specified, this holds for every directory +specified through ‘<samp><span class="samp">--po-dir</span></samp>’, instead of <samp><span class="file">po/</span></samp>. + + <li>Only if ‘<samp><span class="samp">--intl</span></samp>’ has been specified: +A <samp><span class="file">intl/</span></samp> directory is created and filled with most of the files +originally in the <samp><span class="file">intl/</span></samp> directory of the GNU <code>gettext</code> +distribution. Also, if option <code>--force</code> (<code>-f</code>) is given, +the <samp><span class="file">intl/</span></samp> directory is emptied first. + + <li>The file <samp><span class="file">config.rpath</span></samp> is copied into the directory containing +configuration support files. It is needed by the <code>AM_GNU_GETTEXT</code> +autoconf macro. + + <li>Only if the project is using GNU <code>automake</code>: +A set of <code>autoconf</code> macro files is copied into the package's +<code>autoconf</code> macro repository, usually in a directory called <samp><span class="file">m4/</span></samp>. + </ol> + + <p>If your site support symbolic links, <code>gettextize</code> will not +actually copy the files into your package, but establish symbolic +links instead. This avoids duplicating the disk space needed in +all packages. Merely using the ‘<samp><span class="samp">-h</span></samp>’ option while creating the +<code>tar</code> archive of your distribution will resolve each link by an +actual copy in the distribution archive. So, to insist, you really +should use ‘<samp><span class="samp">-h</span></samp>’ option with <code>tar</code> within your <code>dist</code> +goal of your main <samp><span class="file">Makefile.in</span></samp>. + + <p>Furthermore, <code>gettextize</code> will update all <samp><span class="file">Makefile.am</span></samp> files +in each affected directory, as well as the top level <samp><span class="file">configure.ac</span></samp> +or <samp><span class="file">configure.in</span></samp> file. + + <p>It is interesting to understand that most new files for supporting +GNU <code>gettext</code> facilities in one package go in <samp><span class="file">intl/</span></samp>, +<samp><span class="file">po/</span></samp> and <samp><span class="file">m4/</span></samp> subdirectories. One distinction between +<samp><span class="file">intl/</span></samp> and the two other directories is that <samp><span class="file">intl/</span></samp> is +meant to be completely identical in all packages using GNU <code>gettext</code>, +while the other directories will mostly contain package dependent +files. + + <p>The <code>gettextize</code> program makes backup files for all files it +replaces or changes, and also write ChangeLog entries about these +changes. This way, the careful maintainer can check after running +<code>gettextize</code> whether its changes are acceptable to him, and +possibly adjust them. An exception to this rule is the <samp><span class="file">intl/</span></samp> +directory, which is added or replaced or removed as a whole. + + <p>It is important to understand that <code>gettextize</code> can not do the +entire job of adapting a package for using GNU <code>gettext</code>. The +amount of remaining work depends on whether the package uses GNU +<code>automake</code> or not. But in any case, the maintainer should still +read the section <a href="#Adjusting-Files">Adjusting Files</a> after invoking <code>gettextize</code>. + + <p>In particular, if after using ‘<samp><span class="samp">gettexize</span></samp>’, you get an error +‘<samp><span class="samp">AC_COMPILE_IFELSE was called before AC_GNU_SOURCE</span></samp>’ or +‘<samp><span class="samp">AC_RUN_IFELSE was called before AC_GNU_SOURCE</span></samp>’, you can fix it +by modifying <samp><span class="file">configure.ac</span></samp>, as described in <a href="#configure_002eac">configure.ac</a>. + + <p>It is also important to understand that <code>gettextize</code> is not part +of the GNU build system, in the sense that it should not be invoked +automatically, and not be invoked by someone who doesn't assume the +responsibilities of a package maintainer. For the latter purpose, a +separate tool is provided, see <a href="#autopoint-Invocation">autopoint Invocation</a>. + +<div class="node"> +<a name="Adjusting-Files"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#autoconf-macros">autoconf macros</a>, +Previous: <a rel="previous" accesskey="p" href="#gettextize-Invocation">gettextize Invocation</a>, +Up: <a rel="up" accesskey="u" href="#Maintainers">Maintainers</a> + +</div> + +<h3 class="section">13.4 Files You Must Create or Alter</h3> + + <p><a name="index-g_t_0040code_007bgettext_007d-files-1129"></a> +Besides files which are automatically added through <code>gettextize</code>, +there are many files needing revision for properly interacting with +GNU <code>gettext</code>. If you are closely following GNU standards for +Makefile engineering and auto-configuration, the adaptations should +be easier to achieve. Here is a point by point description of the +changes needed in each. + + <p>So, here comes a list of files, each one followed by a description of +all alterations it needs. Many examples are taken out from the GNU +<code>gettext</code> 0.18 distribution itself, or from the GNU +<code>hello</code> distribution (<a href="http://www.franken.de/users/gnu/ke/hello">http://www.franken.de/users/gnu/ke/hello</a> +or <a href="http://www.gnu.franken.de/ke/hello/">http://www.gnu.franken.de/ke/hello/</a>) You may indeed +refer to the source code of the GNU <code>gettext</code> and GNU <code>hello</code> +packages, as they are intended to be good examples for using GNU +gettext functionality. + +<ul class="menu"> +<li><a accesskey="1" href="#po_002fPOTFILES_002ein">po/POTFILES.in</a>: <samp><span class="file">POTFILES.in</span></samp> in <samp><span class="file">po/</span></samp> +<li><a accesskey="2" href="#po_002fLINGUAS">po/LINGUAS</a>: <samp><span class="file">LINGUAS</span></samp> in <samp><span class="file">po/</span></samp> +<li><a accesskey="3" href="#po_002fMakevars">po/Makevars</a>: <samp><span class="file">Makevars</span></samp> in <samp><span class="file">po/</span></samp> +<li><a accesskey="4" href="#po_002fRules_002d_002a">po/Rules-*</a>: Extending <samp><span class="file">Makefile</span></samp> in <samp><span class="file">po/</span></samp> +<li><a accesskey="5" href="#configure_002eac">configure.ac</a>: <samp><span class="file">configure.ac</span></samp> at top level +<li><a accesskey="6" href="#config_002eguess">config.guess</a>: <samp><span class="file">config.guess</span></samp>, <samp><span class="file">config.sub</span></samp> at top level +<li><a accesskey="7" href="#mkinstalldirs">mkinstalldirs</a>: <samp><span class="file">mkinstalldirs</span></samp> at top level +<li><a accesskey="8" href="#aclocal">aclocal</a>: <samp><span class="file">aclocal.m4</span></samp> at top level +<li><a accesskey="9" href="#acconfig">acconfig</a>: <samp><span class="file">acconfig.h</span></samp> at top level +<li><a href="#config_002eh_002ein">config.h.in</a>: <samp><span class="file">config.h.in</span></samp> at top level +<li><a href="#Makefile">Makefile</a>: <samp><span class="file">Makefile.in</span></samp> at top level +<li><a href="#src_002fMakefile">src/Makefile</a>: <samp><span class="file">Makefile.in</span></samp> in <samp><span class="file">src/</span></samp> +<li><a href="#lib_002fgettext_002eh">lib/gettext.h</a>: <samp><span class="file">gettext.h</span></samp> in <samp><span class="file">lib/</span></samp> +</ul> + +<div class="node"> +<a name="po%2fPOTFILES.in"></a> +<a name="po_002fPOTFILES_002ein"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#po_002fLINGUAS">po/LINGUAS</a>, +Previous: <a rel="previous" accesskey="p" href="#Adjusting-Files">Adjusting Files</a>, +Up: <a rel="up" accesskey="u" href="#Adjusting-Files">Adjusting Files</a> + +</div> + +<h4 class="subsection">13.4.1 <samp><span class="file">POTFILES.in</span></samp> in <samp><span class="file">po/</span></samp></h4> + + <p><a name="index-g_t_0040file_007bPOTFILES_002ein_007d-file-1130"></a> +The <samp><span class="file">po/</span></samp> directory should receive a file named +<samp><span class="file">POTFILES.in</span></samp>. This file tells which files, among all program +sources, have marked strings needing translation. Here is an example +of such a file: + +<pre class="example"> # List of source files containing translatable strings. + # Copyright (C) 1995 Free Software Foundation, Inc. + + # Common library files + lib/error.c + lib/getopt.c + lib/xmalloc.c + + # Package source files + src/gettext.c + src/msgfmt.c + src/xgettext.c +</pre> + <p class="noindent">Hash-marked comments and white lines are ignored. All other lines +list those source files containing strings marked for translation +(see <a href="#Mark-Keywords">Mark Keywords</a>), in a notation relative to the top level +of your whole distribution, rather than the location of the +<samp><span class="file">POTFILES.in</span></samp> file itself. + + <p>When a C file is automatically generated by a tool, like <code>flex</code> or +<code>bison</code>, that doesn't introduce translatable strings by itself, +it is recommended to list in <samp><span class="file">po/POTFILES.in</span></samp> the real source file +(ending in <samp><span class="file">.l</span></samp> in the case of <code>flex</code>, or in <samp><span class="file">.y</span></samp> in the +case of <code>bison</code>), not the generated C file. + +<div class="node"> +<a name="po%2fLINGUAS"></a> +<a name="po_002fLINGUAS"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#po_002fMakevars">po/Makevars</a>, +Previous: <a rel="previous" accesskey="p" href="#po_002fPOTFILES_002ein">po/POTFILES.in</a>, +Up: <a rel="up" accesskey="u" href="#Adjusting-Files">Adjusting Files</a> + +</div> + +<h4 class="subsection">13.4.2 <samp><span class="file">LINGUAS</span></samp> in <samp><span class="file">po/</span></samp></h4> + + <p><a name="index-g_t_0040file_007bLINGUAS_007d-file-1131"></a> +The <samp><span class="file">po/</span></samp> directory should also receive a file named +<samp><span class="file">LINGUAS</span></samp>. This file contains the list of available translations. +It is a whitespace separated list. Hash-marked comments and white lines +are ignored. Here is an example file: + +<pre class="example"> # Set of available languages. + de fr +</pre> + <p class="noindent">This example means that German and French PO files are available, so +that these languages are currently supported by your package. If you +want to further restrict, at installation time, the set of installed +languages, this should not be done by modifying the <samp><span class="file">LINGUAS</span></samp> file, +but rather by using the <code>LINGUAS</code> environment variable +(see <a href="#Installers">Installers</a>). + + <p>It is recommended that you add the "languages" ‘<samp><span class="samp">en@quot</span></samp>’ and +‘<samp><span class="samp">en@boldquot</span></samp>’ to the <code>LINGUAS</code> file. <code>en@quot</code> is a +variant of English message catalogs (<code>en</code>) which uses real quotation +marks instead of the ugly looking asymmetric ASCII substitutes ‘<samp><span class="samp">`</span></samp>’ +and ‘<samp><span class="samp">'</span></samp>’. <code>en@boldquot</code> is a variant of <code>en@quot</code> that +additionally outputs quoted pieces of text in a bold font, when used in +a terminal emulator which supports the VT100 escape sequences (such as +<code>xterm</code> or the Linux console, but not Emacs in <kbd>M-x shell</kbd> mode). + + <p>These extra message catalogs ‘<samp><span class="samp">en@quot</span></samp>’ and ‘<samp><span class="samp">en@boldquot</span></samp>’ +are constructed automatically, not by translators; to support them, you +need the files <samp><span class="file">Rules-quot</span></samp>, <samp><span class="file">quot.sed</span></samp>, <samp><span class="file">boldquot.sed</span></samp>, +<samp><span class="file">en@quot.header</span></samp>, <samp><span class="file">en@boldquot.header</span></samp>, <samp><span class="file">insert-header.sin</span></samp> +in the <samp><span class="file">po/</span></samp> directory. You can copy them from GNU gettext's <samp><span class="file">po/</span></samp> +directory; they are also installed by running <code>gettextize</code>. + +<div class="node"> +<a name="po%2fMakevars"></a> +<a name="po_002fMakevars"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#po_002fRules_002d_002a">po/Rules-*</a>, +Previous: <a rel="previous" accesskey="p" href="#po_002fLINGUAS">po/LINGUAS</a>, +Up: <a rel="up" accesskey="u" href="#Adjusting-Files">Adjusting Files</a> + +</div> + +<h4 class="subsection">13.4.3 <samp><span class="file">Makevars</span></samp> in <samp><span class="file">po/</span></samp></h4> + + <p><a name="index-g_t_0040file_007bMakevars_007d-file-1132"></a> +The <samp><span class="file">po/</span></samp> directory also has a file named <samp><span class="file">Makevars</span></samp>. It +contains variables that are specific to your project. <samp><span class="file">po/Makevars</span></samp> +gets inserted into the <samp><span class="file">po/Makefile</span></samp> when the latter is created. +The variables thus take effect when the POT file is created or updated, +and when the message catalogs get installed. + + <p>The first three variables can be left unmodified if your package has a +single message domain and, accordingly, a single <samp><span class="file">po/</span></samp> directory. +Only packages which have multiple <samp><span class="file">po/</span></samp> directories at different +locations need to adjust the three first variables defined in +<samp><span class="file">Makevars</span></samp>. + + <p>As an alternative to the <code>XGETTEXT_OPTIONS</code> variables, it is also +possible to specify <code>xgettext</code> options through the +<code>AM_XGETTEXT_OPTION</code> autoconf macro. See <a href="#AM_005fXGETTEXT_005fOPTION">AM_XGETTEXT_OPTION</a>. + +<div class="node"> +<a name="po%2fRules-*"></a> +<a name="po_002fRules_002d_002a"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#configure_002eac">configure.ac</a>, +Previous: <a rel="previous" accesskey="p" href="#po_002fMakevars">po/Makevars</a>, +Up: <a rel="up" accesskey="u" href="#Adjusting-Files">Adjusting Files</a> + +</div> + +<h4 class="subsection">13.4.4 Extending <samp><span class="file">Makefile</span></samp> in <samp><span class="file">po/</span></samp></h4> + + <p><a name="index-g_t_0040file_007bMakefile_002ein_002ein_007d-extensions-1133"></a> +All files called <samp><span class="file">Rules-*</span></samp> in the <samp><span class="file">po/</span></samp> directory get appended to +the <samp><span class="file">po/Makefile</span></samp> when it is created. They present an opportunity to +add rules for special PO files to the Makefile, without needing to mess +with <samp><span class="file">po/Makefile.in.in</span></samp>. + + <p><a name="index-quotation-marks-1134"></a><a name="index-LANGUAGE_0040r_007b_002c-environment-variable_007d-1135"></a>GNU gettext comes with a <samp><span class="file">Rules-quot</span></samp> file, containing rules for +building catalogs <samp><span class="file">en@quot.po</span></samp> and <samp><span class="file">en@boldquot.po</span></samp>. The +effect of <samp><span class="file">en@quot.po</span></samp> is that people who set their <code>LANGUAGE</code> +environment variable to ‘<samp><span class="samp">en@quot</span></samp>’ will get messages with proper +looking symmetric Unicode quotation marks instead of abusing the ASCII +grave accent and the ASCII apostrophe for indicating quotations. To +enable this catalog, simply add <code>en@quot</code> to the <samp><span class="file">po/LINGUAS</span></samp> +file. The effect of <samp><span class="file">en@boldquot.po</span></samp> is that people who set +<code>LANGUAGE</code> to ‘<samp><span class="samp">en@boldquot</span></samp>’ will get not only proper quotation +marks, but also the quoted text will be shown in a bold font on terminals +and consoles. This catalog is useful only for command-line programs, not +GUI programs. To enable it, similarly add <code>en@boldquot</code> to the +<samp><span class="file">po/LINGUAS</span></samp> file. + + <p>Similarly, you can create rules for building message catalogs for the +<samp><span class="file">sr@latin</span></samp> locale – Serbian written with the Latin alphabet – +from those for the <samp><span class="file">sr</span></samp> locale – Serbian written with Cyrillic +letters. See <a href="#msgfilter-Invocation">msgfilter Invocation</a>. + +<div class="node"> +<a name="configure.ac"></a> +<a name="configure_002eac"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#config_002eguess">config.guess</a>, +Previous: <a rel="previous" accesskey="p" href="#po_002fRules_002d_002a">po/Rules-*</a>, +Up: <a rel="up" accesskey="u" href="#Adjusting-Files">Adjusting Files</a> + +</div> + +<h4 class="subsection">13.4.5 <samp><span class="file">configure.ac</span></samp> at top level</h4> + + <p><samp><span class="file">configure.ac</span></samp> or <samp><span class="file">configure.in</span></samp> - this is the source from which +<code>autoconf</code> generates the <samp><span class="file">configure</span></samp> script. + + <ol type=1 start=1> +<li>Declare the package and version. +<a name="index-package-and-version-declaration-in-_0040file_007bconfigure_002eac_007d-1136"></a> +This is done by a set of lines like these: + + <pre class="example"> PACKAGE=gettext + VERSION=0.18 + AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE") + AC_DEFINE_UNQUOTED(VERSION, "$VERSION") + AC_SUBST(PACKAGE) + AC_SUBST(VERSION) +</pre> + <p class="noindent">or, if you are using GNU <code>automake</code>, by a line like this: + + <pre class="example"> AM_INIT_AUTOMAKE(gettext, 0.18) +</pre> + <p class="noindent">Of course, you replace ‘<samp><span class="samp">gettext</span></samp>’ with the name of your package, +and ‘<samp><span class="samp">0.18</span></samp>’ by its version numbers, exactly as they +should appear in the packaged <code>tar</code> file name of your distribution +(<samp><span class="file">gettext-0.18.tar.gz</span></samp>, here). + + <li>Check for internationalization support. + + <p>Here is the main <code>m4</code> macro for triggering internationalization +support. Just add this line to <samp><span class="file">configure.ac</span></samp>: + + <pre class="example"> AM_GNU_GETTEXT +</pre> + <p class="noindent">This call is purposely simple, even if it generates a lot of configure +time checking and actions. + + <p>If you have suppressed the <samp><span class="file">intl/</span></samp> subdirectory by calling +<code>gettextize</code> without ‘<samp><span class="samp">--intl</span></samp>’ option, this call should read + + <pre class="example"> AM_GNU_GETTEXT([external]) +</pre> + <li>Have output files created. + + <p>The <code>AC_OUTPUT</code> directive, at the end of your <samp><span class="file">configure.ac</span></samp> +file, needs to be modified in two ways: + + <pre class="example"> AC_OUTPUT([<var>existing configuration files</var> intl/Makefile po/Makefile.in], + [<var>existing additional actions</var>]) +</pre> + <p>The modification to the first argument to <code>AC_OUTPUT</code> asks +for substitution in the <samp><span class="file">intl/</span></samp> and <samp><span class="file">po/</span></samp> directories. +Note the ‘<samp><span class="samp">.in</span></samp>’ suffix used for <samp><span class="file">po/</span></samp> only. This is because +the distributed file is really <samp><span class="file">po/Makefile.in.in</span></samp>. + + <p>If you have suppressed the <samp><span class="file">intl/</span></samp> subdirectory by calling +<code>gettextize</code> without ‘<samp><span class="samp">--intl</span></samp>’ option, then you don't need to +add <code>intl/Makefile</code> to the <code>AC_OUTPUT</code> line. + + </ol> + + <p>If, after doing the recommended modifications, a command like +‘<samp><span class="samp">aclocal -I m4</span></samp>’ or ‘<samp><span class="samp">autoconf</span></samp>’ or ‘<samp><span class="samp">autoreconf</span></samp>’ fails with +a trace similar to this: + +<pre class="smallexample"> configure.ac:44: warning: AC_COMPILE_IFELSE was called before AC_GNU_SOURCE + ../../lib/autoconf/specific.m4:335: AC_GNU_SOURCE is expanded from... + m4/lock.m4:224: gl_LOCK is expanded from... + m4/gettext.m4:571: gt_INTL_SUBDIR_CORE is expanded from... + m4/gettext.m4:472: AM_INTL_SUBDIR is expanded from... + m4/gettext.m4:347: AM_GNU_GETTEXT is expanded from... + configure.ac:44: the top level + configure.ac:44: warning: AC_RUN_IFELSE was called before AC_GNU_SOURCE +</pre> + <p class="noindent">you need to add an explicit invocation of ‘<samp><span class="samp">AC_GNU_SOURCE</span></samp>’ in the +<samp><span class="file">configure.ac</span></samp> file - after ‘<samp><span class="samp">AC_PROG_CC</span></samp>’ but before +‘<samp><span class="samp">AM_GNU_GETTEXT</span></samp>’, most likely very close to the ‘<samp><span class="samp">AC_PROG_CC</span></samp>’ +invocation. This is necessary because of ordering restrictions imposed +by GNU autoconf. + +<div class="node"> +<a name="config.guess"></a> +<a name="config_002eguess"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#mkinstalldirs">mkinstalldirs</a>, +Previous: <a rel="previous" accesskey="p" href="#configure_002eac">configure.ac</a>, +Up: <a rel="up" accesskey="u" href="#Adjusting-Files">Adjusting Files</a> + +</div> + +<h4 class="subsection">13.4.6 <samp><span class="file">config.guess</span></samp>, <samp><span class="file">config.sub</span></samp> at top level</h4> + + <p>If you haven't suppressed the <samp><span class="file">intl/</span></samp> subdirectory, +you need to add the GNU <samp><span class="file">config.guess</span></samp> and <samp><span class="file">config.sub</span></samp> files +to your distribution. They are needed because the <samp><span class="file">intl/</span></samp> directory +has platform dependent support for determining the locale's character +encoding and therefore needs to identify the platform. + + <p>You can obtain the newest version of <samp><span class="file">config.guess</span></samp> and +<samp><span class="file">config.sub</span></samp> from the CVS of the ‘<samp><span class="samp">config</span></samp>’ project at +<samp><span class="file">http://savannah.gnu.org/</span></samp>. The commands to fetch them are +<pre class="smallexample"> $ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.guess' + $ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.sub' +</pre> + <p class="noindent">Less recent versions are also contained in the GNU <code>automake</code> and +GNU <code>libtool</code> packages. + + <p>Normally, <samp><span class="file">config.guess</span></samp> and <samp><span class="file">config.sub</span></samp> are put at the +top level of a distribution. But it is also possible to put them in a +subdirectory, altogether with other configuration support files like +<samp><span class="file">install-sh</span></samp>, <samp><span class="file">ltconfig</span></samp>, <samp><span class="file">ltmain.sh</span></samp> or <samp><span class="file">missing</span></samp>. +All you need to do, other than moving the files, is to add the following line +to your <samp><span class="file">configure.ac</span></samp>. + +<pre class="example"> AC_CONFIG_AUX_DIR([<var>subdir</var>]) +</pre> + <div class="node"> +<a name="mkinstalldirs"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#aclocal">aclocal</a>, +Previous: <a rel="previous" accesskey="p" href="#config_002eguess">config.guess</a>, +Up: <a rel="up" accesskey="u" href="#Adjusting-Files">Adjusting Files</a> + +</div> + +<h4 class="subsection">13.4.7 <samp><span class="file">mkinstalldirs</span></samp> at top level</h4> + + <p><a name="index-g_t_0040file_007bmkinstalldirs_007d-file-1137"></a> +With earlier versions of GNU gettext, you needed to add the GNU +<samp><span class="file">mkinstalldirs</span></samp> script to your distribution. This is not needed any +more. You can remove it if you not also using an automake version older than +automake 1.9. + +<div class="node"> +<a name="aclocal"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#acconfig">acconfig</a>, +Previous: <a rel="previous" accesskey="p" href="#mkinstalldirs">mkinstalldirs</a>, +Up: <a rel="up" accesskey="u" href="#Adjusting-Files">Adjusting Files</a> + +</div> + +<h4 class="subsection">13.4.8 <samp><span class="file">aclocal.m4</span></samp> at top level</h4> + + <p><a name="index-g_t_0040file_007baclocal_002em4_007d-file-1138"></a> +If you do not have an <samp><span class="file">aclocal.m4</span></samp> file in your distribution, +the simplest is to concatenate the files <samp><span class="file">codeset.m4</span></samp>, <samp><span class="file">fcntl-o.m4</span></samp>, +<samp><span class="file">gettext.m4</span></samp>, <samp><span class="file">glibc2.m4</span></samp>, <samp><span class="file">glibc21.m4</span></samp>, <samp><span class="file">iconv.m4</span></samp>, +<samp><span class="file">intdiv0.m4</span></samp>, <samp><span class="file">intl.m4</span></samp>, <samp><span class="file">intldir.m4</span></samp>, <samp><span class="file">intlmacosx.m4</span></samp>, +<samp><span class="file">intmax.m4</span></samp>, <samp><span class="file">inttypes_h.m4</span></samp>, <samp><span class="file">inttypes-pri.m4</span></samp>, +<samp><span class="file">lcmessage.m4</span></samp>, <samp><span class="file">lib-ld.m4</span></samp>, <samp><span class="file">lib-link.m4</span></samp>, +<samp><span class="file">lib-prefix.m4</span></samp>, <samp><span class="file">lock.m4</span></samp>, <samp><span class="file">longlong.m4</span></samp>, <samp><span class="file">nls.m4</span></samp>, +<samp><span class="file">po.m4</span></samp>, <samp><span class="file">printf-posix.m4</span></samp>, <samp><span class="file">progtest.m4</span></samp>, <samp><span class="file">size_max.m4</span></samp>, +<samp><span class="file">stdint_h.m4</span></samp>, <samp><span class="file">threadlib.m4</span></samp>, <samp><span class="file">uintmax_t.m4</span></samp>, +<samp><span class="file">visibility.m4</span></samp>, <samp><span class="file">wchar_t.m4</span></samp>, <samp><span class="file">wint_t.m4</span></samp>, <samp><span class="file">xsize.m4</span></samp> +from GNU <code>gettext</code>'s +<samp><span class="file">m4/</span></samp> directory into a single file. If you have suppressed the +<samp><span class="file">intl/</span></samp> directory, only <samp><span class="file">gettext.m4</span></samp>, <samp><span class="file">iconv.m4</span></samp>, +<samp><span class="file">lib-ld.m4</span></samp>, <samp><span class="file">lib-link.m4</span></samp>, <samp><span class="file">lib-prefix.m4</span></samp>, +<samp><span class="file">nls.m4</span></samp>, <samp><span class="file">po.m4</span></samp>, <samp><span class="file">progtest.m4</span></samp> need to be concatenated. + + <p>If you are not using GNU <code>automake</code> 1.8 or newer, you will need to +add a file <samp><span class="file">mkdirp.m4</span></samp> from a newer automake distribution to the +list of files above. + + <p>If you already have an <samp><span class="file">aclocal.m4</span></samp> file, then you will have +to merge the said macro files into your <samp><span class="file">aclocal.m4</span></samp>. Note that if +you are upgrading from a previous release of GNU <code>gettext</code>, you +should most probably <em>replace</em> the macros (<code>AM_GNU_GETTEXT</code>, +etc.), as they usually +change a little from one release of GNU <code>gettext</code> to the next. +Their contents may vary as we get more experience with strange systems +out there. + + <p>If you are using GNU <code>automake</code> 1.5 or newer, it is enough to put +these macro files into a subdirectory named <samp><span class="file">m4/</span></samp> and add the line + +<pre class="example"> ACLOCAL_AMFLAGS = -I m4 +</pre> + <p class="noindent">to your top level <samp><span class="file">Makefile.am</span></samp>. + + <p>These macros check for the internationalization support functions +and related informations. Hopefully, once stabilized, these macros +might be integrated in the standard Autoconf set, because this +piece of <code>m4</code> code will be the same for all projects using GNU +<code>gettext</code>. + +<div class="node"> +<a name="acconfig"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#config_002eh_002ein">config.h.in</a>, +Previous: <a rel="previous" accesskey="p" href="#aclocal">aclocal</a>, +Up: <a rel="up" accesskey="u" href="#Adjusting-Files">Adjusting Files</a> + +</div> + +<h4 class="subsection">13.4.9 <samp><span class="file">acconfig.h</span></samp> at top level</h4> + + <p><a name="index-g_t_0040file_007bacconfig_002eh_007d-file-1139"></a> +Earlier GNU <code>gettext</code> releases required to put definitions for +<code>ENABLE_NLS</code>, <code>HAVE_GETTEXT</code> and <code>HAVE_LC_MESSAGES</code>, +<code>HAVE_STPCPY</code>, <code>PACKAGE</code> and <code>VERSION</code> into an +<samp><span class="file">acconfig.h</span></samp> file. This is not needed any more; you can remove +them from your <samp><span class="file">acconfig.h</span></samp> file unless your package uses them +independently from the <samp><span class="file">intl/</span></samp> directory. + +<div class="node"> +<a name="config.h.in"></a> +<a name="config_002eh_002ein"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Makefile">Makefile</a>, +Previous: <a rel="previous" accesskey="p" href="#acconfig">acconfig</a>, +Up: <a rel="up" accesskey="u" href="#Adjusting-Files">Adjusting Files</a> + +</div> + +<h4 class="subsection">13.4.10 <samp><span class="file">config.h.in</span></samp> at top level</h4> + + <p><a name="index-g_t_0040file_007bconfig_002eh_002ein_007d-file-1140"></a> +The include file template that holds the C macros to be defined by +<code>configure</code> is usually called <samp><span class="file">config.h.in</span></samp> and may be +maintained either manually or automatically. + + <p>If <code>gettextize</code> has created an <samp><span class="file">intl/</span></samp> directory, this file +must be called <samp><span class="file">config.h.in</span></samp> and must be at the top level. If, +however, you have suppressed the <samp><span class="file">intl/</span></samp> directory by calling +<code>gettextize</code> without ‘<samp><span class="samp">--intl</span></samp>’ option, then you can choose the +name of this file and its location freely. + + <p>If it is maintained automatically, by use of the ‘<samp><span class="samp">autoheader</span></samp>’ +program, you need to do nothing about it. This is the case in particular +if you are using GNU <code>automake</code>. + + <p>If it is maintained manually, and if <code>gettextize</code> has created an +<samp><span class="file">intl/</span></samp> directory, you should switch to using ‘<samp><span class="samp">autoheader</span></samp>’. +The list of C macros to be added for the sake of the <samp><span class="file">intl/</span></samp> +directory is just too long to be maintained manually; it also changes +between different versions of GNU <code>gettext</code>. + + <p>If it is maintained manually, and if on the other hand you have +suppressed the <samp><span class="file">intl/</span></samp> directory by calling <code>gettextize</code> +without ‘<samp><span class="samp">--intl</span></samp>’ option, then you can get away by adding the +following lines to <samp><span class="file">config.h.in</span></samp>: + +<pre class="example"> /* Define to 1 if translation of program messages to the user's + native language is requested. */ + #undef ENABLE_NLS +</pre> + <div class="node"> +<a name="Makefile"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#src_002fMakefile">src/Makefile</a>, +Previous: <a rel="previous" accesskey="p" href="#config_002eh_002ein">config.h.in</a>, +Up: <a rel="up" accesskey="u" href="#Adjusting-Files">Adjusting Files</a> + +</div> + +<h4 class="subsection">13.4.11 <samp><span class="file">Makefile.in</span></samp> at top level</h4> + + <p>Here are a few modifications you need to make to your main, top-level +<samp><span class="file">Makefile.in</span></samp> file. + + <ol type=1 start=1> +<li>Add the following lines near the beginning of your <samp><span class="file">Makefile.in</span></samp>, +so the ‘<samp><span class="samp">dist:</span></samp>’ goal will work properly (as explained further down): + + <pre class="example"> PACKAGE = @PACKAGE@ + VERSION = @VERSION@ +</pre> + <li>Add file <samp><span class="file">ABOUT-NLS</span></samp> to the <code>DISTFILES</code> definition, so the file gets +distributed. + + <li>Wherever you process subdirectories in your <samp><span class="file">Makefile.in</span></samp>, be sure +you also process the subdirectories ‘<samp><span class="samp">intl</span></samp>’ and ‘<samp><span class="samp">po</span></samp>’. Special +rules in the <samp><span class="file">Makefiles</span></samp> take care for the case where no +internationalization is wanted. + + <p>If you are using Makefiles, either generated by automake, or hand-written +so they carefully follow the GNU coding standards, the effected goals for +which the new subdirectories must be handled include ‘<samp><span class="samp">installdirs</span></samp>’, +‘<samp><span class="samp">install</span></samp>’, ‘<samp><span class="samp">uninstall</span></samp>’, ‘<samp><span class="samp">clean</span></samp>’, ‘<samp><span class="samp">distclean</span></samp>’. + + <p>Here is an example of a canonical order of processing. In this +example, we also define <code>SUBDIRS</code> in <code>Makefile.in</code> for it +to be further used in the ‘<samp><span class="samp">dist:</span></samp>’ goal. + + <pre class="example"> SUBDIRS = doc intl lib src po +</pre> + <p>Note that you must arrange for ‘<samp><span class="samp">make</span></samp>’ to descend into the +<code>intl</code> directory before descending into other directories containing +code which make use of the <code>libintl.h</code> header file. For this +reason, here we mention <code>intl</code> before <code>lib</code> and <code>src</code>. + + <li>A delicate point is the ‘<samp><span class="samp">dist:</span></samp>’ goal, as both +<samp><span class="file">intl/Makefile</span></samp> and <samp><span class="file">po/Makefile</span></samp> will later assume that the +proper directory has been set up from the main <samp><span class="file">Makefile</span></samp>. Here is +an example at what the ‘<samp><span class="samp">dist:</span></samp>’ goal might look like: + + <pre class="example"> distdir = $(PACKAGE)-$(VERSION) + dist: Makefile + rm -fr $(distdir) + mkdir $(distdir) + chmod 777 $(distdir) + for file in $(DISTFILES); do \ + ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \ + done + for subdir in $(SUBDIRS); do \ + mkdir $(distdir)/$$subdir || exit 1; \ + chmod 777 $(distdir)/$$subdir; \ + (cd $$subdir && $(MAKE) $@) || exit 1; \ + done + tar chozf $(distdir).tar.gz $(distdir) + rm -fr $(distdir) +</pre> + </ol> + + <p>Note that if you are using GNU <code>automake</code>, <samp><span class="file">Makefile.in</span></samp> is +automatically generated from <samp><span class="file">Makefile.am</span></samp>, and all needed changes +to <samp><span class="file">Makefile.am</span></samp> are already made by running ‘<samp><span class="samp">gettextize</span></samp>’. + +<div class="node"> +<a name="src%2fMakefile"></a> +<a name="src_002fMakefile"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#lib_002fgettext_002eh">lib/gettext.h</a>, +Previous: <a rel="previous" accesskey="p" href="#Makefile">Makefile</a>, +Up: <a rel="up" accesskey="u" href="#Adjusting-Files">Adjusting Files</a> + +</div> + +<h4 class="subsection">13.4.12 <samp><span class="file">Makefile.in</span></samp> in <samp><span class="file">src/</span></samp></h4> + + <p>Some of the modifications made in the main <samp><span class="file">Makefile.in</span></samp> will +also be needed in the <samp><span class="file">Makefile.in</span></samp> from your package sources, +which we assume here to be in the <samp><span class="file">src/</span></samp> subdirectory. Here are +all the modifications needed in <samp><span class="file">src/Makefile.in</span></samp>: + + <ol type=1 start=1> +<li>In view of the ‘<samp><span class="samp">dist:</span></samp>’ goal, you should have these lines near the +beginning of <samp><span class="file">src/Makefile.in</span></samp>: + + <pre class="example"> PACKAGE = @PACKAGE@ + VERSION = @VERSION@ +</pre> + <li>If not done already, you should guarantee that <code>top_srcdir</code> +gets defined. This will serve for <code>cpp</code> include files. Just add +the line: + + <pre class="example"> top_srcdir = @top_srcdir@ +</pre> + <li>You might also want to define <code>subdir</code> as ‘<samp><span class="samp">src</span></samp>’, later +allowing for almost uniform ‘<samp><span class="samp">dist:</span></samp>’ goals in all your +<samp><span class="file">Makefile.in</span></samp>. At list, the ‘<samp><span class="samp">dist:</span></samp>’ goal below assume that +you used: + + <pre class="example"> subdir = src +</pre> + <li>The <code>main</code> function of your program will normally call +<code>bindtextdomain</code> (see see <a href="#Triggering">Triggering</a>), like this: + + <pre class="example"> bindtextdomain (<var>PACKAGE</var>, LOCALEDIR); + textdomain (<var>PACKAGE</var>); +</pre> + <p>To make LOCALEDIR known to the program, add the following lines to +<samp><span class="file">Makefile.in</span></samp> if you are using Autoconf version 2.60 or newer: + + <pre class="example"> datadir = @datadir@ + datarootdir= @datarootdir@ + localedir = @localedir@ + DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@ +</pre> + <p>or these lines if your version of Autoconf is older than 2.60: + + <pre class="example"> datadir = @datadir@ + localedir = $(datadir)/locale + DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@ +</pre> + <p>Note that <code>@datadir@</code> defaults to ‘<samp><span class="samp">$(prefix)/share</span></samp>’, thus +<code>$(localedir)</code> defaults to ‘<samp><span class="samp">$(prefix)/share/locale</span></samp>’. + + <li>You should ensure that the final linking will use <code>@LIBINTL@</code> or +<code>@LTLIBINTL@</code> as a library. <code>@LIBINTL@</code> is for use without +<code>libtool</code>, <code>@LTLIBINTL@</code> is for use with <code>libtool</code>. An +easy way to achieve this is to manage that it gets into <code>LIBS</code>, like +this: + + <pre class="example"> LIBS = @LIBINTL@ @LIBS@ +</pre> + <p>In most packages internationalized with GNU <code>gettext</code>, one will +find a directory <samp><span class="file">lib/</span></samp> in which a library containing some helper +functions will be build. (You need at least the few functions which the +GNU <code>gettext</code> Library itself needs.) However some of the functions +in the <samp><span class="file">lib/</span></samp> also give messages to the user which of course should be +translated, too. Taking care of this, the support library (say +<samp><span class="file">libsupport.a</span></samp>) should be placed before <code>@LIBINTL@</code> and +<code>@LIBS@</code> in the above example. So one has to write this: + + <pre class="example"> LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@ +</pre> + <li>You should also ensure that directory <samp><span class="file">intl/</span></samp> will be searched for +C preprocessor include files in all circumstances. So, you have to +manage so both ‘<samp><span class="samp">-I../intl</span></samp>’ and ‘<samp><span class="samp">-I$(top_srcdir)/intl</span></samp>’ will +be given to the C compiler. + + <li>Your ‘<samp><span class="samp">dist:</span></samp>’ goal has to conform with others. Here is a +reasonable definition for it: + + <pre class="example"> distdir = ../$(PACKAGE)-$(VERSION)/$(subdir) + dist: Makefile $(DISTFILES) + for file in $(DISTFILES); do \ + ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir) || exit 1; \ + done +</pre> + </ol> + + <p>Note that if you are using GNU <code>automake</code>, <samp><span class="file">Makefile.in</span></samp> is +automatically generated from <samp><span class="file">Makefile.am</span></samp>, and the first three +changes and the last change are not necessary. The remaining needed +<samp><span class="file">Makefile.am</span></samp> modifications are the following: + + <ol type=1 start=1> +<li>To make LOCALEDIR known to the program, add the following to +<samp><span class="file">Makefile.am</span></samp>: + + <pre class="example"> <module>_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\" +</pre> + <p class="noindent">for each specific module or compilation unit, or + + <pre class="example"> AM_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\" +</pre> + <p>for all modules and compilation units together. Furthermore, if you are +using an Autoconf version older then 2.60, add this line to define +‘<samp><span class="samp">localedir</span></samp>’: + + <pre class="example"> localedir = $(datadir)/locale +</pre> + <li>To ensure that the final linking will use <code>@LIBINTL@</code> or +<code>@LTLIBINTL@</code> as a library, add the following to +<samp><span class="file">Makefile.am</span></samp>: + + <pre class="example"> <program>_LDADD = @LIBINTL@ +</pre> + <p class="noindent">for each specific program, or + + <pre class="example"> LDADD = @LIBINTL@ +</pre> + <p>for all programs together. Remember that when you use <code>libtool</code> +to link a program, you need to use @LTLIBINTL@ instead of @LIBINTL@ +for that program. + + <li>If you have an <samp><span class="file">intl/</span></samp> directory, whose contents is created by +<code>gettextize</code>, then to ensure that it will be searched for +C preprocessor include files in all circumstances, add something like +this to <samp><span class="file">Makefile.am</span></samp>: + + <pre class="example"> AM_CPPFLAGS = -I../intl -I$(top_srcdir)/intl +</pre> + </ol> + +<div class="node"> +<a name="lib%2fgettext.h"></a> +<a name="lib_002fgettext_002eh"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#src_002fMakefile">src/Makefile</a>, +Up: <a rel="up" accesskey="u" href="#Adjusting-Files">Adjusting Files</a> + +</div> + +<h4 class="subsection">13.4.13 <samp><span class="file">gettext.h</span></samp> in <samp><span class="file">lib/</span></samp></h4> + + <p><a name="index-g_t_0040file_007bgettext_002eh_007d-file-1141"></a><a name="index-turning-off-NLS-support-1142"></a><a name="index-disabling-NLS-1143"></a> +Internationalization of packages, as provided by GNU <code>gettext</code>, is +optional. It can be turned off in two situations: + + <ul> +<li>When the installer has specified ‘<samp><span class="samp">./configure --disable-nls</span></samp>’. This +can be useful when small binaries are more important than features, for +example when building utilities for boot diskettes. It can also be useful +in order to get some specific C compiler warnings about code quality with +some older versions of GCC (older than 3.0). + + <li>When the package does not include the <code>intl/</code> subdirectory, and the +libintl.h header (with its associated libintl library, if any) is not +already installed on the system, it is preferable that the package builds +without internationalization support, rather than to give a compilation +error. +</ul> + + <p>A C preprocessor macro can be used to detect these two cases. Usually, +when <code>libintl.h</code> was found and not explicitly disabled, the +<code>ENABLE_NLS</code> macro will be defined to 1 in the autoconf generated +configuration file (usually called <samp><span class="file">config.h</span></samp>). In the two negative +situations, however, this macro will not be defined, thus it will evaluate +to 0 in C preprocessor expressions. + + <p><a name="index-include-file-_0040file_007blibintl_002eh_007d-1144"></a><samp><span class="file">gettext.h</span></samp> is a convenience header file for conditional use of +<samp><span class="file"><libintl.h></span></samp>, depending on the <code>ENABLE_NLS</code> macro. If +<code>ENABLE_NLS</code> is set, it includes <samp><span class="file"><libintl.h></span></samp>; otherwise it +defines no-op substitutes for the libintl.h functions. We recommend +the use of <code>"gettext.h"</code> over direct use of <samp><span class="file"><libintl.h></span></samp>, +so that portability to older systems is guaranteed and installers can +turn off internationalization if they want to. In the C code, you will +then write + +<pre class="example"> #include "gettext.h" +</pre> + <p class="noindent">instead of + +<pre class="example"> #include <libintl.h> +</pre> + <p>The location of <code>gettext.h</code> is usually in a directory containing +auxiliary include files. In many GNU packages, there is a directory +<samp><span class="file">lib/</span></samp> containing helper functions; <samp><span class="file">gettext.h</span></samp> fits there. +In other packages, it can go into the <samp><span class="file">src</span></samp> directory. + + <p>Do not install the <code>gettext.h</code> file in public locations. Every +package that needs it should contain a copy of it on its own. + +<div class="node"> +<a name="autoconf-macros"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#CVS-Issues">CVS Issues</a>, +Previous: <a rel="previous" accesskey="p" href="#Adjusting-Files">Adjusting Files</a>, +Up: <a rel="up" accesskey="u" href="#Maintainers">Maintainers</a> + +</div> + +<h3 class="section">13.5 Autoconf macros for use in <samp><span class="file">configure.ac</span></samp></h3> + + <p><a name="index-autoconf-macros-for-_0040code_007bgettext_007d-1145"></a> +GNU <code>gettext</code> installs macros for use in a package's +<samp><span class="file">configure.ac</span></samp> or <samp><span class="file">configure.in</span></samp>. +See <a href="autoconf.html#Top">Introduction</a>. +The primary macro is, of course, <code>AM_GNU_GETTEXT</code>. + +<ul class="menu"> +<li><a accesskey="1" href="#AM_005fGNU_005fGETTEXT">AM_GNU_GETTEXT</a>: AM_GNU_GETTEXT in <samp><span class="file">gettext.m4</span></samp> +<li><a accesskey="2" href="#AM_005fGNU_005fGETTEXT_005fVERSION">AM_GNU_GETTEXT_VERSION</a>: AM_GNU_GETTEXT_VERSION in <samp><span class="file">gettext.m4</span></samp> +<li><a accesskey="3" href="#AM_005fGNU_005fGETTEXT_005fNEED">AM_GNU_GETTEXT_NEED</a>: AM_GNU_GETTEXT_NEED in <samp><span class="file">gettext.m4</span></samp> +<li><a accesskey="4" href="#AM_005fGNU_005fGETTEXT_005fINTL_005fSUBDIR">AM_GNU_GETTEXT_INTL_SUBDIR</a>: AM_GNU_GETTEXT_INTL_SUBDIR in <samp><span class="file">intldir.m4</span></samp> +<li><a accesskey="5" href="#AM_005fPO_005fSUBDIRS">AM_PO_SUBDIRS</a>: AM_PO_SUBDIRS in <samp><span class="file">po.m4</span></samp> +<li><a accesskey="6" href="#AM_005fXGETTEXT_005fOPTION">AM_XGETTEXT_OPTION</a>: AM_XGETTEXT_OPTION in <samp><span class="file">po.m4</span></samp> +<li><a accesskey="7" href="#AM_005fICONV">AM_ICONV</a>: AM_ICONV in <samp><span class="file">iconv.m4</span></samp> +</ul> + +<div class="node"> +<a name="AM_GNU_GETTEXT"></a> +<a name="AM_005fGNU_005fGETTEXT"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#AM_005fGNU_005fGETTEXT_005fVERSION">AM_GNU_GETTEXT_VERSION</a>, +Previous: <a rel="previous" accesskey="p" href="#autoconf-macros">autoconf macros</a>, +Up: <a rel="up" accesskey="u" href="#autoconf-macros">autoconf macros</a> + +</div> + +<h4 class="subsection">13.5.1 AM_GNU_GETTEXT in <samp><span class="file">gettext.m4</span></samp></h4> + + <p><a name="index-AM_005fGNU_005fGETTEXT-1146"></a>The <code>AM_GNU_GETTEXT</code> macro tests for the presence of the GNU gettext +function family in either the C library or a separate <code>libintl</code> +library (shared or static libraries are both supported) or in the package's +<samp><span class="file">intl/</span></samp> directory. It also invokes <code>AM_PO_SUBDIRS</code>, thus preparing +the <samp><span class="file">po/</span></samp> directories of the package for building. + + <p><code>AM_GNU_GETTEXT</code> accepts up to three optional arguments. The general +syntax is + +<pre class="example"> AM_GNU_GETTEXT([<var>intlsymbol</var>], [<var>needsymbol</var>], [<var>intldir</var>]) +</pre> + <!-- We don't document @var{intlsymbol} = @samp{use-libtool} here, because --> +<!-- it is of no use for packages other than GNU gettext itself. (Such packages --> +<!-- are not allowed to install the shared libintl. But if they use libtool, --> +<!-- then it is in order to install shared libraries that depend on libintl.) --> + <p><var>intlsymbol</var> can be ‘<samp><span class="samp">external</span></samp>’ or ‘<samp><span class="samp">no-libtool</span></samp>’. The default +(if it is not specified or empty) is ‘<samp><span class="samp">no-libtool</span></samp>’. <var>intlsymbol</var> +should be ‘<samp><span class="samp">external</span></samp>’ for packages with no <samp><span class="file">intl/</span></samp> directory. +For packages with an <samp><span class="file">intl/</span></samp> directory, you can either use an +<var>intlsymbol</var> equal to ‘<samp><span class="samp">no-libtool</span></samp>’, or you can use ‘<samp><span class="samp">external</span></samp>’ +and override by using the macro <code>AM_GNU_GETTEXT_INTL_SUBDIR</code> elsewhere. +The two ways to specify the existence of an <samp><span class="file">intl/</span></samp> directory are +equivalent. At build time, a static library +<code>$(top_builddir)/intl/libintl.a</code> will then be created. + + <p>If <var>needsymbol</var> is specified and is ‘<samp><span class="samp">need-ngettext</span></samp>’, then GNU +gettext implementations (in libc or libintl) without the <code>ngettext()</code> +function will be ignored. If <var>needsymbol</var> is specified and is +‘<samp><span class="samp">need-formatstring-macros</span></samp>’, then GNU gettext implementations that don't +support the ISO C 99 <samp><span class="file"><inttypes.h></span></samp> formatstring macros will be ignored. +Only one <var>needsymbol</var> can be specified. These requirements can also be +specified by using the macro <code>AM_GNU_GETTEXT_NEED</code> elsewhere. To specify +more than one requirement, just specify the strongest one among them, or +invoke the <code>AM_GNU_GETTEXT_NEED</code> macro several times. The hierarchy +among the various alternatives is as follows: ‘<samp><span class="samp">need-formatstring-macros</span></samp>’ +implies ‘<samp><span class="samp">need-ngettext</span></samp>’. + + <p><var>intldir</var> is used to find the intl libraries. If empty, the value +‘<samp><span class="samp">$(top_builddir)/intl/</span></samp>’ is used. + + <p>The <code>AM_GNU_GETTEXT</code> macro determines whether GNU gettext is +available and should be used. If so, it sets the <code>USE_NLS</code> variable +to ‘<samp><span class="samp">yes</span></samp>’; it defines <code>ENABLE_NLS</code> to 1 in the autoconf +generated configuration file (usually called <samp><span class="file">config.h</span></samp>); it sets +the variables <code>LIBINTL</code> and <code>LTLIBINTL</code> to the linker options +for use in a Makefile (<code>LIBINTL</code> for use without libtool, +<code>LTLIBINTL</code> for use with libtool); it adds an ‘<samp><span class="samp">-I</span></samp>’ option to +<code>CPPFLAGS</code> if necessary. In the negative case, it sets +<code>USE_NLS</code> to ‘<samp><span class="samp">no</span></samp>’; it sets <code>LIBINTL</code> and <code>LTLIBINTL</code> +to empty and doesn't change <code>CPPFLAGS</code>. + + <p>The complexities that <code>AM_GNU_GETTEXT</code> deals with are the following: + + <ul> +<li><a name="index-g_t_0040code_007blibintl_007d-library-1147"></a>Some operating systems have <code>gettext</code> in the C library, for example +glibc. Some have it in a separate library <code>libintl</code>. GNU <code>libintl</code> +might have been installed as part of the GNU <code>gettext</code> package. + + <li>GNU <code>libintl</code>, if installed, is not necessarily already in the search +path (<code>CPPFLAGS</code> for the include file search path, <code>LDFLAGS</code> for +the library search path). + + <li>Except for glibc, the operating system's native <code>gettext</code> cannot +exploit the GNU mo files, doesn't have the necessary locale dependency +features, and cannot convert messages from the catalog's text encoding +to the user's locale encoding. + + <li>GNU <code>libintl</code>, if installed, is not necessarily already in the +run time library search path. To avoid the need for setting an environment +variable like <code>LD_LIBRARY_PATH</code>, the macro adds the appropriate +run time search path options to the <code>LIBINTL</code> and <code>LTLIBINTL</code> +variables. This works on most systems, but not on some operating systems +with limited shared library support, like SCO. + + <li>GNU <code>libintl</code> relies on POSIX/XSI <code>iconv</code>. The macro checks for +linker options needed to use iconv and appends them to the <code>LIBINTL</code> +and <code>LTLIBINTL</code> variables. +</ul> + +<div class="node"> +<a name="AM_GNU_GETTEXT_VERSION"></a> +<a name="AM_005fGNU_005fGETTEXT_005fVERSION"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#AM_005fGNU_005fGETTEXT_005fNEED">AM_GNU_GETTEXT_NEED</a>, +Previous: <a rel="previous" accesskey="p" href="#AM_005fGNU_005fGETTEXT">AM_GNU_GETTEXT</a>, +Up: <a rel="up" accesskey="u" href="#autoconf-macros">autoconf macros</a> + +</div> + +<h4 class="subsection">13.5.2 AM_GNU_GETTEXT_VERSION in <samp><span class="file">gettext.m4</span></samp></h4> + + <p><a name="index-AM_005fGNU_005fGETTEXT_005fVERSION-1148"></a>The <code>AM_GNU_GETTEXT_VERSION</code> macro declares the version number of +the GNU gettext infrastructure that is used by the package. + + <p>The use of this macro is optional; only the <code>autopoint</code> program makes +use of it (see <a href="#CVS-Issues">CVS Issues</a>). + +<div class="node"> +<a name="AM_GNU_GETTEXT_NEED"></a> +<a name="AM_005fGNU_005fGETTEXT_005fNEED"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#AM_005fGNU_005fGETTEXT_005fINTL_005fSUBDIR">AM_GNU_GETTEXT_INTL_SUBDIR</a>, +Previous: <a rel="previous" accesskey="p" href="#AM_005fGNU_005fGETTEXT_005fVERSION">AM_GNU_GETTEXT_VERSION</a>, +Up: <a rel="up" accesskey="u" href="#autoconf-macros">autoconf macros</a> + +</div> + +<h4 class="subsection">13.5.3 AM_GNU_GETTEXT_NEED in <samp><span class="file">gettext.m4</span></samp></h4> + + <p><a name="index-AM_005fGNU_005fGETTEXT_005fNEED-1149"></a>The <code>AM_GNU_GETTEXT_NEED</code> macro declares a constraint regarding the +GNU gettext implementation. The syntax is + +<pre class="example"> AM_GNU_GETTEXT_NEED([<var>needsymbol</var>]) +</pre> + <p>If <var>needsymbol</var> is ‘<samp><span class="samp">need-ngettext</span></samp>’, then GNU gettext implementations +(in libc or libintl) without the <code>ngettext()</code> function will be ignored. +If <var>needsymbol</var> is ‘<samp><span class="samp">need-formatstring-macros</span></samp>’, then GNU gettext +implementations that don't support the ISO C 99 <samp><span class="file"><inttypes.h></span></samp> +formatstring macros will be ignored. + + <p>The optional second argument of <code>AM_GNU_GETTEXT</code> is also taken into +account. + + <p>The <code>AM_GNU_GETTEXT_NEED</code> invocations can occur before or after +the <code>AM_GNU_GETTEXT</code> invocation; the order doesn't matter. + +<div class="node"> +<a name="AM_GNU_GETTEXT_INTL_SUBDIR"></a> +<a name="AM_005fGNU_005fGETTEXT_005fINTL_005fSUBDIR"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#AM_005fPO_005fSUBDIRS">AM_PO_SUBDIRS</a>, +Previous: <a rel="previous" accesskey="p" href="#AM_005fGNU_005fGETTEXT_005fNEED">AM_GNU_GETTEXT_NEED</a>, +Up: <a rel="up" accesskey="u" href="#autoconf-macros">autoconf macros</a> + +</div> + +<h4 class="subsection">13.5.4 AM_GNU_GETTEXT_INTL_SUBDIR in <samp><span class="file">intldir.m4</span></samp></h4> + + <p><a name="index-AM_005fGNU_005fGETTEXT_005fINTL_005fSUBDIR-1150"></a>The <code>AM_GNU_GETTEXT_INTL_SUBDIR</code> macro specifies that the +<code>AM_GNU_GETTEXT</code> macro, although invoked with the first argument +‘<samp><span class="samp">external</span></samp>’, should also prepare for building the <samp><span class="file">intl/</span></samp> +subdirectory. + + <p>The <code>AM_GNU_GETTEXT_INTL_SUBDIR</code> invocation can occur before or after +the <code>AM_GNU_GETTEXT</code> invocation; the order doesn't matter. + + <p>The use of this macro requires GNU automake 1.10 or newer and +GNU autoconf 2.61 or newer. + +<div class="node"> +<a name="AM_PO_SUBDIRS"></a> +<a name="AM_005fPO_005fSUBDIRS"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#AM_005fXGETTEXT_005fOPTION">AM_XGETTEXT_OPTION</a>, +Previous: <a rel="previous" accesskey="p" href="#AM_005fGNU_005fGETTEXT_005fINTL_005fSUBDIR">AM_GNU_GETTEXT_INTL_SUBDIR</a>, +Up: <a rel="up" accesskey="u" href="#autoconf-macros">autoconf macros</a> + +</div> + +<h4 class="subsection">13.5.5 AM_PO_SUBDIRS in <samp><span class="file">po.m4</span></samp></h4> + + <p><a name="index-AM_005fPO_005fSUBDIRS-1151"></a>The <code>AM_PO_SUBDIRS</code> macro prepares the <samp><span class="file">po/</span></samp> directories of the +package for building. This macro should be used in internationalized +programs written in other programming languages than C, C++, Objective C, +for example <code>sh</code>, <code>Python</code>, <code>Lisp</code>. See <a href="#Programming-Languages">Programming Languages</a> for a list of programming languages that support localization +through PO files. + + <p>The <code>AM_PO_SUBDIRS</code> macro determines whether internationalization +should be used. If so, it sets the <code>USE_NLS</code> variable to ‘<samp><span class="samp">yes</span></samp>’, +otherwise to ‘<samp><span class="samp">no</span></samp>’. It also determines the right values for Makefile +variables in each <samp><span class="file">po/</span></samp> directory. + +<div class="node"> +<a name="AM_XGETTEXT_OPTION"></a> +<a name="AM_005fXGETTEXT_005fOPTION"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#AM_005fICONV">AM_ICONV</a>, +Previous: <a rel="previous" accesskey="p" href="#AM_005fPO_005fSUBDIRS">AM_PO_SUBDIRS</a>, +Up: <a rel="up" accesskey="u" href="#autoconf-macros">autoconf macros</a> + +</div> + +<h4 class="subsection">13.5.6 AM_XGETTEXT_OPTION in <samp><span class="file">po.m4</span></samp></h4> + + <p><a name="index-AM_005fXGETTEXT_005fOPTION-1152"></a>The <code>AM_XGETTEXT_OPTION</code> macro registers a command-line option to be +used in the invocations of <code>xgettext</code> in the <samp><span class="file">po/</span></samp> directories +of the package. + + <p>For example, if you have a source file that defines a function +‘<samp><span class="samp">error_at_line</span></samp>’ whose fifth argument is a format string, you can use +<pre class="example"> AM_XGETTEXT_OPTION([--flag=error_at_line:5:c-format]) +</pre> + <p class="noindent">to instruct <code>xgettext</code> to mark all translatable strings in ‘<samp><span class="samp">gettext</span></samp>’ +invocations that occur as fifth argument to this function as ‘<samp><span class="samp">c-format</span></samp>’. + + <p>See <a href="#xgettext-Invocation">xgettext Invocation</a> for the list of options that <code>xgettext</code> +accepts. + + <p>The use of this macro is an alternative to the use of the +‘<samp><span class="samp">XGETTEXT_OPTIONS</span></samp>’ variable in <samp><span class="file">po/Makevars</span></samp>. + +<div class="node"> +<a name="AM_ICONV"></a> +<a name="AM_005fICONV"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#AM_005fXGETTEXT_005fOPTION">AM_XGETTEXT_OPTION</a>, +Up: <a rel="up" accesskey="u" href="#autoconf-macros">autoconf macros</a> + +</div> + +<h4 class="subsection">13.5.7 AM_ICONV in <samp><span class="file">iconv.m4</span></samp></h4> + + <p><a name="index-AM_005fICONV-1153"></a>The <code>AM_ICONV</code> macro tests for the presence of the POSIX/XSI +<code>iconv</code> function family in either the C library or a separate +<code>libiconv</code> library. If found, it sets the <code>am_cv_func_iconv</code> +variable to ‘<samp><span class="samp">yes</span></samp>’; it defines <code>HAVE_ICONV</code> to 1 in the autoconf +generated configuration file (usually called <samp><span class="file">config.h</span></samp>); it defines +<code>ICONV_CONST</code> to ‘<samp><span class="samp">const</span></samp>’ or to empty, depending on whether the +second argument of <code>iconv()</code> is of type ‘<samp><span class="samp">const char **</span></samp>’ or +‘<samp><span class="samp">char **</span></samp>’; it sets the variables <code>LIBICONV</code> and +<code>LTLIBICONV</code> to the linker options for use in a Makefile +(<code>LIBICONV</code> for use without libtool, <code>LTLIBICONV</code> for use with +libtool); it adds an ‘<samp><span class="samp">-I</span></samp>’ option to <code>CPPFLAGS</code> if +necessary. If not found, it sets <code>LIBICONV</code> and <code>LTLIBICONV</code> to +empty and doesn't change <code>CPPFLAGS</code>. + + <p>The complexities that <code>AM_ICONV</code> deals with are the following: + + <ul> +<li><a name="index-g_t_0040code_007blibiconv_007d-library-1154"></a>Some operating systems have <code>iconv</code> in the C library, for example +glibc. Some have it in a separate library <code>libiconv</code>, for example +OSF/1 or FreeBSD. Regardless of the operating system, GNU <code>libiconv</code> +might have been installed. In that case, it should be used instead of the +operating system's native <code>iconv</code>. + + <li>GNU <code>libiconv</code>, if installed, is not necessarily already in the search +path (<code>CPPFLAGS</code> for the include file search path, <code>LDFLAGS</code> for +the library search path). + + <li>GNU <code>libiconv</code> is binary incompatible with some operating system's +native <code>iconv</code>, for example on FreeBSD. Use of an <samp><span class="file">iconv.h</span></samp> +and <samp><span class="file">libiconv.so</span></samp> that don't fit together would produce program +crashes. + + <li>GNU <code>libiconv</code>, if installed, is not necessarily already in the +run time library search path. To avoid the need for setting an environment +variable like <code>LD_LIBRARY_PATH</code>, the macro adds the appropriate +run time search path options to the <code>LIBICONV</code> variable. This works +on most systems, but not on some operating systems with limited shared +library support, like SCO. +</ul> + + <p><samp><span class="file">iconv.m4</span></samp> is distributed with the GNU gettext package because +<samp><span class="file">gettext.m4</span></samp> relies on it. + +<div class="node"> +<a name="CVS-Issues"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Release-Management">Release Management</a>, +Previous: <a rel="previous" accesskey="p" href="#autoconf-macros">autoconf macros</a>, +Up: <a rel="up" accesskey="u" href="#Maintainers">Maintainers</a> + +</div> + +<h3 class="section">13.6 Integrating with CVS</h3> + + <p>Many projects use CVS for distributed development, version control and +source backup. This section gives some advice how to manage the uses +of <code>cvs</code>, <code>gettextize</code>, <code>autopoint</code> and <code>autoconf</code>. + +<ul class="menu"> +<li><a accesskey="1" href="#Distributed-CVS">Distributed CVS</a>: Avoiding version mismatch in distributed development +<li><a accesskey="2" href="#Files-under-CVS">Files under CVS</a>: Files to put under CVS version control +<li><a accesskey="3" href="#autopoint-Invocation">autopoint Invocation</a>: Invoking the <code>autopoint</code> Program +</ul> + +<div class="node"> +<a name="Distributed-CVS"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Files-under-CVS">Files under CVS</a>, +Previous: <a rel="previous" accesskey="p" href="#CVS-Issues">CVS Issues</a>, +Up: <a rel="up" accesskey="u" href="#CVS-Issues">CVS Issues</a> + +</div> + +<h4 class="subsection">13.6.1 Avoiding version mismatch in distributed development</h4> + + <p>In a project development with multiple developers, using CVS, there +should be a single developer who occasionally - when there is desire to +upgrade to a new <code>gettext</code> version - runs <code>gettextize</code> and +performs the changes listed in <a href="#Adjusting-Files">Adjusting Files</a>, and then commits +his changes to the CVS. + + <p>It is highly recommended that all developers on a project use the same +version of GNU <code>gettext</code> in the package. In other words, if a +developer runs <code>gettextize</code>, he should go the whole way, make the +necessary remaining changes and commit his changes to the CVS. +Otherwise the following damages will likely occur: + + <ul> +<li>Apparent version mismatch between developers. Since some <code>gettext</code> +specific portions in <samp><span class="file">configure.ac</span></samp>, <samp><span class="file">configure.in</span></samp> and +<code>Makefile.am</code>, <code>Makefile.in</code> files depend on the <code>gettext</code> +version, the use of infrastructure files belonging to different +<code>gettext</code> versions can easily lead to build errors. + + <li>Hidden version mismatch. Such version mismatch can also lead to +malfunctioning of the package, that may be undiscovered by the developers. +The worst case of hidden version mismatch is that internationalization +of the package doesn't work at all. + + <li>Release risks. All developers implicitly perform constant testing on +a package. This is important in the days and weeks before a release. +If the guy who makes the release tar files uses a different version +of GNU <code>gettext</code> than the other developers, the distribution will +be less well tested than if all had been using the same <code>gettext</code> +version. For example, it is possible that a platform specific bug goes +undiscovered due to this constellation. +</ul> + +<div class="node"> +<a name="Files-under-CVS"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#autopoint-Invocation">autopoint Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#Distributed-CVS">Distributed CVS</a>, +Up: <a rel="up" accesskey="u" href="#CVS-Issues">CVS Issues</a> + +</div> + +<h4 class="subsection">13.6.2 Files to put under CVS version control</h4> + + <p>There are basically three ways to deal with generated files in the +context of a CVS repository, such as <samp><span class="file">configure</span></samp> generated from +<samp><span class="file">configure.ac</span></samp>, <var>parser</var><code>.c</code> generated from +<var>parser</var><code>.y</code>, or <code>po/Makefile.in.in</code> autoinstalled by +<code>gettextize</code> or <code>autopoint</code>. + + <ol type=1 start=1> +<li>All generated files are always committed into the repository. + + <li>All generated files are committed into the repository occasionally, +for example each time a release is made. + + <li>Generated files are never committed into the repository. + </ol> + + <p>Each of these three approaches has different advantages and drawbacks. + + <ol type=1 start=1> +<li>The advantage is that anyone can check out the CVS at any moment and +gets a working build. The drawbacks are: 1a. It requires some frequent +"cvs commit" actions by the maintainers. 1b. The repository grows in size +quite fast. + + <li>The advantage is that anyone can check out the CVS, and the usual +"./configure; make" will work. The drawbacks are: 2a. The one who +checks out the repository needs tools like GNU <code>automake</code>, +GNU <code>autoconf</code>, GNU <code>m4</code> installed in his PATH; sometimes +he even needs particular versions of them. 2b. When a release is made +and a commit is made on the generated files, the other developers get +conflicts on the generated files after doing "cvs update". Although +these conflicts are easy to resolve, they are annoying. + + <li>The advantage is less work for the maintainers. The drawback is that +anyone who checks out the CVS not only needs tools like GNU <code>automake</code>, +GNU <code>autoconf</code>, GNU <code>m4</code> installed in his PATH, but also that +he needs to perform a package specific pre-build step before being able +to "./configure; make". + </ol> + + <p>For the first and second approach, all files modified or brought in +by the occasional <code>gettextize</code> invocation and update should be +committed into the CVS. + + <p>For the third approach, the maintainer can omit from the CVS repository +all the files that <code>gettextize</code> mentions as "copy". Instead, he +adds to the <samp><span class="file">configure.ac</span></samp> or <samp><span class="file">configure.in</span></samp> a line of the +form + +<pre class="example"> AM_GNU_GETTEXT_VERSION(0.18) +</pre> + <p class="noindent">and adds to the package's pre-build script an invocation of +‘<samp><span class="samp">autopoint</span></samp>’. For everyone who checks out the CVS, this +<code>autopoint</code> invocation will copy into the right place the +<code>gettext</code> infrastructure files that have been omitted from the CVS. + + <p>The version number used as argument to <code>AM_GNU_GETTEXT_VERSION</code> is +the version of the <code>gettext</code> infrastructure that the package wants +to use. It is also the minimum version number of the ‘<samp><span class="samp">autopoint</span></samp>’ +program. So, if you write <code>AM_GNU_GETTEXT_VERSION(0.11.5)</code> then the +developers can have any version >= 0.11.5 installed; the package will work +with the 0.11.5 infrastructure in all developers' builds. When the +maintainer then runs gettextize from, say, version 0.12.1 on the package, +the occurrence of <code>AM_GNU_GETTEXT_VERSION(0.11.5)</code> will be changed +into <code>AM_GNU_GETTEXT_VERSION(0.12.1)</code>, and all other developers that +use the CVS will henceforth need to have GNU <code>gettext</code> 0.12.1 or newer +installed. + +<div class="node"> +<a name="autopoint-Invocation"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Files-under-CVS">Files under CVS</a>, +Up: <a rel="up" accesskey="u" href="#CVS-Issues">CVS Issues</a> + +</div> + +<h4 class="subsection">13.6.3 Invoking the <code>autopoint</code> Program</h4> + + <p><a name="index-autopoint-1155"></a><a name="index-g_t_0040code_007bautopoint_007d-program_002c-usage-1156"></a> +<pre class="example"> autopoint [<var>option</var>]... +</pre> + <p>The <code>autopoint</code> program copies standard gettext infrastructure files +into a source package. It extracts from a macro call of the form +<code>AM_GNU_GETTEXT_VERSION(</code><var>version</var><code>)</code>, found in the package's +<samp><span class="file">configure.in</span></samp> or <samp><span class="file">configure.ac</span></samp> file, the gettext version +used by the package, and copies the infrastructure files belonging to +this version into the package. + +<h5 class="subsubsection">13.6.3.1 Options</h5> + + <dl> +<dt>‘<samp><span class="samp">-f</span></samp>’<dt>‘<samp><span class="samp">--force</span></samp>’<dd><a name="index-g_t_002df_0040r_007b_002c-_0040code_007bautopoint_007d-option_007d-1157"></a><a name="index-g_t_002d_002dforce_0040r_007b_002c-_0040code_007bautopoint_007d-option_007d-1158"></a>Force overwriting of files that already exist. + + <br><dt>‘<samp><span class="samp">-n</span></samp>’<dt>‘<samp><span class="samp">--dry-run</span></samp>’<dd><a name="index-g_t_002dd_0040r_007b_002c-_0040code_007bautopoint_007d-option_007d-1159"></a><a name="index-g_t_002d_002ddry_002drun_0040r_007b_002c-_0040code_007bautopoint_007d-option_007d-1160"></a>Print modifications but don't perform them. All file copying actions that +<code>autopoint</code> would normally execute are inhibited and instead only +listed on standard output. + + </dl> + +<h5 class="subsubsection">13.6.3.2 Informative output</h5> + + <dl> +<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bautopoint_007d-option_007d-1161"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bautopoint_007d-option_007d-1162"></a>Output version information and exit. + + </dl> + + <p><code>autopoint</code> supports the GNU <code>gettext</code> versions from 0.10.35 to +the current one, 0.18. In order to apply <code>autopoint</code> to +a package using a <code>gettext</code> version newer than 0.18, you +need to install this same version of GNU <code>gettext</code> at least. + + <p>In packages using GNU <code>automake</code>, an invocation of <code>autopoint</code> +should be followed by invocations of <code>aclocal</code> and then <code>autoconf</code> +and <code>autoheader</code>. The reason is that <code>autopoint</code> installs some +autoconf macro files, which are used by <code>aclocal</code> to create +<samp><span class="file">aclocal.m4</span></samp>, and the latter is used by <code>autoconf</code> to create the +package's <samp><span class="file">configure</span></samp> script and by <code>autoheader</code> to create the +package's <samp><span class="file">config.h.in</span></samp> include file template. + + <p>The name ‘<samp><span class="samp">autopoint</span></samp>’ is an abbreviation of ‘<samp><span class="samp">auto-po-intl-m4</span></samp>’; +the tool copies or updates mostly files in the <samp><span class="file">po</span></samp>, <samp><span class="file">intl</span></samp>, +<samp><span class="file">m4</span></samp> directories. + +<div class="node"> +<a name="Release-Management"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#CVS-Issues">CVS Issues</a>, +Up: <a rel="up" accesskey="u" href="#Maintainers">Maintainers</a> + +</div> + +<h3 class="section">13.7 Creating a Distribution Tarball</h3> + + <p><a name="index-release-1163"></a><a name="index-distribution-tarball-1164"></a>In projects that use GNU <code>automake</code>, the usual commands for creating +a distribution tarball, ‘<samp><span class="samp">make dist</span></samp>’ or ‘<samp><span class="samp">make distcheck</span></samp>’, +automatically update the PO files as needed. + + <p>If GNU <code>automake</code> is not used, the maintainer needs to perform this +update before making a release: + +<pre class="example"> $ ./configure + $ (cd po; make update-po) + $ make distclean +</pre> + <div class="node"> +<a name="Installers"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Programming-Languages">Programming Languages</a>, +Previous: <a rel="previous" accesskey="p" href="#Maintainers">Maintainers</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">14 The Installer's and Distributor's View</h2> + + <p><a name="index-package-installer_0027s-view-of-_0040code_007bgettext_007d-1165"></a><a name="index-package-distributor_0027s-view-of-_0040code_007bgettext_007d-1166"></a><a name="index-package-build-and-installation-options-1167"></a><a name="index-setting-up-_0040code_007bgettext_007d-at-build-time-1168"></a> +By default, packages fully using GNU <code>gettext</code>, internally, +are installed in such a way that they to allow translation of +messages. At <em>configuration</em> time, those packages should +automatically detect whether the underlying host system already provides +the GNU <code>gettext</code> functions. If not, +the GNU <code>gettext</code> library should be automatically prepared +and used. Installers may use special options at configuration +time for changing this behavior. The command ‘<samp><span class="samp">./configure +--with-included-gettext</span></samp>’ bypasses system <code>gettext</code> to +use the included GNU <code>gettext</code> instead, +while ‘<samp><span class="samp">./configure --disable-nls</span></samp>’ +produces programs totally unable to translate messages. + + <p><a name="index-LINGUAS_0040r_007b_002c-environment-variable_007d-1169"></a>Internationalized packages have usually many <samp><var>ll</var><span class="file">.po</span></samp> +files. Unless +translations are disabled, all those available are installed together +with the package. However, the environment variable <code>LINGUAS</code> +may be set, prior to configuration, to limit the installed set. +<code>LINGUAS</code> should then contain a space separated list of two-letter +codes, stating which languages are allowed. + +<div class="node"> +<a name="Programming-Languages"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Conclusion">Conclusion</a>, +Previous: <a rel="previous" accesskey="p" href="#Installers">Installers</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">15 Other Programming Languages</h2> + + <p>While the presentation of <code>gettext</code> focuses mostly on C and +implicitly applies to C++ as well, its scope is far broader than that: +Many programming languages, scripting languages and other textual data +like GUI resources or package descriptions can make use of the gettext +approach. + +<ul class="menu"> +<li><a accesskey="1" href="#Language-Implementors">Language Implementors</a>: The Language Implementor's View +<li><a accesskey="2" href="#Programmers-for-other-Languages">Programmers for other Languages</a>: The Programmer's View +<li><a accesskey="3" href="#Translators-for-other-Languages">Translators for other Languages</a>: The Translator's View +<li><a accesskey="4" href="#Maintainers-for-other-Languages">Maintainers for other Languages</a>: The Maintainer's View +<li><a accesskey="5" href="#List-of-Programming-Languages">List of Programming Languages</a>: Individual Programming Languages +<li><a accesskey="6" href="#List-of-Data-Formats">List of Data Formats</a>: Internationalizable Data +</ul> + +<div class="node"> +<a name="Language-Implementors"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Programmers-for-other-Languages">Programmers for other Languages</a>, +Previous: <a rel="previous" accesskey="p" href="#Programming-Languages">Programming Languages</a>, +Up: <a rel="up" accesskey="u" href="#Programming-Languages">Programming Languages</a> + +</div> + +<h3 class="section">15.1 The Language Implementor's View</h3> + + <p><a name="index-programming-languages-1170"></a><a name="index-scripting-languages-1171"></a> +All programming and scripting languages that have the notion of strings +are eligible to supporting <code>gettext</code>. Supporting <code>gettext</code> +means the following: + + <ol type=1 start=1> +<li>You should add to the language a syntax for translatable strings. In +principle, a function call of <code>gettext</code> would do, but a shorthand +syntax helps keeping the legibility of internationalized programs. For +example, in C we use the syntax <code>_("string")</code>, and in GNU awk we use +the shorthand <code>_"string"</code>. + + <li>You should arrange that evaluation of such a translatable string at +runtime calls the <code>gettext</code> function, or performs equivalent +processing. + + <li>Similarly, you should make the functions <code>ngettext</code>, +<code>dcgettext</code>, <code>dcngettext</code> available from within the language. +These functions are less often used, but are nevertheless necessary for +particular purposes: <code>ngettext</code> for correct plural handling, and +<code>dcgettext</code> and <code>dcngettext</code> for obeying other locale-related +environment variables than <code>LC_MESSAGES</code>, such as <code>LC_TIME</code> or +<code>LC_MONETARY</code>. For these latter functions, you need to make the +<code>LC_*</code> constants, available in the C header <code><locale.h></code>, +referenceable from within the language, usually either as enumeration +values or as strings. + + <li>You should allow the programmer to designate a message domain, either by +making the <code>textdomain</code> function available from within the +language, or by introducing a magic variable called <code>TEXTDOMAIN</code>. +Similarly, you should allow the programmer to designate where to search +for message catalogs, by providing access to the <code>bindtextdomain</code> +function. + + <li>You should either perform a <code>setlocale (LC_ALL, "")</code> call during +the startup of your language runtime, or allow the programmer to do so. +Remember that gettext will act as a no-op if the <code>LC_MESSAGES</code> and +<code>LC_CTYPE</code> locale categories are not both set. + + <li>A programmer should have a way to extract translatable strings from a +program into a PO file. The GNU <code>xgettext</code> program is being +extended to support very different programming languages. Please +contact the GNU <code>gettext</code> maintainers to help them doing this. If +the string extractor is best integrated into your language's parser, GNU +<code>xgettext</code> can function as a front end to your string extractor. + + <li>The language's library should have a string formatting facility where +the arguments of a format string are denoted by a positional number or a +name. This is needed because for some languages and some messages with +more than one substitutable argument, the translation will need to +output the substituted arguments in different order. See <a href="#c_002dformat-Flag">c-format Flag</a>. + + <li>If the language has more than one implementation, and not all of the +implementations use <code>gettext</code>, but the programs should be portable +across implementations, you should provide a no-i18n emulation, that +makes the other implementations accept programs written for yours, +without actually translating the strings. + + <li>To help the programmer in the task of marking translatable strings, +which is sometimes performed using the Emacs PO mode (see <a href="#Marking">Marking</a>), +you are welcome to +contact the GNU <code>gettext</code> maintainers, so they can add support for +your language to <samp><span class="file">po-mode.el</span></samp>. + </ol> + + <p>On the implementation side, three approaches are possible, with +different effects on portability and copyright: + + <ul> +<li>You may integrate the GNU <code>gettext</code>'s <samp><span class="file">intl/</span></samp> directory in +your package, as described in <a href="#Maintainers">Maintainers</a>. This allows you to +have internationalization on all kinds of platforms. Note that when you +then distribute your package, it legally falls under the GNU General +Public License, and the GNU project will be glad about your contribution +to the Free Software pool. + + <li>You may link against GNU <code>gettext</code> functions if they are found in +the C library. For example, an autoconf test for <code>gettext()</code> and +<code>ngettext()</code> will detect this situation. For the moment, this test +will succeed on GNU systems and not on other platforms. No severe +copyright restrictions apply. + + <li>You may emulate or reimplement the GNU <code>gettext</code> functionality. +This has the advantage of full portability and no copyright +restrictions, but also the drawback that you have to reimplement the GNU +<code>gettext</code> features (such as the <code>LANGUAGE</code> environment +variable, the locale aliases database, the automatic charset conversion, +and plural handling). +</ul> + +<div class="node"> +<a name="Programmers-for-other-Languages"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Translators-for-other-Languages">Translators for other Languages</a>, +Previous: <a rel="previous" accesskey="p" href="#Language-Implementors">Language Implementors</a>, +Up: <a rel="up" accesskey="u" href="#Programming-Languages">Programming Languages</a> + +</div> + +<h3 class="section">15.2 The Programmer's View</h3> + + <p>For the programmer, the general procedure is the same as for the C +language. The Emacs PO mode marking supports other languages, and the GNU +<code>xgettext</code> string extractor recognizes other languages based on the +file extension or a command-line option. In some languages, +<code>setlocale</code> is not needed because it is already performed by the +underlying language runtime. + +<div class="node"> +<a name="Translators-for-other-Languages"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Maintainers-for-other-Languages">Maintainers for other Languages</a>, +Previous: <a rel="previous" accesskey="p" href="#Programmers-for-other-Languages">Programmers for other Languages</a>, +Up: <a rel="up" accesskey="u" href="#Programming-Languages">Programming Languages</a> + +</div> + +<h3 class="section">15.3 The Translator's View</h3> + + <p>The translator works exactly as in the C language case. The only +difference is that when translating format strings, she has to be aware +of the language's particular syntax for positional arguments in format +strings. + +<ul class="menu"> +<li><a accesskey="1" href="#c_002dformat">c-format</a>: C Format Strings +<li><a accesskey="2" href="#objc_002dformat">objc-format</a>: Objective C Format Strings +<li><a accesskey="3" href="#sh_002dformat">sh-format</a>: Shell Format Strings +<li><a accesskey="4" href="#python_002dformat">python-format</a>: Python Format Strings +<li><a accesskey="5" href="#lisp_002dformat">lisp-format</a>: Lisp Format Strings +<li><a accesskey="6" href="#elisp_002dformat">elisp-format</a>: Emacs Lisp Format Strings +<li><a accesskey="7" href="#librep_002dformat">librep-format</a>: librep Format Strings +<li><a accesskey="8" href="#scheme_002dformat">scheme-format</a>: Scheme Format Strings +<li><a accesskey="9" href="#smalltalk_002dformat">smalltalk-format</a>: Smalltalk Format Strings +<li><a href="#java_002dformat">java-format</a>: Java Format Strings +<li><a href="#csharp_002dformat">csharp-format</a>: C# Format Strings +<li><a href="#awk_002dformat">awk-format</a>: awk Format Strings +<li><a href="#object_002dpascal_002dformat">object-pascal-format</a>: Object Pascal Format Strings +<li><a href="#ycp_002dformat">ycp-format</a>: YCP Format Strings +<li><a href="#tcl_002dformat">tcl-format</a>: Tcl Format Strings +<li><a href="#perl_002dformat">perl-format</a>: Perl Format Strings +<li><a href="#php_002dformat">php-format</a>: PHP Format Strings +<li><a href="#gcc_002dinternal_002dformat">gcc-internal-format</a>: GCC internal Format Strings +<li><a href="#gfc_002dinternal_002dformat">gfc-internal-format</a>: GFC internal Format Strings +<li><a href="#qt_002dformat">qt-format</a>: Qt Format Strings +<li><a href="#qt_002dplural_002dformat">qt-plural-format</a>: Qt Plural Format Strings +<li><a href="#kde_002dformat">kde-format</a>: KDE Format Strings +<li><a href="#boost_002dformat">boost-format</a>: Boost Format Strings +</ul> + +<div class="node"> +<a name="c-format"></a> +<a name="c_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#objc_002dformat">objc-format</a>, +Previous: <a rel="previous" accesskey="p" href="#Translators-for-other-Languages">Translators for other Languages</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.1 C Format Strings</h4> + + <p>C format strings are described in POSIX (IEEE P1003.1 2001), section +XSH 3 fprintf(), +<a href="http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html">http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html</a>. +See also the fprintf() manual page, +<a href="http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php">http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php</a>, +<a href="http://informatik.fh-wuerzburg.de/student/i510/man/printf.html">http://informatik.fh-wuerzburg.de/student/i510/man/printf.html</a>. + + <p>Although format strings with positions that reorder arguments, such as + +<pre class="example"> "Only %2$d bytes free on '%1$s'." +</pre> + <p class="noindent">which is semantically equivalent to + +<pre class="example"> "'%s' has only %d bytes free." +</pre> + <p class="noindent">are a POSIX/XSI feature and not specified by ISO C 99, translators can rely +on this reordering ability: On the few platforms where <code>printf()</code>, +<code>fprintf()</code> etc. don't support this feature natively, <samp><span class="file">libintl.a</span></samp> +or <samp><span class="file">libintl.so</span></samp> provides replacement functions, and GNU <code><libintl.h></code> +activates these replacement functions automatically. + + <p><a name="index-outdigits-1172"></a><a name="index-Arabic-digits-1173"></a>As a special feature for Farsi (Persian) and maybe Arabic, translators can +insert an ‘<samp><span class="samp">I</span></samp>’ flag into numeric format directives. For example, the +translation of <code>"%d"</code> can be <code>"%Id"</code>. The effect of this flag, +on systems with GNU <code>libc</code>, is that in the output, the ASCII digits are +replaced with the ‘<samp><span class="samp">outdigits</span></samp>’ defined in the <code>LC_CTYPE</code> locale +category. On other systems, the <code>gettext</code> function removes this flag, +so that it has no effect. + + <p>Note that the programmer should <em>not</em> put this flag into the +untranslated string. (Putting the ‘<samp><span class="samp">I</span></samp>’ format directive flag into an +<var>msgid</var> string would lead to undefined behaviour on platforms without +glibc when NLS is disabled.) + +<div class="node"> +<a name="objc-format"></a> +<a name="objc_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#sh_002dformat">sh-format</a>, +Previous: <a rel="previous" accesskey="p" href="#c_002dformat">c-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.2 Objective C Format Strings</h4> + + <p>Objective C format strings are like C format strings. They support an +additional format directive: "%@", which when executed consumes an argument +of type <code>Object *</code>. + +<div class="node"> +<a name="sh-format"></a> +<a name="sh_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#python_002dformat">python-format</a>, +Previous: <a rel="previous" accesskey="p" href="#objc_002dformat">objc-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.3 Shell Format Strings</h4> + + <p>Shell format strings, as supported by GNU gettext and the ‘<samp><span class="samp">envsubst</span></samp>’ +program, are strings with references to shell variables in the form +<code>$</code><var>variable</var> or <code>${</code><var>variable</var><code>}</code>. References of the form +<code>${</code><var>variable</var><code>-</code><var>default</var><code>}</code>, +<code>${</code><var>variable</var><code>:-</code><var>default</var><code>}</code>, +<code>${</code><var>variable</var><code>=</code><var>default</var><code>}</code>, +<code>${</code><var>variable</var><code>:=</code><var>default</var><code>}</code>, +<code>${</code><var>variable</var><code>+</code><var>replacement</var><code>}</code>, +<code>${</code><var>variable</var><code>:+</code><var>replacement</var><code>}</code>, +<code>${</code><var>variable</var><code>?</code><var>ignored</var><code>}</code>, +<code>${</code><var>variable</var><code>:?</code><var>ignored</var><code>}</code>, +that would be valid inside shell scripts, are not supported. The +<var>variable</var> names must consist solely of alphanumeric or underscore +ASCII characters, not start with a digit and be nonempty; otherwise such +a variable reference is ignored. + +<div class="node"> +<a name="python-format"></a> +<a name="python_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#lisp_002dformat">lisp-format</a>, +Previous: <a rel="previous" accesskey="p" href="#sh_002dformat">sh-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.4 Python Format Strings</h4> + + <p>Python format strings are described in +Python Library reference<!-- /@w --> / +2. Built-in Types, Exceptions and Functions<!-- /@w --> / +2.2. Built-in Types<!-- /@w --> / +2.2.6. Sequence Types<!-- /@w --> / +2.2.6.2. String Formatting Operations<!-- /@w -->. +<a href="http://www.python.org/doc/2.2.1/lib/typesseq-strings.html">http://www.python.org/doc/2.2.1/lib/typesseq-strings.html</a>. + +<div class="node"> +<a name="lisp-format"></a> +<a name="lisp_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#elisp_002dformat">elisp-format</a>, +Previous: <a rel="previous" accesskey="p" href="#python_002dformat">python-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.5 Lisp Format Strings</h4> + + <p>Lisp format strings are described in the Common Lisp HyperSpec, +chapter 22.3 Formatted Output<!-- /@w -->, +<a href="http://www.lisp.org/HyperSpec/Body/sec_22-3.html">http://www.lisp.org/HyperSpec/Body/sec_22-3.html</a>. + +<div class="node"> +<a name="elisp-format"></a> +<a name="elisp_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#librep_002dformat">librep-format</a>, +Previous: <a rel="previous" accesskey="p" href="#lisp_002dformat">lisp-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.6 Emacs Lisp Format Strings</h4> + + <p>Emacs Lisp format strings are documented in the Emacs Lisp reference, +section Formatting Strings<!-- /@w -->, +<a href="http://www.gnu.org/manual/elisp-manual-21-2.8/html_chapter/elisp_4.html#SEC75">http://www.gnu.org/manual/elisp-manual-21-2.8/html_chapter/elisp_4.html#SEC75</a>. +Note that as of version 21, XEmacs supports numbered argument specifications +in format strings while FSF Emacs doesn't. + +<div class="node"> +<a name="librep-format"></a> +<a name="librep_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#scheme_002dformat">scheme-format</a>, +Previous: <a rel="previous" accesskey="p" href="#elisp_002dformat">elisp-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.7 librep Format Strings</h4> + + <p>librep format strings are documented in the librep manual, section +Formatted Output<!-- /@w -->, +<a href="http://librep.sourceforge.net/librep-manual.html#Formatted%20Output">http://librep.sourceforge.net/librep-manual.html#Formatted%20Output</a>, +<a href="http://www.gwinnup.org/research/docs/librep.html#SEC122">http://www.gwinnup.org/research/docs/librep.html#SEC122</a>. + +<div class="node"> +<a name="scheme-format"></a> +<a name="scheme_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#smalltalk_002dformat">smalltalk-format</a>, +Previous: <a rel="previous" accesskey="p" href="#librep_002dformat">librep-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.8 Scheme Format Strings</h4> + + <p>Scheme format strings are documented in the SLIB manual, section +Format Specification<!-- /@w -->. + +<div class="node"> +<a name="smalltalk-format"></a> +<a name="smalltalk_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#java_002dformat">java-format</a>, +Previous: <a rel="previous" accesskey="p" href="#scheme_002dformat">scheme-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.9 Smalltalk Format Strings</h4> + + <p>Smalltalk format strings are described in the GNU Smalltalk documentation, +class <code>CharArray</code>, methods ‘<samp><span class="samp">bindWith:</span></samp>’ and +‘<samp><span class="samp">bindWithArguments:</span></samp>’. +<a href="http://www.gnu.org/software/smalltalk/gst-manual/gst_68.html#SEC238">http://www.gnu.org/software/smalltalk/gst-manual/gst_68.html#SEC238</a>. +In summary, a directive starts with ‘<samp><span class="samp">%</span></samp>’ and is followed by ‘<samp><span class="samp">%</span></samp>’ +or a nonzero digit (‘<samp><span class="samp">1</span></samp>’ to ‘<samp><span class="samp">9</span></samp>’). + +<div class="node"> +<a name="java-format"></a> +<a name="java_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#csharp_002dformat">csharp-format</a>, +Previous: <a rel="previous" accesskey="p" href="#smalltalk_002dformat">smalltalk-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.10 Java Format Strings</h4> + + <p>Java format strings are described in the JDK documentation for class +<code>java.text.MessageFormat</code>, +<a href="http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html">http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html</a>. +See also the ICU documentation +<a href="http://oss.software.ibm.com/icu/apiref/classMessageFormat.html">http://oss.software.ibm.com/icu/apiref/classMessageFormat.html</a>. + +<div class="node"> +<a name="csharp-format"></a> +<a name="csharp_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#awk_002dformat">awk-format</a>, +Previous: <a rel="previous" accesskey="p" href="#java_002dformat">java-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.11 C# Format Strings</h4> + + <p>C# format strings are described in the .NET documentation for class +<code>System.String</code> and in +<a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpConFormattingOverview.asp">http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpConFormattingOverview.asp</a>. + +<div class="node"> +<a name="awk-format"></a> +<a name="awk_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#object_002dpascal_002dformat">object-pascal-format</a>, +Previous: <a rel="previous" accesskey="p" href="#csharp_002dformat">csharp-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.12 awk Format Strings</h4> + + <p>awk format strings are described in the gawk documentation, section +Printf<!-- /@w -->, +<a href="http://www.gnu.org/manual/gawk/html_node/Printf.html#Printf">http://www.gnu.org/manual/gawk/html_node/Printf.html#Printf</a>. + +<div class="node"> +<a name="object-pascal-format"></a> +<a name="object_002dpascal_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#ycp_002dformat">ycp-format</a>, +Previous: <a rel="previous" accesskey="p" href="#awk_002dformat">awk-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.13 Object Pascal Format Strings</h4> + + <p>Object Pascal format strings are described in the documentation of the +Free Pascal runtime library, section Format, +<a href="http://www.freepascal.org/docs-html/rtl/sysutils/format.html">http://www.freepascal.org/docs-html/rtl/sysutils/format.html</a>. + +<div class="node"> +<a name="ycp-format"></a> +<a name="ycp_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#tcl_002dformat">tcl-format</a>, +Previous: <a rel="previous" accesskey="p" href="#object_002dpascal_002dformat">object-pascal-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.14 YCP Format Strings</h4> + + <p>YCP sformat strings are described in the libycp documentation +<a href="file:/usr/share/doc/packages/libycp/YCP-builtins.html">file:/usr/share/doc/packages/libycp/YCP-builtins.html</a>. +In summary, a directive starts with ‘<samp><span class="samp">%</span></samp>’ and is followed by ‘<samp><span class="samp">%</span></samp>’ +or a nonzero digit (‘<samp><span class="samp">1</span></samp>’ to ‘<samp><span class="samp">9</span></samp>’). + +<div class="node"> +<a name="tcl-format"></a> +<a name="tcl_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#perl_002dformat">perl-format</a>, +Previous: <a rel="previous" accesskey="p" href="#ycp_002dformat">ycp-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.15 Tcl Format Strings</h4> + + <p>Tcl format strings are described in the <samp><span class="file">format.n</span></samp> manual page, +<a href="http://www.scriptics.com/man/tcl8.3/TclCmd/format.htm">http://www.scriptics.com/man/tcl8.3/TclCmd/format.htm</a>. + +<div class="node"> +<a name="perl-format"></a> +<a name="perl_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#php_002dformat">php-format</a>, +Previous: <a rel="previous" accesskey="p" href="#tcl_002dformat">tcl-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.16 Perl Format Strings</h4> + + <p>There are two kinds format strings in Perl: those acceptable to the +Perl built-in function <code>printf</code>, labelled as ‘<samp><span class="samp">perl-format</span></samp>’, +and those acceptable to the <code>libintl-perl</code> function <code>__x</code>, +labelled as ‘<samp><span class="samp">perl-brace-format</span></samp>’. + + <p>Perl <code>printf</code> format strings are described in the <code>sprintf</code> +section of ‘<samp><span class="samp">man perlfunc</span></samp>’. + + <p>Perl brace format strings are described in the +<samp><span class="file">Locale::TextDomain(3pm)</span></samp> manual page of the CPAN package +libintl-perl. In brief, Perl format uses placeholders put between +braces (‘<samp><span class="samp">{</span></samp>’ and ‘<samp><span class="samp">}</span></samp>’). The placeholder must have the syntax +of simple identifiers. + +<div class="node"> +<a name="php-format"></a> +<a name="php_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#gcc_002dinternal_002dformat">gcc-internal-format</a>, +Previous: <a rel="previous" accesskey="p" href="#perl_002dformat">perl-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.17 PHP Format Strings</h4> + + <p>PHP format strings are described in the documentation of the PHP function +<code>sprintf</code>, in <samp><span class="file">phpdoc/manual/function.sprintf.html</span></samp> or +<a href="http://www.php.net/manual/en/function.sprintf.php">http://www.php.net/manual/en/function.sprintf.php</a>. + +<div class="node"> +<a name="gcc-internal-format"></a> +<a name="gcc_002dinternal_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#gfc_002dinternal_002dformat">gfc-internal-format</a>, +Previous: <a rel="previous" accesskey="p" href="#php_002dformat">php-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.18 GCC internal Format Strings</h4> + + <p>These format strings are used inside the GCC sources. In such a format +string, a directive starts with ‘<samp><span class="samp">%</span></samp>’, is optionally followed by a +size specifier ‘<samp><span class="samp">l</span></samp>’, an optional flag ‘<samp><span class="samp">+</span></samp>’, another optional flag +‘<samp><span class="samp">#</span></samp>’, and is finished by a specifier: ‘<samp><span class="samp">%</span></samp>’ denotes a literal +percent sign, ‘<samp><span class="samp">c</span></samp>’ denotes a character, ‘<samp><span class="samp">s</span></samp>’ denotes a string, +‘<samp><span class="samp">i</span></samp>’ and ‘<samp><span class="samp">d</span></samp>’ denote an integer, ‘<samp><span class="samp">o</span></samp>’, ‘<samp><span class="samp">u</span></samp>’, ‘<samp><span class="samp">x</span></samp>’ +denote an unsigned integer, ‘<samp><span class="samp">.*s</span></samp>’ denotes a string preceded by a +width specification, ‘<samp><span class="samp">H</span></samp>’ denotes a ‘<samp><span class="samp">location_t *</span></samp>’ pointer, +‘<samp><span class="samp">D</span></samp>’ denotes a general declaration, ‘<samp><span class="samp">F</span></samp>’ denotes a function +declaration, ‘<samp><span class="samp">T</span></samp>’ denotes a type, ‘<samp><span class="samp">A</span></samp>’ denotes a function argument, +‘<samp><span class="samp">C</span></samp>’ denotes a tree code, ‘<samp><span class="samp">E</span></samp>’ denotes an expression, ‘<samp><span class="samp">L</span></samp>’ +denotes a programming language, ‘<samp><span class="samp">O</span></samp>’ denotes a binary operator, +‘<samp><span class="samp">P</span></samp>’ denotes a function parameter, ‘<samp><span class="samp">Q</span></samp>’ denotes an assignment +operator, ‘<samp><span class="samp">V</span></samp>’ denotes a const/volatile qualifier. + +<div class="node"> +<a name="gfc-internal-format"></a> +<a name="gfc_002dinternal_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#qt_002dformat">qt-format</a>, +Previous: <a rel="previous" accesskey="p" href="#gcc_002dinternal_002dformat">gcc-internal-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.19 GFC internal Format Strings</h4> + + <p>These format strings are used inside the GNU Fortran Compiler sources, +that is, the Fortran frontend in the GCC sources. In such a format +string, a directive starts with ‘<samp><span class="samp">%</span></samp>’ and is finished by a +specifier: ‘<samp><span class="samp">%</span></samp>’ denotes a literal percent sign, ‘<samp><span class="samp">C</span></samp>’ denotes the +current source location, ‘<samp><span class="samp">L</span></samp>’ denotes a source location, ‘<samp><span class="samp">c</span></samp>’ +denotes a character, ‘<samp><span class="samp">s</span></samp>’ denotes a string, ‘<samp><span class="samp">i</span></samp>’ and ‘<samp><span class="samp">d</span></samp>’ +denote an integer, ‘<samp><span class="samp">u</span></samp>’ denotes an unsigned integer. ‘<samp><span class="samp">i</span></samp>’, +‘<samp><span class="samp">d</span></samp>’, and ‘<samp><span class="samp">u</span></samp>’ may be preceded by a size specifier ‘<samp><span class="samp">l</span></samp>’. + +<div class="node"> +<a name="qt-format"></a> +<a name="qt_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#qt_002dplural_002dformat">qt-plural-format</a>, +Previous: <a rel="previous" accesskey="p" href="#gfc_002dinternal_002dformat">gfc-internal-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.20 Qt Format Strings</h4> + + <p>Qt format strings are described in the documentation of the QString class +<a href="file:/usr/lib/qt-4.3.0/doc/html/qstring.html">file:/usr/lib/qt-4.3.0/doc/html/qstring.html</a>. +In summary, a directive consists of a ‘<samp><span class="samp">%</span></samp>’ followed by a digit. The same +directive cannot occur more than once in a format string. + +<div class="node"> +<a name="qt-plural-format"></a> +<a name="qt_002dplural_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#kde_002dformat">kde-format</a>, +Previous: <a rel="previous" accesskey="p" href="#qt_002dformat">qt-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.21 Qt Format Strings</h4> + + <p>Qt format strings are described in the documentation of the QObject::tr method +<a href="file:/usr/lib/qt-4.3.0/doc/html/qobject.html">file:/usr/lib/qt-4.3.0/doc/html/qobject.html</a>. +In summary, the only allowed directive is ‘<samp><span class="samp">%n</span></samp>’. + +<div class="node"> +<a name="kde-format"></a> +<a name="kde_002dformat"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#boost_002dformat">boost-format</a>, +Previous: <a rel="previous" accesskey="p" href="#qt_002dplural_002dformat">qt-plural-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.22 KDE Format Strings</h4> + + <p>KDE 4 format strings are defined as follows: +A directive consists of a ‘<samp><span class="samp">%</span></samp>’ followed by a non-zero decimal number. +If a ‘<samp><span class="samp">%n</span></samp>’ occurs in a format strings, all of ‘<samp><span class="samp">%1</span></samp>’, ..., ‘<samp><span class="samp">%(n-1)</span></samp>’ +must occur as well, except possibly one of them. + +<div class="node"> +<a name="boost-format"></a> +<a name="boost_002dformat"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#kde_002dformat">kde-format</a>, +Up: <a rel="up" accesskey="u" href="#Translators-for-other-Languages">Translators for other Languages</a> + +</div> + +<h4 class="subsection">15.3.23 Boost Format Strings</h4> + + <p>Boost format strings are described in the documentation of the +<code>boost::format</code> class, at +<a href="http://www.boost.org/libs/format/doc/format.html">http://www.boost.org/libs/format/doc/format.html</a>. +In summary, a directive has either the same syntax as in a C format string, +such as ‘<samp><span class="samp">%1$+5d</span></samp>’, or may be surrounded by vertical bars, such as +‘<samp><span class="samp">%|1$+5d|</span></samp>’ or ‘<samp><span class="samp">%|1$+5|</span></samp>’, or consists of just an argument number +between percent signs, such as ‘<samp><span class="samp">%1%</span></samp>’. + +<div class="node"> +<a name="Maintainers-for-other-Languages"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#List-of-Programming-Languages">List of Programming Languages</a>, +Previous: <a rel="previous" accesskey="p" href="#Translators-for-other-Languages">Translators for other Languages</a>, +Up: <a rel="up" accesskey="u" href="#Programming-Languages">Programming Languages</a> + +</div> + +<h3 class="section">15.4 The Maintainer's View</h3> + + <p>For the maintainer, the general procedure differs from the C language +case in two ways. + + <ul> +<li>For those languages that don't use GNU gettext, the <samp><span class="file">intl/</span></samp> directory +is not needed and can be omitted. This means that the maintainer calls the +<code>gettextize</code> program without the ‘<samp><span class="samp">--intl</span></samp>’ option, and that he +invokes the <code>AM_GNU_GETTEXT</code> autoconf macro via +‘<samp><span class="samp">AM_GNU_GETTEXT([external])</span></samp>’. + + <li>If only a single programming language is used, the <code>XGETTEXT_OPTIONS</code> +variable in <samp><span class="file">po/Makevars</span></samp> (see <a href="#po_002fMakevars">po/Makevars</a>) should be adjusted to +match the <code>xgettext</code> options for that particular programming language. +If the package uses more than one programming language with <code>gettext</code> +support, it becomes necessary to change the POT file construction rule +in <samp><span class="file">po/Makefile.in.in</span></samp>. It is recommended to make one <code>xgettext</code> +invocation per programming language, each with the options appropriate for +that language, and to combine the resulting files using <code>msgcat</code>. +</ul> + +<div class="node"> +<a name="List-of-Programming-Languages"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#List-of-Data-Formats">List of Data Formats</a>, +Previous: <a rel="previous" accesskey="p" href="#Maintainers-for-other-Languages">Maintainers for other Languages</a>, +Up: <a rel="up" accesskey="u" href="#Programming-Languages">Programming Languages</a> + +</div> + +<h3 class="section">15.5 Individual Programming Languages</h3> + +<!-- Here is a list of programming languages, as used for Free Software projects --> +<!-- on SourceForge/Freshmeat, as of February 2002. Those supported by gettext --> +<!-- are marked with a star. --> +<!-- C 3580 * --> +<!-- Perl 1911 * --> +<!-- C++ 1379 * --> +<!-- Java 1200 * --> +<!-- PHP 1051 * --> +<!-- Python 613 * --> +<!-- Unix Shell 357 * --> +<!-- Tcl 266 * --> +<!-- SQL 174 --> +<!-- JavaScript 118 --> +<!-- Assembly 108 --> +<!-- Scheme 51 --> +<!-- Ruby 47 --> +<!-- Lisp 45 * --> +<!-- Objective C 39 * --> +<!-- PL/SQL 29 --> +<!-- Fortran 25 --> +<!-- Ada 24 --> +<!-- Delphi 22 --> +<!-- Awk 19 * --> +<!-- Pascal 19 --> +<!-- ML 19 --> +<!-- Eiffel 17 --> +<!-- Emacs-Lisp 14 * --> +<!-- Zope 14 --> +<!-- ASP 12 --> +<!-- Forth 12 --> +<!-- Cold Fusion 10 --> +<!-- Haskell 9 --> +<!-- Visual Basic 9 --> +<!-- C# 6 * --> +<!-- Smalltalk 6 * --> +<!-- Basic 5 --> +<!-- Erlang 5 --> +<!-- Modula 5 --> +<!-- Object Pascal 5 * --> +<!-- Rexx 5 --> +<!-- Dylan 4 --> +<!-- Prolog 4 --> +<!-- APL 3 --> +<!-- PROGRESS 2 --> +<!-- Euler 1 --> +<!-- Euphoria 1 --> +<!-- Pliant 1 --> +<!-- Simula 1 --> +<!-- XBasic 1 --> +<!-- Logo 0 --> +<!-- Other Scripting Engines 49 --> +<!-- Other 116 --> +<ul class="menu"> +<li><a accesskey="1" href="#C">C</a>: C, C++, Objective C +<li><a accesskey="2" href="#sh">sh</a>: sh - Shell Script +<li><a accesskey="3" href="#bash">bash</a>: bash - Bourne-Again Shell Script +<li><a accesskey="4" href="#Python">Python</a>: Python +<li><a accesskey="5" href="#Common-Lisp">Common Lisp</a>: GNU clisp - Common Lisp +<li><a accesskey="6" href="#clisp-C">clisp C</a>: GNU clisp C sources +<li><a accesskey="7" href="#Emacs-Lisp">Emacs Lisp</a>: Emacs Lisp +<li><a accesskey="8" href="#librep">librep</a>: librep +<li><a accesskey="9" href="#Scheme">Scheme</a>: GNU guile - Scheme +<li><a href="#Smalltalk">Smalltalk</a>: GNU Smalltalk +<li><a href="#Java">Java</a>: Java +<li><a href="#C_0023">C#</a>: C# +<li><a href="#gawk">gawk</a>: GNU awk +<li><a href="#Pascal">Pascal</a>: Pascal - Free Pascal Compiler +<li><a href="#wxWidgets">wxWidgets</a>: wxWidgets library +<li><a href="#YCP">YCP</a>: YCP - YaST2 scripting language +<li><a href="#Tcl">Tcl</a>: Tcl - Tk's scripting language +<li><a href="#Perl">Perl</a>: Perl +<li><a href="#PHP">PHP</a>: PHP Hypertext Preprocessor +<li><a href="#Pike">Pike</a>: Pike +<li><a href="#GCC_002dsource">GCC-source</a>: GNU Compiler Collection sources +</ul> + +<div class="node"> +<a name="C"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#sh">sh</a>, +Previous: <a rel="previous" accesskey="p" href="#List-of-Programming-Languages">List of Programming Languages</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.1 C, C++, Objective C</h4> + + <p><a name="index-C-and-C_002dlike-languages-1174"></a> + <dl> +<dt>RPMs<dd>gcc, gpp, gobjc, glibc, gettext + + <br><dt>File extension<dd>For C: <code>c</code>, <code>h</code>. +<br>For C++: <code>C</code>, <code>c++</code>, <code>cc</code>, <code>cxx</code>, <code>cpp</code>, <code>hpp</code>. +<br>For Objective C: <code>m</code>. + + <br><dt>String syntax<dd><code>"abc"</code> + + <br><dt>gettext shorthand<dd><code>_("abc")</code> + + <br><dt>gettext/ngettext functions<dd><code>gettext</code>, <code>dgettext</code>, <code>dcgettext</code>, <code>ngettext</code>, +<code>dngettext</code>, <code>dcngettext</code> + + <br><dt>textdomain<dd><code>textdomain</code> function + + <br><dt>bindtextdomain<dd><code>bindtextdomain</code> function + + <br><dt>setlocale<dd>Programmer must call <code>setlocale (LC_ALL, "")</code> + + <br><dt>Prerequisite<dd><code>#include <libintl.h></code> +<br><code>#include <locale.h></code> +<br><code>#define _(string) gettext (string)</code> + + <br><dt>Use or emulate GNU gettext<dd>Use + + <br><dt>Extractor<dd><code>xgettext -k_</code> + + <br><dt>Formatting with positions<dd><code>fprintf "%2$d %1$d"</code> +<br>In C++: <code>autosprintf "%2$d %1$d"</code> +(see <a href="autosprintf.html#Top">Introduction</a>) + + <br><dt>Portability<dd>autoconf (gettext.m4) and #if ENABLE_NLS + + <br><dt>po-mode marking<dd>yes +</dl> + + <p>The following examples are available in the <samp><span class="file">examples</span></samp> directory: +<code>hello-c</code>, <code>hello-c-gnome</code>, <code>hello-c++</code>, <code>hello-c++-qt</code>, +<code>hello-c++-kde</code>, <code>hello-c++-gnome</code>, <code>hello-c++-wxwidgets</code>, +<code>hello-objc</code>, <code>hello-objc-gnustep</code>, <code>hello-objc-gnome</code>. + +<div class="node"> +<a name="sh"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#bash">bash</a>, +Previous: <a rel="previous" accesskey="p" href="#C">C</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.2 sh - Shell Script</h4> + + <p><a name="index-shell-scripts-1175"></a> + <dl> +<dt>RPMs<dd>bash, gettext + + <br><dt>File extension<dd><code>sh</code> + + <br><dt>String syntax<dd><code>"abc"</code>, <code>'abc'</code>, <code>abc</code> + + <br><dt>gettext shorthand<dd><code>"`gettext \"abc\"`"</code> + + <br><dt>gettext/ngettext functions<dd><a name="index-gettext-1176"></a><a name="index-ngettext-1177"></a><code>gettext</code>, <code>ngettext</code> programs +<br><code>eval_gettext</code>, <code>eval_ngettext</code> shell functions + + <br><dt>textdomain<dd><a name="index-TEXTDOMAIN_0040r_007b_002c-environment-variable_007d-1178"></a>environment variable <code>TEXTDOMAIN</code> + + <br><dt>bindtextdomain<dd><a name="index-TEXTDOMAINDIR_0040r_007b_002c-environment-variable_007d-1179"></a>environment variable <code>TEXTDOMAINDIR</code> + + <br><dt>setlocale<dd>automatic + + <br><dt>Prerequisite<dd><code>. gettext.sh</code> + + <br><dt>Use or emulate GNU gettext<dd>use + + <br><dt>Extractor<dd><code>xgettext</code> + + <br><dt>Formatting with positions<dd>— + + <br><dt>Portability<dd>fully portable + + <br><dt>po-mode marking<dd>— +</dl> + + <p>An example is available in the <samp><span class="file">examples</span></samp> directory: <code>hello-sh</code>. + +<ul class="menu"> +<li><a accesskey="1" href="#Preparing-Shell-Scripts">Preparing Shell Scripts</a>: Preparing Shell Scripts for Internationalization +<li><a accesskey="2" href="#gettext_002esh">gettext.sh</a>: Contents of <code>gettext.sh</code> +<li><a accesskey="3" href="#gettext-Invocation">gettext Invocation</a>: Invoking the <code>gettext</code> program +<li><a accesskey="4" href="#ngettext-Invocation">ngettext Invocation</a>: Invoking the <code>ngettext</code> program +<li><a accesskey="5" href="#envsubst-Invocation">envsubst Invocation</a>: Invoking the <code>envsubst</code> program +<li><a accesskey="6" href="#eval_005fgettext-Invocation">eval_gettext Invocation</a>: Invoking the <code>eval_gettext</code> function +<li><a accesskey="7" href="#eval_005fngettext-Invocation">eval_ngettext Invocation</a>: Invoking the <code>eval_ngettext</code> function +</ul> + +<div class="node"> +<a name="Preparing-Shell-Scripts"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#gettext_002esh">gettext.sh</a>, +Previous: <a rel="previous" accesskey="p" href="#sh">sh</a>, +Up: <a rel="up" accesskey="u" href="#sh">sh</a> + +</div> + +<h5 class="subsubsection">15.5.2.1 Preparing Shell Scripts for Internationalization</h5> + + <p><a name="index-preparing-shell-scripts-for-translation-1180"></a> +Preparing a shell script for internationalization is conceptually similar +to the steps described in <a href="#Sources">Sources</a>. The concrete steps for shell +scripts are as follows. + + <ol type=1 start=1> +<li>Insert the line + + <pre class="smallexample"> . gettext.sh +</pre> + <p>near the top of the script. <code>gettext.sh</code> is a shell function library +that provides the functions +<code>eval_gettext</code> (see <a href="#eval_005fgettext-Invocation">eval_gettext Invocation</a>) and +<code>eval_ngettext</code> (see <a href="#eval_005fngettext-Invocation">eval_ngettext Invocation</a>). +You have to ensure that <code>gettext.sh</code> can be found in the <code>PATH</code>. + + <li>Set and export the <code>TEXTDOMAIN</code> and <code>TEXTDOMAINDIR</code> environment +variables. Usually <code>TEXTDOMAIN</code> is the package or program name, and +<code>TEXTDOMAINDIR</code> is the absolute pathname corresponding to +<code>$prefix/share/locale</code>, where <code>$prefix</code> is the installation location. + + <pre class="smallexample"> TEXTDOMAIN=@PACKAGE@ + export TEXTDOMAIN + TEXTDOMAINDIR=@LOCALEDIR@ + export TEXTDOMAINDIR +</pre> + <li>Prepare the strings for translation, as described in <a href="#Preparing-Strings">Preparing Strings</a>. + + <li>Simplify translatable strings so that they don't contain command substitution +(<code>"`...`"</code> or <code>"$(...)"</code>), variable access with defaulting (like +<code>${</code><var>variable</var><code>-</code><var>default</var><code>}</code>), access to positional arguments +(like <code>$0</code>, <code>$1</code>, ...) or highly volatile shell variables (like +<code>$?</code>). This can always be done through simple local code restructuring. +For example, + + <pre class="smallexample"> echo "Usage: $0 [OPTION] FILE..." +</pre> + <p>becomes + + <pre class="smallexample"> program_name=$0 + echo "Usage: $program_name [OPTION] FILE..." +</pre> + <p>Similarly, + + <pre class="smallexample"> echo "Remaining files: `ls | wc -l`" +</pre> + <p>becomes + + <pre class="smallexample"> filecount="`ls | wc -l`" + echo "Remaining files: $filecount" +</pre> + <li>For each translatable string, change the output command ‘<samp><span class="samp">echo</span></samp>’ or +‘<samp><span class="samp">$echo</span></samp>’ to ‘<samp><span class="samp">gettext</span></samp>’ (if the string contains no references to +shell variables) or to ‘<samp><span class="samp">eval_gettext</span></samp>’ (if it refers to shell variables), +followed by a no-argument ‘<samp><span class="samp">echo</span></samp>’ command (to account for the terminating +newline). Similarly, for cases with plural handling, replace a conditional +‘<samp><span class="samp">echo</span></samp>’ command with an invocation of ‘<samp><span class="samp">ngettext</span></samp>’ or +‘<samp><span class="samp">eval_ngettext</span></samp>’, followed by a no-argument ‘<samp><span class="samp">echo</span></samp>’ command. + + <p>When doing this, you also need to add an extra backslash before the dollar +sign in references to shell variables, so that the ‘<samp><span class="samp">eval_gettext</span></samp>’ +function receives the translatable string before the variable values are +substituted into it. For example, + + <pre class="smallexample"> echo "Remaining files: $filecount" +</pre> + <p>becomes + + <pre class="smallexample"> eval_gettext "Remaining files: \$filecount"; echo +</pre> + <p>If the output command is not ‘<samp><span class="samp">echo</span></samp>’, you can make it use ‘<samp><span class="samp">echo</span></samp>’ +nevertheless, through the use of backquotes. However, note that inside +backquotes, backslashes must be doubled to be effective (because the +backquoting eats one level of backslashes). For example, assuming that +‘<samp><span class="samp">error</span></samp>’ is a shell function that signals an error, + + <pre class="smallexample"> error "file not found: $filename" +</pre> + <p>is first transformed into + + <pre class="smallexample"> error "`echo \"file not found: \$filename\"`" +</pre> + <p>which then becomes + + <pre class="smallexample"> error "`eval_gettext \"file not found: \\\$filename\"`" +</pre> + </ol> + +<div class="node"> +<a name="gettext.sh"></a> +<a name="gettext_002esh"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#gettext-Invocation">gettext Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#Preparing-Shell-Scripts">Preparing Shell Scripts</a>, +Up: <a rel="up" accesskey="u" href="#sh">sh</a> + +</div> + +<h5 class="subsubsection">15.5.2.2 Contents of <code>gettext.sh</code></h5> + + <p><code>gettext.sh</code>, contained in the run-time package of GNU gettext, provides +the following: + + <ul> +<li>$echo +The variable <code>echo</code> is set to a command that outputs its first argument +and a newline, without interpreting backslashes in the argument string. + + <li>eval_gettext +See <a href="#eval_005fgettext-Invocation">eval_gettext Invocation</a>. + + <li>eval_ngettext +See <a href="#eval_005fngettext-Invocation">eval_ngettext Invocation</a>. +</ul> + +<div class="node"> +<a name="gettext-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#ngettext-Invocation">ngettext Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#gettext_002esh">gettext.sh</a>, +Up: <a rel="up" accesskey="u" href="#sh">sh</a> + +</div> + +<h5 class="subsubsection">15.5.2.3 Invoking the <code>gettext</code> program</h5> + + <p><a name="index-gettext-1181"></a><a name="index-g_t_0040code_007bgettext_007d-program_002c-usage-1182"></a> +<pre class="example"> gettext [<var>option</var>] [[<var>textdomain</var>] <var>msgid</var>] + gettext [<var>option</var>] -s [<var>msgid</var>]... +</pre> + <p><a name="index-lookup-message-translation-1183"></a>The <code>gettext</code> program displays the native language translation of a +textual message. + +<p class="noindent"><strong>Arguments</strong> + + <dl> +<dt>‘<samp><span class="samp">-d </span><var>textdomain</var></samp>’<dt>‘<samp><span class="samp">--domain=</span><var>textdomain</var></samp>’<dd><a name="index-g_t_002dd_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1184"></a><a name="index-g_t_002d_002ddomain_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1185"></a>Retrieve translated messages from <var>textdomain</var>. Usually a <var>textdomain</var> +corresponds to a package, a program, or a module of a program. + + <br><dt>‘<samp><span class="samp">-e</span></samp>’<dd><a name="index-g_t_002de_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1186"></a>Enable expansion of some escape sequences. This option is for compatibility +with the ‘<samp><span class="samp">echo</span></samp>’ program or shell built-in. The escape sequences +‘<samp><span class="samp">\a</span></samp>’, ‘<samp><span class="samp">\b</span></samp>’, ‘<samp><span class="samp">\c</span></samp>’, ‘<samp><span class="samp">\f</span></samp>’, ‘<samp><span class="samp">\n</span></samp>’, ‘<samp><span class="samp">\r</span></samp>’, ‘<samp><span class="samp">\t</span></samp>’, +‘<samp><span class="samp">\v</span></samp>’, ‘<samp><span class="samp">\\</span></samp>’, and ‘<samp><span class="samp">\</span></samp>’ followed by one to three octal digits, are +interpreted like the System V ‘<samp><span class="samp">echo</span></samp>’ program did. + + <br><dt>‘<samp><span class="samp">-E</span></samp>’<dd><a name="index-g_t_002dE_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1187"></a>This option is only for compatibility with the ‘<samp><span class="samp">echo</span></samp>’ program or shell +built-in. It has no effect. + + <br><dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1188"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1189"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-n</span></samp>’<dd><a name="index-g_t_002dn_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1190"></a>Suppress trailing newline. By default, <code>gettext</code> adds a newline to +the output. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1191"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1192"></a>Output version information and exit. + + <br><dt>‘<samp><span class="samp">[</span><var>textdomain</var><span class="samp">] </span><var>msgid</var></samp>’<dd>Retrieve translated message corresponding to <var>msgid</var> from <var>textdomain</var>. + + </dl> + + <p>If the <var>textdomain</var> parameter is not given, the domain is determined from +the environment variable <code>TEXTDOMAIN</code>. If the message catalog is not +found in the regular directory, another location can be specified with the +environment variable <code>TEXTDOMAINDIR</code>. + + <p>When used with the <code>-s</code> option the program behaves like the ‘<samp><span class="samp">echo</span></samp>’ +command. But it does not simply copy its arguments to stdout. Instead those +messages found in the selected catalog are translated. + + <p>Note: <code>xgettext</code> supports only the one-argument form of the +<code>gettext</code> invocation, where no options are present and the +<var>textdomain</var> is implicit, from the environment. + +<div class="node"> +<a name="ngettext-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#envsubst-Invocation">envsubst Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#gettext-Invocation">gettext Invocation</a>, +Up: <a rel="up" accesskey="u" href="#sh">sh</a> + +</div> + +<h5 class="subsubsection">15.5.2.4 Invoking the <code>ngettext</code> program</h5> + + <p><a name="index-ngettext-1193"></a><a name="index-g_t_0040code_007bngettext_007d-program_002c-usage-1194"></a> +<pre class="example"> ngettext [<var>option</var>] [<var>textdomain</var>] <var>msgid</var> <var>msgid-plural</var> <var>count</var> +</pre> + <p><a name="index-lookup-plural-message-translation-1195"></a>The <code>ngettext</code> program displays the native language translation of a +textual message whose grammatical form depends on a number. + +<p class="noindent"><strong>Arguments</strong> + + <dl> +<dt>‘<samp><span class="samp">-d </span><var>textdomain</var></samp>’<dt>‘<samp><span class="samp">--domain=</span><var>textdomain</var></samp>’<dd><a name="index-g_t_002dd_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1196"></a><a name="index-g_t_002d_002ddomain_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1197"></a>Retrieve translated messages from <var>textdomain</var>. Usually a <var>textdomain</var> +corresponds to a package, a program, or a module of a program. + + <br><dt>‘<samp><span class="samp">-e</span></samp>’<dd><a name="index-g_t_002de_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1198"></a>Enable expansion of some escape sequences. This option is for compatibility +with the ‘<samp><span class="samp">gettext</span></samp>’ program. The escape sequences +‘<samp><span class="samp">\a</span></samp>’, ‘<samp><span class="samp">\b</span></samp>’, ‘<samp><span class="samp">\c</span></samp>’, ‘<samp><span class="samp">\f</span></samp>’, ‘<samp><span class="samp">\n</span></samp>’, ‘<samp><span class="samp">\r</span></samp>’, ‘<samp><span class="samp">\t</span></samp>’, +‘<samp><span class="samp">\v</span></samp>’, ‘<samp><span class="samp">\\</span></samp>’, and ‘<samp><span class="samp">\</span></samp>’ followed by one to three octal digits, are +interpreted like the System V ‘<samp><span class="samp">echo</span></samp>’ program did. + + <br><dt>‘<samp><span class="samp">-E</span></samp>’<dd><a name="index-g_t_002dE_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1199"></a>This option is only for compatibility with the ‘<samp><span class="samp">gettext</span></samp>’ program. It has +no effect. + + <br><dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1200"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1201"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1202"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1203"></a>Output version information and exit. + + <br><dt>‘<samp><var>textdomain</var></samp>’<dd>Retrieve translated message from <var>textdomain</var>. + + <br><dt>‘<samp><var>msgid</var> <var>msgid-plural</var></samp>’<dd>Translate <var>msgid</var> (English singular) / <var>msgid-plural</var> (English plural). + + <br><dt>‘<samp><var>count</var></samp>’<dd>Choose singular/plural form based on this value. + + </dl> + + <p>If the <var>textdomain</var> parameter is not given, the domain is determined from +the environment variable <code>TEXTDOMAIN</code>. If the message catalog is not +found in the regular directory, another location can be specified with the +environment variable <code>TEXTDOMAINDIR</code>. + + <p>Note: <code>xgettext</code> supports only the three-arguments form of the +<code>ngettext</code> invocation, where no options are present and the +<var>textdomain</var> is implicit, from the environment. + +<div class="node"> +<a name="envsubst-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#eval_005fgettext-Invocation">eval_gettext Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#ngettext-Invocation">ngettext Invocation</a>, +Up: <a rel="up" accesskey="u" href="#sh">sh</a> + +</div> + +<h5 class="subsubsection">15.5.2.5 Invoking the <code>envsubst</code> program</h5> + + <p><a name="index-envsubst-1204"></a><a name="index-g_t_0040code_007benvsubst_007d-program_002c-usage-1205"></a> +<pre class="example"> envsubst [<var>option</var>] [<var>shell-format</var>] +</pre> + <p><a name="index-shell-format-string-1206"></a><a name="index-dollar-substitution-1207"></a><a name="index-environment-variables-1208"></a>The <code>envsubst</code> program substitutes the values of environment variables. + +<p class="noindent"><strong>Operation mode</strong> + + <dl> +<dt>‘<samp><span class="samp">-v</span></samp>’<dt>‘<samp><span class="samp">--variables</span></samp>’<dd><a name="index-g_t_002dv_0040r_007b_002c-_0040code_007benvsubst_007d-option_007d-1209"></a><a name="index-g_t_002d_002dvariables_0040r_007b_002c-_0040code_007benvsubst_007d-option_007d-1210"></a>Output the variables occurring in <var>shell-format</var>. + + </dl> + +<p class="noindent"><strong>Informative output</strong> + + <dl> +<dt>‘<samp><span class="samp">-h</span></samp>’<dt>‘<samp><span class="samp">--help</span></samp>’<dd><a name="index-g_t_002dh_0040r_007b_002c-_0040code_007benvsubst_007d-option_007d-1211"></a><a name="index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007benvsubst_007d-option_007d-1212"></a>Display this help and exit. + + <br><dt>‘<samp><span class="samp">-V</span></samp>’<dt>‘<samp><span class="samp">--version</span></samp>’<dd><a name="index-g_t_002dV_0040r_007b_002c-_0040code_007benvsubst_007d-option_007d-1213"></a><a name="index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007benvsubst_007d-option_007d-1214"></a>Output version information and exit. + + </dl> + + <p>In normal operation mode, standard input is copied to standard output, +with references to environment variables of the form <code>$VARIABLE</code> or +<code>${VARIABLE}</code> being replaced with the corresponding values. If a +<var>shell-format</var> is given, only those environment variables that are +referenced in <var>shell-format</var> are substituted; otherwise all environment +variables references occurring in standard input are substituted. + + <p>These substitutions are a subset of the substitutions that a shell performs +on unquoted and double-quoted strings. Other kinds of substitutions done +by a shell, such as <code>${</code><var>variable</var><code>-</code><var>default</var><code>}</code> or +<code>$(</code><var>command-list</var><code>)</code> or <code>`</code><var>command-list</var><code>`</code>, are not performed +by the <code>envsubst</code> program, due to security reasons. + + <p>When <code>--variables</code> is used, standard input is ignored, and the output +consists of the environment variables that are referenced in +<var>shell-format</var>, one per line. + +<div class="node"> +<a name="eval_gettext-Invocation"></a> +<a name="eval_005fgettext-Invocation"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#eval_005fngettext-Invocation">eval_ngettext Invocation</a>, +Previous: <a rel="previous" accesskey="p" href="#envsubst-Invocation">envsubst Invocation</a>, +Up: <a rel="up" accesskey="u" href="#sh">sh</a> + +</div> + +<h5 class="subsubsection">15.5.2.6 Invoking the <code>eval_gettext</code> function</h5> + + <p><a name="index-g_t_0040code_007beval_005fgettext_007d-function_002c-usage-1215"></a> +<pre class="example"> eval_gettext <var>msgid</var> +</pre> + <p><a name="index-lookup-message-translation-1216"></a>This function outputs the native language translation of a textual message, +performing dollar-substitution on the result. Note that only shell variables +mentioned in <var>msgid</var> will be dollar-substituted in the result. + +<div class="node"> +<a name="eval_ngettext-Invocation"></a> +<a name="eval_005fngettext-Invocation"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#eval_005fgettext-Invocation">eval_gettext Invocation</a>, +Up: <a rel="up" accesskey="u" href="#sh">sh</a> + +</div> + +<h5 class="subsubsection">15.5.2.7 Invoking the <code>eval_ngettext</code> function</h5> + + <p><a name="index-g_t_0040code_007beval_005fngettext_007d-function_002c-usage-1217"></a> +<pre class="example"> eval_ngettext <var>msgid</var> <var>msgid-plural</var> <var>count</var> +</pre> + <p><a name="index-lookup-plural-message-translation-1218"></a>This function outputs the native language translation of a textual message +whose grammatical form depends on a number, performing dollar-substitution +on the result. Note that only shell variables mentioned in <var>msgid</var> or +<var>msgid-plural</var> will be dollar-substituted in the result. + +<div class="node"> +<a name="bash"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Python">Python</a>, +Previous: <a rel="previous" accesskey="p" href="#sh">sh</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.3 bash - Bourne-Again Shell Script</h4> + + <p><a name="index-bash-1219"></a> +GNU <code>bash</code> 2.0 or newer has a special shorthand for translating a +string and substituting variable values in it: <code>$"msgid"</code>. But +the use of this construct is <strong>discouraged</strong>, due to the security +holes it opens and due to its portability problems. + + <p>The security holes of <code>$"..."</code> come from the fact that after looking up +the translation of the string, <code>bash</code> processes it like it processes +any double-quoted string: dollar and backquote processing, like ‘<samp><span class="samp">eval</span></samp>’ +does. + + <ol type=1 start=1> +<li>In a locale whose encoding is one of BIG5, BIG5-HKSCS, GBK, GB18030, SHIFT_JIS, +JOHAB, some double-byte characters have a second byte whose value is +<code>0x60</code>. For example, the byte sequence <code>\xe0\x60</code> is a single +character in these locales. Many versions of <code>bash</code> (all versions +up to bash-2.05, and newer versions on platforms without <code>mbsrtowcs()</code> +function) don't know about character boundaries and see a backquote character +where there is only a particular Chinese character. Thus it can start +executing part of the translation as a command list. This situation can occur +even without the translator being aware of it: if the translator provides +translations in the UTF-8 encoding, it is the <code>gettext()</code> function which +will, during its conversion from the translator's encoding to the user's +locale's encoding, produce the dangerous <code>\x60</code> bytes. + + <li>A translator could - voluntarily or inadvertently - use backquotes +<code>"`...`"</code> or dollar-parentheses <code>"$(...)"</code> in her translations. +The enclosed strings would be executed as command lists by the shell. + </ol> + + <p>The portability problem is that <code>bash</code> must be built with +internationalization support; this is normally not the case on systems +that don't have the <code>gettext()</code> function in libc. + +<div class="node"> +<a name="Python"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Common-Lisp">Common Lisp</a>, +Previous: <a rel="previous" accesskey="p" href="#bash">bash</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.4 Python</h4> + + <p><a name="index-Python-1220"></a> + <dl> +<dt>RPMs<dd>python + + <br><dt>File extension<dd><code>py</code> + + <br><dt>String syntax<dd><code>'abc'</code>, <code>u'abc'</code>, <code>r'abc'</code>, <code>ur'abc'</code>, +<br><code>"abc"</code>, <code>u"abc"</code>, <code>r"abc"</code>, <code>ur"abc"</code>, +<br><code>'''abc'''</code>, <code>u'''abc'''</code>, <code>r'''abc'''</code>, <code>ur'''abc'''</code>, +<br><code>"""abc"""</code>, <code>u"""abc"""</code>, <code>r"""abc"""</code>, <code>ur"""abc"""</code> + + <br><dt>gettext shorthand<dd><code>_('abc')</code> etc. + + <br><dt>gettext/ngettext functions<dd><code>gettext.gettext</code>, <code>gettext.dgettext</code>, +<code>gettext.ngettext</code>, <code>gettext.dngettext</code>, +also <code>ugettext</code>, <code>ungettext</code> + + <br><dt>textdomain<dd><code>gettext.textdomain</code> function, or +<code>gettext.install(</code><var>domain</var><code>)</code> function + + <br><dt>bindtextdomain<dd><code>gettext.bindtextdomain</code> function, or +<code>gettext.install(</code><var>domain</var><code>,</code><var>localedir</var><code>)</code> function + + <br><dt>setlocale<dd>not used by the gettext emulation + + <br><dt>Prerequisite<dd><code>import gettext</code> + + <br><dt>Use or emulate GNU gettext<dd>emulate + + <br><dt>Extractor<dd><code>xgettext</code> + + <br><dt>Formatting with positions<dd><code>'...%(ident)d...' % { 'ident': value }</code> + + <br><dt>Portability<dd>fully portable + + <br><dt>po-mode marking<dd>— +</dl> + + <p>An example is available in the <samp><span class="file">examples</span></samp> directory: <code>hello-python</code>. + + <p>A note about format strings: Python supports format strings with unnamed +arguments, such as <code>'...%d...'</code>, and format strings with named arguments, +such as <code>'...%(ident)d...'</code>. The latter are preferable for +internationalized programs, for two reasons: + + <ul> +<li>When a format string takes more than one argument, the translator can provide +a translation that uses the arguments in a different order, if the format +string uses named arguments. For example, the translator can reformulate + <pre class="smallexample"> "'%(volume)s' has only %(freespace)d bytes free." +</pre> + <p class="noindent">to + <pre class="smallexample"> "Only %(freespace)d bytes free on '%(volume)s'." +</pre> + <p class="noindent">Additionally, the identifiers also provide some context to the translator. + + <li>In the context of plural forms, the format string used for the singular form +does not use the numeric argument in many languages. Even in English, one +prefers to write <code>"one hour"</code> instead of <code>"1 hour"</code>. Omitting +individual arguments from format strings like this is only possible with +the named argument syntax. (With unnamed arguments, Python – unlike C – +verifies that the format string uses all supplied arguments.) +</ul> + +<div class="node"> +<a name="Common-Lisp"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#clisp-C">clisp C</a>, +Previous: <a rel="previous" accesskey="p" href="#Python">Python</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.5 GNU clisp - Common Lisp</h4> + + <p><a name="index-Common-Lisp-1221"></a><a name="index-Lisp-1222"></a><a name="index-clisp-1223"></a> + <dl> +<dt>RPMs<dd>clisp 2.28 or newer + + <br><dt>File extension<dd><code>lisp</code> + + <br><dt>String syntax<dd><code>"abc"</code> + + <br><dt>gettext shorthand<dd><code>(_ "abc")</code>, <code>(ENGLISH "abc")</code> + + <br><dt>gettext/ngettext functions<dd><code>i18n:gettext</code>, <code>i18n:ngettext</code> + + <br><dt>textdomain<dd><code>i18n:textdomain</code> + + <br><dt>bindtextdomain<dd><code>i18n:textdomaindir</code> + + <br><dt>setlocale<dd>automatic + + <br><dt>Prerequisite<dd>— + + <br><dt>Use or emulate GNU gettext<dd>use + + <br><dt>Extractor<dd><code>xgettext -k_ -kENGLISH</code> + + <br><dt>Formatting with positions<dd><code>format "~1@*~D ~0@*~D"</code> + + <br><dt>Portability<dd>On platforms without gettext, no translation. + + <br><dt>po-mode marking<dd>— +</dl> + + <p>An example is available in the <samp><span class="file">examples</span></samp> directory: <code>hello-clisp</code>. + +<div class="node"> +<a name="clisp-C"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Emacs-Lisp">Emacs Lisp</a>, +Previous: <a rel="previous" accesskey="p" href="#Common-Lisp">Common Lisp</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.6 GNU clisp C sources</h4> + + <p><a name="index-clisp-C-sources-1224"></a> + <dl> +<dt>RPMs<dd>clisp + + <br><dt>File extension<dd><code>d</code> + + <br><dt>String syntax<dd><code>"abc"</code> + + <br><dt>gettext shorthand<dd><code>ENGLISH ? "abc" : ""</code> +<br><code>GETTEXT("abc")</code> +<br><code>GETTEXTL("abc")</code> + + <br><dt>gettext/ngettext functions<dd><code>clgettext</code>, <code>clgettextl</code> + + <br><dt>textdomain<dd>— + + <br><dt>bindtextdomain<dd>— + + <br><dt>setlocale<dd>automatic + + <br><dt>Prerequisite<dd><code>#include "lispbibl.c"</code> + + <br><dt>Use or emulate GNU gettext<dd>use + + <br><dt>Extractor<dd><code>clisp-xgettext</code> + + <br><dt>Formatting with positions<dd><code>fprintf "%2$d %1$d"</code> + + <br><dt>Portability<dd>On platforms without gettext, no translation. + + <br><dt>po-mode marking<dd>— +</dl> + +<div class="node"> +<a name="Emacs-Lisp"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#librep">librep</a>, +Previous: <a rel="previous" accesskey="p" href="#clisp-C">clisp C</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.7 Emacs Lisp</h4> + + <p><a name="index-Emacs-Lisp-1225"></a> + <dl> +<dt>RPMs<dd>emacs, xemacs + + <br><dt>File extension<dd><code>el</code> + + <br><dt>String syntax<dd><code>"abc"</code> + + <br><dt>gettext shorthand<dd><code>(_"abc")</code> + + <br><dt>gettext/ngettext functions<dd><code>gettext</code>, <code>dgettext</code> (xemacs only) + + <br><dt>textdomain<dd><code>domain</code> special form (xemacs only) + + <br><dt>bindtextdomain<dd><code>bind-text-domain</code> function (xemacs only) + + <br><dt>setlocale<dd>automatic + + <br><dt>Prerequisite<dd>— + + <br><dt>Use or emulate GNU gettext<dd>use + + <br><dt>Extractor<dd><code>xgettext</code> + + <br><dt>Formatting with positions<dd><code>format "%2$d %1$d"</code> + + <br><dt>Portability<dd>Only XEmacs. Without <code>I18N3</code> defined at build time, no translation. + + <br><dt>po-mode marking<dd>— +</dl> + +<div class="node"> +<a name="librep"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Scheme">Scheme</a>, +Previous: <a rel="previous" accesskey="p" href="#Emacs-Lisp">Emacs Lisp</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.8 librep</h4> + + <p><a name="index-g_t_0040code_007blibrep_007d-Lisp-1226"></a> + <dl> +<dt>RPMs<dd>librep 0.15.3 or newer + + <br><dt>File extension<dd><code>jl</code> + + <br><dt>String syntax<dd><code>"abc"</code> + + <br><dt>gettext shorthand<dd><code>(_"abc")</code> + + <br><dt>gettext/ngettext functions<dd><code>gettext</code> + + <br><dt>textdomain<dd><code>textdomain</code> function + + <br><dt>bindtextdomain<dd><code>bindtextdomain</code> function + + <br><dt>setlocale<dd>— + + <br><dt>Prerequisite<dd><code>(require 'rep.i18n.gettext)</code> + + <br><dt>Use or emulate GNU gettext<dd>use + + <br><dt>Extractor<dd><code>xgettext</code> + + <br><dt>Formatting with positions<dd><code>format "%2$d %1$d"</code> + + <br><dt>Portability<dd>On platforms without gettext, no translation. + + <br><dt>po-mode marking<dd>— +</dl> + + <p>An example is available in the <samp><span class="file">examples</span></samp> directory: <code>hello-librep</code>. + +<div class="node"> +<a name="Scheme"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Smalltalk">Smalltalk</a>, +Previous: <a rel="previous" accesskey="p" href="#librep">librep</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.9 GNU guile - Scheme</h4> + + <p><a name="index-Scheme-1227"></a><a name="index-guile-1228"></a> + <dl> +<dt>RPMs<dd>guile + + <br><dt>File extension<dd><code>scm</code> + + <br><dt>String syntax<dd><code>"abc"</code> + + <br><dt>gettext shorthand<dd><code>(_ "abc")</code> + + <br><dt>gettext/ngettext functions<dd><code>gettext</code>, <code>ngettext</code> + + <br><dt>textdomain<dd><code>textdomain</code> + + <br><dt>bindtextdomain<dd><code>bindtextdomain</code> + + <br><dt>setlocale<dd><code>(catch #t (lambda () (setlocale LC_ALL "")) (lambda args #f))</code> + + <br><dt>Prerequisite<dd><code>(use-modules (ice-9 format))</code> + + <br><dt>Use or emulate GNU gettext<dd>use + + <br><dt>Extractor<dd><code>xgettext -k_</code> + + <br><dt>Formatting with positions<dd><!-- @code{format "~1@@*~D ~0@@*~D~2@@*"}, requires @code{(use-modules (ice-9 format))} --> +<!-- not yet supported --> +— + + <br><dt>Portability<dd>On platforms without gettext, no translation. + + <br><dt>po-mode marking<dd>— +</dl> + + <p>An example is available in the <samp><span class="file">examples</span></samp> directory: <code>hello-guile</code>. + +<div class="node"> +<a name="Smalltalk"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Java">Java</a>, +Previous: <a rel="previous" accesskey="p" href="#Scheme">Scheme</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.10 GNU Smalltalk</h4> + + <p><a name="index-Smalltalk-1229"></a> + <dl> +<dt>RPMs<dd>smalltalk + + <br><dt>File extension<dd><code>st</code> + + <br><dt>String syntax<dd><code>'abc'</code> + + <br><dt>gettext shorthand<dd><code>NLS ? 'abc'</code> + + <br><dt>gettext/ngettext functions<dd><code>LcMessagesDomain>>#at:</code>, <code>LcMessagesDomain>>#at:plural:with:</code> + + <br><dt>textdomain<dd><code>LcMessages>>#domain:localeDirectory:</code> (returns a <code>LcMessagesDomain</code> +object).<br> +Example: <code>I18N Locale default messages domain: 'gettext' localeDirectory: /usr/local/share/locale'</code> + + <br><dt>bindtextdomain<dd><code>LcMessages>>#domain:localeDirectory:</code>, see above. + + <br><dt>setlocale<dd>Automatic if you use <code>I18N Locale default</code>. + + <br><dt>Prerequisite<dd><code>PackageLoader fileInPackage: 'I18N'!</code> + + <br><dt>Use or emulate GNU gettext<dd>emulate + + <br><dt>Extractor<dd><code>xgettext</code> + + <br><dt>Formatting with positions<dd><code>'%1 %2' bindWith: 'Hello' with: 'world'</code> + + <br><dt>Portability<dd>fully portable + + <br><dt>po-mode marking<dd>— +</dl> + + <p>An example is available in the <samp><span class="file">examples</span></samp> directory: +<code>hello-smalltalk</code>. + +<div class="node"> +<a name="Java"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#C_0023">C#</a>, +Previous: <a rel="previous" accesskey="p" href="#Smalltalk">Smalltalk</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.11 Java</h4> + + <p><a name="index-Java-1230"></a> + <dl> +<dt>RPMs<dd>java, java2 + + <br><dt>File extension<dd><code>java</code> + + <br><dt>String syntax<dd>"abc" + + <br><dt>gettext shorthand<dd>_("abc") + + <br><dt>gettext/ngettext functions<dd><code>GettextResource.gettext</code>, <code>GettextResource.ngettext</code>, +<code>GettextResource.pgettext</code>, <code>GettextResource.npgettext</code> + + <br><dt>textdomain<dd>—, use <code>ResourceBundle.getResource</code> instead + + <br><dt>bindtextdomain<dd>—, use CLASSPATH instead + + <br><dt>setlocale<dd>automatic + + <br><dt>Prerequisite<dd>— + + <br><dt>Use or emulate GNU gettext<dd>—, uses a Java specific message catalog format + + <br><dt>Extractor<dd><code>xgettext -k_</code> + + <br><dt>Formatting with positions<dd><code>MessageFormat.format "{1,number} {0,number}"</code> + + <br><dt>Portability<dd>fully portable + + <br><dt>po-mode marking<dd>— +</dl> + + <p>Before marking strings as internationalizable, uses of the string +concatenation operator need to be converted to <code>MessageFormat</code> +applications. For example, <code>"file "+filename+" not found"</code> becomes +<code>MessageFormat.format("file {0} not found", new Object[] { filename })</code>. +Only after this is done, can the strings be marked and extracted. + + <p>GNU gettext uses the native Java internationalization mechanism, namely +<code>ResourceBundle</code>s. There are two formats of <code>ResourceBundle</code>s: +<code>.properties</code> files and <code>.class</code> files. The <code>.properties</code> +format is a text file which the translators can directly edit, like PO +files, but which doesn't support plural forms. Whereas the <code>.class</code> +format is compiled from <code>.java</code> source code and can support plural +forms (provided it is accessed through an appropriate API, see below). + + <p>To convert a PO file to a <code>.properties</code> file, the <code>msgcat</code> +program can be used with the option <code>--properties-output</code>. To convert +a <code>.properties</code> file back to a PO file, the <code>msgcat</code> program +can be used with the option <code>--properties-input</code>. All the tools +that manipulate PO files can work with <code>.properties</code> files as well, +if given the <code>--properties-input</code> and/or <code>--properties-output</code> +option. + + <p>To convert a PO file to a ResourceBundle class, the <code>msgfmt</code> program +can be used with the option <code>--java</code> or <code>--java2</code>. To convert a +ResourceBundle back to a PO file, the <code>msgunfmt</code> program can be used +with the option <code>--java</code>. + + <p>Two different programmatic APIs can be used to access ResourceBundles. +Note that both APIs work with all kinds of ResourceBundles, whether +GNU gettext generated classes, or other <code>.class</code> or <code>.properties</code> +files. + + <ol type=1 start=1> +<li>The <code>java.util.ResourceBundle</code> API. + + <p>In particular, its <code>getString</code> function returns a string translation. +Note that a missing translation yields a <code>MissingResourceException</code>. + + <p>This has the advantage of being the standard API. And it does not require +any additional libraries, only the <code>msgcat</code> generated <code>.properties</code> +files or the <code>msgfmt</code> generated <code>.class</code> files. But it cannot do +plural handling, even if the resource was generated by <code>msgfmt</code> from +a PO file with plural handling. + + <li>The <code>gnu.gettext.GettextResource</code> API. + + <p>Reference documentation in Javadoc 1.1 style format is in the +<a href="javadoc2/index.html">javadoc2 directory</a>. + + <p>Its <code>gettext</code> function returns a string translation. Note that when +a translation is missing, the <var>msgid</var> argument is returned unchanged. + + <p>This has the advantage of having the <code>ngettext</code> function for plural +handling and the <code>pgettext</code> and <code>npgettext</code> for strings constraint +to a particular context. + + <p><a name="index-g_t_0040code_007blibintl_007d-for-Java-1231"></a>To use this API, one needs the <code>libintl.jar</code> file which is part of +the GNU gettext package and distributed under the LGPL. + </ol> + + <p>Four examples, using the second API, are available in the <samp><span class="file">examples</span></samp> +directory: <code>hello-java</code>, <code>hello-java-awt</code>, <code>hello-java-swing</code>, +<code>hello-java-qtjambi</code>. + + <p>Now, to make use of the API and define a shorthand for ‘<samp><span class="samp">getString</span></samp>’, +there are three idioms that you can choose from: + + <ul> +<li>(This one assumes Java 1.5 or newer.) +In a unique class of your project, say ‘<samp><span class="samp">Util</span></samp>’, define a static variable +holding the <code>ResourceBundle</code> instance and the shorthand: + + <pre class="smallexample"> private static ResourceBundle myResources = + ResourceBundle.getBundle("domain-name"); + public static String _(String s) { + return myResources.getString(s); + } +</pre> + <p>All classes containing internationalized strings then contain + + <pre class="smallexample"> import static Util._; +</pre> + <p class="noindent">and the shorthand is used like this: + + <pre class="smallexample"> System.out.println(_("Operation completed.")); +</pre> + <li>In a unique class of your project, say ‘<samp><span class="samp">Util</span></samp>’, define a static variable +holding the <code>ResourceBundle</code> instance: + + <pre class="smallexample"> public static ResourceBundle myResources = + ResourceBundle.getBundle("domain-name"); +</pre> + <p>All classes containing internationalized strings then contain + + <pre class="smallexample"> private static ResourceBundle res = Util.myResources; + private static String _(String s) { return res.getString(s); } +</pre> + <p class="noindent">and the shorthand is used like this: + + <pre class="smallexample"> System.out.println(_("Operation completed.")); +</pre> + <li>You add a class with a very short name, say ‘<samp><span class="samp">S</span></samp>’, containing just the +definition of the resource bundle and of the shorthand: + + <pre class="smallexample"> public class S { + public static ResourceBundle myResources = + ResourceBundle.getBundle("domain-name"); + public static String _(String s) { + return myResources.getString(s); + } + } +</pre> + <p class="noindent">and the shorthand is used like this: + + <pre class="smallexample"> System.out.println(S._("Operation completed.")); +</pre> + </ul> + + <p>Which of the three idioms you choose, will depend on whether your project +requires portability to Java versions prior to Java 1.5 and, if so, whether +copying two lines of codes into every class is more acceptable in your project +than a class with a single-letter name. + +<div class="node"> +<a name="C%23"></a> +<a name="C_0023"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#gawk">gawk</a>, +Previous: <a rel="previous" accesskey="p" href="#Java">Java</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.12 C#</h4> + + <p><a name="index-C_0023-1232"></a> + <dl> +<dt>RPMs<dd>pnet, pnetlib 0.6.2 or newer, or mono 0.29 or newer + + <br><dt>File extension<dd><code>cs</code> + + <br><dt>String syntax<dd><code>"abc"</code>, <code>@"abc"</code> + + <br><dt>gettext shorthand<dd>_("abc") + + <br><dt>gettext/ngettext functions<dd><code>GettextResourceManager.GetString</code>, +<code>GettextResourceManager.GetPluralString</code> +<code>GettextResourceManager.GetParticularString</code> +<code>GettextResourceManager.GetParticularPluralString</code> + + <br><dt>textdomain<dd><code>new GettextResourceManager(domain)</code> + + <br><dt>bindtextdomain<dd>—, compiled message catalogs are located in subdirectories of the directory +containing the executable + + <br><dt>setlocale<dd>automatic + + <br><dt>Prerequisite<dd>— + + <br><dt>Use or emulate GNU gettext<dd>—, uses a C# specific message catalog format + + <br><dt>Extractor<dd><code>xgettext -k_</code> + + <br><dt>Formatting with positions<dd><code>String.Format "{1} {0}"</code> + + <br><dt>Portability<dd>fully portable + + <br><dt>po-mode marking<dd>— +</dl> + + <p>Before marking strings as internationalizable, uses of the string +concatenation operator need to be converted to <code>String.Format</code> +invocations. For example, <code>"file "+filename+" not found"</code> becomes +<code>String.Format("file {0} not found", filename)</code>. +Only after this is done, can the strings be marked and extracted. + + <p>GNU gettext uses the native C#/.NET internationalization mechanism, namely +the classes <code>ResourceManager</code> and <code>ResourceSet</code>. Applications +use the <code>ResourceManager</code> methods to retrieve the native language +translation of strings. An instance of <code>ResourceSet</code> is the in-memory +representation of a message catalog file. The <code>ResourceManager</code> loads +and accesses <code>ResourceSet</code> instances as needed to look up the +translations. + + <p>There are two formats of <code>ResourceSet</code>s that can be directly loaded by +the C# runtime: <code>.resources</code> files and <code>.dll</code> files. + + <ul> +<li>The <code>.resources</code> format is a binary file usually generated through the +<code>resgen</code> or <code>monoresgen</code> utility, but which doesn't support plural +forms. <code>.resources</code> files can also be embedded in .NET <code>.exe</code> files. +This only affects whether a file system access is performed to load the message +catalog; it doesn't affect the contents of the message catalog. + + <li>On the other hand, the <code>.dll</code> format is a binary file that is compiled +from <code>.cs</code> source code and can support plural forms (provided it is +accessed through the GNU gettext API, see below). +</ul> + + <p>Note that these .NET <code>.dll</code> and <code>.exe</code> files are not tied to a +particular platform; their file format and GNU gettext for C# can be used +on any platform. + + <p>To convert a PO file to a <code>.resources</code> file, the <code>msgfmt</code> program +can be used with the option ‘<samp><span class="samp">--csharp-resources</span></samp>’. To convert a +<code>.resources</code> file back to a PO file, the <code>msgunfmt</code> program can be +used with the option ‘<samp><span class="samp">--csharp-resources</span></samp>’. You can also, in some cases, +use the <code>resgen</code> program (from the <code>pnet</code> package) or the +<code>monoresgen</code> program (from the <code>mono</code>/<code>mcs</code> package). These +programs can also convert a <code>.resources</code> file back to a PO file. But +beware: as of this writing (January 2004), the <code>monoresgen</code> converter is +quite buggy and the <code>resgen</code> converter ignores the encoding of the PO +files. + + <p>To convert a PO file to a <code>.dll</code> file, the <code>msgfmt</code> program can be +used with the option <code>--csharp</code>. The result will be a <code>.dll</code> file +containing a subclass of <code>GettextResourceSet</code>, which itself is a subclass +of <code>ResourceSet</code>. To convert a <code>.dll</code> file containing a +<code>GettextResourceSet</code> subclass back to a PO file, the <code>msgunfmt</code> +program can be used with the option <code>--csharp</code>. + + <p>The advantages of the <code>.dll</code> format over the <code>.resources</code> format +are: + + <ol type=1 start=1> +<li>Freedom to localize: Users can add their own translations to an application +after it has been built and distributed. Whereas when the programmer uses +a <code>ResourceManager</code> constructor provided by the system, the set of +<code>.resources</code> files for an application must be specified when the +application is built and cannot be extended afterwards. +<!-- If this were the only issue with the @code{.resources} format, one could --> +<!-- use the @code{ResourceManager.CreateFileBasedResourceManager} function. --> + + <li>Plural handling: A message catalog in <code>.dll</code> format supports the plural +handling function <code>GetPluralString</code>. Whereas <code>.resources</code> files can +only contain data and only support lookups that depend on a single string. + + <li>Context handling: A message catalog in <code>.dll</code> format supports the +query-with-context functions <code>GetParticularString</code> and +<code>GetParticularPluralString</code>. Whereas <code>.resources</code> files can +only contain data and only support lookups that depend on a single string. + + <li>The <code>GettextResourceManager</code> that loads the message catalogs in +<code>.dll</code> format also provides for inheritance on a per-message basis. +For example, in Austrian (<code>de_AT</code>) locale, translations from the German +(<code>de</code>) message catalog will be used for messages not found in the +Austrian message catalog. This has the consequence that the Austrian +translators need only translate those few messages for which the translation +into Austrian differs from the German one. Whereas when working with +<code>.resources</code> files, each message catalog must provide the translations +of all messages by itself. + + <li>The <code>GettextResourceManager</code> that loads the message catalogs in +<code>.dll</code> format also provides for a fallback: The English <var>msgid</var> is +returned when no translation can be found. Whereas when working with +<code>.resources</code> files, a language-neutral <code>.resources</code> file must +explicitly be provided as a fallback. + </ol> + + <p>On the side of the programmatic APIs, the programmer can use either the +standard <code>ResourceManager</code> API and the GNU <code>GettextResourceManager</code> +API. The latter is an extension of the former, because +<code>GettextResourceManager</code> is a subclass of <code>ResourceManager</code>. + + <ol type=1 start=1> +<li>The <code>System.Resources.ResourceManager</code> API. + + <p>This API works with resources in <code>.resources</code> format. + + <p>The creation of the <code>ResourceManager</code> is done through + <pre class="smallexample"> new ResourceManager(domainname, Assembly.GetExecutingAssembly()) +</pre> + <p class="noindent">The <code>GetString</code> function returns a string's translation. Note that this +function returns null when a translation is missing (i.e. not even found in +the fallback resource file). + + <li>The <code>GNU.Gettext.GettextResourceManager</code> API. + + <p>This API works with resources in <code>.dll</code> format. + + <p>Reference documentation is in the +<a href="csharpdoc/index.html">csharpdoc directory</a>. + + <p>The creation of the <code>ResourceManager</code> is done through + <pre class="smallexample"> new GettextResourceManager(domainname) +</pre> + <p>The <code>GetString</code> function returns a string's translation. Note that when +a translation is missing, the <var>msgid</var> argument is returned unchanged. + + <p>The <code>GetPluralString</code> function returns a string translation with plural +handling, like the <code>ngettext</code> function in C. + + <p>The <code>GetParticularString</code> function returns a string's translation, +specific to a particular context, like the <code>pgettext</code> function in C. +Note that when a translation is missing, the <var>msgid</var> argument is returned +unchanged. + + <p>The <code>GetParticularPluralString</code> function returns a string translation, +specific to a particular context, with plural handling, like the +<code>npgettext</code> function in C. + + <p><a name="index-g_t_0040code_007blibintl_007d-for-C_0023-1233"></a>To use this API, one needs the <code>GNU.Gettext.dll</code> file which is part of +the GNU gettext package and distributed under the LGPL. + </ol> + + <p>You can also mix both approaches: use the +<code>GNU.Gettext.GettextResourceManager</code> constructor, but otherwise use +only the <code>ResourceManager</code> type and only the <code>GetString</code> method. +This is appropriate when you want to profit from the tools for PO files, +but don't want to change an existing source code that uses +<code>ResourceManager</code> and don't (yet) need the <code>GetPluralString</code> method. + + <p>Two examples, using the second API, are available in the <samp><span class="file">examples</span></samp> +directory: <code>hello-csharp</code>, <code>hello-csharp-forms</code>. + + <p>Now, to make use of the API and define a shorthand for ‘<samp><span class="samp">GetString</span></samp>’, +there are two idioms that you can choose from: + + <ul> +<li>In a unique class of your project, say ‘<samp><span class="samp">Util</span></samp>’, define a static variable +holding the <code>ResourceManager</code> instance: + + <pre class="smallexample"> public static GettextResourceManager MyResourceManager = + new GettextResourceManager("domain-name"); +</pre> + <p>All classes containing internationalized strings then contain + + <pre class="smallexample"> private static GettextResourceManager Res = Util.MyResourceManager; + private static String _(String s) { return Res.GetString(s); } +</pre> + <p class="noindent">and the shorthand is used like this: + + <pre class="smallexample"> Console.WriteLine(_("Operation completed.")); +</pre> + <li>You add a class with a very short name, say ‘<samp><span class="samp">S</span></samp>’, containing just the +definition of the resource manager and of the shorthand: + + <pre class="smallexample"> public class S { + public static GettextResourceManager MyResourceManager = + new GettextResourceManager("domain-name"); + public static String _(String s) { + return MyResourceManager.GetString(s); + } + } +</pre> + <p class="noindent">and the shorthand is used like this: + + <pre class="smallexample"> Console.WriteLine(S._("Operation completed.")); +</pre> + </ul> + + <p>Which of the two idioms you choose, will depend on whether copying two lines +of codes into every class is more acceptable in your project than a class +with a single-letter name. + +<div class="node"> +<a name="gawk"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Pascal">Pascal</a>, +Previous: <a rel="previous" accesskey="p" href="#C_0023">C#</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.13 GNU awk</h4> + + <p><a name="index-awk-1234"></a><a name="index-gawk-1235"></a> + <dl> +<dt>RPMs<dd>gawk 3.1 or newer + + <br><dt>File extension<dd><code>awk</code> + + <br><dt>String syntax<dd><code>"abc"</code> + + <br><dt>gettext shorthand<dd><code>_"abc"</code> + + <br><dt>gettext/ngettext functions<dd><code>dcgettext</code>, missing <code>dcngettext</code> in gawk-3.1.0 + + <br><dt>textdomain<dd><code>TEXTDOMAIN</code> variable + + <br><dt>bindtextdomain<dd><code>bindtextdomain</code> function + + <br><dt>setlocale<dd>automatic, but missing <code>setlocale (LC_MESSAGES, "")</code> in gawk-3.1.0 + + <br><dt>Prerequisite<dd>— + + <br><dt>Use or emulate GNU gettext<dd>use + + <br><dt>Extractor<dd><code>xgettext</code> + + <br><dt>Formatting with positions<dd><code>printf "%2$d %1$d"</code> (GNU awk only) + + <br><dt>Portability<dd>On platforms without gettext, no translation. On non-GNU awks, you must +define <code>dcgettext</code>, <code>dcngettext</code> and <code>bindtextdomain</code> +yourself. + + <br><dt>po-mode marking<dd>— +</dl> + + <p>An example is available in the <samp><span class="file">examples</span></samp> directory: <code>hello-gawk</code>. + +<div class="node"> +<a name="Pascal"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#wxWidgets">wxWidgets</a>, +Previous: <a rel="previous" accesskey="p" href="#gawk">gawk</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.14 Pascal - Free Pascal Compiler</h4> + + <p><a name="index-Pascal-1236"></a><a name="index-Free-Pascal-1237"></a><a name="index-Object-Pascal-1238"></a> + <dl> +<dt>RPMs<dd>fpk + + <br><dt>File extension<dd><code>pp</code>, <code>pas</code> + + <br><dt>String syntax<dd><code>'abc'</code> + + <br><dt>gettext shorthand<dd>automatic + + <br><dt>gettext/ngettext functions<dd>—, use <code>ResourceString</code> data type instead + + <br><dt>textdomain<dd>—, use <code>TranslateResourceStrings</code> function instead + + <br><dt>bindtextdomain<dd>—, use <code>TranslateResourceStrings</code> function instead + + <br><dt>setlocale<dd>automatic, but uses only LANG, not LC_MESSAGES or LC_ALL + + <br><dt>Prerequisite<dd><code>{$mode delphi}</code> or <code>{$mode objfpc}</code><br><code>uses gettext;</code> + + <br><dt>Use or emulate GNU gettext<dd>emulate partially + + <br><dt>Extractor<dd><code>ppc386</code> followed by <code>xgettext</code> or <code>rstconv</code> + + <br><dt>Formatting with positions<dd><code>uses sysutils;</code><br><code>format "%1:d %0:d"</code> + + <br><dt>Portability<dd>? + + <br><dt>po-mode marking<dd>— +</dl> + + <p>The Pascal compiler has special support for the <code>ResourceString</code> data +type. It generates a <code>.rst</code> file. This is then converted to a +<code>.pot</code> file by use of <code>xgettext</code> or <code>rstconv</code>. At runtime, +a <code>.mo</code> file corresponding to translations of this <code>.pot</code> file +can be loaded using the <code>TranslateResourceStrings</code> function in the +<code>gettext</code> unit. + + <p>An example is available in the <samp><span class="file">examples</span></samp> directory: <code>hello-pascal</code>. + +<div class="node"> +<a name="wxWidgets"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#YCP">YCP</a>, +Previous: <a rel="previous" accesskey="p" href="#Pascal">Pascal</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.15 wxWidgets library</h4> + + <p><a name="index-g_t_0040code_007bwxWidgets_007d-library-1239"></a> + <dl> +<dt>RPMs<dd>wxGTK, gettext + + <br><dt>File extension<dd><code>cpp</code> + + <br><dt>String syntax<dd><code>"abc"</code> + + <br><dt>gettext shorthand<dd><code>_("abc")</code> + + <br><dt>gettext/ngettext functions<dd><code>wxLocale::GetString</code>, <code>wxGetTranslation</code> + + <br><dt>textdomain<dd><code>wxLocale::AddCatalog</code> + + <br><dt>bindtextdomain<dd><code>wxLocale::AddCatalogLookupPathPrefix</code> + + <br><dt>setlocale<dd><code>wxLocale::Init</code>, <code>wxSetLocale</code> + + <br><dt>Prerequisite<dd><code>#include <wx/intl.h></code> + + <br><dt>Use or emulate GNU gettext<dd>emulate, see <code>include/wx/intl.h</code> and <code>src/common/intl.cpp</code> + + <br><dt>Extractor<dd><code>xgettext</code> + + <br><dt>Formatting with positions<dd>wxString::Format supports positions if and only if the system has +<code>wprintf()</code>, <code>vswprintf()</code> functions and they support positions +according to POSIX. + + <br><dt>Portability<dd>fully portable + + <br><dt>po-mode marking<dd>yes +</dl> + +<div class="node"> +<a name="YCP"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Tcl">Tcl</a>, +Previous: <a rel="previous" accesskey="p" href="#wxWidgets">wxWidgets</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.16 YCP - YaST2 scripting language</h4> + + <p><a name="index-YCP-1240"></a><a name="index-YaST2-scripting-language-1241"></a> + <dl> +<dt>RPMs<dd>libycp, libycp-devel, yast2-core, yast2-core-devel + + <br><dt>File extension<dd><code>ycp</code> + + <br><dt>String syntax<dd><code>"abc"</code> + + <br><dt>gettext shorthand<dd><code>_("abc")</code> + + <br><dt>gettext/ngettext functions<dd><code>_()</code> with 1 or 3 arguments + + <br><dt>textdomain<dd><code>textdomain</code> statement + + <br><dt>bindtextdomain<dd>— + + <br><dt>setlocale<dd>— + + <br><dt>Prerequisite<dd>— + + <br><dt>Use or emulate GNU gettext<dd>use + + <br><dt>Extractor<dd><code>xgettext</code> + + <br><dt>Formatting with positions<dd><code>sformat "%2 %1"</code> + + <br><dt>Portability<dd>fully portable + + <br><dt>po-mode marking<dd>— +</dl> + + <p>An example is available in the <samp><span class="file">examples</span></samp> directory: <code>hello-ycp</code>. + +<div class="node"> +<a name="Tcl"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Perl">Perl</a>, +Previous: <a rel="previous" accesskey="p" href="#YCP">YCP</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.17 Tcl - Tk's scripting language</h4> + + <p><a name="index-Tcl-1242"></a><a name="index-Tk_0027s-scripting-language-1243"></a> + <dl> +<dt>RPMs<dd>tcl + + <br><dt>File extension<dd><code>tcl</code> + + <br><dt>String syntax<dd><code>"abc"</code> + + <br><dt>gettext shorthand<dd><code>[_ "abc"]</code> + + <br><dt>gettext/ngettext functions<dd><code>::msgcat::mc</code> + + <br><dt>textdomain<dd>— + + <br><dt>bindtextdomain<dd>—, use <code>::msgcat::mcload</code> instead + + <br><dt>setlocale<dd>automatic, uses LANG, but ignores LC_MESSAGES and LC_ALL + + <br><dt>Prerequisite<dd><code>package require msgcat</code> +<br><code>proc _ {s} {return [::msgcat::mc $s]}</code> + + <br><dt>Use or emulate GNU gettext<dd>—, uses a Tcl specific message catalog format + + <br><dt>Extractor<dd><code>xgettext -k_</code> + + <br><dt>Formatting with positions<dd><code>format "%2\$d %1\$d"</code> + + <br><dt>Portability<dd>fully portable + + <br><dt>po-mode marking<dd>— +</dl> + + <p>Two examples are available in the <samp><span class="file">examples</span></samp> directory: +<code>hello-tcl</code>, <code>hello-tcl-tk</code>. + + <p>Before marking strings as internationalizable, substitutions of variables +into the string need to be converted to <code>format</code> applications. For +example, <code>"file $filename not found"</code> becomes +<code>[format "file %s not found" $filename]</code>. +Only after this is done, can the strings be marked and extracted. +After marking, this example becomes +<code>[format [_ "file %s not found"] $filename]</code> or +<code>[msgcat::mc "file %s not found" $filename]</code>. Note that the +<code>msgcat::mc</code> function implicitly calls <code>format</code> when more than one +argument is given. + +<div class="node"> +<a name="Perl"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#PHP">PHP</a>, +Previous: <a rel="previous" accesskey="p" href="#Tcl">Tcl</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.18 Perl</h4> + + <p><a name="index-Perl-1244"></a> + <dl> +<dt>RPMs<dd>perl + + <br><dt>File extension<dd><code>pl</code>, <code>PL</code>, <code>pm</code>, <code>cgi</code> + + <br><dt>String syntax<dd> + <ul> +<li><code>"abc"</code> + + <li><code>'abc'</code> + + <li><code>qq (abc)</code> + + <li><code>q (abc)</code> + + <li><code>qr /abc/</code> + + <li><code>qx (/bin/date)</code> + + <li><code>/pattern match/</code> + + <li><code>?pattern match?</code> + + <li><code>s/substitution/operators/</code> + + <li><code>$tied_hash{"message"}</code> + + <li><code>$tied_hash_reference->{"message"}</code> + + <li>etc., issue the command ‘<samp><span class="samp">man perlsyn</span></samp>’ for details + + </ul> + + <br><dt>gettext shorthand<dd><code>__</code> (double underscore) + + <br><dt>gettext/ngettext functions<dd><code>gettext</code>, <code>dgettext</code>, <code>dcgettext</code>, <code>ngettext</code>, +<code>dngettext</code>, <code>dcngettext</code> + + <br><dt>textdomain<dd><code>textdomain</code> function + + <br><dt>bindtextdomain<dd><code>bindtextdomain</code> function + + <br><dt>bind_textdomain_codeset<dd><code>bind_textdomain_codeset</code> function + + <br><dt>setlocale<dd>Use <code>setlocale (LC_ALL, "");</code> + + <br><dt>Prerequisite<dd><code>use POSIX;</code> +<br><code>use Locale::TextDomain;</code> (included in the package libintl-perl +which is available on the Comprehensive Perl Archive Network CPAN, +http://www.cpan.org/). + + <br><dt>Use or emulate GNU gettext<dd>platform dependent: gettext_pp emulates, gettext_xs uses GNU gettext + + <br><dt>Extractor<dd><code>xgettext -k__ -k\$__ -k%__ -k__x -k__n:1,2 -k__nx:1,2 -k__xn:1,2 -kN__ -k</code> + + <br><dt>Formatting with positions<dd>Both kinds of format strings support formatting with positions. +<br><code>printf "%2\$d %1\$d", ...</code> (requires Perl 5.8.0 or newer) +<br><code>__expand("[new] replaces [old]", old => $oldvalue, new => $newvalue)</code> + + <br><dt>Portability<dd>The <code>libintl-perl</code> package is platform independent but is not +part of the Perl core. The programmer is responsible for +providing a dummy implementation of the required functions if the +package is not installed on the target system. + + <br><dt>po-mode marking<dd>— + + <br><dt>Documentation<dd>Included in <code>libintl-perl</code>, available on CPAN +(http://www.cpan.org/). + + </dl> + + <p>An example is available in the <samp><span class="file">examples</span></samp> directory: <code>hello-perl</code>. + + <p><a name="index-marking-Perl-sources-1245"></a> +The <code>xgettext</code> parser backend for Perl differs significantly from +the parser backends for other programming languages, just as Perl +itself differs significantly from other programming languages. The +Perl parser backend offers many more string marking facilities than +the other backends but it also has some Perl specific limitations, the +worst probably being its imperfectness. + +<ul class="menu"> +<li><a accesskey="1" href="#General-Problems">General Problems</a>: General Problems Parsing Perl Code +<li><a accesskey="2" href="#Default-Keywords">Default Keywords</a>: Which Keywords Will xgettext Look For? +<li><a accesskey="3" href="#Special-Keywords">Special Keywords</a>: How to Extract Hash Keys +<li><a accesskey="4" href="#Quote_002dlike-Expressions">Quote-like Expressions</a>: What are Strings And Quote-like Expressions? +<li><a accesskey="5" href="#Interpolation-I">Interpolation I</a>: Invalid String Interpolation +<li><a accesskey="6" href="#Interpolation-II">Interpolation II</a>: Valid String Interpolation +<li><a accesskey="7" href="#Parentheses">Parentheses</a>: When To Use Parentheses +<li><a accesskey="8" href="#Long-Lines">Long Lines</a>: How To Grok with Long Lines +<li><a accesskey="9" href="#Perl-Pitfalls">Perl Pitfalls</a>: Bugs, Pitfalls, and Things That Do Not Work +</ul> + +<div class="node"> +<a name="General-Problems"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Default-Keywords">Default Keywords</a>, +Up: <a rel="up" accesskey="u" href="#Perl">Perl</a> + +</div> + +<h5 class="subsubsection">15.5.18.1 General Problems Parsing Perl Code</h5> + + <p>It is often heard that only Perl can parse Perl. This is not true. +Perl cannot be <em>parsed</em> at all, it can only be <em>executed</em>. +Perl has various built-in ambiguities that can only be resolved at runtime. + + <p>The following example may illustrate one common problem: + +<pre class="example"> print gettext "Hello World!"; +</pre> + <p>Although this example looks like a bullet-proof case of a function +invocation, it is not: + +<pre class="example"> open gettext, ">testfile" or die; + print gettext "Hello world!" +</pre> + <p>In this context, the string <code>gettext</code> looks more like a +file handle. But not necessarily: + +<pre class="example"> use Locale::Messages qw (:libintl_h); + open gettext ">testfile" or die; + print gettext "Hello world!"; +</pre> + <p>Now, the file is probably syntactically incorrect, provided that the module +<code>Locale::Messages</code> found first in the Perl include path exports a +function <code>gettext</code>. But what if the module +<code>Locale::Messages</code> really looks like this? + +<pre class="example"> use vars qw (*gettext); + + 1; +</pre> + <p>In this case, the string <code>gettext</code> will be interpreted as a file +handle again, and the above example will create a file <samp><span class="file">testfile</span></samp> +and write the string “Hello world!” into it. Even advanced +control flow analysis will not really help: + +<pre class="example"> if (0.5 < rand) { + eval "use Sane"; + } else { + eval "use InSane"; + } + print gettext "Hello world!"; +</pre> + <p>If the module <code>Sane</code> exports a function <code>gettext</code> that does +what we expect, and the module <code>InSane</code> opens a file for writing +and associates the <em>handle</em> <code>gettext</code> with this output +stream, we are clueless again about what will happen at runtime. It is +completely unpredictable. The truth is that Perl has so many ways to +fill its symbol table at runtime that it is impossible to interpret a +particular piece of code without executing it. + + <p>Of course, <code>xgettext</code> will not execute your Perl sources while +scanning for translatable strings, but rather use heuristics in order +to guess what you meant. + + <p>Another problem is the ambiguity of the slash and the question mark. +Their interpretation depends on the context: + +<pre class="example"> # A pattern match. + print "OK\n" if /foobar/; + + # A division. + print 1 / 2; + + # Another pattern match. + print "OK\n" if ?foobar?; + + # Conditional. + print $x ? "foo" : "bar"; +</pre> + <p>The slash may either act as the division operator or introduce a +pattern match, whereas the question mark may act as the ternary +conditional operator or as a pattern match, too. Other programming +languages like <code>awk</code> present similar problems, but the consequences of a +misinterpretation are particularly nasty with Perl sources. In <code>awk</code> +for instance, a statement can never exceed one line and the parser +can recover from a parsing error at the next newline and interpret +the rest of the input stream correctly. Perl is different, as a +pattern match is terminated by the next appearance of the delimiter +(the slash or the question mark) in the input stream, regardless of +the semantic context. If a slash is really a division sign but +mis-interpreted as a pattern match, the rest of the input file is most +probably parsed incorrectly. + + <p>There are certain cases, where the ambiguity cannot be resolved at all: + +<pre class="example"> $x = wantarray ? 1 : 0; +</pre> + <p>The Perl built-in function <code>wantarray</code> does not accept any arguments. +The Perl parser therefore knows that the question mark does not start +a regular expression but is the ternary conditional operator. + +<pre class="example"> sub wantarrays {} + $x = wantarrays ? 1 : 0; +</pre> + <p>Now the situation is different. The function <code>wantarrays</code> takes +a variable number of arguments (like any non-prototyped Perl function). +The question mark is now the delimiter of a pattern match, and hence +the piece of code does not compile. + +<pre class="example"> sub wantarrays() {} + $x = wantarrays ? 1 : 0; +</pre> + <p>Now the function is prototyped, Perl knows that it does not accept any +arguments, and the question mark is therefore interpreted as the +ternaray operator again. But that unfortunately outsmarts <code>xgettext</code>. + + <p>The Perl parser in <code>xgettext</code> cannot know whether a function has +a prototype and what that prototype would look like. It therefore makes +an educated guess. If a function is known to be a Perl built-in and +this function does not accept any arguments, a following question mark +or slash is treated as an operator, otherwise as the delimiter of a +following regular expression. The Perl built-ins that do not accept +arguments are <code>wantarray</code>, <code>fork</code>, <code>time</code>, <code>times</code>, +<code>getlogin</code>, <code>getppid</code>, <code>getpwent</code>, <code>getgrent</code>, +<code>gethostent</code>, <code>getnetent</code>, <code>getprotoent</code>, <code>getservent</code>, +<code>setpwent</code>, <code>setgrent</code>, <code>endpwent</code>, <code>endgrent</code>, +<code>endhostent</code>, <code>endnetent</code>, <code>endprotoent</code>, and +<code>endservent</code>. + + <p>If you find that <code>xgettext</code> fails to extract strings from +portions of your sources, you should therefore look out for slashes +and/or question marks preceding these sections. You may have come +across a bug in <code>xgettext</code>'s Perl parser (and of course you +should report that bug). In the meantime you should consider to +reformulate your code in a manner less challenging to <code>xgettext</code>. + + <p>In particular, if the parser is too dumb to see that a function +does not accept arguments, use parentheses: + +<pre class="example"> $x = somefunc() ? 1 : 0; + $y = (somefunc) ? 1 : 0; +</pre> + <p>In fact the Perl parser itself has similar problems and warns you +about such constructs. + +<div class="node"> +<a name="Default-Keywords"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Special-Keywords">Special Keywords</a>, +Previous: <a rel="previous" accesskey="p" href="#General-Problems">General Problems</a>, +Up: <a rel="up" accesskey="u" href="#Perl">Perl</a> + +</div> + +<h5 class="subsubsection">15.5.18.2 Which keywords will xgettext look for?</h5> + + <p><a name="index-Perl-default-keywords-1246"></a> +Unless you instruct <code>xgettext</code> otherwise by invoking it with one +of the options <code>--keyword</code> or <code>-k</code>, it will recognize the +following keywords in your Perl sources: + + <ul> +<li><code>gettext</code> + + <li><code>dgettext</code> + + <li><code>dcgettext</code> + + <li><code>ngettext:1,2</code> + + <p>The first (singular) and the second (plural) argument will be +extracted. + + <li><code>dngettext:1,2</code> + + <p>The first (singular) and the second (plural) argument will be +extracted. + + <li><code>dcngettext:1,2</code> + + <p>The first (singular) and the second (plural) argument will be +extracted. + + <li><code>gettext_noop</code> + + <li><code>%gettext</code> + + <p>The keys of lookups into the hash <code>%gettext</code> will be extracted. + + <li><code>$gettext</code> + + <p>The keys of lookups into the hash reference <code>$gettext</code> will be extracted. + + </ul> + +<div class="node"> +<a name="Special-Keywords"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Quote_002dlike-Expressions">Quote-like Expressions</a>, +Previous: <a rel="previous" accesskey="p" href="#Default-Keywords">Default Keywords</a>, +Up: <a rel="up" accesskey="u" href="#Perl">Perl</a> + +</div> + +<h5 class="subsubsection">15.5.18.3 How to Extract Hash Keys</h5> + + <p><a name="index-Perl-special-keywords-for-hash_002dlookups-1247"></a> +Translating messages at runtime is normally performed by looking up the +original string in the translation database and returning the +translated version. The “natural” Perl implementation is a hash +lookup, and, of course, <code>xgettext</code> supports such practice. + +<pre class="example"> print __"Hello world!"; + print $__{"Hello world!"}; + print $__->{"Hello world!"}; + print $$__{"Hello world!"}; +</pre> + <p>The above four lines all do the same thing. The Perl module +<code>Locale::TextDomain</code> exports by default a hash <code>%__</code> that +is tied to the function <code>__()</code>. It also exports a reference +<code>$__</code> to <code>%__</code>. + + <p>If an argument to the <code>xgettext</code> option <code>--keyword</code>, +resp. <code>-k</code> starts with a percent sign, the rest of the keyword is +interpreted as the name of a hash. If it starts with a dollar +sign, the rest of the keyword is interpreted as a reference to a +hash. + + <p>Note that you can omit the quotation marks (single or double) around +the hash key (almost) whenever Perl itself allows it: + +<pre class="example"> print $gettext{Error}; +</pre> + <p>The exact rule is: You can omit the surrounding quotes, when the hash +key is a valid C (!) identifier, i.e. when it starts with an +underscore or an ASCII letter and is followed by an arbitrary number +of underscores, ASCII letters or digits. Other Unicode characters +are <em>not</em> allowed, regardless of the <code>use utf8</code> pragma. + +<div class="node"> +<a name="Quote-like-Expressions"></a> +<a name="Quote_002dlike-Expressions"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Interpolation-I">Interpolation I</a>, +Previous: <a rel="previous" accesskey="p" href="#Special-Keywords">Special Keywords</a>, +Up: <a rel="up" accesskey="u" href="#Perl">Perl</a> + +</div> + +<h5 class="subsubsection">15.5.18.4 What are Strings And Quote-like Expressions?</h5> + + <p><a name="index-Perl-quote_002dlike-expressions-1248"></a> +Perl offers a plethora of different string constructs. Those that can +be used either as arguments to functions or inside braces for hash +lookups are generally supported by <code>xgettext</code>. + + <ul> +<li><strong>double-quoted strings</strong> +<br> + <pre class="example"> print gettext "Hello World!"; +</pre> + <li><strong>single-quoted strings</strong> +<br> + <pre class="example"> print gettext 'Hello World!'; +</pre> + <li><strong>the operator qq</strong> +<br> + <pre class="example"> print gettext qq |Hello World!|; + print gettext qq <E-mail: <guido\@imperia.net>>; +</pre> + <p>The operator <code>qq</code> is fully supported. You can use arbitrary +delimiters, including the four bracketing delimiters (round, angle, +square, curly) that nest. + + <li><strong>the operator q</strong> +<br> + <pre class="example"> print gettext q |Hello World!|; + print gettext q <E-mail: <guido@imperia.net>>; +</pre> + <p>The operator <code>q</code> is fully supported. You can use arbitrary +delimiters, including the four bracketing delimiters (round, angle, +square, curly) that nest. + + <li><strong>the operator qx</strong> +<br> + <pre class="example"> print gettext qx ;LANGUAGE=C /bin/date; + print gettext qx [/usr/bin/ls | grep '^[A-Z]*']; +</pre> + <p>The operator <code>qx</code> is fully supported. You can use arbitrary +delimiters, including the four bracketing delimiters (round, angle, +square, curly) that nest. + + <p>The example is actually a useless use of <code>gettext</code>. It will +invoke the <code>gettext</code> function on the output of the command +specified with the <code>qx</code> operator. The feature was included +in order to make the interface consistent (the parser will extract +all strings and quote-like expressions). + + <li><strong>here documents</strong> +<br> + <pre class="example"> print gettext <<'EOF'; + program not found in $PATH + EOF + + print ngettext <<EOF, <<"EOF"; + one file deleted + EOF + several files deleted + EOF +</pre> + <p>Here-documents are recognized. If the delimiter is enclosed in single +quotes, the string is not interpolated. If it is enclosed in double +quotes or has no quotes at all, the string is interpolated. + + <p>Delimiters that start with a digit are not supported! + + </ul> + +<div class="node"> +<a name="Interpolation-I"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Interpolation-II">Interpolation II</a>, +Previous: <a rel="previous" accesskey="p" href="#Quote_002dlike-Expressions">Quote-like Expressions</a>, +Up: <a rel="up" accesskey="u" href="#Perl">Perl</a> + +</div> + +<h5 class="subsubsection">15.5.18.5 Invalid Uses Of String Interpolation</h5> + + <p><a name="index-Perl-invalid-string-interpolation-1249"></a> +Perl is capable of interpolating variables into strings. This offers +some nice features in localized programs but can also lead to +problems. + + <p>A common error is a construct like the following: + +<pre class="example"> print gettext "This is the program $0!\n"; +</pre> + <p>Perl will interpolate at runtime the value of the variable <code>$0</code> +into the argument of the <code>gettext()</code> function. Hence, this +argument is not a string constant but a variable argument (<code>$0</code> +is a global variable that holds the name of the Perl script being +executed). The interpolation is performed by Perl before the string +argument is passed to <code>gettext()</code> and will therefore depend on +the name of the script which can only be determined at runtime. +Consequently, it is almost impossible that a translation can be looked +up at runtime (except if, by accident, the interpolated string is found +in the message catalog). + + <p>The <code>xgettext</code> program will therefore terminate parsing with a fatal +error if it encounters a variable inside of an extracted string. In +general, this will happen for all kinds of string interpolations that +cannot be safely performed at compile time. If you absolutely know +what you are doing, you can always circumvent this behavior: + +<pre class="example"> my $know_what_i_am_doing = "This is program $0!\n"; + print gettext $know_what_i_am_doing; +</pre> + <p>Since the parser only recognizes strings and quote-like expressions, +but not variables or other terms, the above construct will be +accepted. You will have to find another way, however, to let your +original string make it into your message catalog. + + <p>If invoked with the option <code>--extract-all</code>, resp. <code>-a</code>, +variable interpolation will be accepted. Rationale: You will +generally use this option in order to prepare your sources for +internationalization. + + <p>Please see the manual page ‘<samp><span class="samp">man perlop</span></samp>’ for details of strings and +quote-like expressions that are subject to interpolation and those +that are not. Safe interpolations (that will not lead to a fatal +error) are: + + <ul> +<li>the escape sequences <code>\t</code> (tab, HT, TAB), <code>\n</code> +(newline, NL), <code>\r</code> (return, CR), <code>\f</code> (form feed, FF), +<code>\b</code> (backspace, BS), <code>\a</code> (alarm, bell, BEL), and <code>\e</code> +(escape, ESC). + + <li>octal chars, like <code>\033</code> +<br> +Note that octal escapes in the range of 400-777 are translated into a +UTF-8 representation, regardless of the presence of the <code>use utf8</code> pragma. + + <li>hex chars, like <code>\x1b</code> + + <li>wide hex chars, like <code>\x{263a}</code> +<br> +Note that this escape is translated into a UTF-8 representation, +regardless of the presence of the <code>use utf8</code> pragma. + + <li>control chars, like <code>\c[</code> (CTRL-[) + + <li>named Unicode chars, like <code>\N{LATIN CAPITAL LETTER C WITH CEDILLA}</code> +<br> +Note that this escape is translated into a UTF-8 representation, +regardless of the presence of the <code>use utf8</code> pragma. +</ul> + + <p>The following escapes are considered partially safe: + + <ul> +<li><code>\l</code> lowercase next char + + <li><code>\u</code> uppercase next char + + <li><code>\L</code> lowercase till \E + + <li><code>\U</code> uppercase till \E + + <li><code>\E</code> end case modification + + <li><code>\Q</code> quote non-word characters till \E + + </ul> + + <p>These escapes are only considered safe if the string consists of +ASCII characters only. Translation of characters outside the range +defined by ASCII is locale-dependent and can actually only be performed +at runtime; <code>xgettext</code> doesn't do these locale-dependent translations +at extraction time. + + <p>Except for the modifier <code>\Q</code>, these translations, albeit valid, +are generally useless and only obfuscate your sources. If a +translation can be safely performed at compile time you can just as +well write what you mean. + +<div class="node"> +<a name="Interpolation-II"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Parentheses">Parentheses</a>, +Previous: <a rel="previous" accesskey="p" href="#Interpolation-I">Interpolation I</a>, +Up: <a rel="up" accesskey="u" href="#Perl">Perl</a> + +</div> + +<h5 class="subsubsection">15.5.18.6 Valid Uses Of String Interpolation</h5> + + <p><a name="index-Perl-valid-string-interpolation-1250"></a> +Perl is often used to generate sources for other programming languages +or arbitrary file formats. Web applications that output HTML code +make a prominent example for such usage. + + <p>You will often come across situations where you want to intersperse +code written in the target (programming) language with translatable +messages, like in the following HTML example: + +<pre class="example"> print gettext <<EOF; + <h1>My Homepage</h1> + <script language="JavaScript"><!-- + for (i = 0; i < 100; ++i) { + alert ("Thank you so much for visiting my homepage!"); + } + //--></script> + EOF +</pre> + <p>The parser will extract the entire here document, and it will appear +entirely in the resulting PO file, including the JavaScript snippet +embedded in the HTML code. If you exaggerate with constructs like +the above, you will run the risk that the translators of your package +will look out for a less challenging project. You should consider an +alternative expression here: + +<pre class="example"> print <<EOF; + <h1>$gettext{"My Homepage"}</h1> + <script language="JavaScript"><!-- + for (i = 0; i < 100; ++i) { + alert ("$gettext{'Thank you so much for visiting my homepage!'}"); + } + //--></script> + EOF +</pre> + <p>Only the translatable portions of the code will be extracted here, and +the resulting PO file will begrudgingly improve in terms of readability. + + <p>You can interpolate hash lookups in all strings or quote-like +expressions that are subject to interpolation (see the manual page +‘<samp><span class="samp">man perlop</span></samp>’ for details). Double interpolation is invalid, however: + +<pre class="example"> # TRANSLATORS: Replace "the earth" with the name of your planet. + print gettext qq{Welcome to $gettext->{"the earth"}}; +</pre> + <p>The <code>qq</code>-quoted string is recognized as an argument to <code>xgettext</code> in +the first place, and checked for invalid variable interpolation. The +dollar sign of hash-dereferencing will therefore terminate the parser +with an “invalid interpolation” error. + + <p>It is valid to interpolate hash lookups in regular expressions: + +<pre class="example"> if ($var =~ /$gettext{"the earth"}/) { + print gettext "Match!\n"; + } + s/$gettext{"U. S. A."}/$gettext{"U. S. A."} $gettext{"(dial +0)"}/g; +</pre> + <div class="node"> +<a name="Parentheses"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Long-Lines">Long Lines</a>, +Previous: <a rel="previous" accesskey="p" href="#Interpolation-II">Interpolation II</a>, +Up: <a rel="up" accesskey="u" href="#Perl">Perl</a> + +</div> + +<h5 class="subsubsection">15.5.18.7 When To Use Parentheses</h5> + + <p><a name="index-Perl-parentheses-1251"></a> +In Perl, parentheses around function arguments are mostly optional. +<code>xgettext</code> will always assume that all +recognized keywords (except for hashes and hash references) are names +of properly prototyped functions, and will (hopefully) only require +parentheses where Perl itself requires them. All constructs in the +following example are therefore ok to use: + +<pre class="example"> print gettext ("Hello World!\n"); + print gettext "Hello World!\n"; + print dgettext ($package => "Hello World!\n"); + print dgettext $package, "Hello World!\n"; + + # The "fat comma" => turns the left-hand side argument into a + # single-quoted string! + print dgettext smellovision => "Hello World!\n"; + + # The following assignment only works with prototyped functions. + # Otherwise, the functions will act as "greedy" list operators and + # eat up all following arguments. + my $anonymous_hash = { + planet => gettext "earth", + cakes => ngettext "one cake", "several cakes", $n, + still => $works, + }; + # The same without fat comma: + my $other_hash = { + 'planet', gettext "earth", + 'cakes', ngettext "one cake", "several cakes", $n, + 'still', $works, + }; + + # Parentheses are only significant for the first argument. + print dngettext 'package', ("one cake", "several cakes", $n), $discarded; +</pre> + <div class="node"> +<a name="Long-Lines"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Perl-Pitfalls">Perl Pitfalls</a>, +Previous: <a rel="previous" accesskey="p" href="#Parentheses">Parentheses</a>, +Up: <a rel="up" accesskey="u" href="#Perl">Perl</a> + +</div> + +<h5 class="subsubsection">15.5.18.8 How To Grok with Long Lines</h5> + + <p><a name="index-Perl-long-lines-1252"></a> +The necessity of long messages can often lead to a cumbersome or +unreadable coding style. Perl has several options that may prevent +you from writing unreadable code, and +<code>xgettext</code> does its best to do likewise. This is where the dot +operator (the string concatenation operator) may come in handy: + +<pre class="example"> print gettext ("This is a very long" + . " message that is still" + . " readable, because" + . " it is split into" + . " multiple lines.\n"); +</pre> + <p>Perl is smart enough to concatenate these constant string fragments +into one long string at compile time, and so is +<code>xgettext</code>. You will only find one long message in the resulting +POT file. + + <p>Note that the future Perl 6 will probably use the underscore +(‘<samp><span class="samp">_</span></samp>’) as the string concatenation operator, and the dot +(‘<samp><span class="samp">.</span></samp>’) for dereferencing. This new syntax is not yet supported by +<code>xgettext</code>. + + <p>If embedded newline characters are not an issue, or even desired, you +may also insert newline characters inside quoted strings wherever you +feel like it: + +<pre class="example"> print gettext ("<em>In HTML output + embedded newlines are generally no + problem, since adjacent whitespace + is always rendered into a single + space character.</em>"); +</pre> + <p>You may also consider to use here documents: + +<pre class="example"> print gettext <<EOF; + <em>In HTML output + embedded newlines are generally no + problem, since adjacent whitespace + is always rendered into a single + space character.</em> + EOF +</pre> + <p>Please do not forget that the line breaks are real, i.e. they +translate into newline characters that will consequently show up in +the resulting POT file. + +<div class="node"> +<a name="Perl-Pitfalls"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Long-Lines">Long Lines</a>, +Up: <a rel="up" accesskey="u" href="#Perl">Perl</a> + +</div> + +<h5 class="subsubsection">15.5.18.9 Bugs, Pitfalls, And Things That Do Not Work</h5> + + <p><a name="index-Perl-pitfalls-1253"></a> +The foregoing sections should have proven that +<code>xgettext</code> is quite smart in extracting translatable strings from +Perl sources. Yet, some more or less exotic constructs that could be +expected to work, actually do not work. + + <p>One of the more relevant limitations can be found in the +implementation of variable interpolation inside quoted strings. Only +simple hash lookups can be used there: + +<pre class="example"> print <<EOF; + $gettext{"The dot operator" + . " does not work" + . "here!"} + Likewise, you cannot @{[ gettext ("interpolate function calls") ]} + inside quoted strings or quote-like expressions. + EOF +</pre> + <p>This is valid Perl code and will actually trigger invocations of the +<code>gettext</code> function at runtime. Yet, the Perl parser in +<code>xgettext</code> will fail to recognize the strings. A less obvious +example can be found in the interpolation of regular expressions: + +<pre class="example"> s/<!--START_OF_WEEK-->/gettext ("Sunday")/e; +</pre> + <p>The modifier <code>e</code> will cause the substitution to be interpreted as +an evaluable statement. Consequently, at runtime the function +<code>gettext()</code> is called, but again, the parser fails to extract the +string “Sunday”. Use a temporary variable as a simple workaround if +you really happen to need this feature: + +<pre class="example"> my $sunday = gettext "Sunday"; + s/<!--START_OF_WEEK-->/$sunday/; +</pre> + <p>Hash slices would also be handy but are not recognized: + +<pre class="example"> my @weekdays = @gettext{'Sunday', 'Monday', 'Tuesday', 'Wednesday', + 'Thursday', 'Friday', 'Saturday'}; + # Or even: + @weekdays = @gettext{qw (Sunday Monday Tuesday Wednesday Thursday + Friday Saturday) }; +</pre> + <p>This is perfectly valid usage of the tied hash <code>%gettext</code> but the +strings are not recognized and therefore will not be extracted. + + <p>Another caveat of the current version is its rudimentary support for +non-ASCII characters in identifiers. You may encounter serious +problems if you use identifiers with characters outside the range of +'A'-'Z', 'a'-'z', '0'-'9' and the underscore '_'. + + <p>Maybe some of these missing features will be implemented in future +versions, but since you can always make do without them at minimal effort, +these todos have very low priority. + + <p>A nasty problem are brace format strings that already contain braces +as part of the normal text, for example the usage strings typically +encountered in programs: + +<pre class="example"> die "usage: $0 {OPTIONS} FILENAME...\n"; +</pre> + <p>If you want to internationalize this code with Perl brace format strings, +you will run into a problem: + +<pre class="example"> die __x ("usage: {program} {OPTIONS} FILENAME...\n", program => $0); +</pre> + <p>Whereas ‘<samp><span class="samp">{program}</span></samp>’ is a placeholder, ‘<samp><span class="samp">{OPTIONS}</span></samp>’ +is not and should probably be translated. Yet, there is no way to teach +the Perl parser in <code>xgettext</code> to recognize the first one, and leave +the other one alone. + + <p>There are two possible work-arounds for this problem. If you are +sure that your program will run under Perl 5.8.0 or newer (these +Perl versions handle positional parameters in <code>printf()</code>) or +if you are sure that the translator will not have to reorder the arguments +in her translation – for example if you have only one brace placeholder +in your string, or if it describes a syntax, like in this one –, you can +mark the string as <code>no-perl-brace-format</code> and use <code>printf()</code>: + +<pre class="example"> # xgettext: no-perl-brace-format + die sprintf ("usage: %s {OPTIONS} FILENAME...\n", $0); +</pre> + <p>If you want to use the more portable Perl brace format, you will have to do +put placeholders in place of the literal braces: + +<pre class="example"> die __x ("usage: {program} {[}OPTIONS{]} FILENAME...\n", + program => $0, '[' => '{', ']' => '}'); +</pre> + <p>Perl brace format strings know no escaping mechanism. No matter how this +escaping mechanism looked like, it would either give the programmer a +hard time, make translating Perl brace format strings heavy-going, or +result in a performance penalty at runtime, when the format directives +get executed. Most of the time you will happily get along with +<code>printf()</code> for this special case. + +<div class="node"> +<a name="PHP"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Pike">Pike</a>, +Previous: <a rel="previous" accesskey="p" href="#Perl">Perl</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.19 PHP Hypertext Preprocessor</h4> + + <p><a name="index-PHP-1254"></a> + <dl> +<dt>RPMs<dd>mod_php4, mod_php4-core, phpdoc + + <br><dt>File extension<dd><code>php</code>, <code>php3</code>, <code>php4</code> + + <br><dt>String syntax<dd><code>"abc"</code>, <code>'abc'</code> + + <br><dt>gettext shorthand<dd><code>_("abc")</code> + + <br><dt>gettext/ngettext functions<dd><code>gettext</code>, <code>dgettext</code>, <code>dcgettext</code>; starting with PHP 4.2.0 +also <code>ngettext</code>, <code>dngettext</code>, <code>dcngettext</code> + + <br><dt>textdomain<dd><code>textdomain</code> function + + <br><dt>bindtextdomain<dd><code>bindtextdomain</code> function + + <br><dt>setlocale<dd>Programmer must call <code>setlocale (LC_ALL, "")</code> + + <br><dt>Prerequisite<dd>— + + <br><dt>Use or emulate GNU gettext<dd>use + + <br><dt>Extractor<dd><code>xgettext</code> + + <br><dt>Formatting with positions<dd><code>printf "%2\$d %1\$d"</code> + + <br><dt>Portability<dd>On platforms without gettext, the functions are not available. + + <br><dt>po-mode marking<dd>— +</dl> + + <p>An example is available in the <samp><span class="file">examples</span></samp> directory: <code>hello-php</code>. + +<div class="node"> +<a name="Pike"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#GCC_002dsource">GCC-source</a>, +Previous: <a rel="previous" accesskey="p" href="#PHP">PHP</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.20 Pike</h4> + + <p><a name="index-Pike-1255"></a> + <dl> +<dt>RPMs<dd>roxen + + <br><dt>File extension<dd><code>pike</code> + + <br><dt>String syntax<dd><code>"abc"</code> + + <br><dt>gettext shorthand<dd>— + + <br><dt>gettext/ngettext functions<dd><code>gettext</code>, <code>dgettext</code>, <code>dcgettext</code> + + <br><dt>textdomain<dd><code>textdomain</code> function + + <br><dt>bindtextdomain<dd><code>bindtextdomain</code> function + + <br><dt>setlocale<dd><code>setlocale</code> function + + <br><dt>Prerequisite<dd><code>import Locale.Gettext;</code> + + <br><dt>Use or emulate GNU gettext<dd>use + + <br><dt>Extractor<dd>— + + <br><dt>Formatting with positions<dd>— + + <br><dt>Portability<dd>On platforms without gettext, the functions are not available. + + <br><dt>po-mode marking<dd>— +</dl> + +<div class="node"> +<a name="GCC-source"></a> +<a name="GCC_002dsource"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Pike">Pike</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Programming-Languages">List of Programming Languages</a> + +</div> + +<h4 class="subsection">15.5.21 GNU Compiler Collection sources</h4> + + <p><a name="index-GCC_002dsource-1256"></a> + <dl> +<dt>RPMs<dd>gcc + + <br><dt>File extension<dd><code>c</code>, <code>h</code>. + + <br><dt>String syntax<dd><code>"abc"</code> + + <br><dt>gettext shorthand<dd><code>_("abc")</code> + + <br><dt>gettext/ngettext functions<dd><code>gettext</code>, <code>dgettext</code>, <code>dcgettext</code>, <code>ngettext</code>, +<code>dngettext</code>, <code>dcngettext</code> + + <br><dt>textdomain<dd><code>textdomain</code> function + + <br><dt>bindtextdomain<dd><code>bindtextdomain</code> function + + <br><dt>setlocale<dd>Programmer must call <code>setlocale (LC_ALL, "")</code> + + <br><dt>Prerequisite<dd><code>#include "intl.h"</code> + + <br><dt>Use or emulate GNU gettext<dd>Use + + <br><dt>Extractor<dd><code>xgettext -k_</code> + + <br><dt>Formatting with positions<dd>— + + <br><dt>Portability<dd>Uses autoconf macros + + <br><dt>po-mode marking<dd>yes +</dl> + +<!-- This is the template for new languages. --> +<div class="node"> +<a name="List-of-Data-Formats"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#List-of-Programming-Languages">List of Programming Languages</a>, +Up: <a rel="up" accesskey="u" href="#Programming-Languages">Programming Languages</a> + +</div> + +<h3 class="section">15.6 Internationalizable Data</h3> + + <p>Here is a list of other data formats which can be internationalized +using GNU gettext. + +<ul class="menu"> +<li><a accesskey="1" href="#POT">POT</a>: POT - Portable Object Template +<li><a accesskey="2" href="#RST">RST</a>: Resource String Table +<li><a accesskey="3" href="#Glade">Glade</a>: Glade - GNOME user interface description +</ul> + +<div class="node"> +<a name="POT"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#RST">RST</a>, +Previous: <a rel="previous" accesskey="p" href="#List-of-Data-Formats">List of Data Formats</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Data-Formats">List of Data Formats</a> + +</div> + +<h4 class="subsection">15.6.1 POT - Portable Object Template</h4> + + <dl> +<dt>RPMs<dd>gettext + + <br><dt>File extension<dd><code>pot</code>, <code>po</code> + + <br><dt>Extractor<dd><code>xgettext</code> +</dl> + +<div class="node"> +<a name="RST"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Glade">Glade</a>, +Previous: <a rel="previous" accesskey="p" href="#POT">POT</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Data-Formats">List of Data Formats</a> + +</div> + +<h4 class="subsection">15.6.2 Resource String Table</h4> + + <p><a name="index-RST-1257"></a> + <dl> +<dt>RPMs<dd>fpk + + <br><dt>File extension<dd><code>rst</code> + + <br><dt>Extractor<dd><code>xgettext</code>, <code>rstconv</code> +</dl> + +<div class="node"> +<a name="Glade"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#RST">RST</a>, +Up: <a rel="up" accesskey="u" href="#List-of-Data-Formats">List of Data Formats</a> + +</div> + +<h4 class="subsection">15.6.3 Glade - GNOME user interface description</h4> + + <dl> +<dt>RPMs<dd>glade, libglade, glade2, libglade2, intltool + + <br><dt>File extension<dd><code>glade</code>, <code>glade2</code> + + <br><dt>Extractor<dd><code>xgettext</code>, <code>libglade-xgettext</code>, <code>xml-i18n-extract</code>, <code>intltool-extract</code> +</dl> + +<!-- This is the template for new data formats. --> +<div class="node"> +<a name="Conclusion"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Language-Codes">Language Codes</a>, +Previous: <a rel="previous" accesskey="p" href="#Programming-Languages">Programming Languages</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="chapter">16 Concluding Remarks</h2> + + <p>We would like to conclude this GNU <code>gettext</code> 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. + +<ul class="menu"> +<li><a accesskey="1" href="#History">History</a>: History of GNU <code>gettext</code> +<li><a accesskey="2" href="#References">References</a>: Related Readings +</ul> + +<div class="node"> +<a name="History"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#References">References</a>, +Previous: <a rel="previous" accesskey="p" href="#Conclusion">Conclusion</a>, +Up: <a rel="up" accesskey="u" href="#Conclusion">Conclusion</a> + +</div> + +<h3 class="section">16.1 History of GNU <code>gettext</code></h3> + + <p><a name="index-history-of-GNU-_0040code_007bgettext_007d-1258"></a> +Internationalization concerns and algorithms have been informally +and casually discussed for years in GNU, sometimes around GNU +<code>libc</code>, maybe around the incoming <code>Hurd</code>, or otherwise +(nobody clearly remembers). And even then, when the work started for +real, this was somewhat independently of these previous discussions. + + <p>This all began in July 1994, when Patrick D'Cruze had the idea and +initiative of internationalizing version 3.9.2 of GNU <code>fileutils</code>. +He then asked Jim Meyering, the maintainer, how to get those changes +folded into an official release. That first draft was full of +<code>#ifdef</code>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 <code>glocale</code>, at that time. + + <p>Jim implemented <code>glocale</code> and got a lot of exhausting feedback +from Patrick and Richard, of course, but also from Mitchum DSouza +(who wrote a <code>catgets</code>-like package), Roland McGrath, maybe David +MacKenzie, Franç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, <code>glocale</code> was torn apart. +In particular, Paul Eggert – always keeping an eye on developments +in Solaris – advocated the use of the <code>gettext</code> API over +<code>glocale</code>'s <code>catgets</code>-based API. + + <p>While Jim took some distance and time and became dad for a second +time, Roland wanted to get GNU <code>libc</code> internationalized, and +got Ulrich Drepper involved in that project. Instead of starting +from <code>glocale</code>, Ulrich rewrote something from scratch, but +more conforming to the set of guidelines who emerged out of the +<code>glocale</code> effort. Then, Ulrich got people from the previous +forum to involve themselves into this new project, and the switch +from <code>glocale</code> to what was first named <code>msgutils</code>, renamed +<code>nlsutils</code>, and later <code>gettext</code>, became officially accepted +by Richard in May 1995 or so. + + <p>Let's summarize by saying that Ulrich Drepper wrote GNU <code>gettext</code> +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 <code>THANKS</code> file which comes with the GNU <code>gettext</code> +distribution. + + <p>While this was being done, François adapted half a dozen of +GNU packages to <code>glocale</code> first, then later to <code>gettext</code>, +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. + + <p>Franç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 <code>gettext</code> Texinfo manual. + + <p>In 1997, Ulrich Drepper released the GNU libc 2.0, which included the +<code>gettext</code>, <code>textdomain</code> and <code>bindtextdomain</code> functions. + + <p>In 2000, Ulrich Drepper added plural form handling (the <code>ngettext</code> +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. + + <p>Ulrich being quite busy in his role of General Maintainer of GNU libc, +he handed over the GNU <code>gettext</code> 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. + +<div class="node"> +<a name="References"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#History">History</a>, +Up: <a rel="up" accesskey="u" href="#Conclusion">Conclusion</a> + +</div> + +<h3 class="section">16.2 Related Readings</h3> + + <p><a name="index-related-reading-1259"></a><a name="index-bibliography-1260"></a> +<strong> NOTE: </strong> This documentation section is outdated and needs to be +revised. + + <p>Eugene H. Dorr (<samp><span class="file">dorre@well.com</span></samp>) maintains an interesting +bibliography on internationalization matters, called +<cite>Internationalization Reference List</cite>, which is available as: +<pre class="example"> ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt +</pre> + <p>Michael Gschwind (<samp><span class="file">mike@vlsivie.tuwien.ac.at</span></samp>) maintains a +Frequently Asked Questions (FAQ) list, entitled <cite>Programming for +Internationalisation</cite>. 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<!-- /@w -->. It is regularly published in Usenet +groups <samp><span class="file">comp.unix.questions</span></samp>, <samp><span class="file">comp.std.internat</span></samp>, +<samp><span class="file">comp.software.international</span></samp>, <samp><span class="file">comp.lang.c</span></samp>, +<samp><span class="file">comp.windows.x</span></samp>, <samp><span class="file">comp.std.c</span></samp>, <samp><span class="file">comp.answers</span></samp> +and <samp><span class="file">news.answers</span></samp>. The home location of this document is: +<pre class="example"> ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming +</pre> + <p>Patrick D'Cruze (<samp><span class="file">pdcruze@li.org</span></samp>) wrote a tutorial about NLS +matters, and Jochen Hein (<samp><span class="file">Hein@student.tu-clausthal.de</span></samp>) took +over the responsibility of maintaining it. It may be found as: +<pre class="example"> ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/... + ...locale-tutorial-0.8.txt.gz +</pre> + <p class="noindent">This site is mirrored in: +<pre class="example"> ftp://ftp.ibp.fr/pub/linux/sunsite/ +</pre> + <p>A French version of the same tutorial should be findable at: +<pre class="example"> ftp://ftp.ibp.fr/pub/linux/french/docs/ +</pre> + <p class="noindent">together with French translations of many Linux-related documents. + +<div class="node"> +<a name="Language-Codes"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Country-Codes">Country Codes</a>, +Previous: <a rel="previous" accesskey="p" href="#Conclusion">Conclusion</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="appendix">Appendix A Language Codes</h2> + + <p><a name="index-language-codes-1261"></a><a name="index-ISO-639-1262"></a> +The ISO 639<!-- /@w --> standard defines two-letter codes for many languages, and +three-letter codes for more rarely used languages. +All abbreviations for languages used in the Translation Project should +come from this standard. + +<ul class="menu"> +<li><a accesskey="1" href="#Usual-Language-Codes">Usual Language Codes</a>: Two-letter ISO 639 language codes +<li><a accesskey="2" href="#Rare-Language-Codes">Rare Language Codes</a>: Three-letter ISO 639 language codes +</ul> + +<div class="node"> +<a name="Usual-Language-Codes"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Rare-Language-Codes">Rare Language Codes</a>, +Previous: <a rel="previous" accesskey="p" href="#Language-Codes">Language Codes</a>, +Up: <a rel="up" accesskey="u" href="#Language-Codes">Language Codes</a> + +</div> + +<h3 class="appendixsec">A.1 Usual Language Codes</h3> + + <p>For the commonly used languages, the ISO 639-1<!-- /@w --> standard defines two-letter +codes. + + <dl> +<dt>‘<samp><span class="samp">aa</span></samp>’<dd>Afar. +<br><dt>‘<samp><span class="samp">ab</span></samp>’<dd>Abkhazian. +<br><dt>‘<samp><span class="samp">ae</span></samp>’<dd>Avestan. +<br><dt>‘<samp><span class="samp">af</span></samp>’<dd>Afrikaans. +<br><dt>‘<samp><span class="samp">ak</span></samp>’<dd>Akan. +<br><dt>‘<samp><span class="samp">am</span></samp>’<dd>Amharic. +<br><dt>‘<samp><span class="samp">an</span></samp>’<dd>Aragonese. +<br><dt>‘<samp><span class="samp">ar</span></samp>’<dd>Arabic. +<br><dt>‘<samp><span class="samp">as</span></samp>’<dd>Assamese. +<br><dt>‘<samp><span class="samp">av</span></samp>’<dd>Avaric. +<br><dt>‘<samp><span class="samp">ay</span></samp>’<dd>Aymara. +<br><dt>‘<samp><span class="samp">az</span></samp>’<dd>Azerbaijani. +<br><dt>‘<samp><span class="samp">ba</span></samp>’<dd>Bashkir. +<br><dt>‘<samp><span class="samp">be</span></samp>’<dd>Belarusian. +<br><dt>‘<samp><span class="samp">bg</span></samp>’<dd>Bulgarian. +<br><dt>‘<samp><span class="samp">bh</span></samp>’<dd>Bihari. +<br><dt>‘<samp><span class="samp">bi</span></samp>’<dd>Bislama. +<br><dt>‘<samp><span class="samp">bm</span></samp>’<dd>Bambara. +<br><dt>‘<samp><span class="samp">bn</span></samp>’<dd>Bengali; Bangla. +<br><dt>‘<samp><span class="samp">bo</span></samp>’<dd>Tibetan. +<br><dt>‘<samp><span class="samp">br</span></samp>’<dd>Breton. +<br><dt>‘<samp><span class="samp">bs</span></samp>’<dd>Bosnian. +<br><dt>‘<samp><span class="samp">ca</span></samp>’<dd>Catalan. +<br><dt>‘<samp><span class="samp">ce</span></samp>’<dd>Chechen. +<br><dt>‘<samp><span class="samp">ch</span></samp>’<dd>Chamorro. +<br><dt>‘<samp><span class="samp">co</span></samp>’<dd>Corsican. +<br><dt>‘<samp><span class="samp">cr</span></samp>’<dd>Cree. +<br><dt>‘<samp><span class="samp">cs</span></samp>’<dd>Czech. +<br><dt>‘<samp><span class="samp">cu</span></samp>’<dd>Church Slavic. +<br><dt>‘<samp><span class="samp">cv</span></samp>’<dd>Chuvash. +<br><dt>‘<samp><span class="samp">cy</span></samp>’<dd>Welsh. +<br><dt>‘<samp><span class="samp">da</span></samp>’<dd>Danish. +<br><dt>‘<samp><span class="samp">de</span></samp>’<dd>German. +<br><dt>‘<samp><span class="samp">dv</span></samp>’<dd>Divehi; Maldivian. +<br><dt>‘<samp><span class="samp">dz</span></samp>’<dd>Dzongkha; Bhutani. +<br><dt>‘<samp><span class="samp">ee</span></samp>’<dd>Éwé. +<br><dt>‘<samp><span class="samp">el</span></samp>’<dd>Greek. +<br><dt>‘<samp><span class="samp">en</span></samp>’<dd>English. +<br><dt>‘<samp><span class="samp">eo</span></samp>’<dd>Esperanto. +<br><dt>‘<samp><span class="samp">es</span></samp>’<dd>Spanish. +<br><dt>‘<samp><span class="samp">et</span></samp>’<dd>Estonian. +<br><dt>‘<samp><span class="samp">eu</span></samp>’<dd>Basque. +<br><dt>‘<samp><span class="samp">fa</span></samp>’<dd>Persian. +<br><dt>‘<samp><span class="samp">ff</span></samp>’<dd>Fulah. +<br><dt>‘<samp><span class="samp">fi</span></samp>’<dd>Finnish. +<br><dt>‘<samp><span class="samp">fj</span></samp>’<dd>Fijian; Fiji. +<br><dt>‘<samp><span class="samp">fo</span></samp>’<dd>Faroese. +<br><dt>‘<samp><span class="samp">fr</span></samp>’<dd>French. +<br><dt>‘<samp><span class="samp">fy</span></samp>’<dd>Western Frisian. +<br><dt>‘<samp><span class="samp">ga</span></samp>’<dd>Irish. +<br><dt>‘<samp><span class="samp">gd</span></samp>’<dd>Scottish Gaelic. +<br><dt>‘<samp><span class="samp">gl</span></samp>’<dd>Galician. +<br><dt>‘<samp><span class="samp">gn</span></samp>’<dd>Guarani. +<br><dt>‘<samp><span class="samp">gu</span></samp>’<dd>Gujarati. +<br><dt>‘<samp><span class="samp">gv</span></samp>’<dd>Manx. +<br><dt>‘<samp><span class="samp">ha</span></samp>’<dd>Hausa. +<br><dt>‘<samp><span class="samp">he</span></samp>’<dd>Hebrew (formerly iw). +<br><dt>‘<samp><span class="samp">hi</span></samp>’<dd>Hindi. +<br><dt>‘<samp><span class="samp">ho</span></samp>’<dd>Hiri Motu. +<br><dt>‘<samp><span class="samp">hr</span></samp>’<dd>Croatian. +<br><dt>‘<samp><span class="samp">ht</span></samp>’<dd>Haitian; Haitian Creole. +<br><dt>‘<samp><span class="samp">hu</span></samp>’<dd>Hungarian. +<br><dt>‘<samp><span class="samp">hy</span></samp>’<dd>Armenian. +<br><dt>‘<samp><span class="samp">hz</span></samp>’<dd>Herero. +<br><dt>‘<samp><span class="samp">ia</span></samp>’<dd>Interlingua. +<br><dt>‘<samp><span class="samp">id</span></samp>’<dd>Indonesian (formerly in). +<br><dt>‘<samp><span class="samp">ie</span></samp>’<dd>Interlingue; Occidental. +<br><dt>‘<samp><span class="samp">ig</span></samp>’<dd>Igbo. +<br><dt>‘<samp><span class="samp">ii</span></samp>’<dd>Sichuan Yi; Nuosu. +<br><dt>‘<samp><span class="samp">ik</span></samp>’<dd>Inupiak; Inupiaq. +<br><dt>‘<samp><span class="samp">io</span></samp>’<dd>Ido. +<br><dt>‘<samp><span class="samp">is</span></samp>’<dd>Icelandic. +<br><dt>‘<samp><span class="samp">it</span></samp>’<dd>Italian. +<br><dt>‘<samp><span class="samp">iu</span></samp>’<dd>Inuktitut. +<br><dt>‘<samp><span class="samp">ja</span></samp>’<dd>Japanese. +<br><dt>‘<samp><span class="samp">jv</span></samp>’<dd>Javanese. +<br><dt>‘<samp><span class="samp">ka</span></samp>’<dd>Georgian. +<br><dt>‘<samp><span class="samp">kg</span></samp>’<dd>Kongo. +<br><dt>‘<samp><span class="samp">ki</span></samp>’<dd>Kikuyu; Gikuyu. +<br><dt>‘<samp><span class="samp">kj</span></samp>’<dd>Kuanyama; Kwanyama. +<br><dt>‘<samp><span class="samp">kk</span></samp>’<dd>Kazakh. +<br><dt>‘<samp><span class="samp">kl</span></samp>’<dd>Kalaallisut; Greenlandic. +<br><dt>‘<samp><span class="samp">km</span></samp>’<dd>Central Khmer; Cambodian. +<br><dt>‘<samp><span class="samp">kn</span></samp>’<dd>Kannada. +<br><dt>‘<samp><span class="samp">ko</span></samp>’<dd>Korean. +<br><dt>‘<samp><span class="samp">kr</span></samp>’<dd>Kanuri. +<br><dt>‘<samp><span class="samp">ks</span></samp>’<dd>Kashmiri. +<br><dt>‘<samp><span class="samp">ku</span></samp>’<dd>Kurdish. +<br><dt>‘<samp><span class="samp">kv</span></samp>’<dd>Komi. +<br><dt>‘<samp><span class="samp">kw</span></samp>’<dd>Cornish. +<br><dt>‘<samp><span class="samp">ky</span></samp>’<dd>Kirghiz. +<br><dt>‘<samp><span class="samp">la</span></samp>’<dd>Latin. +<br><dt>‘<samp><span class="samp">lb</span></samp>’<dd>Letzeburgesch; Luxembourgish. +<br><dt>‘<samp><span class="samp">lg</span></samp>’<dd>Ganda. +<br><dt>‘<samp><span class="samp">li</span></samp>’<dd>Limburgish; Limburger; Limburgan. +<br><dt>‘<samp><span class="samp">ln</span></samp>’<dd>Lingala. +<br><dt>‘<samp><span class="samp">lo</span></samp>’<dd>Lao; Laotian. +<br><dt>‘<samp><span class="samp">lt</span></samp>’<dd>Lithuanian. +<br><dt>‘<samp><span class="samp">lu</span></samp>’<dd>Luba-Katanga. +<br><dt>‘<samp><span class="samp">lv</span></samp>’<dd>Latvian; Lettish. +<br><dt>‘<samp><span class="samp">mg</span></samp>’<dd>Malagasy. +<br><dt>‘<samp><span class="samp">mh</span></samp>’<dd>Marshallese. +<br><dt>‘<samp><span class="samp">mi</span></samp>’<dd>Maori. +<br><dt>‘<samp><span class="samp">mk</span></samp>’<dd>Macedonian. +<br><dt>‘<samp><span class="samp">ml</span></samp>’<dd>Malayalam. +<br><dt>‘<samp><span class="samp">mn</span></samp>’<dd>Mongolian. +<br><dt>‘<samp><span class="samp">mo</span></samp>’<dd>Moldavian. +<br><dt>‘<samp><span class="samp">mr</span></samp>’<dd>Marathi. +<br><dt>‘<samp><span class="samp">ms</span></samp>’<dd>Malay. +<br><dt>‘<samp><span class="samp">mt</span></samp>’<dd>Maltese. +<br><dt>‘<samp><span class="samp">my</span></samp>’<dd>Burmese. +<br><dt>‘<samp><span class="samp">na</span></samp>’<dd>Nauru. +<br><dt>‘<samp><span class="samp">nb</span></samp>’<dd>Norwegian Bokmål. +<br><dt>‘<samp><span class="samp">nd</span></samp>’<dd>Ndebele, North. +<br><dt>‘<samp><span class="samp">ne</span></samp>’<dd>Nepali. +<br><dt>‘<samp><span class="samp">ng</span></samp>’<dd>Ndonga. +<br><dt>‘<samp><span class="samp">nl</span></samp>’<dd>Dutch. +<br><dt>‘<samp><span class="samp">nn</span></samp>’<dd>Norwegian Nynorsk. +<br><dt>‘<samp><span class="samp">no</span></samp>’<dd>Norwegian. +<br><dt>‘<samp><span class="samp">nr</span></samp>’<dd>Ndebele, South. +<br><dt>‘<samp><span class="samp">nv</span></samp>’<dd>Navajo; Navaho. +<br><dt>‘<samp><span class="samp">ny</span></samp>’<dd>Chichewa; Nyanja. +<br><dt>‘<samp><span class="samp">oc</span></samp>’<dd>Occitan; Provençal. +<br><dt>‘<samp><span class="samp">oj</span></samp>’<dd>Ojibwa. +<br><dt>‘<samp><span class="samp">om</span></samp>’<dd>(Afan) Oromo. +<br><dt>‘<samp><span class="samp">or</span></samp>’<dd>Oriya. +<br><dt>‘<samp><span class="samp">os</span></samp>’<dd>Ossetian; Ossetic. +<br><dt>‘<samp><span class="samp">pa</span></samp>’<dd>Panjabi; Punjabi. +<br><dt>‘<samp><span class="samp">pi</span></samp>’<dd>Pali. +<br><dt>‘<samp><span class="samp">pl</span></samp>’<dd>Polish. +<br><dt>‘<samp><span class="samp">ps</span></samp>’<dd>Pashto; Pushto. +<br><dt>‘<samp><span class="samp">pt</span></samp>’<dd>Portuguese. +<br><dt>‘<samp><span class="samp">qu</span></samp>’<dd>Quechua. +<br><dt>‘<samp><span class="samp">rm</span></samp>’<dd>Romansh. +<br><dt>‘<samp><span class="samp">rn</span></samp>’<dd>Rundi; Kirundi. +<br><dt>‘<samp><span class="samp">ro</span></samp>’<dd>Romanian. +<br><dt>‘<samp><span class="samp">ru</span></samp>’<dd>Russian. +<br><dt>‘<samp><span class="samp">rw</span></samp>’<dd>Kinyarwanda. +<br><dt>‘<samp><span class="samp">sa</span></samp>’<dd>Sanskrit. +<br><dt>‘<samp><span class="samp">sc</span></samp>’<dd>Sardinian. +<br><dt>‘<samp><span class="samp">sd</span></samp>’<dd>Sindhi. +<br><dt>‘<samp><span class="samp">se</span></samp>’<dd>Northern Sami. +<br><dt>‘<samp><span class="samp">sg</span></samp>’<dd>Sango; Sangro. +<br><dt>‘<samp><span class="samp">si</span></samp>’<dd>Sinhala; Sinhalese. +<br><dt>‘<samp><span class="samp">sk</span></samp>’<dd>Slovak. +<br><dt>‘<samp><span class="samp">sl</span></samp>’<dd>Slovenian. +<br><dt>‘<samp><span class="samp">sm</span></samp>’<dd>Samoan. +<br><dt>‘<samp><span class="samp">sn</span></samp>’<dd>Shona. +<br><dt>‘<samp><span class="samp">so</span></samp>’<dd>Somali. +<br><dt>‘<samp><span class="samp">sq</span></samp>’<dd>Albanian. +<br><dt>‘<samp><span class="samp">sr</span></samp>’<dd>Serbian. +<br><dt>‘<samp><span class="samp">ss</span></samp>’<dd>Swati; Siswati. +<br><dt>‘<samp><span class="samp">st</span></samp>’<dd>Sesotho; Sotho, Southern. +<br><dt>‘<samp><span class="samp">su</span></samp>’<dd>Sundanese. +<br><dt>‘<samp><span class="samp">sv</span></samp>’<dd>Swedish. +<br><dt>‘<samp><span class="samp">sw</span></samp>’<dd>Swahili. +<br><dt>‘<samp><span class="samp">ta</span></samp>’<dd>Tamil. +<br><dt>‘<samp><span class="samp">te</span></samp>’<dd>Telugu. +<br><dt>‘<samp><span class="samp">tg</span></samp>’<dd>Tajik. +<br><dt>‘<samp><span class="samp">th</span></samp>’<dd>Thai. +<br><dt>‘<samp><span class="samp">ti</span></samp>’<dd>Tigrinya. +<br><dt>‘<samp><span class="samp">tk</span></samp>’<dd>Turkmen. +<br><dt>‘<samp><span class="samp">tl</span></samp>’<dd>Tagalog. +<br><dt>‘<samp><span class="samp">tn</span></samp>’<dd>Tswana; Setswana. +<br><dt>‘<samp><span class="samp">to</span></samp>’<dd>Tonga. +<br><dt>‘<samp><span class="samp">tr</span></samp>’<dd>Turkish. +<br><dt>‘<samp><span class="samp">ts</span></samp>’<dd>Tsonga. +<br><dt>‘<samp><span class="samp">tt</span></samp>’<dd>Tatar. +<br><dt>‘<samp><span class="samp">tw</span></samp>’<dd>Twi. +<br><dt>‘<samp><span class="samp">ty</span></samp>’<dd>Tahitian. +<br><dt>‘<samp><span class="samp">ug</span></samp>’<dd>Uighur. +<br><dt>‘<samp><span class="samp">uk</span></samp>’<dd>Ukrainian. +<br><dt>‘<samp><span class="samp">ur</span></samp>’<dd>Urdu. +<br><dt>‘<samp><span class="samp">uz</span></samp>’<dd>Uzbek. +<br><dt>‘<samp><span class="samp">ve</span></samp>’<dd>Venda. +<br><dt>‘<samp><span class="samp">vi</span></samp>’<dd>Vietnamese. +<br><dt>‘<samp><span class="samp">vo</span></samp>’<dd>Volapük; Volapuk. +<br><dt>‘<samp><span class="samp">wa</span></samp>’<dd>Walloon. +<br><dt>‘<samp><span class="samp">wo</span></samp>’<dd>Wolof. +<br><dt>‘<samp><span class="samp">xh</span></samp>’<dd>Xhosa. +<br><dt>‘<samp><span class="samp">yi</span></samp>’<dd>Yiddish (formerly ji). +<br><dt>‘<samp><span class="samp">yo</span></samp>’<dd>Yoruba. +<br><dt>‘<samp><span class="samp">za</span></samp>’<dd>Zhuang. +<br><dt>‘<samp><span class="samp">zh</span></samp>’<dd>Chinese. +<br><dt>‘<samp><span class="samp">zu</span></samp>’<dd>Zulu. +</dl> + +<div class="node"> +<a name="Rare-Language-Codes"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Usual-Language-Codes">Usual Language Codes</a>, +Up: <a rel="up" accesskey="u" href="#Language-Codes">Language Codes</a> + +</div> + +<h3 class="appendixsec">A.2 Rare Language Codes</h3> + + <p>For rarely used languages, the ISO 639-2<!-- /@w --> standard defines three-letter +codes. Here is the current list, reduced to only living languages with at least +one million of speakers. + + <dl> +<dt>‘<samp><span class="samp">ace</span></samp>’<dd>Achinese. +<br><dt>‘<samp><span class="samp">awa</span></samp>’<dd>Awadhi. +<br><dt>‘<samp><span class="samp">bal</span></samp>’<dd>Baluchi. +<br><dt>‘<samp><span class="samp">ban</span></samp>’<dd>Balinese. +<br><dt>‘<samp><span class="samp">bej</span></samp>’<dd>Beja; Bedawiyet. +<br><dt>‘<samp><span class="samp">bem</span></samp>’<dd>Bemba. +<br><dt>‘<samp><span class="samp">bho</span></samp>’<dd>Bhojpuri. +<br><dt>‘<samp><span class="samp">bik</span></samp>’<dd>Bikol. +<br><dt>‘<samp><span class="samp">bin</span></samp>’<dd>Bini; Edo. +<br><dt>‘<samp><span class="samp">bug</span></samp>’<dd>Buginese. +<br><dt>‘<samp><span class="samp">ceb</span></samp>’<dd>Cebuano. +<br><dt>‘<samp><span class="samp">din</span></samp>’<dd>Dinka. +<br><dt>‘<samp><span class="samp">doi</span></samp>’<dd>Dogri. +<br><dt>‘<samp><span class="samp">fil</span></samp>’<dd>Filipino; Pilipino. +<br><dt>‘<samp><span class="samp">fon</span></samp>’<dd>Fon. +<br><dt>‘<samp><span class="samp">gon</span></samp>’<dd>Gondi. +<br><dt>‘<samp><span class="samp">gsw</span></samp>’<dd>Swiss German; Alemannic; Alsatian. +<br><dt>‘<samp><span class="samp">hil</span></samp>’<dd>Hiligaynon. +<br><dt>‘<samp><span class="samp">hmn</span></samp>’<dd>Hmong. +<br><dt>‘<samp><span class="samp">ilo</span></samp>’<dd>Iloko. +<br><dt>‘<samp><span class="samp">kab</span></samp>’<dd>Kabyle. +<br><dt>‘<samp><span class="samp">kam</span></samp>’<dd>Kamba. +<br><dt>‘<samp><span class="samp">kbd</span></samp>’<dd>Kabardian. +<br><dt>‘<samp><span class="samp">kmb</span></samp>’<dd>Kimbundu. +<br><dt>‘<samp><span class="samp">kok</span></samp>’<dd>Konkani. +<br><dt>‘<samp><span class="samp">kru</span></samp>’<dd>Kurukh. +<br><dt>‘<samp><span class="samp">lua</span></samp>’<dd>Luba-Lulua. +<br><dt>‘<samp><span class="samp">luo</span></samp>’<dd>Luo (Kenya and Tanzania). +<br><dt>‘<samp><span class="samp">mad</span></samp>’<dd>Madurese. +<br><dt>‘<samp><span class="samp">mag</span></samp>’<dd>Magahi. +<br><dt>‘<samp><span class="samp">mai</span></samp>’<dd>Maithili. +<br><dt>‘<samp><span class="samp">mak</span></samp>’<dd>Makasar. +<br><dt>‘<samp><span class="samp">man</span></samp>’<dd>Mandingo. +<br><dt>‘<samp><span class="samp">men</span></samp>’<dd>Mende. +<br><dt>‘<samp><span class="samp">min</span></samp>’<dd>Minangkabau. +<br><dt>‘<samp><span class="samp">mni</span></samp>’<dd>Manipuri. +<br><dt>‘<samp><span class="samp">mos</span></samp>’<dd>Mossi. +<br><dt>‘<samp><span class="samp">mwr</span></samp>’<dd>Marwari. +<br><dt>‘<samp><span class="samp">nap</span></samp>’<dd>Neapolitan. +<br><dt>‘<samp><span class="samp">nso</span></samp>’<dd>Pedi; Sepedi; Northern Sotho. +<br><dt>‘<samp><span class="samp">nym</span></samp>’<dd>Nyamwezi. +<br><dt>‘<samp><span class="samp">nyn</span></samp>’<dd>Nyankole. +<br><dt>‘<samp><span class="samp">pag</span></samp>’<dd>Pangasinan. +<br><dt>‘<samp><span class="samp">pam</span></samp>’<dd>Pampanga; Kapampangan. +<br><dt>‘<samp><span class="samp">raj</span></samp>’<dd>Rajasthani. +<br><dt>‘<samp><span class="samp">sas</span></samp>’<dd>Sasak. +<br><dt>‘<samp><span class="samp">sat</span></samp>’<dd>Santali. +<br><dt>‘<samp><span class="samp">scn</span></samp>’<dd>Sicilian. +<br><dt>‘<samp><span class="samp">shn</span></samp>’<dd>Shan. +<br><dt>‘<samp><span class="samp">sid</span></samp>’<dd>Sidamo. +<br><dt>‘<samp><span class="samp">srr</span></samp>’<dd>Serer. +<br><dt>‘<samp><span class="samp">suk</span></samp>’<dd>Sukuma. +<br><dt>‘<samp><span class="samp">sus</span></samp>’<dd>Susu. +<br><dt>‘<samp><span class="samp">tem</span></samp>’<dd>Timne. +<br><dt>‘<samp><span class="samp">tiv</span></samp>’<dd>Tiv. +<br><dt>‘<samp><span class="samp">tum</span></samp>’<dd>Tumbuka. +<br><dt>‘<samp><span class="samp">umb</span></samp>’<dd>Umbundu. +<br><dt>‘<samp><span class="samp">wal</span></samp>’<dd>Walamo. +<br><dt>‘<samp><span class="samp">war</span></samp>’<dd>Waray. +<br><dt>‘<samp><span class="samp">yao</span></samp>’<dd>Yao. +</dl> + +<div class="node"> +<a name="Country-Codes"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Licenses">Licenses</a>, +Previous: <a rel="previous" accesskey="p" href="#Language-Codes">Language Codes</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="appendix">Appendix B Country Codes</h2> + + <p><a name="index-country-codes-1263"></a><a name="index-ISO-3166-1264"></a> +The ISO 3166<!-- /@w --> standard defines two character codes for many countries +and territories. All abbreviations for countries used in the Translation +Project should come from this standard. + + <dl> +<dt>‘<samp><span class="samp">AD</span></samp>’<dd>Andorra. +<br><dt>‘<samp><span class="samp">AE</span></samp>’<dd>United Arab Emirates. +<br><dt>‘<samp><span class="samp">AF</span></samp>’<dd>Afghanistan. +<br><dt>‘<samp><span class="samp">AG</span></samp>’<dd>Antigua and Barbuda. +<br><dt>‘<samp><span class="samp">AI</span></samp>’<dd>Anguilla. +<br><dt>‘<samp><span class="samp">AL</span></samp>’<dd>Albania. +<br><dt>‘<samp><span class="samp">AM</span></samp>’<dd>Armenia. +<br><dt>‘<samp><span class="samp">AN</span></samp>’<dd>Netherlands Antilles. +<br><dt>‘<samp><span class="samp">AO</span></samp>’<dd>Angola. +<br><dt>‘<samp><span class="samp">AQ</span></samp>’<dd>Antarctica. +<br><dt>‘<samp><span class="samp">AR</span></samp>’<dd>Argentina. +<br><dt>‘<samp><span class="samp">AS</span></samp>’<dd>Samoa (American). +<br><dt>‘<samp><span class="samp">AT</span></samp>’<dd>Austria. +<br><dt>‘<samp><span class="samp">AU</span></samp>’<dd>Australia. +<br><dt>‘<samp><span class="samp">AW</span></samp>’<dd>Aruba. +<br><dt>‘<samp><span class="samp">AX</span></samp>’<dd>Aaland Islands. +<br><dt>‘<samp><span class="samp">AZ</span></samp>’<dd>Azerbaijan. +<br><dt>‘<samp><span class="samp">BA</span></samp>’<dd>Bosnia and Herzegovina. +<br><dt>‘<samp><span class="samp">BB</span></samp>’<dd>Barbados. +<br><dt>‘<samp><span class="samp">BD</span></samp>’<dd>Bangladesh. +<br><dt>‘<samp><span class="samp">BE</span></samp>’<dd>Belgium. +<br><dt>‘<samp><span class="samp">BF</span></samp>’<dd>Burkina Faso. +<br><dt>‘<samp><span class="samp">BG</span></samp>’<dd>Bulgaria. +<br><dt>‘<samp><span class="samp">BH</span></samp>’<dd>Bahrain. +<br><dt>‘<samp><span class="samp">BI</span></samp>’<dd>Burundi. +<br><dt>‘<samp><span class="samp">BJ</span></samp>’<dd>Benin. +<br><dt>‘<samp><span class="samp">BM</span></samp>’<dd>Bermuda. +<br><dt>‘<samp><span class="samp">BN</span></samp>’<dd>Brunei. +<br><dt>‘<samp><span class="samp">BO</span></samp>’<dd>Bolivia. +<br><dt>‘<samp><span class="samp">BR</span></samp>’<dd>Brazil. +<br><dt>‘<samp><span class="samp">BS</span></samp>’<dd>Bahamas. +<br><dt>‘<samp><span class="samp">BT</span></samp>’<dd>Bhutan. +<br><dt>‘<samp><span class="samp">BV</span></samp>’<dd>Bouvet Island. +<br><dt>‘<samp><span class="samp">BW</span></samp>’<dd>Botswana. +<br><dt>‘<samp><span class="samp">BY</span></samp>’<dd>Belarus. +<br><dt>‘<samp><span class="samp">BZ</span></samp>’<dd>Belize. +<br><dt>‘<samp><span class="samp">CA</span></samp>’<dd>Canada. +<br><dt>‘<samp><span class="samp">CC</span></samp>’<dd>Cocos (Keeling) Islands. +<br><dt>‘<samp><span class="samp">CD</span></samp>’<dd>Congo (Dem. Rep.). +<br><dt>‘<samp><span class="samp">CF</span></samp>’<dd>Central African Republic. +<br><dt>‘<samp><span class="samp">CG</span></samp>’<dd>Congo (Rep.). +<br><dt>‘<samp><span class="samp">CH</span></samp>’<dd>Switzerland. +<br><dt>‘<samp><span class="samp">CI</span></samp>’<dd>Côte d'Ivoire. +<br><dt>‘<samp><span class="samp">CK</span></samp>’<dd>Cook Islands. +<br><dt>‘<samp><span class="samp">CL</span></samp>’<dd>Chile. +<br><dt>‘<samp><span class="samp">CM</span></samp>’<dd>Cameroon. +<br><dt>‘<samp><span class="samp">CN</span></samp>’<dd>China. +<br><dt>‘<samp><span class="samp">CO</span></samp>’<dd>Colombia. +<br><dt>‘<samp><span class="samp">CR</span></samp>’<dd>Costa Rica. +<br><dt>‘<samp><span class="samp">CU</span></samp>’<dd>Cuba. +<br><dt>‘<samp><span class="samp">CV</span></samp>’<dd>Cape Verde. +<br><dt>‘<samp><span class="samp">CX</span></samp>’<dd>Christmas Island. +<br><dt>‘<samp><span class="samp">CY</span></samp>’<dd>Cyprus. +<br><dt>‘<samp><span class="samp">CZ</span></samp>’<dd>Czech Republic. +<br><dt>‘<samp><span class="samp">DE</span></samp>’<dd>Germany. +<br><dt>‘<samp><span class="samp">DJ</span></samp>’<dd>Djibouti. +<br><dt>‘<samp><span class="samp">DK</span></samp>’<dd>Denmark. +<br><dt>‘<samp><span class="samp">DM</span></samp>’<dd>Dominica. +<br><dt>‘<samp><span class="samp">DO</span></samp>’<dd>Dominican Republic. +<br><dt>‘<samp><span class="samp">DZ</span></samp>’<dd>Algeria. +<br><dt>‘<samp><span class="samp">EC</span></samp>’<dd>Ecuador. +<br><dt>‘<samp><span class="samp">EE</span></samp>’<dd>Estonia. +<br><dt>‘<samp><span class="samp">EG</span></samp>’<dd>Egypt. +<br><dt>‘<samp><span class="samp">EH</span></samp>’<dd>Western Sahara. +<br><dt>‘<samp><span class="samp">ER</span></samp>’<dd>Eritrea. +<br><dt>‘<samp><span class="samp">ES</span></samp>’<dd>Spain. +<br><dt>‘<samp><span class="samp">ET</span></samp>’<dd>Ethiopia. +<br><dt>‘<samp><span class="samp">FI</span></samp>’<dd>Finland. +<br><dt>‘<samp><span class="samp">FJ</span></samp>’<dd>Fiji. +<br><dt>‘<samp><span class="samp">FK</span></samp>’<dd>Falkland Islands. +<br><dt>‘<samp><span class="samp">FM</span></samp>’<dd>Micronesia. +<br><dt>‘<samp><span class="samp">FO</span></samp>’<dd>Faeroe Islands. +<br><dt>‘<samp><span class="samp">FR</span></samp>’<dd>France. +<br><dt>‘<samp><span class="samp">GA</span></samp>’<dd>Gabon. +<br><dt>‘<samp><span class="samp">GB</span></samp>’<dd>Britain (United Kingdom). +<br><dt>‘<samp><span class="samp">GD</span></samp>’<dd>Grenada. +<br><dt>‘<samp><span class="samp">GE</span></samp>’<dd>Georgia. +<br><dt>‘<samp><span class="samp">GF</span></samp>’<dd>French Guiana. +<br><dt>‘<samp><span class="samp">GG</span></samp>’<dd>Guernsey. +<br><dt>‘<samp><span class="samp">GH</span></samp>’<dd>Ghana. +<br><dt>‘<samp><span class="samp">GI</span></samp>’<dd>Gibraltar. +<br><dt>‘<samp><span class="samp">GL</span></samp>’<dd>Greenland. +<br><dt>‘<samp><span class="samp">GM</span></samp>’<dd>Gambia. +<br><dt>‘<samp><span class="samp">GN</span></samp>’<dd>Guinea. +<br><dt>‘<samp><span class="samp">GP</span></samp>’<dd>Guadeloupe. +<br><dt>‘<samp><span class="samp">GQ</span></samp>’<dd>Equatorial Guinea. +<br><dt>‘<samp><span class="samp">GR</span></samp>’<dd>Greece. +<br><dt>‘<samp><span class="samp">GS</span></samp>’<dd>South Georgia and the South Sandwich Islands. +<br><dt>‘<samp><span class="samp">GT</span></samp>’<dd>Guatemala. +<br><dt>‘<samp><span class="samp">GU</span></samp>’<dd>Guam. +<br><dt>‘<samp><span class="samp">GW</span></samp>’<dd>Guinea-Bissau. +<br><dt>‘<samp><span class="samp">GY</span></samp>’<dd>Guyana. +<br><dt>‘<samp><span class="samp">HK</span></samp>’<dd>Hong Kong. +<br><dt>‘<samp><span class="samp">HM</span></samp>’<dd>Heard Island and McDonald Islands. +<br><dt>‘<samp><span class="samp">HN</span></samp>’<dd>Honduras. +<br><dt>‘<samp><span class="samp">HR</span></samp>’<dd>Croatia. +<br><dt>‘<samp><span class="samp">HT</span></samp>’<dd>Haiti. +<br><dt>‘<samp><span class="samp">HU</span></samp>’<dd>Hungary. +<br><dt>‘<samp><span class="samp">ID</span></samp>’<dd>Indonesia. +<br><dt>‘<samp><span class="samp">IE</span></samp>’<dd>Ireland. +<br><dt>‘<samp><span class="samp">IL</span></samp>’<dd>Israel. +<br><dt>‘<samp><span class="samp">IM</span></samp>’<dd>Isle of Man. +<br><dt>‘<samp><span class="samp">IN</span></samp>’<dd>India. +<br><dt>‘<samp><span class="samp">IO</span></samp>’<dd>British Indian Ocean Territory. +<br><dt>‘<samp><span class="samp">IQ</span></samp>’<dd>Iraq. +<br><dt>‘<samp><span class="samp">IR</span></samp>’<dd>Iran. +<br><dt>‘<samp><span class="samp">IS</span></samp>’<dd>Iceland. +<br><dt>‘<samp><span class="samp">IT</span></samp>’<dd>Italy. +<br><dt>‘<samp><span class="samp">JE</span></samp>’<dd>Jersey. +<br><dt>‘<samp><span class="samp">JM</span></samp>’<dd>Jamaica. +<br><dt>‘<samp><span class="samp">JO</span></samp>’<dd>Jordan. +<br><dt>‘<samp><span class="samp">JP</span></samp>’<dd>Japan. +<br><dt>‘<samp><span class="samp">KE</span></samp>’<dd>Kenya. +<br><dt>‘<samp><span class="samp">KG</span></samp>’<dd>Kyrgyzstan. +<br><dt>‘<samp><span class="samp">KH</span></samp>’<dd>Cambodia. +<br><dt>‘<samp><span class="samp">KI</span></samp>’<dd>Kiribati. +<br><dt>‘<samp><span class="samp">KM</span></samp>’<dd>Comoros. +<br><dt>‘<samp><span class="samp">KN</span></samp>’<dd>St Kitts and Nevis. +<br><dt>‘<samp><span class="samp">KP</span></samp>’<dd>Korea (North). +<br><dt>‘<samp><span class="samp">KR</span></samp>’<dd>Korea (South). +<br><dt>‘<samp><span class="samp">KW</span></samp>’<dd>Kuwait. +<br><dt>‘<samp><span class="samp">KY</span></samp>’<dd>Cayman Islands. +<br><dt>‘<samp><span class="samp">KZ</span></samp>’<dd>Kazakhstan. +<br><dt>‘<samp><span class="samp">LA</span></samp>’<dd>Laos. +<br><dt>‘<samp><span class="samp">LB</span></samp>’<dd>Lebanon. +<br><dt>‘<samp><span class="samp">LC</span></samp>’<dd>St Lucia. +<br><dt>‘<samp><span class="samp">LI</span></samp>’<dd>Liechtenstein. +<br><dt>‘<samp><span class="samp">LK</span></samp>’<dd>Sri Lanka. +<br><dt>‘<samp><span class="samp">LR</span></samp>’<dd>Liberia. +<br><dt>‘<samp><span class="samp">LS</span></samp>’<dd>Lesotho. +<br><dt>‘<samp><span class="samp">LT</span></samp>’<dd>Lithuania. +<br><dt>‘<samp><span class="samp">LU</span></samp>’<dd>Luxembourg. +<br><dt>‘<samp><span class="samp">LV</span></samp>’<dd>Latvia. +<br><dt>‘<samp><span class="samp">LY</span></samp>’<dd>Libya. +<br><dt>‘<samp><span class="samp">MA</span></samp>’<dd>Morocco. +<br><dt>‘<samp><span class="samp">MC</span></samp>’<dd>Monaco. +<br><dt>‘<samp><span class="samp">MD</span></samp>’<dd>Moldova. +<br><dt>‘<samp><span class="samp">ME</span></samp>’<dd>Montenegro. +<br><dt>‘<samp><span class="samp">MG</span></samp>’<dd>Madagascar. +<br><dt>‘<samp><span class="samp">MH</span></samp>’<dd>Marshall Islands. +<br><dt>‘<samp><span class="samp">MK</span></samp>’<dd>Macedonia. +<br><dt>‘<samp><span class="samp">ML</span></samp>’<dd>Mali. +<br><dt>‘<samp><span class="samp">MM</span></samp>’<dd>Myanmar (Burma). +<br><dt>‘<samp><span class="samp">MN</span></samp>’<dd>Mongolia. +<br><dt>‘<samp><span class="samp">MO</span></samp>’<dd>Macao. +<br><dt>‘<samp><span class="samp">MP</span></samp>’<dd>Northern Mariana Islands. +<br><dt>‘<samp><span class="samp">MQ</span></samp>’<dd>Martinique. +<br><dt>‘<samp><span class="samp">MR</span></samp>’<dd>Mauritania. +<br><dt>‘<samp><span class="samp">MS</span></samp>’<dd>Montserrat. +<br><dt>‘<samp><span class="samp">MT</span></samp>’<dd>Malta. +<br><dt>‘<samp><span class="samp">MU</span></samp>’<dd>Mauritius. +<br><dt>‘<samp><span class="samp">MV</span></samp>’<dd>Maldives. +<br><dt>‘<samp><span class="samp">MW</span></samp>’<dd>Malawi. +<br><dt>‘<samp><span class="samp">MX</span></samp>’<dd>Mexico. +<br><dt>‘<samp><span class="samp">MY</span></samp>’<dd>Malaysia. +<br><dt>‘<samp><span class="samp">MZ</span></samp>’<dd>Mozambique. +<br><dt>‘<samp><span class="samp">NA</span></samp>’<dd>Namibia. +<br><dt>‘<samp><span class="samp">NC</span></samp>’<dd>New Caledonia. +<br><dt>‘<samp><span class="samp">NE</span></samp>’<dd>Niger. +<br><dt>‘<samp><span class="samp">NF</span></samp>’<dd>Norfolk Island. +<br><dt>‘<samp><span class="samp">NG</span></samp>’<dd>Nigeria. +<br><dt>‘<samp><span class="samp">NI</span></samp>’<dd>Nicaragua. +<br><dt>‘<samp><span class="samp">NL</span></samp>’<dd>Netherlands. +<br><dt>‘<samp><span class="samp">NO</span></samp>’<dd>Norway. +<br><dt>‘<samp><span class="samp">NP</span></samp>’<dd>Nepal. +<br><dt>‘<samp><span class="samp">NR</span></samp>’<dd>Nauru. +<br><dt>‘<samp><span class="samp">NU</span></samp>’<dd>Niue. +<br><dt>‘<samp><span class="samp">NZ</span></samp>’<dd>New Zealand. +<br><dt>‘<samp><span class="samp">OM</span></samp>’<dd>Oman. +<br><dt>‘<samp><span class="samp">PA</span></samp>’<dd>Panama. +<br><dt>‘<samp><span class="samp">PE</span></samp>’<dd>Peru. +<br><dt>‘<samp><span class="samp">PF</span></samp>’<dd>French Polynesia. +<br><dt>‘<samp><span class="samp">PG</span></samp>’<dd>Papua New Guinea. +<br><dt>‘<samp><span class="samp">PH</span></samp>’<dd>Philippines. +<br><dt>‘<samp><span class="samp">PK</span></samp>’<dd>Pakistan. +<br><dt>‘<samp><span class="samp">PL</span></samp>’<dd>Poland. +<br><dt>‘<samp><span class="samp">PM</span></samp>’<dd>St Pierre and Miquelon. +<br><dt>‘<samp><span class="samp">PN</span></samp>’<dd>Pitcairn. +<br><dt>‘<samp><span class="samp">PR</span></samp>’<dd>Puerto Rico. +<br><dt>‘<samp><span class="samp">PS</span></samp>’<dd>Palestine. +<br><dt>‘<samp><span class="samp">PT</span></samp>’<dd>Portugal. +<br><dt>‘<samp><span class="samp">PW</span></samp>’<dd>Palau. +<br><dt>‘<samp><span class="samp">PY</span></samp>’<dd>Paraguay. +<br><dt>‘<samp><span class="samp">QA</span></samp>’<dd>Qatar. +<br><dt>‘<samp><span class="samp">RE</span></samp>’<dd>Reunion. +<br><dt>‘<samp><span class="samp">RO</span></samp>’<dd>Romania. +<br><dt>‘<samp><span class="samp">RS</span></samp>’<dd>Serbia. +<br><dt>‘<samp><span class="samp">RU</span></samp>’<dd>Russia. +<br><dt>‘<samp><span class="samp">RW</span></samp>’<dd>Rwanda. +<br><dt>‘<samp><span class="samp">SA</span></samp>’<dd>Saudi Arabia. +<br><dt>‘<samp><span class="samp">SB</span></samp>’<dd>Solomon Islands. +<br><dt>‘<samp><span class="samp">SC</span></samp>’<dd>Seychelles. +<br><dt>‘<samp><span class="samp">SD</span></samp>’<dd>Sudan. +<br><dt>‘<samp><span class="samp">SE</span></samp>’<dd>Sweden. +<br><dt>‘<samp><span class="samp">SG</span></samp>’<dd>Singapore. +<br><dt>‘<samp><span class="samp">SH</span></samp>’<dd>St Helena. +<br><dt>‘<samp><span class="samp">SI</span></samp>’<dd>Slovenia. +<br><dt>‘<samp><span class="samp">SJ</span></samp>’<dd>Svalbard and Jan Mayen. +<br><dt>‘<samp><span class="samp">SK</span></samp>’<dd>Slovakia. +<br><dt>‘<samp><span class="samp">SL</span></samp>’<dd>Sierra Leone. +<br><dt>‘<samp><span class="samp">SM</span></samp>’<dd>San Marino. +<br><dt>‘<samp><span class="samp">SN</span></samp>’<dd>Senegal. +<br><dt>‘<samp><span class="samp">SO</span></samp>’<dd>Somalia. +<br><dt>‘<samp><span class="samp">SR</span></samp>’<dd>Suriname. +<br><dt>‘<samp><span class="samp">ST</span></samp>’<dd>Sao Tome and Principe. +<br><dt>‘<samp><span class="samp">SV</span></samp>’<dd>El Salvador. +<br><dt>‘<samp><span class="samp">SY</span></samp>’<dd>Syria. +<br><dt>‘<samp><span class="samp">SZ</span></samp>’<dd>Swaziland. +<br><dt>‘<samp><span class="samp">TC</span></samp>’<dd>Turks and Caicos Islands. +<br><dt>‘<samp><span class="samp">TD</span></samp>’<dd>Chad. +<br><dt>‘<samp><span class="samp">TF</span></samp>’<dd>French Southern and Antarctic Lands. +<br><dt>‘<samp><span class="samp">TG</span></samp>’<dd>Togo. +<br><dt>‘<samp><span class="samp">TH</span></samp>’<dd>Thailand. +<br><dt>‘<samp><span class="samp">TJ</span></samp>’<dd>Tajikistan. +<br><dt>‘<samp><span class="samp">TK</span></samp>’<dd>Tokelau. +<br><dt>‘<samp><span class="samp">TL</span></samp>’<dd>Timor-Leste. +<br><dt>‘<samp><span class="samp">TM</span></samp>’<dd>Turkmenistan. +<br><dt>‘<samp><span class="samp">TN</span></samp>’<dd>Tunisia. +<br><dt>‘<samp><span class="samp">TO</span></samp>’<dd>Tonga. +<br><dt>‘<samp><span class="samp">TR</span></samp>’<dd>Turkey. +<br><dt>‘<samp><span class="samp">TT</span></samp>’<dd>Trinidad and Tobago. +<br><dt>‘<samp><span class="samp">TV</span></samp>’<dd>Tuvalu. +<br><dt>‘<samp><span class="samp">TW</span></samp>’<dd>Taiwan. +<br><dt>‘<samp><span class="samp">TZ</span></samp>’<dd>Tanzania. +<br><dt>‘<samp><span class="samp">UA</span></samp>’<dd>Ukraine. +<br><dt>‘<samp><span class="samp">UG</span></samp>’<dd>Uganda. +<br><dt>‘<samp><span class="samp">UM</span></samp>’<dd>US minor outlying islands. +<br><dt>‘<samp><span class="samp">US</span></samp>’<dd>United States. +<br><dt>‘<samp><span class="samp">UY</span></samp>’<dd>Uruguay. +<br><dt>‘<samp><span class="samp">UZ</span></samp>’<dd>Uzbekistan. +<br><dt>‘<samp><span class="samp">VA</span></samp>’<dd>Vatican City. +<br><dt>‘<samp><span class="samp">VC</span></samp>’<dd>St Vincent and the Grenadines. +<br><dt>‘<samp><span class="samp">VE</span></samp>’<dd>Venezuela. +<br><dt>‘<samp><span class="samp">VG</span></samp>’<dd>Virgin Islands (UK). +<br><dt>‘<samp><span class="samp">VI</span></samp>’<dd>Virgin Islands (US). +<br><dt>‘<samp><span class="samp">VN</span></samp>’<dd>Vietnam. +<br><dt>‘<samp><span class="samp">VU</span></samp>’<dd>Vanuatu. +<br><dt>‘<samp><span class="samp">WF</span></samp>’<dd>Wallis and Futuna. +<br><dt>‘<samp><span class="samp">WS</span></samp>’<dd>Samoa (Western). +<br><dt>‘<samp><span class="samp">YE</span></samp>’<dd>Yemen. +<br><dt>‘<samp><span class="samp">YT</span></samp>’<dd>Mayotte. +<br><dt>‘<samp><span class="samp">ZA</span></samp>’<dd>South Africa. +<br><dt>‘<samp><span class="samp">ZM</span></samp>’<dd>Zambia. +<br><dt>‘<samp><span class="samp">ZW</span></samp>’<dd>Zimbabwe. +</dl> + +<div class="node"> +<a name="Licenses"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Program-Index">Program Index</a>, +Previous: <a rel="previous" accesskey="p" href="#Country-Codes">Country Codes</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="appendix">Appendix C Licenses</h2> + + <p><a name="index-Licenses-1265"></a> +The files of this package are covered by the licenses indicated in each +particular file or directory. Here is a summary: + + <ul> +<li>The <code>libintl</code> and <code>libasprintf</code> libraries are covered by the +GNU Library General Public License (LGPL). +A copy of the license is included in <a href="#GNU-LGPL">GNU LGPL</a>. + + <li>The executable programs of this package and the <code>libgettextpo</code> library +are covered by the GNU General Public License (GPL). +A copy of the license is included in <a href="#GNU-GPL">GNU GPL</a>. + + <li>This manual is free documentation. It is dually licensed under the +GNU FDL and the GNU GPL. This means that you can redistribute this +manual under either of these two licenses, at your choice. +<br> +This manual is covered by the GNU FDL. Permission is granted to copy, +distribute and/or modify this document under the terms of the +GNU Free Documentation License (FDL), either version 1.2 of the +License, or (at your option) any later version published by the +Free Software Foundation (FSF); with no Invariant Sections, with no +Front-Cover Text, and with no Back-Cover Texts. +A copy of the license is included in <a href="#GNU-FDL">GNU FDL</a>. +<br> +This manual is covered by the GNU GPL. You can redistribute it and/or +modify it under the terms of the GNU General Public License (GPL), either +version 2 of the License, or (at your option) any later version published +by the Free Software Foundation (FSF). +A copy of the license is included in <a href="#GNU-GPL">GNU GPL</a>. +</ul> + +<ul class="menu"> +<li><a accesskey="1" href="#GNU-GPL">GNU GPL</a>: GNU General Public License +<li><a accesskey="2" href="#GNU-LGPL">GNU LGPL</a>: GNU Lesser General Public License +<li><a accesskey="3" href="#GNU-FDL">GNU FDL</a>: GNU Free Documentation License +</ul> + +<div class="node"> +<a name="GNU-GPL"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#GNU-LGPL">GNU LGPL</a>, +Up: <a rel="up" accesskey="u" href="#Licenses">Licenses</a> + +</div> + +<h3 class="appendixsec">C.1 GNU GENERAL PUBLIC LICENSE</h3> + + <p><a name="index-GPL_002c-GNU-General-Public-License-1266"></a><a name="index-License_002c-GNU-GPL-1267"></a><div align="center">Version 2, June 1991</div> + +<!-- This file is intended to be included in another file. --> +<pre class="display"> Copyright © 1989, 1991 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. +</pre> +<h4 class="unnumberedsubsec">Preamble</h4> + + <p>The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software—to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + <p>When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + <p>To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + <p>For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + <p>We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + <p>Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + <p>Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + <p>The precise terms and conditions for copying, distribution and +modification follow. + + <ol type=1 start=0> +<li>This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The “Program”, below, +refers to any such program or work, and a “work based on the Program” +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term “modification”.) Each licensee is addressed as “you”. + + <p>Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + <li>You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + + <p>You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + <li>You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + <ol type=a start=1> +<li>You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + + <li>You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + + <li>If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) + </ol> + + <p>These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + + <p>Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + + <p>In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + <li>You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + <ol type=a start=1> +<li>Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + + <li>Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + + <li>Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) + </ol> + + <p>The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + + <p>If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + <li>You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + <li>You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + <li>Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + <li>If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + + <p>If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + + <p>It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + + <p>This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + <li>If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + <li>The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + <p>Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and “any +later version”, you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + <li>If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + <li>BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + <li>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + </ol> + +<h4 class="unnumberedsubsec">Appendix: How to Apply These Terms to Your New Programs</h4> + + <p>If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + <p>To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the “copyright” line and a pointer to where the full notice is found. + +<pre class="smallexample"> <var>one line to give the program's name and a brief idea of what it does.</var> + Copyright (C) <var>yyyy</var> <var>name of author</var> + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +</pre> + <p>Also add information on how to contact you by electronic and paper mail. + + <p>If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +<pre class="smallexample"> Gnomovision version 69, Copyright (C) 19<var>yy</var> <var>name of author</var> + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. +</pre> + <p>The hypothetical commands ‘<samp><span class="samp">show w</span></samp>’ and ‘<samp><span class="samp">show c</span></samp>’ should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than ‘<samp><span class="samp">show w</span></samp>’ and +‘<samp><span class="samp">show c</span></samp>’; they could even be mouse-clicks or menu items—whatever +suits your program. + + <p>You should also get your employer (if you work as a programmer) or your +school, if any, to sign a “copyright disclaimer” for the program, if +necessary. Here is a sample; alter the names: + +<pre class="example"> Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + <var>signature of Ty Coon</var>, 1 April 1989 + Ty Coon, President of Vice +</pre> + <p>This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. + +<div class="node"> +<a name="GNU-LGPL"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#GNU-FDL">GNU FDL</a>, +Previous: <a rel="previous" accesskey="p" href="#GNU-GPL">GNU GPL</a>, +Up: <a rel="up" accesskey="u" href="#Licenses">Licenses</a> + +</div> + +<h3 class="appendixsec">C.2 GNU LESSER GENERAL PUBLIC LICENSE</h3> + + <p><a name="index-LGPL_002c-GNU-Lesser-General-Public-License-1268"></a><a name="index-License_002c-GNU-LGPL-1269"></a><div align="center">Version 2.1, February 1999</div> + +<pre class="display"> Copyright © 1991, 1999 Free Software Foundation, Inc. + 51 Franklin St – Fifth Floor, Boston, MA 02110-1301, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + [This is the first released version of the Lesser GPL. It also counts + as the successor of the GNU Library Public License, version 2, hence the + version number 2.1.] +</pre> +<h4 class="unnumberedsubsec">Preamble</h4> + + <p>The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +Licenses are intended to guarantee your freedom to share and change +free software—to make sure the software is free for all its users. + + <p>This license, the Lesser General Public License, applies to some +specially designated software—typically libraries—of the Free +Software Foundation and other authors who decide to use it. You can use +it too, but we suggest you first think carefully about whether this +license or the ordinary General Public License is the better strategy to +use in any particular case, based on the explanations below. + + <p>When we speak of free software, we are referring to freedom of use, +not price. Our General Public Licenses are designed to make sure that +you have the freedom to distribute copies of free software (and charge +for this service if you wish); that you receive source code or can get +it if you want it; that you can change the software and use pieces of it +in new free programs; and that you are informed that you can do these +things. + + <p>To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. + + <p>For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link other code with the library, you must provide +complete object files to the recipients, so that they can relink them +with the library after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + + <p>We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + + <p>To protect each distributor, we want to make it very clear that +there is no warranty for the free library. Also, if the library is +modified by someone else and passed on, the recipients should know +that what they have is not the original version, so that the original +author's reputation will not be affected by problems that might be +introduced by others. + + <p>Finally, software patents pose a constant threat to the existence of +any free program. We wish to make sure that a company cannot +effectively restrict the users of a free program by obtaining a +restrictive license from a patent holder. Therefore, we insist that +any patent license obtained for a version of the library must be +consistent with the full freedom of use specified in this license. + + <p>Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License. This license, the GNU Lesser +General Public License, applies to certain designated libraries, and +is quite different from the ordinary General Public License. We use +this license for certain libraries in order to permit linking those +libraries into non-free programs. + + <p>When a program is linked with a library, whether statically or using +a shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the +entire combination fits its criteria of freedom. The Lesser General +Public License permits more lax criteria for linking other code with +the library. + + <p>We call this license the <dfn>Lesser</dfn> General Public License because it +does <em>Less</em> to protect the user's freedom than the ordinary General +Public License. It also provides other free software developers Less +of an advantage over competing non-free programs. These disadvantages +are the reason we use the ordinary General Public License for many +libraries. However, the Lesser license provides advantages in certain +special circumstances. + + <p>For example, on rare occasions, there may be a special need to +encourage the widest possible use of a certain library, so that it becomes +a de-facto standard. To achieve this, non-free programs must be +allowed to use the library. A more frequent case is that a free +library does the same job as widely used non-free libraries. In this +case, there is little to gain by limiting the free library to free +software only, so we use the Lesser General Public License. + + <p>In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of +free software. For example, permission to use the GNU C Library in +non-free programs enables many more people to use the whole GNU +operating system, as well as its variant, the GNU/Linux operating +system. + + <p>Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is +linked with the Library has the freedom and the wherewithal to run +that program using a modified version of the Library. + + <p>The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +“work based on the library” and a “work that uses the library”. The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + + <ol type=1 start=0> +<li>This License Agreement applies to any software library or other program +which contains a notice placed by the copyright holder or other +authorized party saying it may be distributed under the terms of this +Lesser General Public License (also called “this License”). Each +licensee is addressed as “you”. + + <p>A “library” means a collection of software functions and/or data +prepared so as to be conveniently linked with application programs +(which use some of those functions and data) to form executables. + + <p>The “Library”, below, refers to any such software library or work +which has been distributed under these terms. A “work based on the +Library” means either the Library or any derivative work under +copyright law: that is to say, a work containing the Library or a +portion of it, either verbatim or with modifications and/or translated +straightforwardly into another language. (Hereinafter, translation is +included without limitation in the term “modification”.) + + <p>“Source code” for a work means the preferred form of the work for +making modifications to it. For a library, complete source code means +all the source code for all modules it contains, plus any associated +interface definition files, plus the scripts used to control compilation +and installation of the library. + + <p>Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running a program using the Library is not restricted, and output from +such a program is covered only if its contents constitute a work based +on the Library (independent of the use of the Library in a tool for +writing it). Whether that is true depends on what the Library does +and what the program that uses the Library does. + + <li>You may copy and distribute verbatim copies of the Library's +complete source code as you receive it, in any medium, provided that +you conspicuously and appropriately publish on each copy an +appropriate copyright notice and disclaimer of warranty; keep intact +all the notices that refer to this License and to the absence of any +warranty; and distribute a copy of this License along with the +Library. + + <p>You may charge a fee for the physical act of transferring a copy, +and you may at your option offer warranty protection in exchange for a +fee. + + <li>You may modify your copy or copies of the Library or any portion +of it, thus forming a work based on the Library, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + <ol type=a start=1> +<li>The modified work must itself be a software library. + + <li>You must cause the files modified to carry prominent notices +stating that you changed the files and the date of any change. + + <li>You must cause the whole of the work to be licensed at no +charge to all third parties under the terms of this License. + + <li>If a facility in the modified Library refers to a function or a +table of data to be supplied by an application program that uses +the facility, other than as an argument passed when the facility +is invoked, then you must make a good faith effort to ensure that, +in the event an application does not supply such function or +table, the facility still operates, and performs whatever part of +its purpose remains meaningful. + + <p>(For example, a function in a library to compute square roots has +a purpose that is entirely well-defined independent of the +application. Therefore, Subsection 2d requires that any +application-supplied function or table used by this function must +be optional: if the application does not supply it, the square +root function must still compute square roots.) + </ol> + + <p>These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Library, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Library, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote +it. + + <p>Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Library. + + <p>In addition, mere aggregation of another work not based on the Library +with the Library (or with a work based on the Library) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + <li>You may opt to apply the terms of the ordinary GNU General Public +License instead of this License to a given copy of the Library. To do +this, you must alter all the notices that refer to this License, so +that they refer to the ordinary GNU General Public License, version 2, +instead of to this License. (If a newer version than version 2 of the +ordinary GNU General Public License has appeared, then you can specify +that version instead if you wish.) Do not make any other change in +these notices. + + <p>Once this change is made in a given copy, it is irreversible for +that copy, so the ordinary GNU General Public License applies to all +subsequent copies and derivative works made from that copy. + + <p>This option is useful when you wish to copy part of the code of +the Library into a program that is not a library. + + <li>You may copy and distribute the Library (or a portion or +derivative of it, under Section 2) in object code or executable form +under the terms of Sections 1 and 2 above provided that you accompany +it with the complete corresponding machine-readable source code, which +must be distributed under the terms of Sections 1 and 2 above on a +medium customarily used for software interchange. + + <p>If distribution of object code is made by offering access to copy +from a designated place, then offering equivalent access to copy the +source code from the same place satisfies the requirement to +distribute the source code, even though third parties are not +compelled to copy the source along with the object code. + + <li>A program that contains no derivative of any portion of the +Library, but is designed to work with the Library by being compiled or +linked with it, is called a “work that uses the Library”. Such a +work, in isolation, is not a derivative work of the Library, and +therefore falls outside the scope of this License. + + <p>However, linking a “work that uses the Library” with the Library +creates an executable that is a derivative of the Library (because it +contains portions of the Library), rather than a “work that uses the +library”. The executable is therefore covered by this License. +Section 6 states terms for distribution of such executables. + + <p>When a “work that uses the Library” uses material from a header file +that is part of the Library, the object code for the work may be a +derivative work of the Library even though the source code is not. +Whether this is true is especially significant if the work can be +linked without the Library, or if the work is itself a library. The +threshold for this to be true is not precisely defined by law. + + <p>If such an object file uses only numerical parameters, data +structure layouts and accessors, and small macros and small inline +functions (ten lines or less in length), then the use of the object +file is unrestricted, regardless of whether it is legally a derivative +work. (Executables containing this object code plus portions of the +Library will still fall under Section 6.) + + <p>Otherwise, if the work is a derivative of the Library, you may +distribute the object code for the work under the terms of Section 6. +Any executables containing that work also fall under Section 6, +whether or not they are linked directly with the Library itself. + + <li>As an exception to the Sections above, you may also combine or +link a “work that uses the Library” with the Library to produce a +work containing portions of the Library, and distribute that work +under terms of your choice, provided that the terms permit +modification of the work for the customer's own use and reverse +engineering for debugging such modifications. + + <p>You must give prominent notice with each copy of the work that the +Library is used in it and that the Library and its use are covered by +this License. You must supply a copy of this License. If the work +during execution displays copyright notices, you must include the +copyright notice for the Library among them, as well as a reference +directing the user to the copy of this License. Also, you must do one +of these things: + + <ol type=a start=1> +<li>Accompany the work with the complete corresponding +machine-readable source code for the Library including whatever +changes were used in the work (which must be distributed under +Sections 1 and 2 above); and, if the work is an executable linked +with the Library, with the complete machine-readable “work that +uses the Library”, as object code and/or source code, so that the +user can modify the Library and then relink to produce a modified +executable containing the modified Library. (It is understood +that the user who changes the contents of definitions files in the +Library will not necessarily be able to recompile the application +to use the modified definitions.) + + <li>Use a suitable shared library mechanism for linking with the Library. A +suitable mechanism is one that (1) uses at run time a copy of the +library already present on the user's computer system, rather than +copying library functions into the executable, and (2) will operate +properly with a modified version of the library, if the user installs +one, as long as the modified version is interface-compatible with the +version that the work was made with. + + <li>Accompany the work with a written offer, valid for at +least three years, to give the same user the materials +specified in Subsection 6a, above, for a charge no more +than the cost of performing this distribution. + + <li>If distribution of the work is made by offering access to copy +from a designated place, offer equivalent access to copy the above +specified materials from the same place. + + <li>Verify that the user has already received a copy of these +materials or that you have already sent this user a copy. + </ol> + + <p>For an executable, the required form of the “work that uses the +Library” must include any data and utility programs needed for +reproducing the executable from it. However, as a special exception, +the materials to be distributed need not include anything that is +normally distributed (in either source or binary form) with the major +components (compiler, kernel, and so on) of the operating system on +which the executable runs, unless that component itself accompanies the +executable. + + <p>It may happen that this requirement contradicts the license +restrictions of other proprietary libraries that do not normally +accompany the operating system. Such a contradiction means you cannot +use both them and the Library together in an executable that you +distribute. + + <li>You may place library facilities that are a work based on the +Library side-by-side in a single library together with other library +facilities not covered by this License, and distribute such a combined +library, provided that the separate distribution of the work based on +the Library and of the other library facilities is otherwise +permitted, and provided that you do these two things: + + <ol type=a start=1> +<li>Accompany the combined library with a copy of the same work +based on the Library, uncombined with any other library +facilities. This must be distributed under the terms of the +Sections above. + + <li>Give prominent notice with the combined library of the fact +that part of it is a work based on the Library, and explaining +where to find the accompanying uncombined form of the same work. + </ol> + + <li>You may not copy, modify, sublicense, link with, or distribute +the Library except as expressly provided under this License. Any +attempt otherwise to copy, modify, sublicense, link with, or +distribute the Library is void, and will automatically terminate your +rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses +terminated so long as such parties remain in full compliance. + + <li>You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Library or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Library (or any work based on the +Library), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Library or works based on it. + + <li>Each time you redistribute the Library (or any work based on the +Library), the recipient automatically receives a license from the +original licensor to copy, distribute, link with or modify the Library +subject to these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties with +this License. + + <li>If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Library at all. For example, if a patent +license would not permit royalty-free redistribution of the Library by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Library. + + <p>If any portion of this section is held invalid or unenforceable under any +particular circumstance, the balance of the section is intended to apply, +and the section as a whole is intended to apply in other circumstances. + + <p>It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + + <p>This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + <li>If the distribution and/or use of the Library is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Library under this License may add +an explicit geographical distribution limitation excluding those countries, +so that distribution is permitted only in or among countries not thus +excluded. In such case, this License incorporates the limitation as if +written in the body of this License. + + <li>The Free Software Foundation may publish revised and/or new +versions of the Lesser General Public License from time to time. +Such new versions will be similar in spirit to the present version, +but may differ in detail to address new problems or concerns. + + <p>Each version is given a distinguishing version number. If the Library +specifies a version number of this License which applies to it and +“any later version”, you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Library does not specify a +license version number, you may choose any version ever published by +the Free Software Foundation. + + <li>If you wish to incorporate parts of the Library into other free +programs whose distribution conditions are incompatible with these, +write to the author to ask for permission. For software which is +copyrighted by the Free Software Foundation, write to the Free +Software Foundation; we sometimes make exceptions for this. Our +decision will be guided by the two goals of preserving the free status +of all derivatives of our free software and of promoting the sharing +and reuse of software generally. + + <li>BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE +LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + <li>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A +FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES. + </ol> + +<h4 class="unnumberedsubsec">How to Apply These Terms to Your New Libraries</h4> + + <p>If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of the +ordinary General Public License). + + <p>To apply these terms, attach the following notices to the library. It is +safest to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least the +“copyright” line and a pointer to where the full notice is found. + +<pre class="smallexample"> <var>one line to give the library's name and an idea of what it does.</var> + Copyright (C) <var>year</var> <var>name of author</var> + + This library is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at + your option) any later version. + + This library is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA. +</pre> + <p>Also add information on how to contact you by electronic and paper mail. + + <p>You should also get your employer (if you work as a programmer) or your +school, if any, to sign a “copyright disclaimer” for the library, if +necessary. Here is a sample; alter the names: + +<pre class="smallexample"> Yoyodyne, Inc., hereby disclaims all copyright interest in the library + `Frob' (a library for tweaking knobs) written by James Random Hacker. + + <var>signature of Ty Coon</var>, 1 April 1990 + Ty Coon, President of Vice +</pre> + <p>That's all there is to it! + +<div class="node"> +<a name="GNU-FDL"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#GNU-LGPL">GNU LGPL</a>, +Up: <a rel="up" accesskey="u" href="#Licenses">Licenses</a> + +</div> + +<h3 class="appendixsec">C.3 GNU Free Documentation License</h3> + + <p><a name="index-FDL_002c-GNU-Free-Documentation-License-1270"></a><a name="index-License_002c-GNU-FDL-1271"></a><div align="center">Version 1.2, November 2002</div> + +<pre class="display"> Copyright © 2000,2001,2002 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. +</pre> + <ol type=1 start=0> +<li>PREAMBLE + + <p>The purpose of this License is to make a manual, textbook, or other +functional and useful document <dfn>free</dfn> in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + + <p>This License is a kind of “copyleft”, which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + + <p>We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + <li>APPLICABILITY AND DEFINITIONS + + <p>This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The “Document”, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as “you”. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + + <p>A “Modified Version” of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + + <p>A “Secondary Section” is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + + <p>The “Invariant Sections” are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + + <p>The “Cover Texts” are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + + <p>A “Transparent” copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not “Transparent” is called “Opaque”. + + <p>Examples of suitable formats for Transparent copies include plain +<span class="sc">ascii</span> without markup, Texinfo input format, LaTeX input +format, SGML or XML using a publicly available +DTD, and standard-conforming simple HTML, +PostScript or PDF designed for human modification. Examples +of transparent image formats include PNG, XCF and +JPG. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, SGML or +XML for which the DTD and/or processing tools are +not generally available, and the machine-generated HTML, +PostScript or PDF produced by some word processors for +output purposes only. + + <p>The “Title Page” means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, “Title Page” means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + <p>A section “Entitled XYZ” means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as “Acknowledgements”, +“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” +of such a section when you modify the Document means that it remains a +section “Entitled XYZ” according to this definition. + + <p>The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + <li>VERBATIM COPYING + + <p>You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + + <p>You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + <li>COPYING IN QUANTITY + + <p>If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + + <p>If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + + <p>If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + + <p>It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + <li>MODIFICATIONS + + <p>You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + + <ol type=A start=1> +<li>Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + + <li>List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + + <li>State on the Title page the name of the publisher of the +Modified Version, as the publisher. + + <li>Preserve all the copyright notices of the Document. + + <li>Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + + <li>Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + + <li>Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + + <li>Include an unaltered copy of this License. + + <li>Preserve the section Entitled “History”, Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled “History” in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + + <li>Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the “History” section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + + <li>For any section Entitled “Acknowledgements” or “Dedications”, Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + + <li>Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + + <li>Delete any section Entitled “Endorsements”. Such a section +may not be included in the Modified Version. + + <li>Do not retitle any existing section to be Entitled “Endorsements” or +to conflict in title with any Invariant Section. + + <li>Preserve any Warranty Disclaimers. + </ol> + + <p>If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + + <p>You may add a section Entitled “Endorsements”, provided it contains +nothing but endorsements of your Modified Version by various +parties—for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + + <p>You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + + <p>The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + <li>COMBINING DOCUMENTS + + <p>You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + + <p>The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + + <p>In the combination, you must combine any sections Entitled “History” +in the various original documents, forming one section Entitled +“History”; likewise combine any sections Entitled “Acknowledgements”, +and any sections Entitled “Dedications”. You must delete all +sections Entitled “Endorsements.” + + <li>COLLECTIONS OF DOCUMENTS + + <p>You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + + <p>You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + <li>AGGREGATION WITH INDEPENDENT WORKS + + <p>A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an “aggregate” if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + + <p>If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + <li>TRANSLATION + + <p>Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + + <p>If a section in the Document is Entitled “Acknowledgements”, +“Dedications”, or “History”, the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + <li>TERMINATION + + <p>You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + <li>FUTURE REVISIONS OF THIS LICENSE + + <p>The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +<a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>. + + <p>Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License “or any later version” applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + </ol> + +<h4 class="unnumberedsubsec">ADDENDUM: How to use this License for your documents</h4> + + <p>To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +<pre class="smallexample"> Copyright (C) <var>year</var> <var>your name</var>. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +</pre> + <p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the “with...Texts.” line with this: + +<pre class="smallexample"> with the Invariant Sections being <var>list their titles</var>, with + the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts + being <var>list</var>. +</pre> + <p>If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + <p>If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +<!-- Local Variables: --> +<!-- ispell-local-pdict: "ispell-dict" --> +<!-- End: --> +<div class="node"> +<a name="Program-Index"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Option-Index">Option Index</a>, +Previous: <a rel="previous" accesskey="p" href="#Licenses">Licenses</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="unnumbered">Program Index</h2> + +<ul class="index-pg" compact> +<li><a href="#index-autopoint-1155"><code>autopoint</code></a>: <a href="#autopoint-Invocation">autopoint Invocation</a></li> +<li><a href="#index-envsubst-1204"><code>envsubst</code></a>: <a href="#envsubst-Invocation">envsubst Invocation</a></li> +<li><a href="#index-gettext-1181"><code>gettext</code></a>: <a href="#gettext-Invocation">gettext Invocation</a></li> +<li><a href="#index-gettext-1176"><code>gettext</code></a>: <a href="#sh">sh</a></li> +<li><a href="#index-gettextize-1117"><code>gettextize</code></a>: <a href="#gettextize-Invocation">gettextize Invocation</a></li> +<li><a href="#index-msgattrib-828"><code>msgattrib</code></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-msgcat-542"><code>msgcat</code></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-msgcmp-810"><code>msgcmp</code></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-msgcomm-768"><code>msgcomm</code></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-msgconv-590"><code>msgconv</code></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-msgen-878"><code>msgen</code></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-msgexec-911"><code>msgexec</code></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-msgfilter-679"><code>msgfilter</code></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-msgfmt-947"><code>msgfmt</code></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-msggrep-624"><code>msggrep</code></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-msginit-239"><code>msginit</code></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-msgmerge-276"><code>msgmerge</code></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-msgunfmt-1009"><code>msgunfmt</code></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-msguniq-727"><code>msguniq</code></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-ngettext-1193"><code>ngettext</code></a>: <a href="#ngettext-Invocation">ngettext Invocation</a></li> +<li><a href="#index-ngettext-1177"><code>ngettext</code></a>: <a href="#sh">sh</a></li> +<li><a href="#index-recode_002dsr_002dlatin-700"><code>recode-sr-latin</code></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-xgettext-159"><code>xgettext</code></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> + </ul><div class="node"> +<a name="Option-Index"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Variable-Index">Variable Index</a>, +Previous: <a rel="previous" accesskey="p" href="#Program-Index">Program Index</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="unnumbered">Option Index</h2> + + + +<ul class="index-op" compact> +<li><a href="#index-g_t_002d_002dadd_002dcomments_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-183"><code>--add-comments</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-862"><code>--add-location</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-573"><code>--add-location</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-793"><code>--add-location</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-608"><code>--add-location</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-895"><code>--add-location</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-711"><code>--add-location</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-665"><code>--add-location</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-306"><code>--add-location</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-752"><code>--add-location</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dadd_002dlocation_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-211"><code>--add-location</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dalignment_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1000"><code>--alignment</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dbackup_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-287"><code>--backup</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dboost_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-200"><code>--boost</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dc_002b_002b_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-176"><code>--c++</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dcheck_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-984"><code>--check</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dcheck_002daccelerators_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-992"><code>--check-accelerators</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dcheck_002dcompatibility_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-990"><code>--check-compatibility</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dcheck_002ddomain_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-988"><code>--check-domain</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dcheck_002dformat_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-985"><code>--check-format</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dcheck_002dheader_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-987"><code>--check-header</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dclear_002dfuzzy_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-844"><code>--clear-fuzzy</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dclear_002dobsolete_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-846"><code>--clear-obsolete</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dclear_002dprevious_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-847"><code>--clear-previous</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-855"><code>--color</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-930"><code>--color</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#The-_002d_002dcolor-option">The --color option</a></li> +<li><a href="#index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-566"><code>--color</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-786"><code>--color</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-602"><code>--color</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-889"><code>--color</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-705"><code>--color</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-660"><code>--color</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-253"><code>--color</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-300"><code>--color</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1035"><code>--color</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-745"><code>--color</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dcolor_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-204"><code>--color</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dcomment_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-642"><code>--comment</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dcompendium_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-281"><code>--compendium</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dcopyright_002dholder_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-225"><code>--copyright-holder</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dcsharp_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-956"><code>--csharp</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dcsharp_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1015"><code>--csharp</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dcsharp_002dresources_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-958"><code>--csharp-resources</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dcsharp_002dresources_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1017"><code>--csharp-resources</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002ddebug_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-202"><code>--debug</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002ddefault_002ddomain_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-166"><code>--default-domain</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-833"><code>--directory</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-549"><code>--directory</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-814"><code>--directory</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-774"><code>--directory</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-594"><code>--directory</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-882"><code>--directory</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-922"><code>--directory</code><span class="roman">, </span><code>msgexec</code><span class="roman"> option</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-688"><code>--directory</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-951"><code>--directory</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-628"><code>--directory</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-279"><code>--directory</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-732"><code>--directory</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002ddirectory_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-164"><code>--directory</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002ddomain_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1185"><code>--domain</code><span class="roman">, </span><code>gettext</code><span class="roman"> option</span></a>: <a href="#gettext-Invocation">gettext Invocation</a></li> +<li><a href="#index-g_t_002d_002ddomain_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-634"><code>--domain</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002ddomain_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1197"><code>--domain</code><span class="roman">, </span><code>ngettext</code><span class="roman"> option</span></a>: <a href="#ngettext-Invocation">ngettext Invocation</a></li> +<li><a href="#index-g_t_002d_002ddry_002drun_0040r_007b_002c-_0040code_007bautopoint_007d-option_007d-1160"><code>--dry-run</code><span class="roman">, </span><code>autopoint</code><span class="roman"> option</span></a>: <a href="#autopoint-Invocation">autopoint Invocation</a></li> +<li><a href="#index-g_t_002d_002ddry_002drun_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1126"><code>--dry-run</code><span class="roman">, </span><code>gettextize</code><span class="roman"> option</span></a>: <a href="#gettextize-Invocation">gettextize Invocation</a></li> +<li><a href="#index-g_t_002d_002dexclude_002dfile_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-181"><code>--exclude-file</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dexpression_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-694"><code>--expression</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dextended_002dregexp_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-646"><code>--extended-regexp</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dextract_002dall_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-185"><code>--extract-all</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dextracted_002dcomment_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-644"><code>--extracted-comment</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dfile_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-696"><code>--file</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dfile_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-652"><code>--file</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dfiles_002dfrom_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-547"><code>--files-from</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dfiles_002dfrom_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-772"><code>--files-from</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dfiles_002dfrom_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-162"><code>--files-from</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dfixed_002dstrings_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-648"><code>--fixed-strings</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dflag_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-190"><code>--flag</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dforce_0040r_007b_002c-_0040code_007bautopoint_007d-option_007d-1158"><code>--force</code><span class="roman">, </span><code>autopoint</code><span class="roman"> option</span></a>: <a href="#autopoint-Invocation">autopoint Invocation</a></li> +<li><a href="#index-g_t_002d_002dforce_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1120"><code>--force</code><span class="roman">, </span><code>gettextize</code><span class="roman"> option</span></a>: <a href="#gettextize-Invocation">gettextize Invocation</a></li> +<li><a href="#index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-857"><code>--force-po</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-568"><code>--force-po</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-788"><code>--force-po</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-604"><code>--force-po</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-891"><code>--force-po</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-707"><code>--force-po</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-662"><code>--force-po</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-302"><code>--force-po</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1037"><code>--force-po</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-747"><code>--force-po</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dforce_002dpo_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-206"><code>--force-po</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dforeign_002duser_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-226"><code>--foreign-user</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dfrom_002dcode_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-177"><code>--from-code</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dfuzzy_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-850"><code>--fuzzy</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bautopoint_007d-option_007d-1161"><code>--help</code><span class="roman">, </span><code>autopoint</code><span class="roman"> option</span></a>: <a href="#autopoint-Invocation">autopoint Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007benvsubst_007d-option_007d-1212"><code>--help</code><span class="roman">, </span><code>envsubst</code><span class="roman"> option</span></a>: <a href="#envsubst-Invocation">envsubst Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1189"><code>--help</code><span class="roman">, </span><code>gettext</code><span class="roman"> option</span></a>: <a href="#gettext-Invocation">gettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1127"><code>--help</code><span class="roman">, </span><code>gettextize</code><span class="roman"> option</span></a>: <a href="#gettextize-Invocation">gettextize Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-875"><code>--help</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-587"><code>--help</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-825"><code>--help</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-807"><code>--help</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-621"><code>--help</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-908"><code>--help</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-927"><code>--help</code><span class="roman">, </span><code>msgexec</code><span class="roman"> option</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-724"><code>--help</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1003"><code>--help</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-676"><code>--help</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-262"><code>--help</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-320"><code>--help</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1051"><code>--help</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-765"><code>--help</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1201"><code>--help</code><span class="roman">, </span><code>ngettext</code><span class="roman"> option</span></a>: <a href="#ngettext-Invocation">ngettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dhelp_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-235"><code>--help</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dignore_002dcase_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-654"><code>--ignore-case</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dignore_002dfile_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-849"><code>--ignore-file</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-859"><code>--indent</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-570"><code>--indent</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-790"><code>--indent</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-606"><code>--indent</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-893"><code>--indent</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-708"><code>--indent</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-663"><code>--indent</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-304"><code>--indent</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1039"><code>--indent</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-749"><code>--indent</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dindent_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-208"><code>--indent</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dinput_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-920"><code>--input</code><span class="roman">, </span><code>msgexec</code><span class="roman"> option</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_002d_002dinput_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-686"><code>--input</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dinput_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-244"><code>--input</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002dintl_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1121"><code>--intl</code><span class="roman">, </span><code>gettextize</code><span class="roman"> option</span></a>: <a href="#gettextize-Invocation">gettextize Invocation</a></li> +<li><a href="#index-g_t_002d_002dinvert_002dmatch_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-656"><code>--invert-match</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002djava_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-953"><code>--java</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002djava_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1013"><code>--java</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002djava2_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-955"><code>--java2</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002djoin_002dexisting_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-179"><code>--join-existing</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dkde_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-198"><code>--kde</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dkeep_002dheader_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-709"><code>--keep-header</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dkeyword_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-187"><code>--keyword</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dlang_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-888"><code>--lang</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dlang_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-565"><code>--lang</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dlang_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-299"><code>--lang</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dlanguage_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-173"><code>--language</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dless_002dthan_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-554"><code>--less-than</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dless_002dthan_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-778"><code>--less-than</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dlocale_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-970"><code>--locale</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dlocale_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-251"><code>--locale</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002dlocale_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1024"><code>--locale</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dlocation_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-632"><code>--location</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dmore_002dthan_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-556"><code>--more-than</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dmore_002dthan_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-780"><code>--more-than</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dmsgctxt_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-636"><code>--msgctxt</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dmsgid_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-638"><code>--msgid</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dmsgid_002dbugs_002daddress_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-229"><code>--msgid-bugs-address</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dmsgstr_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-640"><code>--msgstr</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dmsgstr_002dprefix_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-231"><code>--msgstr-prefix</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dmsgstr_002dsuffix_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-233"><code>--msgstr-suffix</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dmulti_002ddomain_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-816"><code>--multi-domain</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002d_002dmulti_002ddomain_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-292"><code>--multi-domain</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dchangelog_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1123"><code>--no-changelog</code><span class="roman">, </span><code>gettextize</code><span class="roman"> option</span></a>: <a href="#gettextize-Invocation">gettextize Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dfuzzy_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-838"><code>--no-fuzzy</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dfuzzy_002dmatching_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-818"><code>--no-fuzzy-matching</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dfuzzy_002dmatching_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-294"><code>--no-fuzzy-matching</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dhash_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1001"><code>--no-hash</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-860"><code>--no-location</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-571"><code>--no-location</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-791"><code>--no-location</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-607"><code>--no-location</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-894"><code>--no-location</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-710"><code>--no-location</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-664"><code>--no-location</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-305"><code>--no-location</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-750"><code>--no-location</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dlocation_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-209"><code>--no-location</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dobsolete_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-840"><code>--no-obsolete</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dtranslator_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-252"><code>--no-translator</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-869"><code>--no-wrap</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-580"><code>--no-wrap</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-800"><code>--no-wrap</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-615"><code>--no-wrap</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-902"><code>--no-wrap</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-718"><code>--no-wrap</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-672"><code>--no-wrap</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-260"><code>--no-wrap</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-313"><code>--no-wrap</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1046"><code>--no-wrap</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-759"><code>--no-wrap</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dno_002dwrap_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-217"><code>--no-wrap</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dobsolete_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-851"><code>--obsolete</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002domit_002dheader_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-805"><code>--omit-header</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002domit_002dheader_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-223"><code>--omit-header</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002donly_002dfile_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-848"><code>--only-file</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002donly_002dfuzzy_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-839"><code>--only-fuzzy</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002donly_002dobsolete_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-841"><code>--only-obsolete</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-168"><code>--output</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_002ddir_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-170"><code>--output-dir</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-835"><code>--output-file</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-551"><code>--output-file</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-776"><code>--output-file</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-596"><code>--output-file</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-884"><code>--output-file</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-690"><code>--output-file</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-965"><code>--output-file</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-630"><code>--output-file</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-246"><code>--output-file</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-285"><code>--output-file</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1034"><code>--output-file</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002doutput_002dfile_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-734"><code>--output-file</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dpackage_002dname_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-227"><code>--package-name</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dpackage_002dversion_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-228"><code>--package-version</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dpo_002ddir_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1122"><code>--po-dir</code><span class="roman">, </span><code>gettextize</code><span class="roman"> option</span></a>: <a href="#gettextize-Invocation">gettextize Invocation</a></li> +<li><a href="#index-g_t_002d_002dprevious_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-295"><code>--previous</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-853"><code>--properties-input</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-560"><code>--properties-input</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-822"><code>--properties-input</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-784"><code>--properties-input</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-600"><code>--properties-input</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-886"><code>--properties-input</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-924"><code>--properties-input</code><span class="roman">, </span><code>msgexec</code><span class="roman"> option</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-703"><code>--properties-input</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-981"><code>--properties-input</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-658"><code>--properties-input</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-248"><code>--properties-input</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-297"><code>--properties-input</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002dinput_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-740"><code>--properties-input</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-865"><code>--properties-output</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-576"><code>--properties-output</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-796"><code>--properties-output</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-611"><code>--properties-output</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-898"><code>--properties-output</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-714"><code>--properties-output</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-668"><code>--properties-output</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-256"><code>--properties-output</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-309"><code>--properties-output</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1042"><code>--properties-output</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-755"><code>--properties-output</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dproperties_002doutput_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-213"><code>--properties-output</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dqt_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-962"><code>--qt</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dqt_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-196"><code>--qt</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dquiet_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-698"><code>--quiet</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dquiet_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-326"><code>--quiet</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dregexp_003d_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-650"><code>--regexp=</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002drepeated_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-736"><code>--repeated</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dresource_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-968"><code>--resource</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dresource_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1022"><code>--resource</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dset_002dfuzzy_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-843"><code>--set-fuzzy</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dset_002dobsolete_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-845"><code>--set-obsolete</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dsilent_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-699"><code>--silent</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dsilent_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-327"><code>--silent</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-873"><code>--sort-by-file</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-585"><code>--sort-by-file</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-804"><code>--sort-by-file</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-619"><code>--sort-by-file</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-906"><code>--sort-by-file</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-722"><code>--sort-by-file</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-674"><code>--sort-by-file</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-318"><code>--sort-by-file</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-763"><code>--sort-by-file</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002dby_002dfile_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-222"><code>--sort-by-file</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-871"><code>--sort-output</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-582"><code>--sort-output</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-802"><code>--sort-output</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-617"><code>--sort-output</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-904"><code>--sort-output</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-720"><code>--sort-output</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-673"><code>--sort-output</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-315"><code>--sort-output</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1048"><code>--sort-output</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-761"><code>--sort-output</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dsort_002doutput_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-219"><code>--sort-output</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dstatistics_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1006"><code>--statistics</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-863"><code>--strict</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-574"><code>--strict</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-794"><code>--strict</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-609"><code>--strict</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-896"><code>--strict</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-712"><code>--strict</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-966"><code>--strict</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-666"><code>--strict</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-307"><code>--strict</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1040"><code>--strict</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-753"><code>--strict</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dstrict_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-212"><code>--strict</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-854"><code>--stringtable-input</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-561"><code>--stringtable-input</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-823"><code>--stringtable-input</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-785"><code>--stringtable-input</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-887"><code>--stringtable-input</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-925"><code>--stringtable-input</code><span class="roman">, </span><code>msgexec</code><span class="roman"> option</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-704"><code>--stringtable-input</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-982"><code>--stringtable-input</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-659"><code>--stringtable-input</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-249"><code>--stringtable-input</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-298"><code>--stringtable-input</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsgonv_007d-option_007d-601"><code>--stringtable-input</code><span class="roman">, </span><code>msgonv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002dinput_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-741"><code>--stringtable-input</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-866"><code>--stringtable-output</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-577"><code>--stringtable-output</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-797"><code>--stringtable-output</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-612"><code>--stringtable-output</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-899"><code>--stringtable-output</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-715"><code>--stringtable-output</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-669"><code>--stringtable-output</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-257"><code>--stringtable-output</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-310"><code>--stringtable-output</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1043"><code>--stringtable-output</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-756"><code>--stringtable-output</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dstringtable_002doutput_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-214"><code>--stringtable-output</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-856"><code>--style</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-932"><code>--style</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#The-_002d_002dstyle-option">The --style option</a></li> +<li><a href="#index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-567"><code>--style</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-787"><code>--style</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-603"><code>--style</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-890"><code>--style</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-706"><code>--style</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-661"><code>--style</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-254"><code>--style</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-301"><code>--style</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1036"><code>--style</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-746"><code>--style</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dstyle_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-205"><code>--style</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dsuffix_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-289"><code>--suffix</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dsymlink_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1124"><code>--symlink</code><span class="roman">, </span><code>gettextize</code><span class="roman"> option</span></a>: <a href="#gettextize-Invocation">gettextize Invocation</a></li> +<li><a href="#index-g_t_002d_002dtcl_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-960"><code>--tcl</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dtcl_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1019"><code>--tcl</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dto_002dcode_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-563"><code>--to-code</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dto_002dcode_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-598"><code>--to-code</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dto_002dcode_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-743"><code>--to-code</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dtranslated_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-836"><code>--translated</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dtrigraphs_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-194"><code>--trigraphs</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dunique_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-558"><code>--unique</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dunique_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-782"><code>--unique</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dunique_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-738"><code>--unique</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002duntranslated_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-837"><code>--untranslated</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dupdate_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-283"><code>--update</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002duse_002dfirst_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-564"><code>--use-first</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002duse_002dfirst_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-744"><code>--use-first</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002duse_002dfuzzy_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-819"><code>--use-fuzzy</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002d_002duse_002dfuzzy_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-997"><code>--use-fuzzy</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002duse_002duntranslated_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-820"><code>--use-untranslated</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002d_002dvariables_0040r_007b_002c-_0040code_007benvsubst_007d-option_007d-1210"><code>--variables</code><span class="roman">, </span><code>envsubst</code><span class="roman"> option</span></a>: <a href="#envsubst-Invocation">envsubst Invocation</a></li> +<li><a href="#index-g_t_002d_002dverbose_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1008"><code>--verbose</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dverbose_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-324"><code>--verbose</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dverbose_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1055"><code>--verbose</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bautopoint_007d-option_007d-1162"><code>--version</code><span class="roman">, </span><code>autopoint</code><span class="roman"> option</span></a>: <a href="#autopoint-Invocation">autopoint Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007benvsubst_007d-option_007d-1214"><code>--version</code><span class="roman">, </span><code>envsubst</code><span class="roman"> option</span></a>: <a href="#envsubst-Invocation">envsubst Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1192"><code>--version</code><span class="roman">, </span><code>gettext</code><span class="roman"> option</span></a>: <a href="#gettext-Invocation">gettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1128"><code>--version</code><span class="roman">, </span><code>gettextize</code><span class="roman"> option</span></a>: <a href="#gettextize-Invocation">gettextize Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-877"><code>--version</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-589"><code>--version</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-827"><code>--version</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-809"><code>--version</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-623"><code>--version</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-910"><code>--version</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-929"><code>--version</code><span class="roman">, </span><code>msgexec</code><span class="roman"> option</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-726"><code>--version</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1005"><code>--version</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-678"><code>--version</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-264"><code>--version</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-322"><code>--version</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1053"><code>--version</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-767"><code>--version</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1203"><code>--version</code><span class="roman">, </span><code>ngettext</code><span class="roman"> option</span></a>: <a href="#ngettext-Invocation">ngettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dversion_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-237"><code>--version</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-868"><code>--width</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-579"><code>--width</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-799"><code>--width</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-614"><code>--width</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-901"><code>--width</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-717"><code>--width</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-671"><code>--width</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-259"><code>--width</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-312"><code>--width</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1045"><code>--width</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-758"><code>--width</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002d_002dwidth_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-216"><code>--width</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002d_003c_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-553"><code>-<</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_003c_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-777"><code>-<</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002d_003e_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-555"><code>-></code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002d_003e_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-779"><code>-></code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002da_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-999"><code>-a</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002da_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-184"><code>-a</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dC_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-989"><code>-C</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002dc_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-983"><code>-c</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002dC_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-641"><code>-C</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dC_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-280"><code>-C</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002dc_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-182"><code>-c</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dC_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-175"><code>-C</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dd_0040r_007b_002c-_0040code_007bautopoint_007d-option_007d-1159"><code>-d</code><span class="roman">, </span><code>autopoint</code><span class="roman"> option</span></a>: <a href="#autopoint-Invocation">autopoint Invocation</a></li> +<li><a href="#index-g_t_002dd_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1184"><code>-d</code><span class="roman">, </span><code>gettext</code><span class="roman"> option</span></a>: <a href="#gettext-Invocation">gettext Invocation</a></li> +<li><a href="#index-g_t_002dd_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1125"><code>-d</code><span class="roman">, </span><code>gettextize</code><span class="roman"> option</span></a>: <a href="#gettextize-Invocation">gettextize Invocation</a></li> +<li><a href="#index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-832"><code>-D</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-548"><code>-D</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-813"><code>-D</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-773"><code>-D</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-593"><code>-D</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-881"><code>-D</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-921"><code>-D</code><span class="roman">, </span><code>msgexec</code><span class="roman"> option</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-687"><code>-D</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002dd_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-971"><code>-d</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-950"><code>-D</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002dD_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-627"><code>-D</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dD_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-278"><code>-D</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002dd_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1029"><code>-d</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002dd_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-735"><code>-d</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002dD_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-731"><code>-D</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002dd_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1196"><code>-d</code><span class="roman">, </span><code>ngettext</code><span class="roman"> option</span></a>: <a href="#ngettext-Invocation">ngettext Invocation</a></li> +<li><a href="#index-g_t_002dd_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-165"><code>-d</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dD_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-163"><code>-D</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dE_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1187"><code>-E</code><span class="roman">, </span><code>gettext</code><span class="roman"> option</span></a>: <a href="#gettext-Invocation">gettext Invocation</a></li> +<li><a href="#index-g_t_002de_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1186"><code>-e</code><span class="roman">, </span><code>gettext</code><span class="roman"> option</span></a>: <a href="#gettext-Invocation">gettext Invocation</a></li> +<li><a href="#index-g_t_002de_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-693"><code>-e</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002de_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-649"><code>-e</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dE_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-645"><code>-E</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dE_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1199"><code>-E</code><span class="roman">, </span><code>ngettext</code><span class="roman"> option</span></a>: <a href="#ngettext-Invocation">ngettext Invocation</a></li> +<li><a href="#index-g_t_002de_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1198"><code>-e</code><span class="roman">, </span><code>ngettext</code><span class="roman"> option</span></a>: <a href="#ngettext-Invocation">ngettext Invocation</a></li> +<li><a href="#index-g_t_002df_0040r_007b_002c-_0040code_007bautopoint_007d-option_007d-1157"><code>-f</code><span class="roman">, </span><code>autopoint</code><span class="roman"> option</span></a>: <a href="#autopoint-Invocation">autopoint Invocation</a></li> +<li><a href="#index-g_t_002df_0040r_007b_002c-_0040code_007bgettextize_007d-option_007d-1119"><code>-f</code><span class="roman">, </span><code>gettextize</code><span class="roman"> option</span></a>: <a href="#gettextize-Invocation">gettextize Invocation</a></li> +<li><a href="#index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-872"><code>-F</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-584"><code>-F</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002df_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-546"><code>-f</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-803"><code>-F</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002df_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-771"><code>-f</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-618"><code>-F</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-905"><code>-F</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-721"><code>-F</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002df_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-695"><code>-f</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002df_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-996"><code>-f</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002df_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-651"><code>-f</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dF_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-647"><code>-F</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dF_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-317"><code>-F</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002dF_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-762"><code>-F</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002dF_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-221"><code>-F</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002df_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-161"><code>-f</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007benvsubst_007d-option_007d-1211"><code>-h</code><span class="roman">, </span><code>envsubst</code><span class="roman"> option</span></a>: <a href="#envsubst-Invocation">envsubst Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1188"><code>-h</code><span class="roman">, </span><code>gettext</code><span class="roman"> option</span></a>: <a href="#gettext-Invocation">gettext Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-874"><code>-h</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-586"><code>-h</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-824"><code>-h</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-806"><code>-h</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-620"><code>-h</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-907"><code>-h</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-926"><code>-h</code><span class="roman">, </span><code>msgexec</code><span class="roman"> option</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-723"><code>-h</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1002"><code>-h</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-675"><code>-h</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-261"><code>-h</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-319"><code>-h</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1050"><code>-h</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-764"><code>-h</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1200"><code>-h</code><span class="roman">, </span><code>ngettext</code><span class="roman"> option</span></a>: <a href="#ngettext-Invocation">ngettext Invocation</a></li> +<li><a href="#index-g_t_002dh_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-234"><code>-h</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002di_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-858"><code>-i</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002di_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-569"><code>-i</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002di_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-789"><code>-i</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002di_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-605"><code>-i</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002di_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-892"><code>-i</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002di_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-919"><code>-i</code><span class="roman">, </span><code>msgexec</code><span class="roman"> option</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_002di_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-685"><code>-i</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002di_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-653"><code>-i</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002di_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-243"><code>-i</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002di_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-303"><code>-i</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002di_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1038"><code>-i</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002di_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-748"><code>-i</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002di_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-207"><code>-i</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dj_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-952"><code>-j</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002dJ_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-635"><code>-J</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dj_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1012"><code>-j</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002dj_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-178"><code>-j</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dK_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-637"><code>-K</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dk_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-186"><code>-k</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dl_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-969"><code>-l</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002dl_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-250"><code>-l</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002dl_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1023"><code>-l</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002dL_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-172"><code>-L</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dm_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-815"><code>-m</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002dM_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-633"><code>-M</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dm_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-291"><code>-m</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002dM_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-232"><code>-M</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dm_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-230"><code>-m</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dn_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1190"><code>-n</code><span class="roman">, </span><code>gettext</code><span class="roman"> option</span></a>: <a href="#gettext-Invocation">gettext Invocation</a></li> +<li><a href="#index-g_t_002dn_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-861"><code>-n</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002dn_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-572"><code>-n</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002dN_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-817"><code>-N</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002dn_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-792"><code>-n</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002dn_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-697"><code>-n</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002dN_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-631"><code>-N</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dN_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-293"><code>-N</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002dn_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-751"><code>-n</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002dn_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-210"><code>-n</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002do_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-834"><code>-o</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002do_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-550"><code>-o</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002do_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-775"><code>-o</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002do_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-595"><code>-o</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002do_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-883"><code>-o</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002do_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-689"><code>-o</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002do_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-964"><code>-o</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002do_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-629"><code>-o</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002do_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-245"><code>-o</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002do_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-284"><code>-o</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002do_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1033"><code>-o</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002do_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-733"><code>-o</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002do_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-167"><code>-o</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-864"><code>-p</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-852"><code>-P</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-575"><code>-p</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-559"><code>-P</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-821"><code>-P</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-795"><code>-p</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-783"><code>-P</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-610"><code>-p</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-599"><code>-P</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-897"><code>-p</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-885"><code>-P</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-923"><code>-P</code><span class="roman">, </span><code>msgexec</code><span class="roman"> option</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-713"><code>-p</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-702"><code>-P</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-980"><code>-P</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002dp_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-667"><code>-p</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dP_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-657"><code>-P</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dp_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-255"><code>-p</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002dP_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-247"><code>-P</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-308"><code>-p</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002dP_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-296"><code>-P</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002dp_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1041"><code>-p</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002dp_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-754"><code>-p</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002dP_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-739"><code>-P</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002dp_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-169"><code>-p</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dq_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-325"><code>-q</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002dr_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-967"><code>-r</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002dr_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1021"><code>-r</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-870"><code>-s</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-581"><code>-s</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-801"><code>-s</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-616"><code>-s</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-903"><code>-s</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-719"><code>-s</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-314"><code>-s</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002ds_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1047"><code>-s</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002ds_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-760"><code>-s</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002ds_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-218"><code>-s</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dt_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-562"><code>-t</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002dt_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-597"><code>-t</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002dT_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-639"><code>-T</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dt_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-742"><code>-t</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002dT_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-193"><code>-T</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002du_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-557"><code>-u</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002du_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-781"><code>-u</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002dU_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-282"><code>-U</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002du_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-737"><code>-u</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007benvsubst_007d-option_007d-1213"><code>-V</code><span class="roman">, </span><code>envsubst</code><span class="roman"> option</span></a>: <a href="#envsubst-Invocation">envsubst Invocation</a></li> +<li><a href="#index-g_t_002dv_0040r_007b_002c-_0040code_007benvsubst_007d-option_007d-1209"><code>-v</code><span class="roman">, </span><code>envsubst</code><span class="roman"> option</span></a>: <a href="#envsubst-Invocation">envsubst Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bgettext_007d-option_007d-1191"><code>-V</code><span class="roman">, </span><code>gettext</code><span class="roman"> option</span></a>: <a href="#gettext-Invocation">gettext Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-876"><code>-V</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-588"><code>-V</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgcmp_007d-option_007d-826"><code>-V</code><span class="roman">, </span><code>msgcmp</code><span class="roman"> option</span></a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-808"><code>-V</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-622"><code>-V</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-909"><code>-V</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgexec_007d-option_007d-928"><code>-V</code><span class="roman">, </span><code>msgexec</code><span class="roman"> option</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-725"><code>-V</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002dv_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1007"><code>-v</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgfmt_007d-option_007d-1004"><code>-V</code><span class="roman">, </span><code>msgfmt</code><span class="roman"> option</span></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-677"><code>-V</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dv_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-655"><code>-v</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-263"><code>-V</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002dv_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-323"><code>-v</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-321"><code>-V</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002dv_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1054"><code>-v</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1052"><code>-V</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-766"><code>-V</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bngettext_007d-option_007d-1202"><code>-V</code><span class="roman">, </span><code>ngettext</code><span class="roman"> option</span></a>: <a href="#ngettext-Invocation">ngettext Invocation</a></li> +<li><a href="#index-g_t_002dV_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-236"><code>-V</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgattrib_007d-option_007d-867"><code>-w</code><span class="roman">, </span><code>msgattrib</code><span class="roman"> option</span></a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgcat_007d-option_007d-578"><code>-w</code><span class="roman">, </span><code>msgcat</code><span class="roman"> option</span></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgcomm_007d-option_007d-798"><code>-w</code><span class="roman">, </span><code>msgcomm</code><span class="roman"> option</span></a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgconv_007d-option_007d-613"><code>-w</code><span class="roman">, </span><code>msgconv</code><span class="roman"> option</span></a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgen_007d-option_007d-900"><code>-w</code><span class="roman">, </span><code>msgen</code><span class="roman"> option</span></a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgfilter_007d-option_007d-716"><code>-w</code><span class="roman">, </span><code>msgfilter</code><span class="roman"> option</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_002dw_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-670"><code>-w</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dw_0040r_007b_002c-_0040code_007bmsginit_007d-option_007d-258"><code>-w</code><span class="roman">, </span><code>msginit</code><span class="roman"> option</span></a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgmerge_007d-option_007d-311"><code>-w</code><span class="roman">, </span><code>msgmerge</code><span class="roman"> option</span></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_002dw_0040r_007b_002c-_0040code_007bmsgunfmt_007d-option_007d-1044"><code>-w</code><span class="roman">, </span><code>msgunfmt</code><span class="roman"> option</span></a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_002dw_0040r_007b_002c-_0040code_007bmsguniq_007d-option_007d-757"><code>-w</code><span class="roman">, </span><code>msguniq</code><span class="roman"> option</span></a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-g_t_002dw_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-215"><code>-w</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_002dX_0040r_007b_002c-_0040code_007bmsggrep_007d-option_007d-643"><code>-X</code><span class="roman">, </span><code>msggrep</code><span class="roman"> option</span></a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-g_t_002dx_0040r_007b_002c-_0040code_007bxgettext_007d-option_007d-180"><code>-x</code><span class="roman">, </span><code>xgettext</code><span class="roman"> option</span></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> + </ul><div class="node"> +<a name="Variable-Index"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#PO-Mode-Index">PO Mode Index</a>, +Previous: <a rel="previous" accesskey="p" href="#Option-Index">Option Index</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="unnumbered">Variable Index</h2> + + + +<ul class="index-vr" compact> +<li><a href="#index-GETTEXT_005fLOG_005fUNTRANSLATED_0040r_007b_002c-environment-variable_007d-1112"><code>GETTEXT_LOG_UNTRANSLATED</code><span class="roman">, environment variable</span></a>: <a href="#Prioritizing-messages">Prioritizing messages</a></li> +<li><a href="#index-LANG_0040r_007b_002c-environment-variable_007d-1109"><code>LANG</code><span class="roman">, environment variable</span></a>: <a href="#gettext-grok">gettext grok</a></li> +<li><a href="#index-LANG_0040r_007b_002c-environment-variable_007d-51"><code>LANG</code><span class="roman">, environment variable</span></a>: <a href="#Locale-Environment-Variables">Locale Environment Variables</a></li> +<li><a href="#index-LANGUAGE_0040r_007b_002c-environment-variable_007d-1135"><code>LANGUAGE</code><span class="roman">, environment variable</span></a>: <a href="#po_002fRules_002d_002a">po/Rules-*</a></li> +<li><a href="#index-LANGUAGE_0040r_007b_002c-environment-variable_007d-1101"><code>LANGUAGE</code><span class="roman">, environment variable</span></a>: <a href="#gettext-grok">gettext grok</a></li> +<li><a href="#index-LANGUAGE_0040r_007b_002c-environment-variable_007d-43"><code>LANGUAGE</code><span class="roman">, environment variable</span></a>: <a href="#Locale-Environment-Variables">Locale Environment Variables</a></li> +<li><a href="#index-LC_005fALL_0040r_007b_002c-environment-variable_007d-1102"><code>LC_ALL</code><span class="roman">, environment variable</span></a>: <a href="#gettext-grok">gettext grok</a></li> +<li><a href="#index-LC_005fALL_0040r_007b_002c-environment-variable_007d-44"><code>LC_ALL</code><span class="roman">, environment variable</span></a>: <a href="#Locale-Environment-Variables">Locale Environment Variables</a></li> +<li><a href="#index-LC_005fCOLLATE_0040r_007b_002c-environment-variable_007d-1106"><code>LC_COLLATE</code><span class="roman">, environment variable</span></a>: <a href="#gettext-grok">gettext grok</a></li> +<li><a href="#index-LC_005fCOLLATE_0040r_007b_002c-environment-variable_007d-48"><code>LC_COLLATE</code><span class="roman">, environment variable</span></a>: <a href="#Locale-Environment-Variables">Locale Environment Variables</a></li> +<li><a href="#index-LC_005fCTYPE_0040r_007b_002c-environment-variable_007d-1103"><code>LC_CTYPE</code><span class="roman">, environment variable</span></a>: <a href="#gettext-grok">gettext grok</a></li> +<li><a href="#index-LC_005fCTYPE_0040r_007b_002c-environment-variable_007d-45"><code>LC_CTYPE</code><span class="roman">, environment variable</span></a>: <a href="#Locale-Environment-Variables">Locale Environment Variables</a></li> +<li><a href="#index-LC_005fMESSAGES_0040r_007b_002c-environment-variable_007d-1108"><code>LC_MESSAGES</code><span class="roman">, environment variable</span></a>: <a href="#gettext-grok">gettext grok</a></li> +<li><a href="#index-LC_005fMESSAGES_0040r_007b_002c-environment-variable_007d-50"><code>LC_MESSAGES</code><span class="roman">, environment variable</span></a>: <a href="#Locale-Environment-Variables">Locale Environment Variables</a></li> +<li><a href="#index-LC_005fMONETARY_0040r_007b_002c-environment-variable_007d-1107"><code>LC_MONETARY</code><span class="roman">, environment variable</span></a>: <a href="#gettext-grok">gettext grok</a></li> +<li><a href="#index-LC_005fMONETARY_0040r_007b_002c-environment-variable_007d-49"><code>LC_MONETARY</code><span class="roman">, environment variable</span></a>: <a href="#Locale-Environment-Variables">Locale Environment Variables</a></li> +<li><a href="#index-LC_005fNUMERIC_0040r_007b_002c-environment-variable_007d-1104"><code>LC_NUMERIC</code><span class="roman">, environment variable</span></a>: <a href="#gettext-grok">gettext grok</a></li> +<li><a href="#index-LC_005fNUMERIC_0040r_007b_002c-environment-variable_007d-46"><code>LC_NUMERIC</code><span class="roman">, environment variable</span></a>: <a href="#Locale-Environment-Variables">Locale Environment Variables</a></li> +<li><a href="#index-LC_005fTIME_0040r_007b_002c-environment-variable_007d-1105"><code>LC_TIME</code><span class="roman">, environment variable</span></a>: <a href="#gettext-grok">gettext grok</a></li> +<li><a href="#index-LC_005fTIME_0040r_007b_002c-environment-variable_007d-47"><code>LC_TIME</code><span class="roman">, environment variable</span></a>: <a href="#Locale-Environment-Variables">Locale Environment Variables</a></li> +<li><a href="#index-LINGUAS_0040r_007b_002c-environment-variable_007d-1169"><code>LINGUAS</code><span class="roman">, environment variable</span></a>: <a href="#Installers">Installers</a></li> +<li><a href="#index-MSGEXEC_005fLOCATION_0040r_007b_002c-environment-variable_007d-917"><code>MSGEXEC_LOCATION</code><span class="roman">, environment variable</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-MSGEXEC_005fMSGCTXT_0040r_007b_002c-environment-variable_007d-915"><code>MSGEXEC_MSGCTXT</code><span class="roman">, environment variable</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-MSGEXEC_005fMSGID_0040r_007b_002c-environment-variable_007d-916"><code>MSGEXEC_MSGID</code><span class="roman">, environment variable</span></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-MSGFILTER_005fLOCATION_0040r_007b_002c-environment-variable_007d-684"><code>MSGFILTER_LOCATION</code><span class="roman">, environment variable</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-MSGFILTER_005fMSGCTXT_0040r_007b_002c-environment-variable_007d-682"><code>MSGFILTER_MSGCTXT</code><span class="roman">, environment variable</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-MSGFILTER_005fMSGID_0040r_007b_002c-environment-variable_007d-683"><code>MSGFILTER_MSGID</code><span class="roman">, environment variable</span></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-PO_005fSTYLE_0040r_007b_002c-environment-variable_007d-933"><code>PO_STYLE</code><span class="roman">, environment variable</span></a>: <a href="#The-_002d_002dstyle-option">The --style option</a></li> +<li><a href="#index-TERM_0040r_007b_002c-environment-variable_007d-931"><code>TERM</code><span class="roman">, environment variable</span></a>: <a href="#The-TERM-variable">The TERM variable</a></li> +<li><a href="#index-TEXTDOMAIN_0040r_007b_002c-environment-variable_007d-1178"><code>TEXTDOMAIN</code><span class="roman">, environment variable</span></a>: <a href="#sh">sh</a></li> +<li><a href="#index-TEXTDOMAINDIR_0040r_007b_002c-environment-variable_007d-1179"><code>TEXTDOMAINDIR</code><span class="roman">, environment variable</span></a>: <a href="#sh">sh</a></li> + </ul><div class="node"> +<a name="PO-Mode-Index"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Autoconf-Macro-Index">Autoconf Macro Index</a>, +Previous: <a rel="previous" accesskey="p" href="#Variable-Index">Variable Index</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="unnumbered">PO Mode Index</h2> + + + +<ul class="index-em" compact> +<li><a href="#index-g_t_0023_0040r_007b_002c-PO-Mode-command_007d-467"><code>#</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Comments">Modifying Comments</a></li> +<li><a href="#index-g_t_002c_0040r_007b_002c-PO-Mode-command_007d-148"><code>,</code><span class="roman">, PO Mode command</span></a>: <a href="#Marking">Marking</a></li> +<li><a href="#index-g_t_002e_0040r_007b_002c-PO-Mode-command_007d-364"><code>.</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-g_t_0040file_007b_002eemacs_007d-customizations-334"><samp><span class="file">.emacs</span></samp> customizations</a>: <a href="#Installation">Installation</a></li> +<li><a href="#index-g_t0_0040r_007b_002c-PO-Mode-command_007d-341"><code>0</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-g_t_003c_0040r_007b_002c-PO-Mode-command_007d-367"><code><</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-g_t_003d_0040r_007b_002c-PO-Mode-command_007d-344"><code>=</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-g_t_003e_0040r_007b_002c-PO-Mode-command_007d-368"><code>></code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-g_t_003f_0040r_007b_002c-PO-Mode-command_007d-342"><code>?</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-g_t_005f_0040r_007b_002c-PO-Mode-command_007d-338"><code>_</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-a_0040r_007b_002c-PO-Mode-command_007d-520"><code>a</code><span class="roman">, PO Mode command</span></a>: <a href="#Auxiliary">Auxiliary</a></li> +<li><a href="#index-A_0040r_007b_002c-PO-Mode-command_007d-514"><code>A</code><span class="roman">, PO Mode command</span></a>: <a href="#Auxiliary">Auxiliary</a></li> +<li><a href="#index-a_0040r_007b_002c-PO-Mode-command_007d-512"><code>a</code><span class="roman">, PO Mode command</span></a>: <a href="#Auxiliary">Auxiliary</a></li> +<li><a href="#index-auxiliary-PO-file-511">auxiliary PO file</a>: <a href="#Auxiliary">Auxiliary</a></li> +<li><a href="#index-C_002dc-C_002da_0040r_007b_002c-PO-Mode-command_007d-513"><code>C-c C-a</code><span class="roman">, PO Mode command</span></a>: <a href="#Auxiliary">Auxiliary</a></li> +<li><a href="#index-C_002dc-C_002da_0040r_007b_002c-PO-Mode-command_007d-483"><code>C-c C-a</code><span class="roman">, PO Mode command</span></a>: <a href="#Subedit">Subedit</a></li> +<li><a href="#index-C_002dc-C_002dc_0040r_007b_002c-PO-Mode-command_007d-481"><code>C-c C-c</code><span class="roman">, PO Mode command</span></a>: <a href="#Subedit">Subedit</a></li> +<li><a href="#index-C_002dc-C_002dk_0040r_007b_002c-PO-Mode-command_007d-482"><code>C-c C-k</code><span class="roman">, PO Mode command</span></a>: <a href="#Subedit">Subedit</a></li> +<li><a href="#index-C_002dj_0040r_007b_002c-PO-Mode-command_007d-446"><code>C-j</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-commands-337">commands</a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-comment-out-PO-file-entry-441">comment out PO file entry</a>: <a href="#Obsolete-Entries">Obsolete Entries</a></li> +<li><a href="#index-consulting-program-sources-493">consulting program sources</a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-consulting-translations-to-other-languages-509">consulting translations to other languages</a>: <a href="#Auxiliary">Auxiliary</a></li> +<li><a href="#index-current-entry-of-a-PO-file-362">current entry of a PO file</a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-cut-and-paste-for-translated-strings-457">cut and paste for translated strings</a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-DEL_0040r_007b_002c-PO-Mode-command_007d-433"><code>DEL</code><span class="roman">, PO Mode command</span></a>: <a href="#Obsolete-Entries">Obsolete Entries</a></li> +<li><a href="#index-DEL_0040r_007b_002c-PO-Mode-command_007d-416"><code>DEL</code><span class="roman">, PO Mode command</span></a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-editing-comments-466">editing comments</a>: <a href="#Modifying-Comments">Modifying Comments</a></li> +<li><a href="#index-editing-multiple-entries-491">editing multiple entries</a>: <a href="#Subedit">Subedit</a></li> +<li><a href="#index-editing-translations-443">editing translations</a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-g_t_0040code_007betags_007d_002c-using-for-marking-strings-146"><code>etags</code>, using for marking strings</a>: <a href="#Marking">Marking</a></li> +<li><a href="#index-exiting-PO-subedit-484">exiting PO subedit</a>: <a href="#Subedit">Subedit</a></li> +<li><a href="#index-F_0040r_007b_002c-PO-Mode-command_007d-411"><code>F</code><span class="roman">, PO Mode command</span></a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-f_0040r_007b_002c-PO-Mode-command_007d-409"><code>f</code><span class="roman">, PO Mode command</span></a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-F_0040r_007b_002c-PO-Mode-command_007d-407"><code>F</code><span class="roman">, PO Mode command</span></a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-f_0040r_007b_002c-PO-Mode-command_007d-406"><code>f</code><span class="roman">, PO Mode command</span></a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-find-source-fragment-for-a-PO-file-entry-496">find source fragment for a PO file entry</a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-h_0040r_007b_002c-PO-Mode-command_007d-343"><code>h</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-installing-PO-mode-335">installing PO mode</a>: <a href="#Installation">Installation</a></li> +<li><a href="#index-K_0040r_007b_002c-PO-Mode-command_007d-468"><code>K</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Comments">Modifying Comments</a></li> +<li><a href="#index-k_0040r_007b_002c-PO-Mode-command_007d-447"><code>k</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-k_0040r_007b_002c-PO-Mode-command_007d-422"><code>k</code><span class="roman">, PO Mode command</span></a>: <a href="#Untranslated-Entries">Untranslated Entries</a></li> +<li><a href="#index-LFD_0040r_007b_002c-PO-Mode-command_007d-445"><code>LFD</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-looking-at-the-source-to-aid-translation-494">looking at the source to aid translation</a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-m_0040r_007b_002c-PO-Mode-command_007d-369"><code>m</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-M_002d_002c_0040r_007b_002c-PO-Mode-command_007d-149"><code>M-,</code><span class="roman">, PO Mode command</span></a>: <a href="#Marking">Marking</a></li> +<li><a href="#index-M_002d_002e_0040r_007b_002c-PO-Mode-command_007d-150"><code>M-.</code><span class="roman">, PO Mode command</span></a>: <a href="#Marking">Marking</a></li> +<li><a href="#index-M_002dA_0040r_007b_002c-PO-Mode-command_007d-515"><code>M-A</code><span class="roman">, PO Mode command</span></a>: <a href="#Auxiliary">Auxiliary</a></li> +<li><a href="#index-M_002dS_0040r_007b_002c-PO-Mode-command_007d-507"><code>M-S</code><span class="roman">, PO Mode command</span></a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-M_002ds_0040r_007b_002c-PO-Mode-command_007d-503"><code>M-s</code><span class="roman">, PO Mode command</span></a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-M_002dS_0040r_007b_002c-PO-Mode-command_007d-500"><code>M-S</code><span class="roman">, PO Mode command</span></a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-M_002ds_0040r_007b_002c-PO-Mode-command_007d-498"><code>M-s</code><span class="roman">, PO Mode command</span></a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-marking-strings-for-translation-145">marking strings for translation</a>: <a href="#Marking">Marking</a></li> +<li><a href="#index-moving-by-fuzzy-entries-405">moving by fuzzy entries</a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-moving-by-obsolete-entries-430">moving by obsolete entries</a>: <a href="#Obsolete-Entries">Obsolete Entries</a></li> +<li><a href="#index-moving-by-translated-entries-394">moving by translated entries</a>: <a href="#Translated-Entries">Translated Entries</a></li> +<li><a href="#index-moving-by-untranslated-entries-419">moving by untranslated entries</a>: <a href="#Untranslated-Entries">Untranslated Entries</a></li> +<li><a href="#index-moving-through-a-PO-file-363">moving through a PO file</a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-n_0040r_007b_002c-PO-Mode-command_007d-365"><code>n</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-next_002derror_0040r_007b_002c-stepping-through-PO-file-validation-results_007d-361"><code>next-error</code><span class="roman">, stepping through PO file validation results</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-normalize_0040r_007b_002c-PO-Mode-command_007d-524"><code>normalize</code><span class="roman">, PO Mode command</span></a>: <a href="#Auxiliary">Auxiliary</a></li> +<li><a href="#index-O_0040r_007b_002c-PO-Mode-command_007d-436"><code>O</code><span class="roman">, PO Mode command</span></a>: <a href="#Obsolete-Entries">Obsolete Entries</a></li> +<li><a href="#index-o_0040r_007b_002c-PO-Mode-command_007d-434"><code>o</code><span class="roman">, PO Mode command</span></a>: <a href="#Obsolete-Entries">Obsolete Entries</a></li> +<li><a href="#index-O_0040r_007b_002c-PO-Mode-command_007d-432"><code>O</code><span class="roman">, PO Mode command</span></a>: <a href="#Obsolete-Entries">Obsolete Entries</a></li> +<li><a href="#index-o_0040r_007b_002c-PO-Mode-command_007d-431"><code>o</code><span class="roman">, PO Mode command</span></a>: <a href="#Obsolete-Entries">Obsolete Entries</a></li> +<li><a href="#index-obsolete-active-entry-440">obsolete active entry</a>: <a href="#Obsolete-Entries">Obsolete Entries</a></li> +<li><a href="#index-p_0040r_007b_002c-PO-Mode-command_007d-366"><code>p</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-pending-subedits-492">pending subedits</a>: <a href="#Subedit">Subedit</a></li> +<li><a href="#index-po_002dauto_002dedit_002dwith_002dmsgid_0040r_007b_002c-PO-Mode-variable_007d-455"><code>po-auto-edit-with-msgid</code><span class="roman">, PO Mode variable</span></a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-po_002dauto_002dfuzzy_002don_002dedit_0040r_007b_002c-PO-Mode-variable_007d-401"><code>po-auto-fuzzy-on-edit</code><span class="roman">, PO Mode variable</span></a>: <a href="#Translated-Entries">Translated Entries</a></li> +<li><a href="#index-po_002dauto_002dselect_002don_002dunfuzzy_0040r_007b_002c-PO-Mode-variable_007d-415"><code>po-auto-select-on-unfuzzy</code><span class="roman">, PO Mode variable</span></a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-po_002dconfirm_002dand_002dquit_0040r_007b_002c-PO-Mode-command_007d-351"><code>po-confirm-and-quit</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-po_002dconsider_002das_002dauxiliary_0040r_007b_002c-PO-Mode-command_007d-517"><code>po-consider-as-auxiliary</code><span class="roman">, PO Mode command</span></a>: <a href="#Auxiliary">Auxiliary</a></li> +<li><a href="#index-po_002dconsider_002dsource_002dpath_0040r_007b_002c-PO-Mode-command_007d-506"><code>po-consider-source-path</code><span class="roman">, PO Mode command</span></a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-po_002dcurrent_002dentry_0040r_007b_002c-PO-Mode-command_007d-373"><code>po-current-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-po_002dcycle_002dauxiliary_0040r_007b_002c-PO-Mode-command_007d-521"><code>po-cycle-auxiliary</code><span class="roman">, PO Mode command</span></a>: <a href="#Auxiliary">Auxiliary</a></li> +<li><a href="#index-po_002dcycle_002dsource_002dreference_0040r_007b_002c-PO-Mode-command_007d-502"><code>po-cycle-source-reference</code><span class="roman">, PO Mode command</span></a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-po_002dedit_002dcomment_0040r_007b_002c-PO-Mode-command_007d-472"><code>po-edit-comment</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Comments">Modifying Comments</a></li> +<li><a href="#index-po_002dedit_002dmsgstr_0040r_007b_002c-PO-Mode-command_007d-451"><code>po-edit-msgstr</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-po_002dexchange_002dlocation_0040r_007b_002c-PO-Mode-command_007d-387"><code>po-exchange-location</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-po_002dfade_002dout_002dentry_0040r_007b_002c-PO-Mode-command_007d-439"><code>po-fade-out-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Obsolete-Entries">Obsolete Entries</a></li> +<li><a href="#index-po_002dfade_002dout_002dentry_0040r_007b_002c-PO-Mode-command_007d-417"><code>po-fade-out-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-po_002dfirst_002dentry_0040r_007b_002c-PO-Mode-command_007d-379"><code>po-first-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-po_002dhelp_0040r_007b_002c-PO-Mode-command_007d-356"><code>po-help</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-po_002dignore_002das_002dauxiliary_0040r_007b_002c-PO-Mode-command_007d-519"><code>po-ignore-as-auxiliary</code><span class="roman">, PO Mode command</span></a>: <a href="#Auxiliary">Auxiliary</a></li> +<li><a href="#index-po_002dignore_002dsource_002dpath_0040r_007b_002c-PO-Mode-command_007d-508"><code>po-ignore-source-path</code><span class="roman">, PO Mode command</span></a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-po_002dkill_002dcomment_0040r_007b_002c-PO-Mode-command_007d-475"><code>po-kill-comment</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Comments">Modifying Comments</a></li> +<li><a href="#index-po_002dkill_002dmsgstr_0040r_007b_002c-PO-Mode-command_007d-459"><code>po-kill-msgstr</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-po_002dkill_002dmsgstr_0040r_007b_002c-PO-Mode-command_007d-428"><code>po-kill-msgstr</code><span class="roman">, PO Mode command</span></a>: <a href="#Untranslated-Entries">Untranslated Entries</a></li> +<li><a href="#index-po_002dkill_002dring_002dsave_002dcomment_0040r_007b_002c-PO-Mode-command_007d-477"><code>po-kill-ring-save-comment</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Comments">Modifying Comments</a></li> +<li><a href="#index-po_002dkill_002dring_002dsave_002dmsgstr_0040r_007b_002c-PO-Mode-command_007d-461"><code>po-kill-ring-save-msgstr</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-po_002dlast_002dentry_0040r_007b_002c-PO-Mode-command_007d-381"><code>po-last-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-po_002dmark_002dtranslatable_0040r_007b_002c-PO-Mode-command_007d-152"><code>po-mark-translatable</code><span class="roman">, PO Mode command</span></a>: <a href="#Marking">Marking</a></li> +<li><a href="#index-po_002dmsgid_002dto_002dmsgstr_0040r_007b_002c-PO-Mode-command_007d-454"><code>po-msgid-to-msgstr</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-po_002dnext_002dentry_0040r_007b_002c-PO-Mode-command_007d-375"><code>po-next-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-po_002dnext_002dfuzzy_002dentry_0040r_007b_002c-PO-Mode-command_007d-410"><code>po-next-fuzzy-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-po_002dnext_002dobsolete_002dentry_0040r_007b_002c-PO-Mode-command_007d-435"><code>po-next-obsolete-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Obsolete-Entries">Obsolete Entries</a></li> +<li><a href="#index-po_002dnext_002dtranslated_002dentry_0040r_007b_002c-PO-Mode-command_007d-398"><code>po-next-translated-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Translated-Entries">Translated Entries</a></li> +<li><a href="#index-po_002dnext_002duntranslated_002dentry_0040r_007b_002c-PO-Mode-command_007d-424"><code>po-next-untranslated-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Untranslated-Entries">Untranslated Entries</a></li> +<li><a href="#index-po_002dnormalize_0040r_007b_002c-PO-Mode-command_007d-390"><code>po-normalize</code><span class="roman">, PO Mode command</span></a>: <a href="#Normalizing">Normalizing</a></li> +<li><a href="#index-po_002dother_002dwindow_0040r_007b_002c-PO-Mode-command_007d-353"><code>po-other-window</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-po_002dpop_002dlocation_0040r_007b_002c-PO-Mode-command_007d-385"><code>po-pop-location</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-po_002dprevious_002dentry_0040r_007b_002c-PO-Mode-command_007d-377"><code>po-previous-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-po_002dprevious_002dfuzzy_002dentry_0040r_007b_002c-PO-Mode-command_007d-412"><code>po-previous-fuzzy-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-po_002dprevious_002dobsolete_002dentry_0040r_007b_002c-PO-Mode-command_007d-437"><code>po-previous-obsolete-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Obsolete-Entries">Obsolete Entries</a></li> +<li><a href="#index-po_002dprevious_002dtranslated_002dentry_0040r_007b_002c-PO-Mode-command_007d-400"><code>po-previous-translated-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Translated-Entries">Translated Entries</a></li> +<li><a href="#index-po_002dprevious_002duntransted_002dentry_0040r_007b_002c-PO-Mode-command_007d-426"><code>po-previous-untransted-entry</code><span class="roman">, PO Mode command</span></a>: <a href="#Untranslated-Entries">Untranslated Entries</a></li> +<li><a href="#index-po_002dpush_002dlocation_0040r_007b_002c-PO-Mode-command_007d-383"><code>po-push-location</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-po_002dquit_0040r_007b_002c-PO-Mode-command_007d-350"><code>po-quit</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-po_002dselect_002dauxiliary_0040r_007b_002c-PO-Mode-command_007d-523"><code>po-select-auxiliary</code><span class="roman">, PO Mode command</span></a>: <a href="#Auxiliary">Auxiliary</a></li> +<li><a href="#index-po_002dselect_002dmark_002dand_002dmark_0040r_007b_002c-PO-Mode-command_007d-153"><code>po-select-mark-and-mark</code><span class="roman">, PO Mode command</span></a>: <a href="#Marking">Marking</a></li> +<li><a href="#index-po_002dselect_002dsource_002dreference_0040r_007b_002c-PO-Mode-command_007d-504"><code>po-select-source-reference</code><span class="roman">, PO Mode command</span></a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-po_002dstatistics_0040r_007b_002c-PO-Mode-command_007d-358"><code>po-statistics</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-po_002dsubedit_002dabort_0040r_007b_002c-PO-Mode-command_007d-488"><code>po-subedit-abort</code><span class="roman">, PO Mode command</span></a>: <a href="#Subedit">Subedit</a></li> +<li><a href="#index-po_002dsubedit_002dcycle_002dauxiliary_0040r_007b_002c-PO-Mode-command_007d-490"><code>po-subedit-cycle-auxiliary</code><span class="roman">, PO Mode command</span></a>: <a href="#Subedit">Subedit</a></li> +<li><a href="#index-po_002dsubedit_002dexit_0040r_007b_002c-PO-Mode-command_007d-486"><code>po-subedit-exit</code><span class="roman">, PO Mode command</span></a>: <a href="#Subedit">Subedit</a></li> +<li><a href="#index-po_002dsubedit_002dmode_002dhook_0040r_007b_002c-PO-Mode-variable_007d-473"><code>po-subedit-mode-hook</code><span class="roman">, PO Mode variable</span></a>: <a href="#Modifying-Comments">Modifying Comments</a></li> +<li><a href="#index-po_002dtags_002dsearch_0040r_007b_002c-PO-Mode-command_007d-151"><code>po-tags-search</code><span class="roman">, PO Mode command</span></a>: <a href="#Marking">Marking</a></li> +<li><a href="#index-po_002dundo_0040r_007b_002c-PO-Mode-command_007d-347"><code>po-undo</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-po_002dunfuzzy_0040r_007b_002c-PO-Mode-command_007d-414"><code>po-unfuzzy</code><span class="roman">, PO Mode command</span></a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-po_002dvalidate_0040r_007b_002c-PO-Mode-command_007d-360"><code>po-validate</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-po_002dyank_002dcomment_0040r_007b_002c-PO-Mode-command_007d-479"><code>po-yank-comment</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Comments">Modifying Comments</a></li> +<li><a href="#index-po_002dyank_002dmsgstr_0040r_007b_002c-PO-Mode-command_007d-463"><code>po-yank-msgstr</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-q_0040r_007b_002c-PO-Mode-command_007d-349"><code>q</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-Q_0040r_007b_002c-PO-Mode-command_007d-348"><code>Q</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-q_0040r_007b_002c-PO-Mode-command_007d-340"><code>q</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-Q_0040r_007b_002c-PO-Mode-command_007d-339"><code>Q</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-r_0040r_007b_002c-PO-Mode-command_007d-370"><code>r</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-RET_0040r_007b_002c-PO-Mode-command_007d-444"><code>RET</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-S_0040r_007b_002c-PO-Mode-command_007d-505"><code>S</code><span class="roman">, PO Mode command</span></a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-s_0040r_007b_002c-PO-Mode-command_007d-501"><code>s</code><span class="roman">, PO Mode command</span></a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-S_0040r_007b_002c-PO-Mode-command_007d-499"><code>S</code><span class="roman">, PO Mode command</span></a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-s_0040r_007b_002c-PO-Mode-command_007d-497"><code>s</code><span class="roman">, PO Mode command</span></a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-starting-a-string-translation-456">starting a string translation</a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-string-normalization-in-entries-389">string normalization in entries</a>: <a href="#Normalizing">Normalizing</a></li> +<li><a href="#index-subedit-minor-mode-480">subedit minor mode</a>: <a href="#Subedit">Subedit</a></li> +<li><a href="#index-T_0040r_007b_002c-PO-Mode-command_007d-399"><code>T</code><span class="roman">, PO Mode command</span></a>: <a href="#Translated-Entries">Translated Entries</a></li> +<li><a href="#index-t_0040r_007b_002c-PO-Mode-command_007d-397"><code>t</code><span class="roman">, PO Mode command</span></a>: <a href="#Translated-Entries">Translated Entries</a></li> +<li><a href="#index-T_0040r_007b_002c-PO-Mode-command_007d-396"><code>T</code><span class="roman">, PO Mode command</span></a>: <a href="#Translated-Entries">Translated Entries</a></li> +<li><a href="#index-t_0040r_007b_002c-PO-Mode-command_007d-395"><code>t</code><span class="roman">, PO Mode command</span></a>: <a href="#Translated-Entries">Translated Entries</a></li> +<li><a href="#index-TAB_0040r_007b_002c-PO-Mode-command_007d-408"><code>TAB</code><span class="roman">, PO Mode command</span></a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-g_t_0040file_007bTAGS_007d_002c-and-marking-translatable-strings-147"><samp><span class="file">TAGS</span></samp>, and marking translatable strings</a>: <a href="#Marking">Marking</a></li> +<li><a href="#index-U_0040r_007b_002c-PO-Mode-command_007d-425"><code>U</code><span class="roman">, PO Mode command</span></a>: <a href="#Untranslated-Entries">Untranslated Entries</a></li> +<li><a href="#index-u_0040r_007b_002c-PO-Mode-command_007d-423"><code>u</code><span class="roman">, PO Mode command</span></a>: <a href="#Untranslated-Entries">Untranslated Entries</a></li> +<li><a href="#index-U_0040r_007b_002c-PO-Mode-command_007d-421"><code>U</code><span class="roman">, PO Mode command</span></a>: <a href="#Untranslated-Entries">Untranslated Entries</a></li> +<li><a href="#index-u_0040r_007b_002c-PO-Mode-command_007d-420"><code>u</code><span class="roman">, PO Mode command</span></a>: <a href="#Untranslated-Entries">Untranslated Entries</a></li> +<li><a href="#index-use-the-source_002c-Luke-495">use the source, Luke</a>: <a href="#C-Sources-Context">C Sources Context</a></li> +<li><a href="#index-using-obsolete-translations-to-make-new-entries-464">using obsolete translations to make new entries</a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-using-translation-compendia-525">using translation compendia</a>: <a href="#Compendium">Compendium</a></li> +<li><a href="#index-V_0040r_007b_002c-PO-Mode-command_007d-345"><code>V</code><span class="roman">, PO Mode command</span></a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-W_0040r_007b_002c-PO-Mode-command_007d-469"><code>W</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Comments">Modifying Comments</a></li> +<li><a href="#index-w_0040r_007b_002c-PO-Mode-command_007d-448"><code>w</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-x_0040r_007b_002c-PO-Mode-command_007d-371"><code>x</code><span class="roman">, PO Mode command</span></a>: <a href="#Entry-Positioning">Entry Positioning</a></li> +<li><a href="#index-Y_0040r_007b_002c-PO-Mode-command_007d-470"><code>Y</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Comments">Modifying Comments</a></li> +<li><a href="#index-y_0040r_007b_002c-PO-Mode-command_007d-449"><code>y</code><span class="roman">, PO Mode command</span></a>: <a href="#Modifying-Translations">Modifying Translations</a></li> + </ul><div class="node"> +<a name="Autoconf-Macro-Index"></a> +<p><hr> +Next: <a rel="next" accesskey="n" href="#Index">Index</a>, +Previous: <a rel="previous" accesskey="p" href="#PO-Mode-Index">PO Mode Index</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="unnumbered">Autoconf Macro Index</h2> + + + +<ul class="index-am" compact> +<li><a href="#index-AM_005fGNU_005fGETTEXT-1146"><code>AM_GNU_GETTEXT</code></a>: <a href="#AM_005fGNU_005fGETTEXT">AM_GNU_GETTEXT</a></li> +<li><a href="#index-AM_005fGNU_005fGETTEXT_005fINTL_005fSUBDIR-1150"><code>AM_GNU_GETTEXT_INTL_SUBDIR</code></a>: <a href="#AM_005fGNU_005fGETTEXT_005fINTL_005fSUBDIR">AM_GNU_GETTEXT_INTL_SUBDIR</a></li> +<li><a href="#index-AM_005fGNU_005fGETTEXT_005fNEED-1149"><code>AM_GNU_GETTEXT_NEED</code></a>: <a href="#AM_005fGNU_005fGETTEXT_005fNEED">AM_GNU_GETTEXT_NEED</a></li> +<li><a href="#index-AM_005fGNU_005fGETTEXT_005fVERSION-1148"><code>AM_GNU_GETTEXT_VERSION</code></a>: <a href="#AM_005fGNU_005fGETTEXT_005fVERSION">AM_GNU_GETTEXT_VERSION</a></li> +<li><a href="#index-AM_005fICONV-1153"><code>AM_ICONV</code></a>: <a href="#AM_005fICONV">AM_ICONV</a></li> +<li><a href="#index-AM_005fPO_005fSUBDIRS-1151"><code>AM_PO_SUBDIRS</code></a>: <a href="#AM_005fPO_005fSUBDIRS">AM_PO_SUBDIRS</a></li> +<li><a href="#index-AM_005fXGETTEXT_005fOPTION-1152"><code>AM_XGETTEXT_OPTION</code></a>: <a href="#AM_005fXGETTEXT_005fOPTION">AM_XGETTEXT_OPTION</a></li> + </ul><div class="node"> +<a name="Index"></a> +<p><hr> +Previous: <a rel="previous" accesskey="p" href="#Autoconf-Macro-Index">Autoconf Macro Index</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> + +</div> + +<h2 class="unnumbered">General Index</h2> + + + +<ul class="index-cp" compact> +<li><a href="#index-g_t_0040code_007b_005f_007d_002c-a-macro-to-mark-strings-for-translation-144"><code>_</code>, a macro to mark strings for translation</a>: <a href="#Mark-Keywords">Mark Keywords</a></li> +<li><a href="#index-g_t_0040code_007b_005fnl_005fmsg_005fcat_005fcntr_007d-1110"><code>_nl_msg_cat_cntr</code></a>: <a href="#gettext-grok">gettext grok</a></li> +<li><a href="#index-g_t_0040file_007bABOUT_002dNLS_007d-file-54"><samp><span class="file">ABOUT-NLS</span></samp> file</a>: <a href="#Installing-Localizations">Installing Localizations</a></li> +<li><a href="#index-g_t_0040file_007bacconfig_002eh_007d-file-1139"><samp><span class="file">acconfig.h</span></samp> file</a>: <a href="#acconfig">acconfig</a></li> +<li><a href="#index-accumulating-translations-530">accumulating translations</a>: <a href="#Creating-Compendia">Creating Compendia</a></li> +<li><a href="#index-g_t_0040file_007baclocal_002em4_007d-file-1138"><samp><span class="file">aclocal.m4</span></samp> file</a>: <a href="#aclocal">aclocal</a></li> +<li><a href="#index-adding-keywords_002c-_0040code_007bxgettext_007d-188">adding keywords, <code>xgettext</code></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-ambiguities-132">ambiguities</a>: <a href="#Preparing-Strings">Preparing Strings</a></li> +<li><a href="#index-apply-a-filter-to-translations-681">apply a filter to translations</a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-apply-command-to-all-translations-in-a-catalog-913">apply command to all translations in a catalog</a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-Arabic-digits-1173">Arabic digits</a>: <a href="#c_002dformat">c-format</a></li> +<li><a href="#index-attribute-manipulation-831">attribute manipulation</a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-attribute_002c-fuzzy-404">attribute, fuzzy</a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-attributes-of-a-PO-file-entry-403">attributes of a PO file entry</a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-attributes_002c-manipulating-541">attributes, manipulating</a>: <a href="#Manipulating">Manipulating</a></li> +<li><a href="#index-autoconf-macros-for-_0040code_007bgettext_007d-1145">autoconf macros for <code>gettext</code></a>: <a href="#autoconf-macros">autoconf macros</a></li> +<li><a href="#index-g_t_0040code_007bautopoint_007d-program_002c-usage-1156"><code>autopoint</code> program, usage</a>: <a href="#autopoint-Invocation">autopoint Invocation</a></li> +<li><a href="#index-auxiliary-PO-file-510">auxiliary PO file</a>: <a href="#Auxiliary">Auxiliary</a></li> +<li><a href="#index-available-translations-53">available translations</a>: <a href="#Installing-Localizations">Installing Localizations</a></li> +<li><a href="#index-awk-1234">awk</a>: <a href="#gawk">gawk</a></li> +<li><a href="#index-awk_002dformat_0040r_007b-flag_007d-85"><code>awk-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-backup-old-file_002c-and-_0040code_007bmsgmerge_007d-program-288">backup old file, and <code>msgmerge</code> program</a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-bash-1219">bash</a>: <a href="#bash">bash</a></li> +<li><a href="#index-bibliography-1260">bibliography</a>: <a href="#References">References</a></li> +<li><a href="#index-big-picture-31">big picture</a>: <a href="#Overview">Overview</a></li> +<li><a href="#index-bind_005ftextdomain_005fcodeset-1076"><code>bind_textdomain_codeset</code></a>: <a href="#Charset-conversion">Charset conversion</a></li> +<li><a href="#index-Boost-format-strings-201">Boost format strings</a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-boost_002dformat_0040r_007b-flag_007d-109"><code>boost-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-bug-report-address-4">bug report address</a>: <a href="#Introduction">Introduction</a></li> +<li><a href="#index-C-and-C_002dlike-languages-1174">C and C-like languages</a>: <a href="#C">C</a></li> +<li><a href="#index-C-trigraphs-195">C trigraphs</a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-C_0023-1232">C#</a>: <a href="#C_0023">C#</a></li> +<li><a href="#index-C_0023-mode_002c-and-_0040code_007bmsgfmt_007d-program-957">C# mode, and <code>msgfmt</code> program</a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-C_0023-mode_002c-and-_0040code_007bmsgunfmt_007d-program-1016">C# mode, and <code>msgunfmt</code> program</a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-C_0023-resources-mode_002c-and-_0040code_007bmsgfmt_007d-program-959">C# resources mode, and <code>msgfmt</code> program</a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-C_0023-resources-mode_002c-and-_0040code_007bmsgunfmt_007d-program-1018">C# resources mode, and <code>msgunfmt</code> program</a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-C_0023_002c-string-concatenation-140">C#, string concatenation</a>: <a href="#Preparing-Strings">Preparing Strings</a></li> +<li><a href="#index-c_002dformat_0040r_007b-flag_007d-63"><code>c-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-c_002dformat_0040r_007b_002c-and-_0040code_007bxgettext_007d_007d-155"><code>c-format</code><span class="roman">, and </span><code>xgettext</code></a>: <a href="#c_002dformat-Flag">c-format Flag</a></li> +<li><a href="#index-catalog-encoding-and-_0040code_007bmsgexec_007d-output-918">catalog encoding and <code>msgexec</code> output</a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_0040code_007bcatclose_007d_002c-a-_0040code_007bcatgets_007d-function-1066"><code>catclose</code>, a <code>catgets</code> function</a>: <a href="#Interface-to-catgets">Interface to catgets</a></li> +<li><a href="#index-g_t_0040code_007bcatgets_007d_002c-a-_0040code_007bcatgets_007d-function-1065"><code>catgets</code>, a <code>catgets</code> function</a>: <a href="#Interface-to-catgets">Interface to catgets</a></li> +<li><a href="#index-g_t_0040code_007bcatgets_007d_002c-X_002fOpen-specification-1062"><code>catgets</code>, X/Open specification</a>: <a href="#catgets">catgets</a></li> +<li><a href="#index-g_t_0040code_007bcatopen_007d_002c-a-_0040code_007bcatgets_007d-function-1064"><code>catopen</code>, a <code>catgets</code> function</a>: <a href="#Interface-to-catgets">Interface to catgets</a></li> +<li><a href="#index-character-encoding-17">character encoding</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-charset-conversion-at-runtime-1074">charset conversion at runtime</a>: <a href="#Charset-conversion">Charset conversion</a></li> +<li><a href="#index-charset-of-PO-files-268">charset of PO files</a>: <a href="#Header-Entry">Header Entry</a></li> +<li><a href="#index-check-format-strings-986">check format strings</a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-checking-of-translations-539">checking of translations</a>: <a href="#Manipulating">Manipulating</a></li> +<li><a href="#index-clisp-1223">clisp</a>: <a href="#Common-Lisp">Common Lisp</a></li> +<li><a href="#index-clisp-C-sources-1224">clisp C sources</a>: <a href="#clisp-C">clisp C</a></li> +<li><a href="#index-codeset-15">codeset</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-comments-in-PO-files-117">comments in PO files</a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-comments_002c-automatic-58">comments, automatic</a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-comments_002c-extracted-59">comments, extracted</a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-comments_002c-translator-57">comments, translator</a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-Common-Lisp-1221">Common Lisp</a>: <a href="#Common-Lisp">Common Lisp</a></li> +<li><a href="#index-compare-PO-files-812">compare PO files</a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-comparison-of-interfaces-1097">comparison of interfaces</a>: <a href="#Comparison">Comparison</a></li> +<li><a href="#index-compatibility-with-X_002fOpen-_0040code_007bmsgfmt_007d-991">compatibility with X/Open <code>msgfmt</code></a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-compendium-526">compendium</a>: <a href="#Compendium">Compendium</a></li> +<li><a href="#index-compendium_002c-creating-528">compendium, creating</a>: <a href="#Creating-Compendia">Creating Compendia</a></li> +<li><a href="#index-concatenate-PO-files-544">concatenate PO files</a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-concatenating-PO-files-into-a-compendium-529">concatenating PO files into a compendium</a>: <a href="#Creating-Compendia">Creating Compendia</a></li> +<li><a href="#index-concatenation-of-strings-137">concatenation of strings</a>: <a href="#Preparing-Strings">Preparing Strings</a></li> +<li><a href="#index-g_t_0040file_007bconfig_002eh_002ein_007d-file-1140"><samp><span class="file">config.h.in</span></samp> file</a>: <a href="#config_002eh_002ein">config.h.in</a></li> +<li><a href="#index-context-1077">context</a>: <a href="#Contexts">Contexts</a></li> +<li><a href="#index-context_002c-argument-specification-in-_0040code_007bxgettext_007d-189">context, argument specification in <code>xgettext</code></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-context_002c-in-MO-files-1060">context, in MO files</a>: <a href="#MO-Files">MO Files</a></li> +<li><a href="#index-context_002c-in-PO-files-112">context, in PO files</a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-control-characters-142">control characters</a>: <a href="#Preparing-Strings">Preparing Strings</a></li> +<li><a href="#index-convert-binary-message-catalog-into-PO-file-1011">convert binary message catalog into PO file</a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-convert-translations-to-a-different-encoding-592">convert translations to a different encoding</a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-converting-a-package-to-use-_0040code_007bgettext_007d-1114">converting a package to use <code>gettext</code></a>: <a href="#Prerequisites">Prerequisites</a></li> +<li><a href="#index-country-codes-1263">country codes</a>: <a href="#Country-Codes">Country Codes</a></li> +<li><a href="#index-create-new-PO-file-241">create new PO file</a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-creating-a-new-PO-file-238">creating a new PO file</a>: <a href="#Creating">Creating</a></li> +<li><a href="#index-creating-compendia-527">creating compendia</a>: <a href="#Creating-Compendia">Creating Compendia</a></li> +<li><a href="#index-csharp_002dformat_0040r_007b-flag_007d-83"><code>csharp-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-currency-symbols-19">currency symbols</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-date-format-21">date format</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-dcngettext-1090"><code>dcngettext</code></a>: <a href="#Plural-forms">Plural forms</a></li> +<li><a href="#index-dcpgettext-1083"><code>dcpgettext</code></a>: <a href="#Contexts">Contexts</a></li> +<li><a href="#index-dcpgettext_005fexpr-1086"><code>dcpgettext_expr</code></a>: <a href="#Contexts">Contexts</a></li> +<li><a href="#index-debugging-messages-marked-as-format-strings-203">debugging messages marked as format strings</a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-dialect-537">dialect</a>: <a href="#Manipulating">Manipulating</a></li> +<li><a href="#index-disabling-NLS-1143">disabling NLS</a>: <a href="#lib_002fgettext_002eh">lib/gettext.h</a></li> +<li><a href="#index-distribution-tarball-1164">distribution tarball</a>: <a href="#Release-Management">Release Management</a></li> +<li><a href="#index-dngettext-1089"><code>dngettext</code></a>: <a href="#Plural-forms">Plural forms</a></li> +<li><a href="#index-dollar-substitution-1207">dollar substitution</a>: <a href="#envsubst-Invocation">envsubst Invocation</a></li> +<li><a href="#index-domain-ambiguities-1071">domain ambiguities</a>: <a href="#Ambiguities">Ambiguities</a></li> +<li><a href="#index-dpgettext-1082"><code>dpgettext</code></a>: <a href="#Contexts">Contexts</a></li> +<li><a href="#index-dpgettext_005fexpr-1085"><code>dpgettext_expr</code></a>: <a href="#Contexts">Contexts</a></li> +<li><a href="#index-duplicate-elimination-540">duplicate elimination</a>: <a href="#Manipulating">Manipulating</a></li> +<li><a href="#index-duplicate-removal-730">duplicate removal</a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-editing-comments-in-PO-files-465">editing comments in PO files</a>: <a href="#Modifying-Comments">Modifying Comments</a></li> +<li><a href="#index-Editing-PO-Files-328">Editing PO Files</a>: <a href="#Editing">Editing</a></li> +<li><a href="#index-editing-translations-442">editing translations</a>: <a href="#Modifying-Translations">Modifying Translations</a></li> +<li><a href="#index-elisp_002dformat_0040r_007b-flag_007d-73"><code>elisp-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-Emacs-Lisp-1225">Emacs Lisp</a>: <a href="#Emacs-Lisp">Emacs Lisp</a></li> +<li><a href="#index-Emacs-PO-Mode-331">Emacs PO Mode</a>: <a href="#PO-Mode">PO Mode</a></li> +<li><a href="#index-encoding-16">encoding</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-encoding-conversion-536">encoding conversion</a>: <a href="#Manipulating">Manipulating</a></li> +<li><a href="#index-encoding-conversion-at-runtime-1075">encoding conversion at runtime</a>: <a href="#Charset-conversion">Charset conversion</a></li> +<li><a href="#index-encoding-for-your-language-272">encoding for your language</a>: <a href="#Header-Entry">Header Entry</a></li> +<li><a href="#index-encoding-list-270">encoding list</a>: <a href="#Header-Entry">Header Entry</a></li> +<li><a href="#index-encoding-of-PO-files-267">encoding of PO files</a>: <a href="#Header-Entry">Header Entry</a></li> +<li><a href="#index-environment-variables-1208">environment variables</a>: <a href="#envsubst-Invocation">envsubst Invocation</a></li> +<li><a href="#index-g_t_0040code_007benvsubst_007d-program_002c-usage-1205"><code>envsubst</code> program, usage</a>: <a href="#envsubst-Invocation">envsubst Invocation</a></li> +<li><a href="#index-g_t_0040code_007beval_005fgettext_007d-function_002c-usage-1215"><code>eval_gettext</code> function, usage</a>: <a href="#eval_005fgettext-Invocation">eval_gettext Invocation</a></li> +<li><a href="#index-g_t_0040code_007beval_005fngettext_007d-function_002c-usage-1217"><code>eval_ngettext</code> function, usage</a>: <a href="#eval_005fngettext-Invocation">eval_ngettext Invocation</a></li> +<li><a href="#index-evolution-of-packages-39">evolution of packages</a>: <a href="#Overview">Overview</a></li> +<li><a href="#index-extracting-parts-of-a-PO-file-into-a-compendium-531">extracting parts of a PO file into a compendium</a>: <a href="#Creating-Compendia">Creating Compendia</a></li> +<li><a href="#index-FDL_002c-GNU-Free-Documentation-License-1270">FDL, GNU Free Documentation License</a>: <a href="#GNU-FDL">GNU FDL</a></li> +<li><a href="#index-file-format_002c-_0040file_007b_002emo_007d-1057">file format, <samp><span class="file">.mo</span></samp></a>: <a href="#MO-Files">MO Files</a></li> +<li><a href="#index-file-format_002c-_0040file_007b_002epo_007d-56">file format, <samp><span class="file">.po</span></samp></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-files_002c-_0040file_007b_002epo_007d-and-_0040file_007b_002emo_007d-29">files, <samp><span class="file">.po</span></samp> and <samp><span class="file">.mo</span></samp></a>: <a href="#Files">Files</a></li> +<li><a href="#index-files_002c-_0040file_007b_002epot_007d-38">files, <samp><span class="file">.pot</span></samp></a>: <a href="#Overview">Overview</a></li> +<li><a href="#index-filter-messages-according-to-attributes-830">filter messages according to attributes</a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-find-common-messages-770">find common messages</a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-force-use-of-fuzzy-entries-998">force use of fuzzy entries</a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-format-strings-154">format strings</a>: <a href="#c_002dformat-Flag">c-format Flag</a></li> +<li><a href="#index-Free-Pascal-1237">Free Pascal</a>: <a href="#Pascal">Pascal</a></li> +<li><a href="#index-function-attribute_002c-_005f_005fformat_005f_005f-191">function attribute, __format__</a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-function-attribute_002c-_005f_005fformat_005farg_005f_005f-192">function attribute, __format_arg__</a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-fuzzy-entries-402">fuzzy entries</a>: <a href="#Fuzzy-Entries">Fuzzy Entries</a></li> +<li><a href="#index-fuzzy_0040r_007b-flag_007d-62"><code>fuzzy</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-gawk-1235">gawk</a>: <a href="#gawk">gawk</a></li> +<li><a href="#index-gcc_002dinternal_002dformat_0040r_007b-flag_007d-99"><code>gcc-internal-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-GCC_002dsource-1256">GCC-source</a>: <a href="#GCC_002dsource">GCC-source</a></li> +<li><a href="#index-generate-binary-message-catalog-from-PO-file-949">generate binary message catalog from PO file</a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-generate-translation-catalog-in-English-880">generate translation catalog in English</a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_0040code_007bgettext_007d-files-1129"><code>gettext</code> files</a>: <a href="#Adjusting-Files">Adjusting Files</a></li> +<li><a href="#index-g_t_0040code_007bgettext_007d-installation-333"><code>gettext</code> installation</a>: <a href="#Installation">Installation</a></li> +<li><a href="#index-g_t_0040code_007bgettext_007d-interface-1069"><code>gettext</code> interface</a>: <a href="#Interface-to-gettext">Interface to gettext</a></li> +<li><a href="#index-g_t_0040code_007bgettext_007d-program_002c-usage-1182"><code>gettext</code> program, usage</a>: <a href="#gettext-Invocation">gettext Invocation</a></li> +<li><a href="#index-g_t_0040code_007bgettext_007d-vs-_0040code_007bcatgets_007d-1096"><code>gettext</code> vs <code>catgets</code></a>: <a href="#Comparison">Comparison</a></li> +<li><a href="#index-g_t_0040code_007bgettext_007d_002c-a-programmer_0027s-view-1068"><code>gettext</code>, a programmer's view</a>: <a href="#gettext">gettext</a></li> +<li><a href="#index-g_t_0040file_007bgettext_002eh_007d-file-1141"><samp><span class="file">gettext.h</span></samp> file</a>: <a href="#lib_002fgettext_002eh">lib/gettext.h</a></li> +<li><a href="#index-g_t_0040code_007bgettextize_007d-program_002c-usage-1118"><code>gettextize</code> program, usage</a>: <a href="#gettextize-Invocation">gettextize Invocation</a></li> +<li><a href="#index-gfc_002dinternal_002dformat_0040r_007b-flag_007d-101"><code>gfc-internal-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-GNOME-PO-file-editor-330">GNOME PO file editor</a>: <a href="#Gtranslator">Gtranslator</a></li> +<li><a href="#index-GPL_002c-GNU-General-Public-License-1266">GPL, GNU General Public License</a>: <a href="#GNU-GPL">GNU GPL</a></li> +<li><a href="#index-GUI-programs-1078">GUI programs</a>: <a href="#Contexts">Contexts</a></li> +<li><a href="#index-guile-1228">guile</a>: <a href="#Scheme">Scheme</a></li> +<li><a href="#index-hash-table_002c-inside-MO-files-1059">hash table, inside MO files</a>: <a href="#MO-Files">MO Files</a></li> +<li><a href="#index-he_002c-she_002c-and-they-2">he, she, and they</a>: <a href="#Introduction">Introduction</a></li> +<li><a href="#index-header-entry-of-a-PO-file-265">header entry of a PO file</a>: <a href="#Header-Entry">Header Entry</a></li> +<li><a href="#index-help-option-135">help option</a>: <a href="#Preparing-Strings">Preparing Strings</a></li> +<li><a href="#index-history-of-GNU-_0040code_007bgettext_007d-1258">history of GNU <code>gettext</code></a>: <a href="#History">History</a></li> +<li><a href="#index-i18n-6">i18n</a>: <a href="#Concepts">Concepts</a></li> +<li><a href="#index-importing-PO-files-391">importing PO files</a>: <a href="#Normalizing">Normalizing</a></li> +<li><a href="#index-include-file-_0040file_007blibintl_002eh_007d-1144">include file <samp><span class="file">libintl.h</span></samp></a>: <a href="#lib_002fgettext_002eh">lib/gettext.h</a></li> +<li><a href="#index-include-file-_0040file_007blibintl_002eh_007d-1098">include file <samp><span class="file">libintl.h</span></samp></a>: <a href="#Comparison">Comparison</a></li> +<li><a href="#index-include-file-_0040file_007blibintl_002eh_007d-119">include file <samp><span class="file">libintl.h</span></samp></a>: <a href="#Importing">Importing</a></li> +<li><a href="#index-include-file-_0040file_007blibintl_002eh_007d-34">include file <samp><span class="file">libintl.h</span></samp></a>: <a href="#Overview">Overview</a></li> +<li><a href="#index-initialization-120">initialization</a>: <a href="#Triggering">Triggering</a></li> +<li><a href="#index-initialize-new-PO-file-242">initialize new PO file</a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-initialize-translations-from-a-compendium-532">initialize translations from a compendium</a>: <a href="#Using-Compendia">Using Compendia</a></li> +<li><a href="#index-installing-_0040code_007bgettext_007d-332">installing <code>gettext</code></a>: <a href="#Installation">Installation</a></li> +<li><a href="#index-interface-to-_0040code_007bcatgets_007d-1063">interface to <code>catgets</code></a>: <a href="#Interface-to-catgets">Interface to catgets</a></li> +<li><a href="#index-internationalization-8">internationalization</a>: <a href="#Concepts">Concepts</a></li> +<li><a href="#index-g_t_0040code_007binttypes_002eh_007d-138"><code>inttypes.h</code></a>: <a href="#Preparing-Strings">Preparing Strings</a></li> +<li><a href="#index-ISO-3166-1264">ISO 3166</a>: <a href="#Country-Codes">Country Codes</a></li> +<li><a href="#index-ISO-639-1262">ISO 639</a>: <a href="#Language-Codes">Language Codes</a></li> +<li><a href="#index-Java-1230">Java</a>: <a href="#Java">Java</a></li> +<li><a href="#index-Java-mode_002c-and-_0040code_007bmsgfmt_007d-program-954">Java mode, and <code>msgfmt</code> program</a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-Java-mode_002c-and-_0040code_007bmsgunfmt_007d-program-1014">Java mode, and <code>msgunfmt</code> program</a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-Java_002c-string-concatenation-139">Java, string concatenation</a>: <a href="#Preparing-Strings">Preparing Strings</a></li> +<li><a href="#index-java_002dformat_0040r_007b-flag_007d-81"><code>java-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-KDE-format-strings-199">KDE format strings</a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-KDE-PO-file-editor-329">KDE PO file editor</a>: <a href="#KBabel">KBabel</a></li> +<li><a href="#index-kde_002dformat_0040r_007b-flag_007d-107"><code>kde-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-keyboard-accelerator-checking-993">keyboard accelerator checking</a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-l10n-7">l10n</a>: <a href="#Concepts">Concepts</a></li> +<li><a href="#index-language-codes-1261">language codes</a>: <a href="#Language-Codes">Language Codes</a></li> +<li><a href="#index-language-selection-42">language selection</a>: <a href="#Locale-Environment-Variables">Locale Environment Variables</a></li> +<li><a href="#index-language-selection-at-runtime-1100">language selection at runtime</a>: <a href="#gettext-grok">gettext grok</a></li> +<li><a href="#index-large-package-1072">large package</a>: <a href="#Ambiguities">Ambiguities</a></li> +<li><a href="#index-LGPL_002c-GNU-Lesser-General-Public-License-1268">LGPL, GNU Lesser General Public License</a>: <a href="#GNU-LGPL">GNU LGPL</a></li> +<li><a href="#index-g_t_0040code_007blibiconv_007d-library-1154"><code>libiconv</code> library</a>: <a href="#AM_005fICONV">AM_ICONV</a></li> +<li><a href="#index-g_t_0040code_007blibintl_007d-for-C_0023-1233"><code>libintl</code> for C#</a>: <a href="#C_0023">C#</a></li> +<li><a href="#index-g_t_0040code_007blibintl_007d-for-Java-1231"><code>libintl</code> for Java</a>: <a href="#Java">Java</a></li> +<li><a href="#index-g_t_0040code_007blibintl_007d-library-1147"><code>libintl</code> library</a>: <a href="#AM_005fGNU_005fGETTEXT">AM_GNU_GETTEXT</a></li> +<li><a href="#index-g_t_0040code_007blibrep_007d-Lisp-1226"><code>librep</code> Lisp</a>: <a href="#librep">librep</a></li> +<li><a href="#index-librep_002dformat_0040r_007b-flag_007d-75"><code>librep-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-License_002c-GNU-FDL-1271">License, GNU FDL</a>: <a href="#GNU-FDL">GNU FDL</a></li> +<li><a href="#index-License_002c-GNU-GPL-1267">License, GNU GPL</a>: <a href="#GNU-GPL">GNU GPL</a></li> +<li><a href="#index-License_002c-GNU-LGPL-1269">License, GNU LGPL</a>: <a href="#GNU-LGPL">GNU LGPL</a></li> +<li><a href="#index-Licenses-1265">Licenses</a>: <a href="#Licenses">Licenses</a></li> +<li><a href="#index-g_t_0040file_007bLINGUAS_007d-file-1131"><samp><span class="file">LINGUAS</span></samp> file</a>: <a href="#po_002fLINGUAS">po/LINGUAS</a></li> +<li><a href="#index-link-with-_0040file_007blibintl_007d-35">link with <samp><span class="file">libintl</span></samp></a>: <a href="#Overview">Overview</a></li> +<li><a href="#index-Linux-271">Linux</a>: <a href="#Header-Entry">Header Entry</a></li> +<li><a href="#index-Linux-36">Linux</a>: <a href="#Overview">Overview</a></li> +<li><a href="#index-Linux-28">Linux</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-Lisp-1222">Lisp</a>: <a href="#Common-Lisp">Common Lisp</a></li> +<li><a href="#index-lisp_002dformat_0040r_007b-flag_007d-71"><code>lisp-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-list-of-translation-teams_002c-where-to-find-266">list of translation teams, where to find</a>: <a href="#Header-Entry">Header Entry</a></li> +<li><a href="#index-locale-categories-14">locale categories</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-locale-category_002c-LC_005fALL-121">locale category, LC_ALL</a>: <a href="#Triggering">Triggering</a></li> +<li><a href="#index-locale-category_002c-LC_005fCOLLATE-124">locale category, LC_COLLATE</a>: <a href="#Triggering">Triggering</a></li> +<li><a href="#index-locale-category_002c-LC_005fCTYPE-122">locale category, LC_CTYPE</a>: <a href="#Triggering">Triggering</a></li> +<li><a href="#index-locale-category_002c-LC_005fCTYPE-18">locale category, LC_CTYPE</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-locale-category_002c-LC_005fMESSAGES-128">locale category, LC_MESSAGES</a>: <a href="#Triggering">Triggering</a></li> +<li><a href="#index-locale-category_002c-LC_005fMESSAGES-26">locale category, LC_MESSAGES</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-locale-category_002c-LC_005fMONETARY-125">locale category, LC_MONETARY</a>: <a href="#Triggering">Triggering</a></li> +<li><a href="#index-locale-category_002c-LC_005fMONETARY-20">locale category, LC_MONETARY</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-locale-category_002c-LC_005fNUMERIC-126">locale category, LC_NUMERIC</a>: <a href="#Triggering">Triggering</a></li> +<li><a href="#index-locale-category_002c-LC_005fNUMERIC-24">locale category, LC_NUMERIC</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-locale-category_002c-LC_005fRESPONSES-129">locale category, LC_RESPONSES</a>: <a href="#Triggering">Triggering</a></li> +<li><a href="#index-locale-category_002c-LC_005fTIME-127">locale category, LC_TIME</a>: <a href="#Triggering">Triggering</a></li> +<li><a href="#index-locale-category_002c-LC_005fTIME-22">locale category, LC_TIME</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-g_t_0040code_007blocale_007d-program-269"><code>locale</code> program</a>: <a href="#Header-Entry">Header Entry</a></li> +<li><a href="#index-localization-9">localization</a>: <a href="#Concepts">Concepts</a></li> +<li><a href="#index-lookup-message-translation-1216">lookup message translation</a>: <a href="#eval_005fgettext-Invocation">eval_gettext Invocation</a></li> +<li><a href="#index-lookup-message-translation-1183">lookup message translation</a>: <a href="#gettext-Invocation">gettext Invocation</a></li> +<li><a href="#index-lookup-plural-message-translation-1218">lookup plural message translation</a>: <a href="#eval_005fngettext-Invocation">eval_ngettext Invocation</a></li> +<li><a href="#index-lookup-plural-message-translation-1195">lookup plural message translation</a>: <a href="#ngettext-Invocation">ngettext Invocation</a></li> +<li><a href="#index-magic-signature-of-MO-files-1058">magic signature of MO files</a>: <a href="#MO-Files">MO Files</a></li> +<li><a href="#index-g_t_0040file_007bMakefile_002ein_002ein_007d-extensions-1133"><samp><span class="file">Makefile.in.in</span></samp> extensions</a>: <a href="#po_002fRules_002d_002a">po/Rules-*</a></li> +<li><a href="#index-g_t_0040file_007bMakevars_007d-file-1132"><samp><span class="file">Makevars</span></samp> file</a>: <a href="#po_002fMakevars">po/Makevars</a></li> +<li><a href="#index-manipulating-PO-files-534">manipulating PO files</a>: <a href="#Manipulating">Manipulating</a></li> +<li><a href="#index-marking-Perl-sources-1245">marking Perl sources</a>: <a href="#Perl">Perl</a></li> +<li><a href="#index-marking-string-initializers-157">marking string initializers</a>: <a href="#Special-cases">Special cases</a></li> +<li><a href="#index-marking-strings-that-require-translation-143">marking strings that require translation</a>: <a href="#Mark-Keywords">Mark Keywords</a></li> +<li><a href="#index-marking-strings_002c-preparations-130">marking strings, preparations</a>: <a href="#Preparing-Strings">Preparing Strings</a></li> +<li><a href="#index-marking-translatable-strings-33">marking translatable strings</a>: <a href="#Overview">Overview</a></li> +<li><a href="#index-markup-141">markup</a>: <a href="#Preparing-Strings">Preparing Strings</a></li> +<li><a href="#index-menu-entries-1080">menu entries</a>: <a href="#Contexts">Contexts</a></li> +<li><a href="#index-menu_002c-keyboard-accelerator-support-994">menu, keyboard accelerator support</a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-merge-PO-files-545">merge PO files</a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-merging-two-PO-files-535">merging two PO files</a>: <a href="#Manipulating">Manipulating</a></li> +<li><a href="#index-message-catalog-files-location-1073">message catalog files location</a>: <a href="#Locating-Catalogs">Locating Catalogs</a></li> +<li><a href="#index-messages-25">messages</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-migration-from-earlier-versions-of-_0040code_007bgettext_007d-1115">migration from earlier versions of <code>gettext</code></a>: <a href="#Prerequisites">Prerequisites</a></li> +<li><a href="#index-g_t_0040file_007bmkinstalldirs_007d-file-1137"><samp><span class="file">mkinstalldirs</span></samp> file</a>: <a href="#mkinstalldirs">mkinstalldirs</a></li> +<li><a href="#index-mnemonics-of-menu-entries-995">mnemonics of menu entries</a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-MO-file_0027s-format-1056">MO file's format</a>: <a href="#MO-Files">MO Files</a></li> +<li><a href="#index-modify-message-attributes-842">modify message attributes</a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_0040code_007bmsgattrib_007d-program_002c-usage-829"><code>msgattrib</code> program, usage</a>: <a href="#msgattrib-Invocation">msgattrib Invocation</a></li> +<li><a href="#index-g_t_0040code_007bmsgcat_007d-program_002c-usage-543"><code>msgcat</code> program, usage</a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-g_t_0040code_007bmsgcmp_007d-program_002c-usage-811"><code>msgcmp</code> program, usage</a>: <a href="#msgcmp-Invocation">msgcmp Invocation</a></li> +<li><a href="#index-g_t_0040code_007bmsgcomm_007d-program_002c-usage-769"><code>msgcomm</code> program, usage</a>: <a href="#msgcomm-Invocation">msgcomm Invocation</a></li> +<li><a href="#index-g_t_0040code_007bmsgconv_007d-program_002c-usage-591"><code>msgconv</code> program, usage</a>: <a href="#msgconv-Invocation">msgconv Invocation</a></li> +<li><a href="#index-msgctxt-111"><code>msgctxt</code></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-g_t_0040code_007bmsgen_007d-program_002c-usage-879"><code>msgen</code> program, usage</a>: <a href="#msgen-Invocation">msgen Invocation</a></li> +<li><a href="#index-g_t_0040code_007bmsgexec_007d-program_002c-usage-912"><code>msgexec</code> program, usage</a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_0040code_007bmsgfilter_007d-filter-and-catalog-encoding-691"><code>msgfilter</code> filter and catalog encoding</a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_0040code_007bmsgfilter_007d-program_002c-usage-680"><code>msgfilter</code> program, usage</a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_0040code_007bmsgfmt_007d-program_002c-usage-948"><code>msgfmt</code> program, usage</a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-g_t_0040code_007bmsggrep_007d-program_002c-usage-625"><code>msggrep</code> program, usage</a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-msgid-60"><code>msgid</code></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-msgid_005fplural-113"><code>msgid_plural</code></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-g_t_0040code_007bmsginit_007d-program_002c-usage-240"><code>msginit</code> program, usage</a>: <a href="#msginit-Invocation">msginit Invocation</a></li> +<li><a href="#index-g_t_0040code_007bmsgmerge_007d-program_002c-usage-277"><code>msgmerge</code> program, usage</a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-msgstr-61"><code>msgstr</code></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-g_t_0040code_007bmsgunfmt_007d-program_002c-usage-1010"><code>msgunfmt</code> program, usage</a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-g_t_0040code_007bmsguniq_007d-program_002c-usage-728"><code>msguniq</code> program, usage</a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-multi_002dline-strings-392">multi-line strings</a>: <a href="#Normalizing">Normalizing</a></li> +<li><a href="#index-g_t_0040code_007bN_005f_007d_002c-a-convenience-macro-1099"><code>N_</code>, a convenience macro</a>: <a href="#Comparison">Comparison</a></li> +<li><a href="#index-Native-Language-Support-11">Native Language Support</a>: <a href="#Concepts">Concepts</a></li> +<li><a href="#index-Natural-Language-Support-12">Natural Language Support</a>: <a href="#Concepts">Concepts</a></li> +<li><a href="#index-newlines-in-PO-files-116">newlines in PO files</a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-ngettext-1088"><code>ngettext</code></a>: <a href="#Plural-forms">Plural forms</a></li> +<li><a href="#index-g_t_0040code_007bngettext_007d-program_002c-usage-1194"><code>ngettext</code> program, usage</a>: <a href="#ngettext-Invocation">ngettext Invocation</a></li> +<li><a href="#index-NLS-10">NLS</a>: <a href="#Concepts">Concepts</a></li> +<li><a href="#index-no_002dawk_002dformat_0040r_007b-flag_007d-86"><code>no-awk-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dboost_002dformat_0040r_007b-flag_007d-110"><code>no-boost-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dc_002dformat_0040r_007b-flag_007d-64"><code>no-c-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dc_002dformat_0040r_007b_002c-and-_0040code_007bxgettext_007d_007d-156"><code>no-c-format</code><span class="roman">, and </span><code>xgettext</code></a>: <a href="#c_002dformat-Flag">c-format Flag</a></li> +<li><a href="#index-no_002dcsharp_002dformat_0040r_007b-flag_007d-84"><code>no-csharp-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002delisp_002dformat_0040r_007b-flag_007d-74"><code>no-elisp-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dgcc_002dinternal_002dformat_0040r_007b-flag_007d-100"><code>no-gcc-internal-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dgfc_002dinternal_002dformat_0040r_007b-flag_007d-102"><code>no-gfc-internal-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002djava_002dformat_0040r_007b-flag_007d-82"><code>no-java-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dkde_002dformat_0040r_007b-flag_007d-108"><code>no-kde-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dlibrep_002dformat_0040r_007b-flag_007d-76"><code>no-librep-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dlisp_002dformat_0040r_007b-flag_007d-72"><code>no-lisp-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dobjc_002dformat_0040r_007b-flag_007d-66"><code>no-objc-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dobject_002dpascal_002dformat_0040r_007b-flag_007d-88"><code>no-object-pascal-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dperl_002dbrace_002dformat_0040r_007b-flag_007d-96"><code>no-perl-brace-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dperl_002dformat_0040r_007b-flag_007d-94"><code>no-perl-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dphp_002dformat_0040r_007b-flag_007d-98"><code>no-php-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dpython_002dformat_0040r_007b-flag_007d-70"><code>no-python-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dqt_002dformat_0040r_007b-flag_007d-104"><code>no-qt-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dqt_002dplural_002dformat_0040r_007b-flag_007d-106"><code>no-qt-plural-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dscheme_002dformat_0040r_007b-flag_007d-78"><code>no-scheme-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dsh_002dformat_0040r_007b-flag_007d-68"><code>no-sh-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dsmalltalk_002dformat_0040r_007b-flag_007d-80"><code>no-smalltalk-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dtcl_002dformat_0040r_007b-flag_007d-92"><code>no-tcl-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-no_002dycp_002dformat_0040r_007b-flag_007d-90"><code>no-ycp-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-nplurals_0040r_007b_002c-in-a-PO-file-header_007d-1092"><code>nplurals</code><span class="roman">, in a PO file header</span></a>: <a href="#Plural-forms">Plural forms</a></li> +<li><a href="#index-number-format-23">number format</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-objc_002dformat_0040r_007b-flag_007d-65"><code>objc-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-Object-Pascal-1238">Object Pascal</a>: <a href="#Pascal">Pascal</a></li> +<li><a href="#index-object_002dpascal_002dformat_0040r_007b-flag_007d-87"><code>object-pascal-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-obsolete-entries-429">obsolete entries</a>: <a href="#Obsolete-Entries">Obsolete Entries</a></li> +<li><a href="#index-optimization-of-_0040code_007bgettext_007d-functions-1095">optimization of <code>gettext</code> functions</a>: <a href="#Optimized-gettext">Optimized gettext</a></li> +<li><a href="#index-orthography-538">orthography</a>: <a href="#Manipulating">Manipulating</a></li> +<li><a href="#index-outdigits-1172">outdigits</a>: <a href="#c_002dformat">c-format</a></li> +<li><a href="#index-output-to-stdout_002c-_0040code_007bxgettext_007d-171">output to stdout, <code>xgettext</code></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-overview-of-_0040code_007bgettext_007d-30">overview of <code>gettext</code></a>: <a href="#Overview">Overview</a></li> +<li><a href="#index-package-and-version-declaration-in-_0040file_007bconfigure_002eac_007d-1136">package and version declaration in <samp><span class="file">configure.ac</span></samp></a>: <a href="#configure_002eac">configure.ac</a></li> +<li><a href="#index-package-build-and-installation-options-1167">package build and installation options</a>: <a href="#Installers">Installers</a></li> +<li><a href="#index-package-distributor_0027s-view-of-_0040code_007bgettext_007d-1166">package distributor's view of <code>gettext</code></a>: <a href="#Installers">Installers</a></li> +<li><a href="#index-package-installer_0027s-view-of-_0040code_007bgettext_007d-1165">package installer's view of <code>gettext</code></a>: <a href="#Installers">Installers</a></li> +<li><a href="#index-package-maintainer_0027s-view-of-_0040code_007bgettext_007d-1113">package maintainer's view of <code>gettext</code></a>: <a href="#Maintainers">Maintainers</a></li> +<li><a href="#index-paragraphs-134">paragraphs</a>: <a href="#Preparing-Strings">Preparing Strings</a></li> +<li><a href="#index-Pascal-1236">Pascal</a>: <a href="#Pascal">Pascal</a></li> +<li><a href="#index-Perl-1244">Perl</a>: <a href="#Perl">Perl</a></li> +<li><a href="#index-Perl-default-keywords-1246">Perl default keywords</a>: <a href="#Default-Keywords">Default Keywords</a></li> +<li><a href="#index-Perl-invalid-string-interpolation-1249">Perl invalid string interpolation</a>: <a href="#Interpolation-I">Interpolation I</a></li> +<li><a href="#index-Perl-long-lines-1252">Perl long lines</a>: <a href="#Long-Lines">Long Lines</a></li> +<li><a href="#index-Perl-parentheses-1251">Perl parentheses</a>: <a href="#Parentheses">Parentheses</a></li> +<li><a href="#index-Perl-pitfalls-1253">Perl pitfalls</a>: <a href="#Perl-Pitfalls">Perl Pitfalls</a></li> +<li><a href="#index-Perl-quote_002dlike-expressions-1248">Perl quote-like expressions</a>: <a href="#Quote_002dlike-Expressions">Quote-like Expressions</a></li> +<li><a href="#index-Perl-special-keywords-for-hash_002dlookups-1247">Perl special keywords for hash-lookups</a>: <a href="#Special-Keywords">Special Keywords</a></li> +<li><a href="#index-Perl-valid-string-interpolation-1250">Perl valid string interpolation</a>: <a href="#Interpolation-II">Interpolation II</a></li> +<li><a href="#index-perl_002dbrace_002dformat_0040r_007b-flag_007d-95"><code>perl-brace-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-perl_002dformat_0040r_007b-flag_007d-93"><code>perl-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-pgettext-1081"><code>pgettext</code></a>: <a href="#Contexts">Contexts</a></li> +<li><a href="#index-pgettext_005fexpr-1084"><code>pgettext_expr</code></a>: <a href="#Contexts">Contexts</a></li> +<li><a href="#index-PHP-1254">PHP</a>: <a href="#PHP">PHP</a></li> +<li><a href="#index-php_002dformat_0040r_007b-flag_007d-97"><code>php-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-Pike-1255">Pike</a>: <a href="#Pike">Pike</a></li> +<li><a href="#index-plural-form-formulas-1094">plural form formulas</a>: <a href="#Plural-forms">Plural forms</a></li> +<li><a href="#index-plural-forms-1087">plural forms</a>: <a href="#Plural-forms">Plural forms</a></li> +<li><a href="#index-plural-forms_002c-in-MO-files-1061">plural forms, in MO files</a>: <a href="#MO-Files">MO Files</a></li> +<li><a href="#index-plural-forms_002c-in-PO-files-114">plural forms, in PO files</a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-plural-forms_002c-translating-1111">plural forms, translating</a>: <a href="#Translating-plural-forms">Translating plural forms</a></li> +<li><a href="#index-plural_0040r_007b_002c-in-a-PO-file-header_007d-1093"><code>plural</code><span class="roman">, in a PO file header</span></a>: <a href="#Plural-forms">Plural forms</a></li> +<li><a href="#index-PO-files_0027-format-55">PO files' format</a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-PO-mode-_0028Emacs_0029-commands-336">PO mode (Emacs) commands</a>: <a href="#Main-PO-Commands">Main PO Commands</a></li> +<li><a href="#index-PO-template-file-158">PO template file</a>: <a href="#Template">Template</a></li> +<li><a href="#index-po_005ffile_005fdomains-939"><code>po_file_domains</code></a>: <a href="#libgettextpo">libgettextpo</a></li> +<li><a href="#index-po_005ffile_005ffree-938"><code>po_file_free</code></a>: <a href="#libgettextpo">libgettextpo</a></li> +<li><a href="#index-po_005ffile_005fread-937"><code>po_file_read</code></a>: <a href="#libgettextpo">libgettextpo</a></li> +<li><a href="#index-po_005fmessage_005fiterator-940"><code>po_message_iterator</code></a>: <a href="#libgettextpo">libgettextpo</a></li> +<li><a href="#index-po_005fmessage_005fiterator_005ffree-941"><code>po_message_iterator_free</code></a>: <a href="#libgettextpo">libgettextpo</a></li> +<li><a href="#index-po_005fmessage_005fmsgid-943"><code>po_message_msgid</code></a>: <a href="#libgettextpo">libgettextpo</a></li> +<li><a href="#index-po_005fmessage_005fmsgid_005fplural-944"><code>po_message_msgid_plural</code></a>: <a href="#libgettextpo">libgettextpo</a></li> +<li><a href="#index-po_005fmessage_005fmsgstr-945"><code>po_message_msgstr</code></a>: <a href="#libgettextpo">libgettextpo</a></li> +<li><a href="#index-po_005fmessage_005fmsgstr_005fplural-946"><code>po_message_msgstr_plural</code></a>: <a href="#libgettextpo">libgettextpo</a></li> +<li><a href="#index-po_005fnext_005fmessage-942"><code>po_next_message</code></a>: <a href="#libgettextpo">libgettextpo</a></li> +<li><a href="#index-portability-problems-with-_0040code_007bsed_007d-692">portability problems with <code>sed</code></a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-g_t_0040file_007bPOTFILES_002ein_007d-file-1130"><samp><span class="file">POTFILES.in</span></samp> file</a>: <a href="#po_002fPOTFILES_002ein">po/POTFILES.in</a></li> +<li><a href="#index-preparing-programs-for-translation-118">preparing programs for translation</a>: <a href="#Sources">Sources</a></li> +<li><a href="#index-preparing-shell-scripts-for-translation-1180">preparing shell scripts for translation</a>: <a href="#Preparing-Shell-Scripts">Preparing Shell Scripts</a></li> +<li><a href="#index-problems-with-_0040code_007bcatgets_007d-interface-1067">problems with <code>catgets</code> interface</a>: <a href="#Problems-with-catgets">Problems with catgets</a></li> +<li><a href="#index-programming-languages-1170">programming languages</a>: <a href="#Language-Implementors">Language Implementors</a></li> +<li><a href="#index-Python-1220">Python</a>: <a href="#Python">Python</a></li> +<li><a href="#index-python_002dformat_0040r_007b-flag_007d-69"><code>python-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-Qt-format-strings-197">Qt format strings</a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-Qt-mode_002c-and-_0040code_007bmsgfmt_007d-program-963">Qt mode, and <code>msgfmt</code> program</a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-qt_002dformat_0040r_007b-flag_007d-103"><code>qt-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-qt_002dplural_002dformat_0040r_007b-flag_007d-105"><code>qt-plural-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-quotation-marks-1134">quotation marks</a>: <a href="#po_002fRules_002d_002a">po/Rules-*</a></li> +<li><a href="#index-quotation-marks-274">quotation marks</a>: <a href="#Header-Entry">Header Entry</a></li> +<li><a href="#index-quote-characters_002c-use-in-PO-files-273">quote characters, use in PO files</a>: <a href="#Header-Entry">Header Entry</a></li> +<li><a href="#index-range_003a_0040r_007b-flag_007d-115"><code>range:</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-g_t_0040code_007brecode_002dsr_002dlatin_007d-program-701"><code>recode-sr-latin</code> program</a>: <a href="#msgfilter-Invocation">msgfilter Invocation</a></li> +<li><a href="#index-related-reading-1259">related reading</a>: <a href="#References">References</a></li> +<li><a href="#index-release-1163">release</a>: <a href="#Release-Management">Release Management</a></li> +<li><a href="#index-RST-1257">RST</a>: <a href="#RST">RST</a></li> +<li><a href="#index-Scheme-1227">Scheme</a>: <a href="#Scheme">Scheme</a></li> +<li><a href="#index-scheme_002dformat_0040r_007b-flag_007d-77"><code>scheme-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-scripting-languages-1171">scripting languages</a>: <a href="#Language-Implementors">Language Implementors</a></li> +<li><a href="#index-search-messages-in-a-catalog-626">search messages in a catalog</a>: <a href="#msggrep-Invocation">msggrep Invocation</a></li> +<li><a href="#index-selecting-message-language-41">selecting message language</a>: <a href="#Locale-Environment-Variables">Locale Environment Variables</a></li> +<li><a href="#index-sentences-133">sentences</a>: <a href="#Preparing-Strings">Preparing Strings</a></li> +<li><a href="#index-setting-up-_0040code_007bgettext_007d-at-build-time-1168">setting up <code>gettext</code> at build time</a>: <a href="#Installers">Installers</a></li> +<li><a href="#index-setting-up-_0040code_007bgettext_007d-at-run-time-40">setting up <code>gettext</code> at run time</a>: <a href="#Locale-Environment-Variables">Locale Environment Variables</a></li> +<li><a href="#index-several-domains-1070">several domains</a>: <a href="#Ambiguities">Ambiguities</a></li> +<li><a href="#index-sex-1">sex</a>: <a href="#Introduction">Introduction</a></li> +<li><a href="#index-sh_002dformat_0040r_007b-flag_007d-67"><code>sh-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-she_002c-he_002c-and-they-3">she, he, and they</a>: <a href="#Introduction">Introduction</a></li> +<li><a href="#index-shell-format-string-1206">shell format string</a>: <a href="#envsubst-Invocation">envsubst Invocation</a></li> +<li><a href="#index-shell-scripts-1175">shell scripts</a>: <a href="#sh">sh</a></li> +<li><a href="#index-Smalltalk-1229">Smalltalk</a>: <a href="#Smalltalk">Smalltalk</a></li> +<li><a href="#index-smalltalk_002dformat_0040r_007b-flag_007d-79"><code>smalltalk-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-sorting-_0040code_007bmsgcat_007d-output-583">sorting <code>msgcat</code> output</a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-sorting-_0040code_007bmsgmerge_007d-output-316">sorting <code>msgmerge</code> output</a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-sorting-_0040code_007bmsgunfmt_007d-output-1049">sorting <code>msgunfmt</code> output</a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-sorting-output-of-_0040code_007bxgettext_007d-220">sorting output of <code>xgettext</code></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-specifying-plural-form-in-a-PO-file-1091">specifying plural form in a PO file</a>: <a href="#Plural-forms">Plural forms</a></li> +<li><a href="#index-standard-output_002c-and-_0040code_007bmsgcat_007d-552">standard output, and <code>msgcat</code></a>: <a href="#msgcat-Invocation">msgcat Invocation</a></li> +<li><a href="#index-standard-output_002c-and-_0040code_007bmsgmerge_007d-program-286">standard output, and <code>msgmerge</code> program</a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-string-concatenation-136">string concatenation</a>: <a href="#Preparing-Strings">Preparing Strings</a></li> +<li><a href="#index-string-normalization-in-entries-388">string normalization in entries</a>: <a href="#Normalizing">Normalizing</a></li> +<li><a href="#index-style-131">style</a>: <a href="#Preparing-Strings">Preparing Strings</a></li> +<li><a href="#index-supported-languages_002c-_0040code_007bxgettext_007d-174">supported languages, <code>xgettext</code></a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-Tcl-1242">Tcl</a>: <a href="#Tcl">Tcl</a></li> +<li><a href="#index-Tcl-mode_002c-and-_0040code_007bmsgfmt_007d-program-961">Tcl mode, and <code>msgfmt</code> program</a>: <a href="#msgfmt-Invocation">msgfmt Invocation</a></li> +<li><a href="#index-Tcl-mode_002c-and-_0040code_007bmsgunfmt_007d-program-1020">Tcl mode, and <code>msgunfmt</code> program</a>: <a href="#msgunfmt-Invocation">msgunfmt Invocation</a></li> +<li><a href="#index-tcl_002dformat_0040r_007b-flag_007d-91"><code>tcl-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> +<li><a href="#index-template-PO-file-37">template PO file</a>: <a href="#Overview">Overview</a></li> +<li><a href="#index-testing-_0040file_007b_002epo_007d-files-for-equivalence-224">testing <samp><span class="file">.po</span></samp> files for equivalence</a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-Tk_0027s-scripting-language-1243">Tk's scripting language</a>: <a href="#Tcl">Tcl</a></li> +<li><a href="#index-translated-entries-393">translated entries</a>: <a href="#Translated-Entries">Translated Entries</a></li> +<li><a href="#index-translating-menu-entries-1079">translating menu entries</a>: <a href="#Contexts">Contexts</a></li> +<li><a href="#index-translation-aspects-13">translation aspects</a>: <a href="#Aspects">Aspects</a></li> +<li><a href="#index-Translation-Matrix-52">Translation Matrix</a>: <a href="#Installing-Localizations">Installing Localizations</a></li> +<li><a href="#index-Translation-Project-5">Translation Project</a>: <a href="#Why">Why</a></li> +<li><a href="#index-turning-off-NLS-support-1142">turning off NLS support</a>: <a href="#lib_002fgettext_002eh">lib/gettext.h</a></li> +<li><a href="#index-tutorial-of-_0040code_007bgettext_007d-usage-32">tutorial of <code>gettext</code> usage</a>: <a href="#Overview">Overview</a></li> +<li><a href="#index-unify-duplicate-translations-729">unify duplicate translations</a>: <a href="#msguniq-Invocation">msguniq Invocation</a></li> +<li><a href="#index-untranslated-entries-418">untranslated entries</a>: <a href="#Untranslated-Entries">Untranslated Entries</a></li> +<li><a href="#index-update-translations-from-a-compendium-533">update translations from a compendium</a>: <a href="#Using-Compendia">Using Compendia</a></li> +<li><a href="#index-upgrading-to-new-versions-of-_0040code_007bgettext_007d-1116">upgrading to new versions of <code>gettext</code></a>: <a href="#Prerequisites">Prerequisites</a></li> +<li><a href="#index-version-control-for-backup-files_002c-_0040code_007bmsgmerge_007d-290">version control for backup files, <code>msgmerge</code></a>: <a href="#msgmerge-Invocation">msgmerge Invocation</a></li> +<li><a href="#index-g_t_0040code_007bwxWidgets_007d-library-1239"><code>wxWidgets</code> library</a>: <a href="#wxWidgets">wxWidgets</a></li> +<li><a href="#index-g_t_0040code_007bxargs_007d_002c-and-output-from-_0040code_007bmsgexec_007d-914"><code>xargs</code>, and output from <code>msgexec</code></a>: <a href="#msgexec-Invocation">msgexec Invocation</a></li> +<li><a href="#index-g_t_0040code_007bxgettext_007d-program_002c-usage-160"><code>xgettext</code> program, usage</a>: <a href="#xgettext-Invocation">xgettext Invocation</a></li> +<li><a href="#index-g_t_0040code_007bxmodmap_007d-program_002c-and-typing-quotation-marks-275"><code>xmodmap</code> program, and typing quotation marks</a>: <a href="#Header-Entry">Header Entry</a></li> +<li><a href="#index-YaST2-scripting-language-1241">YaST2 scripting language</a>: <a href="#YCP">YCP</a></li> +<li><a href="#index-YCP-1240">YCP</a>: <a href="#YCP">YCP</a></li> +<li><a href="#index-ycp_002dformat_0040r_007b-flag_007d-89"><code>ycp-format</code><span class="roman"> flag</span></a>: <a href="#PO-Files">PO Files</a></li> + </ul> <div class="footnote"> +<hr> +<a name="texinfo-footnotes-in-document"></a><h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> In this manual, all mentions of Emacs +refers to either GNU Emacs or to XEmacs, which people sometimes call FSF +Emacs and Lucid Emacs, respectively.</p> + + <p class="footnote"><small>[<a name="fn-2" href="#fnd-2">2</a>]</small> This +limitation is not imposed by GNU <code>gettext</code>, but is for compatibility +with the <code>msgfmt</code> implementation on Solaris.</p> + + <p class="footnote"><small>[<a name="fn-3" href="#fnd-3">3</a>]</small> Some +system, e.g. mingw, don't have <code>LC_MESSAGES</code>. Here we use a more or +less arbitrary value for it, namely 1729, the smallest positive integer +which can be represented in two different ways as the sum of two cubes.</p> + + <p class="footnote"><small>[<a name="fn-4" href="#fnd-4">4</a>]</small> When the system does not support <code>setlocale</code> its behavior +in setting the locale values is simulated by looking at the environment +variables.</p> + + <p class="footnote"><small>[<a name="fn-5" href="#fnd-5">5</a>]</small> Additions are welcome. Send appropriate information to +<a href="mailto:bug-gnu-gettext@gnu.org">bug-gnu-gettext@gnu.org</a> and <a href="mailto:bug-glibc-manual@gnu.org">bug-glibc-manual@gnu.org</a>.</p> + + <hr></div> + +</body></html> + +<!-- + +Local Variables: +coding: utf-8 +End: + +--> diff --git a/package/gettext-tiny/src/docs/msgfmt.txt b/package/gettext-tiny/src/docs/msgfmt.txt new file mode 100644 index 000000000..c0147d785 --- /dev/null +++ b/package/gettext-tiny/src/docs/msgfmt.txt @@ -0,0 +1,74 @@ +Usage: msgfmt [OPTION] filename.po ... + +Generate binary message catalog from textual translation description. + +Mandatory arguments to long options are mandatory for short options too. +Similarly for optional arguments. + +Input file location: + filename.po ... input files + -D, --directory=DIRECTORY add DIRECTORY to list for input files search +If input file is -, standard input is read. + +Operation mode: + -j, --java Java mode: generate a Java ResourceBundle class + --java2 like --java, and assume Java2 (JDK 1.2 or higher) + --csharp C# mode: generate a .NET .dll file + --csharp-resources C# resources mode: generate a .NET .resources file + --tcl Tcl mode: generate a tcl/msgcat .msg file + --qt Qt mode: generate a Qt .qm file + +Output file location: + -o, --output-file=FILE write output to specified file + --strict enable strict Uniforum mode +If output file is -, output is written to standard output. + +Output file location in Java mode: + -r, --resource=RESOURCE resource name + -l, --locale=LOCALE locale name, either language or language_COUNTRY + -d DIRECTORY base directory of classes directory hierarchy +The class name is determined by appending the locale name to the resource name, +separated with an underscore. The -d option is mandatory. The class is +written under the specified directory. + +Output file location in C# mode: + -r, --resource=RESOURCE resource name + -l, --locale=LOCALE locale name, either language or language_COUNTRY + -d DIRECTORY base directory for locale dependent .dll files +The -l and -d options are mandatory. The .dll file is written in a +subdirectory of the specified directory whose name depends on the locale. + +Output file location in Tcl mode: + -l, --locale=LOCALE locale name, either language or language_COUNTRY + -d DIRECTORY base directory of .msg message catalogs +The -l and -d options are mandatory. The .msg file is written in the +specified directory. + +Input file syntax: + -P, --properties-input input files are in Java .properties syntax + --stringtable-input input files are in NeXTstep/GNUstep .strings + syntax + +Input file interpretation: + -c, --check perform all the checks implied by + --check-format, --check-header, --check-domain + --check-format check language dependent format strings + --check-header verify presence and contents of the header entry + --check-domain check for conflicts between domain directives + and the --output-file option + -C, --check-compatibility check that GNU msgfmt behaves like X/Open msgfmt + --check-accelerators[=CHAR] check presence of keyboard accelerators for + menu items + -f, --use-fuzzy use fuzzy entries in output + +Output details: + -a, --alignment=NUMBER align strings to NUMBER bytes (default: 1) + --no-hash binary file will not include the hash table + +Informative output: + -h, --help display this help and exit + -V, --version output version information and exit + --statistics print statistics about translations + -v, --verbose increase verbosity level + +Report bugs to <bug-gnu-gettext@gnu.org>. diff --git a/package/gettext-tiny/src/docs/msgmerge.txt b/package/gettext-tiny/src/docs/msgmerge.txt new file mode 100644 index 000000000..8688e849d --- /dev/null +++ b/package/gettext-tiny/src/docs/msgmerge.txt @@ -0,0 +1,81 @@ +Usage: msgmerge [OPTION] def.po ref.pot + +Merges two Uniforum style .po files together. The def.po file is an +existing PO file with translations which will be taken over to the newly +created file as long as they still match; comments will be preserved, +but extracted comments and file positions will be discarded. The ref.pot +file is the last created PO file with up-to-date source references but +old translations, or a PO Template file (generally created by xgettext); +any translations or comments in the file will be discarded, however dot +comments and file positions will be preserved. Where an exact match +cannot be found, fuzzy matching is used to produce better results. + +Mandatory arguments to long options are mandatory for short options too. + +Input file location: + def.po translations referring to old sources + ref.pot references to new sources + -D, --directory=DIRECTORY add DIRECTORY to list for input files search + -C, --compendium=FILE additional library of message translations, + may be specified more than once + +Operation mode: + -U, --update update def.po, + do nothing if def.po already up to date + +Output file location: + -o, --output-file=FILE write output to specified file +The results are written to standard output if no output file is specified +or if it is -. + +Output file location in update mode: +The result is written back to def.po. + --backup=CONTROL make a backup of def.po + --suffix=SUFFIX override the usual backup suffix +The version control method may be selected via the --backup option or through +the VERSION_CONTROL environment variable. Here are the values: + none, off never make backups (even if --backup is given) + numbered, t make numbered backups + existing, nil numbered if numbered backups exist, simple otherwise + simple, never always make simple backups +The backup suffix is `~', unless set with --suffix or the SIMPLE_BACKUP_SUFFIX +environment variable. + +Operation modifiers: + -m, --multi-domain apply ref.pot to each of the domains in def.po + -N, --no-fuzzy-matching do not use fuzzy matching + --previous keep previous msgids of translated messages + +Input file syntax: + -P, --properties-input input files are in Java .properties syntax + --stringtable-input input files are in NeXTstep/GNUstep .strings + syntax + +Output details: + --lang=CATALOGNAME set 'Language' field in the header entry + --color use colors and other text attributes always + --color=WHEN use colors and other text attributes if WHEN. + WHEN may be 'always', 'never', 'auto', or 'html'. + --style=STYLEFILE specify CSS style rule file for --color + -e, --no-escape do not use C escapes in output (default) + -E, --escape use C escapes in output, no extended chars + --force-po write PO file even if empty + -i, --indent indented output style + --no-location suppress '#: filename:line' lines + --add-location preserve '#: filename:line' lines (default) + --strict strict Uniforum output style + -p, --properties-output write out a Java .properties file + --stringtable-output write out a NeXTstep/GNUstep .strings file + -w, --width=NUMBER set output page width + --no-wrap do not break long message lines, longer than + the output page width, into several lines + -s, --sort-output generate sorted output + -F, --sort-by-file sort output by file location + +Informative output: + -h, --help display this help and exit + -V, --version output version information and exit + -v, --verbose increase verbosity level + -q, --quiet, --silent suppress progress indicators + +Report bugs to <bug-gnu-gettext@gnu.org>. diff --git a/package/gettext-tiny/src/docs/xgettext.txt b/package/gettext-tiny/src/docs/xgettext.txt new file mode 100644 index 000000000..a356e268e --- /dev/null +++ b/package/gettext-tiny/src/docs/xgettext.txt @@ -0,0 +1,101 @@ +Usage: xgettext [OPTION] [INPUTFILE]... + +Extract translatable strings from given input files. + +Mandatory arguments to long options are mandatory for short options too. +Similarly for optional arguments. + +Input file location: + INPUTFILE ... input files + -f, --files-from=FILE get list of input files from FILE + -D, --directory=DIRECTORY add DIRECTORY to list for input files search +If input file is -, standard input is read. + +Output file location: + -d, --default-domain=NAME use NAME.po for output (instead of messages.po) + -o, --output=FILE write output to specified file + -p, --output-dir=DIR output files will be placed in directory DIR +If output file is -, output is written to standard output. + +Choice of input file language: + -L, --language=NAME recognise the specified language + (C, C++, ObjectiveC, PO, Shell, Python, Lisp, + EmacsLisp, librep, Scheme, Smalltalk, Java, + JavaProperties, C#, awk, YCP, Tcl, Perl, PHP, + GCC-source, NXStringTable, RST, Glade) + -C, --c++ shorthand for --language=C++ +By default the language is guessed depending on the input file name extension. + +Input file interpretation: + --from-code=NAME encoding of input files + (except for Python, Tcl, Glade) +By default the input files are assumed to be in ASCII. + +Operation mode: + -j, --join-existing join messages with existing file + -x, --exclude-file=FILE.po entries from FILE.po are not extracted + -cTAG, --add-comments=TAG place comment blocks starting with TAG and + preceding keyword lines in output file + -c, --add-comments place all comment blocks preceding keyword lines + in output file + +Language specific options: + -a, --extract-all extract all strings + (only languages C, C++, ObjectiveC, Shell, + Python, Lisp, EmacsLisp, librep, Scheme, Java, + C#, awk, Tcl, Perl, PHP, GCC-source, Glade) + -kWORD, --keyword=WORD look for WORD as an additional keyword + -k, --keyword do not to use default keywords + (only languages C, C++, ObjectiveC, Shell, + Python, Lisp, EmacsLisp, librep, Scheme, Java, + C#, awk, Tcl, Perl, PHP, GCC-source, Glade) + --flag=WORD:ARG:FLAG additional flag for strings inside the argument + number ARG of keyword WORD + (only languages C, C++, ObjectiveC, Shell, + Python, Lisp, EmacsLisp, librep, Scheme, Java, + C#, awk, YCP, Tcl, Perl, PHP, GCC-source) + -T, --trigraphs understand ANSI C trigraphs for input + (only languages C, C++, ObjectiveC) + --qt recognize Qt format strings + (only language C++) + --kde recognize KDE 4 format strings + (only language C++) + --boost recognize Boost format strings + (only language C++) + --debug more detailed formatstring recognition result + +Output details: + --color use colors and other text attributes always + --color=WHEN use colors and other text attributes if WHEN. + WHEN may be 'always', 'never', 'auto', or 'html'. + --style=STYLEFILE specify CSS style rule file for --color + -e, --no-escape do not use C escapes in output (default) + -E, --escape use C escapes in output, no extended chars + --force-po write PO file even if empty + -i, --indent write the .po file using indented style + --no-location do not write '#: filename:line' lines + -n, --add-location generate '#: filename:line' lines (default) + --strict write out strict Uniforum conforming .po file + --properties-output write out a Java .properties file + --stringtable-output write out a NeXTstep/GNUstep .strings file + -w, --width=NUMBER set output page width + --no-wrap do not break long message lines, longer than + the output page width, into several lines + -s, --sort-output generate sorted output + -F, --sort-by-file sort output by file location + --omit-header don't write header with `msgid ""' entry + --copyright-holder=STRING set copyright holder in output + --foreign-user omit FSF copyright in output for foreign user + --package-name=PACKAGE set package name in output + --package-version=VERSION set package version in output + --msgid-bugs-address=EMAIL@ADDRESS set report address for msgid bugs + -m[STRING], --msgstr-prefix[=STRING] use STRING or "" as prefix for msgstr + values + -M[STRING], --msgstr-suffix[=STRING] use STRING or "" as suffix for msgstr + values + +Informative output: + -h, --help display this help and exit + -V, --version output version information and exit + +Report bugs to <bug-gnu-gettext@gnu.org>. diff --git a/package/gettext-tiny/src/include/libintl.h b/package/gettext-tiny/src/include/libintl.h new file mode 100644 index 000000000..ce5f58ea4 --- /dev/null +++ b/package/gettext-tiny/src/include/libintl.h @@ -0,0 +1,61 @@ +#ifndef LIBINTL_H +#define LIBINTL_H + +char *gettext(const char *msgid); +char *dgettext(const char *domainname, const char *msgid); +char *dcgettext(const char *domainname, const char *msgid, int category); +char *ngettext(const char *msgid1, const char *msgid2, unsigned long n); +char *dngettext(const char *domainname, const char *msgid1, const char *msgid2, unsigned long n); +char *dcngettext(const char *domainname, const char *msgid1, const char *msgid2, unsigned long n, int category); + +char *textdomain(const char *domainname); +char *bind_textdomain_codeset(const char *domainname, const char *codeset); +char *bindtextdomain(const char *domainname, const char *dirname); + +#undef gettext_noop +#define gettext_noop(X) (X) + +#ifndef LIBINTL_NO_MACROS +/* if these macros are defined, configure checks will detect libintl as + * built into the libc because test programs will work without -lintl. + * for example: + * checking for ngettext in libc ... yes + * the consequence is that -lintl will not be added to the LDFLAGS. + * so if for some reason you want that libintl.a gets linked, + * add -DLIBINTL_NO_MACROS=1 to your CPPFLAGS. */ + +#define gettext(X) ((char*) (X)) +#define dgettext(dom, X) ((void)(dom), (char*) (X)) +#define dcgettext(dom, X, cat) ((void)(dom), (void)(cat), (char*) (X)) +#define ngettext(X, Y, N) \ + ((char*) (((N) == 1) ? ((void)(Y), (X)) : ((void)(X), (Y)))) +#define dngettext(dom, X, Y, N) \ + ((dom), (char*) (((N) == 1) ? ((void)(Y), (X)) : ((void)(X), (Y)))) +#define dcngettext(dom, X, Y, N, cat) \ + ((dom), (cat), (char*) (((N) == 1) ? ((void)(Y), (X)) : ((void)(X), (Y)))) +#define bindtextdomain(X, Y) ((void)(X), (void)(Y), (char*) "/") +#define bind_textdomain_codeset(dom, codeset) \ + ((void)(dom), (void)(codeset), (char*) 0) +#define textdomain(X) ((void)(X), (char*) "messages") + +#undef ENABLE_NLS +#undef DISABLE_NLS +#define DISABLE_NLS 1 + +#if __GNUC__ +0 > 3 +/* most ppl call bindtextdomain() without using its return value + thus we get tons of warnings about "statement with no effect" */ +#pragma GCC diagnostic ignored "-Wunused-value" +#endif + +#endif + +#include <stdio.h> +#define gettext_printf(args...) printf(args) + +/* to supply LC_MESSAGES and other stuff GNU expects to be exported when + including libintl.h */ +#include <locale.h> + +#endif + diff --git a/package/gettext-tiny/src/libintl/libintl.c b/package/gettext-tiny/src/libintl/libintl.c new file mode 100644 index 000000000..0851fac1c --- /dev/null +++ b/package/gettext-tiny/src/libintl/libintl.c @@ -0,0 +1,82 @@ +/* Copyright (C) 2003 Manuel Novoa III + * Copyright (C) 2000-2006 Erik Andersen <andersen@uclibc.org> + * + * Trivial Stubs, Public Domain. + */ + +#include <stdlib.h> +#include <string.h> +#include <errno.h> + +char *gettext(const char *msgid) +{ + return (char *) msgid; +} + +char *dgettext(const char *domainname, const char *msgid) +{ + (void) domainname; + return (char *) msgid; +} + +char *dcgettext(const char *domainname, const char *msgid, int category) +{ + (void) domainname; + (void) category; + return (char *) msgid; +} + +char *ngettext(const char *msgid1, const char *msgid2, unsigned long n) +{ + return (char *) ((n == 1) ? msgid1 : msgid2); +} + +char *dngettext(const char *domainname, const char *msgid1, const char *msgid2, unsigned long n) +{ + (void) domainname; + return (char *) ((n == 1) ? msgid1 : msgid2); +} + +char *dcngettext(const char *domainname, const char *msgid1, const char *msgid2, unsigned long n, int category) +{ + (void) domainname; + (void) category; + return (char *) ((n == 1) ? msgid1 : msgid2); +} + +char *textdomain(const char *domainname) +{ + static const char default_str[] = "messages"; + + if (domainname && *domainname && strcmp(domainname, default_str)) { + errno = EINVAL; + return NULL; + } + return (char *) default_str; +} + +char *bindtextdomain(const char *domainname, const char *dirname) +{ + static const char dir[] = "/"; + + if (!domainname || !*domainname + || (dirname && ((dirname[0] != '/') || dirname[1])) + ) { + errno = EINVAL; + return NULL; + } + + return (char *) dir; +} + +char *bind_textdomain_codeset(const char *domainname, const char *codeset) +{ + if (!domainname || !*domainname || (codeset && strcasecmp(codeset, "UTF-8"))) { + errno = EINVAL; + } + return NULL; +} + +/* trick configure tests checking for gnu libintl, as in the copy included in gdb */ +const char *_nl_expand_alias () { return NULL; } +int _nl_msg_cat_cntr = 0; diff --git a/package/gettext-tiny/src/src/StringEscape.c b/package/gettext-tiny/src/src/StringEscape.c new file mode 100644 index 000000000..3a9ddd6cb --- /dev/null +++ b/package/gettext-tiny/src/src/StringEscape.c @@ -0,0 +1,111 @@ +#include <stddef.h> + +//FIXME out gets silently truncated if outsize is too small + +size_t escape(char* in, char* out, size_t outsize) { + size_t l = 0; + while(*in && l + 3 < outsize) { + switch(*in) { + case '\n': + *out++ = '\\'; + l++; + *out = 'n'; + break; + case '\r': + *out++ = '\\'; + l++; + *out = 'r'; + break; + case '\t': + *out++ = '\\'; + l++; + *out = 't'; + break; + case '\\': + *out++ = '\\'; + l++; + *out = '\\'; + break; + case '"': + *out++ = '\\'; + l++; + *out = '"'; + break; + case '\v': + *out++ = '\\'; + l++; + *out = '\v'; + break; + case '\?': + *out++ = '\\'; + l++; + *out = '\?'; + break; + case '\f': + *out++ = '\\'; + l++; + *out = '\f'; + break; + default: + *out = *in; + } + in++; + out++; + l++; + } + *out = 0; + return l; +} +#include <assert.h> +#include <stdlib.h> +size_t unescape(char* in, char *out, size_t outsize) { + size_t l = 0; + while(*in && l + 2 < outsize) { + switch (*in) { + case '\\': + ++in; + assert(*in); + switch(*in) { + case 'n': + *out='\n'; + break; + case 'r': + *out='\r'; + break; + case 't': + *out='\t'; + break; + case '\\': + *out='\\'; + break; + case '"': + *out='"'; + break; + case 'v': + *out='\v'; + break; + case '\?': + *out = '\?'; + break; + case 'f': + *out = '\f'; + break; + case '\'': + *out = '\''; + break; + // FIXME add handling of hex and octal + default: + abort(); + } + break; + default: + *out=*in; + } + in++; + out++; + l++; + } + *out = 0; + return l; +} + diff --git a/package/gettext-tiny/src/src/StringEscape.h b/package/gettext-tiny/src/src/StringEscape.h new file mode 100644 index 000000000..fc764821b --- /dev/null +++ b/package/gettext-tiny/src/src/StringEscape.h @@ -0,0 +1,7 @@ +#ifndef STRINGESCAPE_H +#define STRINGESCAPE_H +#include <stddef.h> +size_t escape(char* in, char *out, size_t outsize); +size_t unescape(char* in, char *out, size_t outsize); +//RcB: DEP "StringEscape.c" +#endif diff --git a/package/gettext-tiny/src/src/msgfmt.c b/package/gettext-tiny/src/src/msgfmt.c new file mode 100644 index 000000000..bf5f3430d --- /dev/null +++ b/package/gettext-tiny/src/src/msgfmt.c @@ -0,0 +1,278 @@ +/* msgfmt utility (C) 2012 rofl0r + * released under the MIT license, see LICENSE for details */ +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <ctype.h> +#include <assert.h> +#include "poparser.h" + +// in DO_NOTHING mode, we simply write the msgid twice, once for msgid, once for msgstr. +// TODO: maybe make it write "" instead of echoing the msgid. +//#define DO_NOTHING + +__attribute__((noreturn)) +static void syntax(void) { + fprintf(stdout, + "Usage: msgfmt [OPTION] filename.po ...\n"); + exit(1); +} + +__attribute__((noreturn)) +static void version(void) { + fprintf(stdout, + "these are not (GNU gettext-tools) 99.9999.9999\n"); + exit(0); +} + +#define streq(A, B) (!strcmp(A, B)) +#define strstarts(S, W) (memcmp(S, W, sizeof(W) - 1) ? NULL : (S + (sizeof(W) - 1))) + +struct mo_hdr { + unsigned magic; + int rev; + unsigned numstring; + unsigned off_tbl_org; + unsigned off_tbl_trans; + unsigned hash_tbl_size; + unsigned off_tbl_hash; +}; + +/* file layout: + header + strtable (lenghts/offsets) + transtable (lenghts/offsets) + [hashtable] + strings section + translations section */ + +const struct mo_hdr def_hdr = { + 0x950412de, + 0, + 0, + sizeof(struct mo_hdr), + 0, + 0, + 0, +}; + + +// pass 0: collect numbers of strings, calculate size and offsets for tables +// print header +// pass 1: print string table [lengths/offsets] +// pass 2: print translation table [lengths/offsets] +// pass 3: print strings +// pass 4: print translations +enum passes { + pass_first = 0, + pass_collect_sizes = pass_first, + pass_second, + pass_print_string_offsets = pass_second, + pass_print_translation_offsets, + pass_print_strings, + pass_print_translations, + pass_max, +}; + +struct callbackdata { + enum passes pass; + unsigned off; + FILE* out; + unsigned num[pe_maxstr]; + unsigned len[pe_maxstr]; +}; + + +int process_line_callback(struct po_info* info, void* user) { + struct callbackdata *d = (struct callbackdata *) user; + assert(info->type == pe_msgid || info->type == pe_msgstr); + switch(d->pass) { + case pass_collect_sizes: + d->num[info->type] += 1; + d->len[info->type] += info->textlen; + break; + case pass_print_string_offsets: + if(info->type == pe_msgstr) break; + write_offsets: + // print length of current string + fwrite(&info->textlen, sizeof(unsigned), 1, d->out); + // print offset of current string + fwrite(&d->off, sizeof(unsigned), 1, d->out); + d->off += info->textlen + 1; + break; + case pass_print_translation_offsets: +#ifndef DO_NOTHING + if(info->type == pe_msgid) break; +#else + if(info->type != pe_msgid) break; +#endif + goto write_offsets; + case pass_print_strings: + if(info->type == pe_msgstr) break; + write_string: + fwrite(info->text, info->textlen + 1, 1, d->out); + break; + case pass_print_translations: +#ifndef DO_NOTHING + if(info->type == pe_msgid) break; +#else + if(info->type != pe_msgid) break; +#endif + goto write_string; + break; + default: + abort(); + } + return 0; +} + +int process(FILE *in, FILE *out) { + struct mo_hdr mohdr = def_hdr; + char line[4096]; char *lp; + char convbuf[16384]; + + struct callbackdata d = { + .num = { + [pe_msgid] = 0, + [pe_msgstr] = 0, + }, + .len = { + [pe_msgid] = 0, + [pe_msgstr] = 0, + }, + .off = 0, + .out = out, + .pass = pass_first, + }; + + struct po_parser pb, *p = &pb; + int invalid_file = 0; + + mohdr.off_tbl_trans = mohdr.off_tbl_org; + for(d.pass = pass_first; d.pass < pass_max; d.pass++) { + if(d.pass == pass_second) { + // start of second pass: + // check that data gathered in first pass is consistent +#ifndef DO_NOTHING + if(d.num[pe_msgid] != d.num[pe_msgstr]) { + // one should actually abort here, + // but gnu gettext simply writes an empty .mo and returns success. + //abort(); + d.num[pe_msgid] = 0; + invalid_file = 1; + } +#endif + + // calculate header fields from len and num arrays + mohdr.numstring = d.num[pe_msgid]; + mohdr.off_tbl_org = sizeof(struct mo_hdr); + mohdr.off_tbl_trans = mohdr.off_tbl_org + d.num[pe_msgid] * (sizeof(unsigned)*2); + // print header + fwrite(&mohdr, sizeof(mohdr), 1, out); + // set offset startvalue + d.off = mohdr.off_tbl_trans + d.num[pe_msgid] * (sizeof(unsigned)*2); + if(invalid_file) return 0; + } + poparser_init(p, convbuf, sizeof(convbuf), process_line_callback, &d); + + while((lp = fgets(line, sizeof(line), in))) { + poparser_feed_line(p, lp, sizeof(line)); + } + + poparser_finish(p); + + fseek(in, 0, SEEK_SET); + } + return 0; +} + + +void set_file(int out, char* fn, FILE** dest) { + if(streq(fn, "-")) { + *dest = out ? stdout : stdin; + } else { + *dest = fopen(fn, out ? "w" : "r"); + } + if(!*dest) { + perror("fopen"); + exit(1); + } +} + +int main(int argc, char**argv) { + if(argc == 1) syntax(); + int arg = 1; + FILE *out = NULL; + FILE *in = NULL; + int expect_out_fn = 0; + int expect_in_fn = 1; + char* dest; +#define A argv[arg] + for(; arg < argc; arg++) { + if(expect_out_fn) { + set_file(1, A, &out); + expect_out_fn = 0; + } else if(A[0] == '-') { + if(A[1] == '-') { + if( + streq(A+2, "java") || + streq(A+2, "java2") || + streq(A+2, "csharp") || + streq(A+2, "csharp-resources") || + streq(A+2, "tcl") || + streq(A+2, "qt") || + streq(A+2, "strict") || + streq(A+2, "properties-input") || + streq(A+2, "stringtable-input") || + streq(A+2, "use-fuzzy") || + strstarts(A+2, "alignment=") || + streq(A+2, "check") || + streq(A+2, "check-format") || + streq(A+2, "check-header") || + streq(A+2, "check-domain") || + streq(A+2, "check-compatibility") || + streq(A+2, "check-accelerators") || + streq(A+2, "no-hash") || + streq(A+2, "verbose") || + streq(A+2, "statistics") || + strstarts(A+2, "check-accelerators=") || + strstarts(A+2, "resource=") || + strstarts(A+2, "locale=") + + ) { + } else if((dest = strstarts(A+2, "output-file="))) { + set_file(1, dest, &out); + } else if(streq(A+2, "version")) { + version(); + } else if(streq(A+2, "help")) syntax(); + + } else if(streq(A + 1, "o")) { + expect_out_fn = 1; + } else if( + streq(A+1, "j") || + streq(A+1, "r") || + streq(A+1, "l") || + streq(A+1, "P") || + streq(A+1, "f") || + streq(A+1, "a") || + streq(A+1, "c") || + streq(A+1, "C") + ) { + } else if (streq(A+1, "v")) { + version(); + } else if (streq(A+1, "d")) { + // no support for -d at this time + fprintf(stderr, "EINVAL\n"); + exit(1); + } else if (streq(A+1, "h")) syntax(); + } else if (expect_in_fn) { + set_file(0, A, &in); + } + } + if(in == NULL || out == NULL) syntax(); + int ret = process(in, out); + fflush(in); fflush(out); + if(in != stdin) fclose(in); + if(out != stdout) fclose(out); + return ret; +} diff --git a/package/gettext-tiny/src/src/msgmerge.c b/package/gettext-tiny/src/src/msgmerge.c new file mode 100644 index 000000000..977f1686e --- /dev/null +++ b/package/gettext-tiny/src/src/msgmerge.c @@ -0,0 +1,222 @@ +/* msgfmt utility (C) 2012 rofl0r + * released under the MIT license, see LICENSE for details */ +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <ctype.h> +#include <assert.h> +#include "poparser.h" +#include "StringEscape.h" + +__attribute__((noreturn)) +static void syntax(void) { + fprintf(stdout, + "Usage: msgmerge [OPTION] def.po ref.pot\n"); + exit(1); +} + +__attribute__((noreturn)) +static void version(void) { + fprintf(stdout, + "these are not (GNU gettext-tools) 99.9999.9999\n"); + exit(0); +} + +#define streq(A, B) (!strcmp(A, B)) +#define strstarts(S, W) (memcmp(S, W, sizeof(W) - 1) ? NULL : (S + (sizeof(W) - 1))) + +struct fiLes { + FILE *out; + /* we can haz 3 different input files: + * the .pot, which is the file containing only the ripped out strings from the program + * (and no translations) + * a .po, which is contains translations and strings made from a previous .pot from that same source file, + * a compendium, which is basically a huge po file containing all sorts of strings (msgid's) and translations (msgstr's) + */ + FILE *po; + FILE *pot; + FILE *compend; +}; + +/* currently we only output input strings as output strings + * i.e. there is no translation lookup at all */ +int process_line_callback(struct po_info* info, void* user) { + char convbuf[8192]; + FILE* out = (FILE*) user; + size_t l; + if(info->type == pe_msgid) { + l = escape(info->text, convbuf, sizeof(convbuf)); + fprintf(out, "msgid \"%s\"\nmsgstr \"%s\"\n", convbuf, convbuf); + } + return 0; +} + +int process(struct fiLes *files, int update, int backup) { + (void) update; (void) backup; + struct po_parser pb, *p = &pb; + char line[4096], conv[8192], *lb; + poparser_init(p, conv, sizeof(conv), process_line_callback, files->out); + while((lb = fgets(line, sizeof(line), files->pot))) { + poparser_feed_line(p, lb, sizeof(line) - (size_t)(lb - line)); + } + poparser_finish(p); + return 0; +} + +void set_file(int out, char* fn, FILE** dest) { + if(streq(fn, "-")) { + *dest = out ? stdout : stdin; + } else { + *dest = fopen(fn, out ? "w" : "r"); + } + if(!*dest) { + perror("fopen"); + exit(1); + } +} + +int getbackuptype(char* str) { + if(!str || !*str || streq(str, "none") || streq(str, "off")) + return 0; + else if(streq(str, "t") || streq(str, "numbered")) + return 1; + else if(streq(str, "nil") || streq(str, "existing")) + return 2; + else if(streq(str, "simple") || streq(str, "never")) + return 3; + else syntax(); +} + +int main(int argc, char**argv) { + if(argc == 1) syntax(); + int arg = 1; + struct expect { + int out; + int po; + int pot; + int compend; + } expect_fn = { + .out = 0, + .po = 1, + .pot = 0, + .compend = 0, + }; + struct fiLes files = {0,0,0,0}; + char* backup_suffix = getenv("SIMPLE_BACKUP_SUFFIX"); + if(!backup_suffix) backup_suffix = "~"; + int update = 0; + int backup = getbackuptype(getenv("VERSION_CONTROL")); + char* dest; + set_file(1, "-", &files.out); +#define A argv[arg] + for(; arg < argc; arg++) { + if(A[0] == '-') { + if(A[1] == '-') { + if( + streq(A+2, "strict") || + streq(A+2, "properties-input") || + streq(A+2, "properties-output") || + streq(A+2, "stringtable-input") || + streq(A+2, "stringtable-output") || + streq(A+2, "no-fuzzy-matching") || + streq(A+2, "multi-domain") || + streq(A+2, "previous") || + streq(A+2, "escape") || + streq(A+2, "no-escape") || + streq(A+2, "force-po") || + streq(A+2, "indent") || + streq(A+2, "add-location") || + streq(A+2, "no-location") || + streq(A+2, "no-wrap") || + streq(A+2, "sort-output") || + streq(A+2, "sort-by-file") || + + strstarts(A+2, "lang=") || + strstarts(A+2, "color") || // can be --color or --color=xxx + strstarts(A+2, "style=") || + strstarts(A+2, "width=") || + + streq(A+2, "verbose") || + streq(A+2, "quiet") || + streq(A+2, "silent") ) { + } else if(streq(A+2, "version")) { + version(); + } else if((dest = strstarts(A+2, "output-file="))) { + set_file(1, dest, &files.out); + } else if((dest = strstarts(A+2, "compendium="))) { + set_file(1, dest, &files.compend); + } else if((dest = strstarts(A+2, "suffix="))) { + backup_suffix = dest; + } else if((dest = strstarts(A+2, "directory="))) { + goto nodir; + } else if((dest = strstarts(A+2, "backup"))) { + if (*dest == '=') + backup = getbackuptype(dest + 1); + else + backup = 0; + } else if(streq(A+2, "update")) { + set_update: + update = 1; + abort(); + } else if(streq(A+2, "help")) syntax(); + + } else if(streq(A + 1, "o")) { + expect_fn.out = 1; + } else if(streq(A + 1, "C")) { + expect_fn.compend = 1; + } else if(streq(A + 1, "U")) { + goto set_update; + } else if( + streq(A+1, "m") || + streq(A+1, "N") || + streq(A+1, "P") || + streq(A+1, "e") || + streq(A+1, "E") || + streq(A+1, "i") || + streq(A+1, "p") || + streq(A+1, "w") || + streq(A+1, "s") || + streq(A+1, "F") || + streq(A+1, "V") || + streq(A+1, "q") + ) { + + } else if (streq(A+1, "v")) { + version(); + } else if (streq(A+1, "D")) { + // no support for -D at this time + nodir: + fprintf(stderr, "EINVAL\n"); + exit(1); + } else if (streq(A+1, "h")) syntax(); + } else if(expect_fn.out) { + set_file(1, A, &files.out); + expect_fn.out = 0; + } else if(expect_fn.compend) { + set_file(1, A, &files.compend); + expect_fn.compend = 0; + } else if(expect_fn.po) { + set_file(0, A, &files.po); + expect_fn.po = 0; + expect_fn.pot = 1; + } else if(expect_fn.pot) { + set_file(0, A, &files.pot); + expect_fn.pot = 0; + } + } + if(!files.out || !files.po || !files.pot) syntax(); + int ret = process(&files, update, backup); + FILE** filearr = (FILE**) &files; + unsigned i; + for (i = 0; i < 4; i++) { + if(filearr[i] != NULL) fflush(filearr[i]); + } + for (i = 0; i < 4; i++) { + if( + filearr[i] != NULL && + filearr[i] != stdout && + filearr[i] != stdin + ) fclose(filearr[i]); + } + return ret; +} diff --git a/package/gettext-tiny/src/src/poparser.c b/package/gettext-tiny/src/src/poparser.c new file mode 100644 index 000000000..e67761305 --- /dev/null +++ b/package/gettext-tiny/src/src/poparser.c @@ -0,0 +1,144 @@ +#include <ctype.h> +#include <assert.h> +#include <stdlib.h> +#include <string.h> +#include "poparser.h" +#include "StringEscape.h" + +#define streq(A, B) (!strcmp(A, B)) +#define strstarts(S, W) (memcmp(S, W, sizeof(W) - 1) ? NULL : (S + (sizeof(W) - 1))) + +static enum po_entry get_type_and_start(char* lp, char* end, size_t *stringstart) { + enum po_entry result_type; + char *x, *y; + size_t start = (size_t) lp; + while(isspace(*lp) && lp < end) lp++; + if(lp[0] == '#') { + inv: + *stringstart = 0; + return pe_invalid; + } + if((y = strstarts(lp, "msg"))) { + if((x = strstarts(y, "id")) && (isspace(*x) || ((x = strstarts(x, "_plural")) && isspace(*x)))) + result_type = pe_msgid; + else if ((x = strstarts(y, "str")) && (isspace(*x) || + (x[0] == '[' && (x[1] == '0' || x[1] == '1') && x[2] == ']' && (x += 3) && isspace(*x)))) + result_type = pe_msgstr; + else + goto inv; + while(isspace(*x) && x < end) x++; + if(*x != '"') abort(); + conv: + *stringstart = ((size_t) x - start) + 1; + } else if(*lp == '"') { + result_type = pe_str; + x = lp; + goto conv; + } else { + goto inv; + } + return result_type; +} + +/* expects a pointer to the first char after a opening " in a string, + * converts the string into convbuf, and returns the length of that string */ +static size_t get_length_and_convert(char* x, char* end, char* convbuf, size_t convbuflen) { + size_t result = 0; + char* e = x + strlen(x); + assert(e > x && e < end && *e == 0); + e--; + while(isspace(*e)) e--; + if(*e != '"') abort(); + *e = 0; + result = unescape(x, convbuf, convbuflen); + return result; +} + + +void poparser_init(struct po_parser *p, char* workbuf, size_t bufsize, poparser_callback cb, void* cbdata) { + p->buf = workbuf; + p->bufsize = bufsize; + p->cb = cb; + p->prev_type = pe_invalid; + p->curr_len = 0; + p->cbdata = cbdata; +} + +enum lineactions { + la_incr, + la_proc, + la_abort, + la_nop, + la_max, +}; + +/* return 0 on success */ +int poparser_feed_line(struct po_parser *p, char* line, size_t buflen) { + char *convbuf = p->buf; + size_t convbuflen = p->bufsize; + size_t strstart; + + static const enum lineactions action_tbl[pe_max][pe_max] = { + // pe_str will never be set as curr_type + [pe_str] = { + [pe_str] = la_abort, + [pe_msgid] = la_abort, + [pe_msgstr] = la_abort, + [pe_invalid] = la_abort, + }, + [pe_msgid] = { + [pe_str] = la_incr, + [pe_msgid] = la_proc, + [pe_msgstr] = la_proc, + [pe_invalid] = la_proc, + }, + [pe_msgstr] = { + [pe_str] = la_incr, + [pe_msgid] = la_proc, + [pe_msgstr] = la_proc, + [pe_invalid] = la_proc, + }, + [pe_invalid] = { + [pe_str] = la_nop, // this can happen when we have msgstr[2] "" ... "foo", since we only parse msgstr[0] and [1] + [pe_msgid] = la_incr, + [pe_msgstr] = la_incr, + [pe_invalid] = la_nop, + }, + }; + + enum po_entry type; + + type = get_type_and_start(line, line + buflen, &strstart); + switch(action_tbl[p->prev_type][type]) { + case la_incr: + assert(type == pe_msgid || type == pe_msgstr || type == pe_str); + p->curr_len += get_length_and_convert(line + strstart, line + buflen, convbuf + p->curr_len, convbuflen - p->curr_len); + break; + case la_proc: + assert(p->prev_type == pe_msgid || p->prev_type == pe_msgstr); + p->info.text = convbuf; + p->info.textlen = p->curr_len; + p->info.type = p->prev_type; + p->cb(&p->info, p->cbdata); + if(type != pe_invalid) + p->curr_len = get_length_and_convert(line + strstart, line + buflen, convbuf, convbuflen); + else + p->curr_len = 0; + break; + case la_nop: + break; + case la_abort: + default: + abort(); + // todo : return error code + } + if(type != pe_str) { + p->prev_type = type; + } + return 0; +} + +int poparser_finish(struct po_parser *p) { + char empty[4] = ""; + return poparser_feed_line(p, empty, sizeof(empty)); +} diff --git a/package/gettext-tiny/src/src/poparser.h b/package/gettext-tiny/src/src/poparser.h new file mode 100644 index 000000000..e29594f35 --- /dev/null +++ b/package/gettext-tiny/src/src/poparser.h @@ -0,0 +1,36 @@ +#ifndef POPARSER_H +#define POPARSER_H +#include <unistd.h> + +enum po_entry { + pe_msgid = 0, + pe_msgstr, + pe_maxstr, + pe_str = pe_maxstr, + pe_invalid, + pe_max, +}; + +struct po_info { + enum po_entry type; + char *text; + size_t textlen; +}; + +typedef int (*poparser_callback)(struct po_info* info, void* user); + +struct po_parser { + struct po_info info; + char *buf; + size_t bufsize; + enum po_entry prev_type; + unsigned curr_len; + poparser_callback cb; + void *cbdata; +}; + +void poparser_init(struct po_parser *p, char* workbuf, size_t bufsize, poparser_callback cb, void* cbdata); +int poparser_feed_line(struct po_parser *p, char* line, size_t buflen); +int poparser_finish(struct po_parser *p); + +#endif diff --git a/package/gettext-tiny/src/src/xgettext.sh b/package/gettext-tiny/src/src/xgettext.sh new file mode 100755 index 000000000..32173556b --- /dev/null +++ b/package/gettext-tiny/src/src/xgettext.sh @@ -0,0 +1,112 @@ +#!/bin/sh + +outputfile= +outputdir=. +domain=messages + +spliteq() { + arg=$1 + echo "${arg#*=}" + #alternatives echo "$arg" | cut -d= -f2- + # or echo "$arg" | sed 's/[^=]*=//' +} + +syntax() { + printf "%s\n" "Usage: xgettext [OPTION] [INPUTFILE]..." + exit 1 +} + +show_version() { + printf "%s\n", "these are not (GNU gettext-tools) 99.9999.9999\n" + exit 0 +} + +while true ; do + case $1 in + #--files-from=*) readfile `spliteq "$1"`;; + #-f) expectfilefrom=1;; + --version) show_version;; + -V) show_version;; + --default-domain=*) domain=`spliteq "$1"` ;; + -d) shift ; domain="$1" ;; + --files-from=*) : ;; + -f) shift ;; + --directory=*) : ;; + -D) shift ;; + -o) shift ; outputfile="$1" ;; + --output=*) outputfile=`spliteq "$1"` ;; + --output-dir=*) outputdir=`spliteq "$1"` ;; + -p) shift ; outputdir=`spliteq "$1"` ;; + --language=*) : ;; + -L) shift ;; + --C) : ;; + --c++) : ;; + --from-code=*) : ;; + --join-existing) : ;; + -j) : ;; + --exclude-file=*) : ;; + -x) shift;; + --add-comments=*) : ;; + -cTAG) shift;; + --add-comments) : ;; + -c) : ;; + --extract-all) : ;; + -a) : ;; + --keyword=*) : ;; + -k*) : ;; + --keyword) : ;; + -k) : ;; + --flag=*) : ;; + --trigraphs) : ;; + -T) : ;; + --qt) : ;; + --kde) : ;; + --boost) : ;; + --debug) : ;; + --color) : ;; + --color=*) : ;; + --style=*) : ;; + --no-escape) : ;; + -e) : ;; + --escape) : ;; + -E) : ;; + --force-po) force=1 ;; + --indent) : ;; + -i) : ;; + --no-location) : ;; + --add-location) : ;; + -n) : ;; + --strict) : ;; + --properties-output) : ;; + --stringtable-output) : ;; + --width=*) : ;; + -w) : ;; + --no-wrap) : ;; + --sort-output) : ;; + -s) : ;; + --sort-by-file) : ;; + -F) : ;; + --omit-header) : ;; + --copyright-holder=*) : ;; + --foreign-user) : ;; + --package-name=*) : ;; + --package-version=*) : ;; + --msgid-bugs-address=*) : ;; + --msgstr-prefix*) : ;; + -m*) : ;; + --msgstr-suffix*) : ;; + -M*) : ;; + --help) syntax ;; + -h) syntax ;; + *) break ;; + esac + shift +done + +[ -z "$outputfile" ] && outputfile=${domain}.po +[ "$outputfile" = "-" ] && exit 0 +if [ ! -z "$outputfile" ] ; then + touch $outputdir/$outputfile +fi + + |