xref: /netbsd-src/external/gpl2/gettext/dist/gettext-tools/doc/gettext_3.html (revision 946379e7b37692fc43f68eb0d1c10daa0a7f3b6c) 
1*946379e7Schristos<HTML>
2*946379e7Schristos<HEAD>
3*946379e7Schristos<!-- This HTML file has been created by texi2html 1.52b
4*946379e7Schristos     from gettext.texi on 27 November 2006 -->
5*946379e7Schristos
6*946379e7Schristos<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
7*946379e7Schristos<TITLE>GNU gettext utilities - 3  The Format of PO Files</TITLE>
8*946379e7Schristos</HEAD>
9*946379e7Schristos<BODY>
10*946379e7SchristosGo to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_2.html">previous</A>, <A HREF="gettext_4.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
11*946379e7Schristos<P><HR><P>
12*946379e7Schristos
13*946379e7Schristos
14*946379e7Schristos<H1><A NAME="SEC10" HREF="gettext_toc.html#TOC10">3  The Format of PO Files</A></H1>
15*946379e7Schristos<P>
16*946379e7Schristos<A NAME="IDX46"></A>
17*946379e7Schristos<A NAME="IDX47"></A>
18*946379e7Schristos
19*946379e7Schristos</P>
20*946379e7Schristos<P>
21*946379e7SchristosThe GNU <CODE>gettext</CODE> toolset helps programmers and translators
22*946379e7Schristosat producing, updating and using translation files, mainly those
23*946379e7SchristosPO files which are textual, editable files.  This chapter explains
24*946379e7Schristosthe format of PO files.
25*946379e7Schristos
26*946379e7Schristos</P>
27*946379e7Schristos<P>
28*946379e7SchristosA PO file is made up of many entries, each entry holding the relation
29*946379e7Schristosbetween an original untranslated string and its corresponding
30*946379e7Schristostranslation.  All entries in a given PO file usually pertain
31*946379e7Schristosto a single project, and all translations are expressed in a single
32*946379e7Schristostarget language.  One PO file <EM>entry</EM> has the following schematic
33*946379e7Schristosstructure:
34*946379e7Schristos
35*946379e7Schristos</P>
36*946379e7Schristos
37*946379e7Schristos<PRE>
38*946379e7Schristos<VAR>white-space</VAR>
39*946379e7Schristos#  <VAR>translator-comments</VAR>
40*946379e7Schristos#. <VAR>extracted-comments</VAR>
41*946379e7Schristos#: <VAR>reference</VAR>...
42*946379e7Schristos#, <VAR>flag</VAR>...
43*946379e7Schristos#| msgid <VAR>previous-untranslated-string</VAR>
44*946379e7Schristosmsgid <VAR>untranslated-string</VAR>
45*946379e7Schristosmsgstr <VAR>translated-string</VAR>
46*946379e7Schristos</PRE>
47*946379e7Schristos
48*946379e7Schristos<P>
49*946379e7SchristosThe general structure of a PO file should be well understood by
50*946379e7Schristosthe translator.  When using PO mode, very little has to be known
51*946379e7Schristosabout the format details, as PO mode takes care of them for her.
52*946379e7Schristos
53*946379e7Schristos</P>
54*946379e7Schristos<P>
55*946379e7SchristosA simple entry can look like this:
56*946379e7Schristos
57*946379e7Schristos</P>
58*946379e7Schristos
59*946379e7Schristos<PRE>
60*946379e7Schristos#: lib/error.c:116
61*946379e7Schristosmsgid "Unknown system error"
62*946379e7Schristosmsgstr "Error desconegut del sistema"
63*946379e7Schristos</PRE>
64*946379e7Schristos
65*946379e7Schristos<P>
66*946379e7Schristos<A NAME="IDX48"></A>
67*946379e7Schristos<A NAME="IDX49"></A>
68*946379e7Schristos<A NAME="IDX50"></A>
69*946379e7SchristosEntries begin with some optional white space.  Usually, when generated
70*946379e7Schristosthrough GNU <CODE>gettext</CODE> tools, there is exactly one blank line
71*946379e7Schristosbetween entries.  Then comments follow, on lines all starting with the
72*946379e7Schristoscharacter <CODE>#</CODE>.  There are two kinds of comments: those which have
73*946379e7Schristossome white space immediately following the <CODE>#</CODE> - the <VAR>translator
74*946379e7Schristoscomments</VAR> -, which comments are created and maintained exclusively by the
75*946379e7Schristostranslator, and those which have some non-white character just after the
76*946379e7Schristos<CODE>#</CODE> - the <VAR>automatic comments</VAR> -, which comments are created and
77*946379e7Schristosmaintained automatically by GNU <CODE>gettext</CODE> tools.  Comment lines
78*946379e7Schristosstarting with <CODE>#.</CODE> contain comments given by the programmer, directed
79*946379e7Schristosat the translator; these comments are called <VAR>extracted comments</VAR>
80*946379e7Schristosbecause the <CODE>xgettext</CODE> program extracts them from the program's
81*946379e7Schristossource code.  Comment lines starting with <CODE>#:</CODE> contain references to
82*946379e7Schristosthe program's source code.  Comment lines starting with <CODE>#,</CODE> contain
83*946379e7Schristosflags; more about these below.  Comment lines starting with <CODE>#|</CODE>
84*946379e7Schristoscontain the previous untranslated string for which the translator gave
85*946379e7Schristosa translation.
86*946379e7Schristos
87*946379e7Schristos</P>
88*946379e7Schristos<P>
89*946379e7SchristosAll comments, of either kind, are optional.
90*946379e7Schristos
91*946379e7Schristos</P>
92*946379e7Schristos<P>
93*946379e7Schristos<A NAME="IDX51"></A>
94*946379e7Schristos<A NAME="IDX52"></A>
95*946379e7SchristosAfter white space and comments, entries show two strings, namely
96*946379e7Schristosfirst the untranslated string as it appears in the original program
97*946379e7Schristossources, and then, the translation of this string.  The original
98*946379e7Schristosstring is introduced by the keyword <CODE>msgid</CODE>, and the translation,
99*946379e7Schristosby <CODE>msgstr</CODE>.  The two strings, untranslated and translated,
100*946379e7Schristosare quoted in various ways in the PO file, using <CODE>"</CODE>
101*946379e7Schristosdelimiters and <CODE>\</CODE> escapes, but the translator does not really
102*946379e7Schristoshave to pay attention to the precise quoting format, as PO mode fully
103*946379e7Schristostakes care of quoting for her.
104*946379e7Schristos
105*946379e7Schristos</P>
106*946379e7Schristos<P>
107*946379e7SchristosThe <CODE>msgid</CODE> strings, as well as automatic comments, are produced
108*946379e7Schristosand managed by other GNU <CODE>gettext</CODE> tools, and PO mode does not
109*946379e7Schristosprovide means for the translator to alter these.  The most she can
110*946379e7Schristosdo is merely deleting them, and only by deleting the whole entry.
111*946379e7SchristosOn the other hand, the <CODE>msgstr</CODE> string, as well as translator
112*946379e7Schristoscomments, are really meant for the translator, and PO mode gives her
113*946379e7Schristosthe full control she needs.
114*946379e7Schristos
115*946379e7Schristos</P>
116*946379e7Schristos<P>
117*946379e7SchristosThe comment lines beginning with <CODE>#,</CODE> are special because they are
118*946379e7Schristosnot completely ignored by the programs as comments generally are.  The
119*946379e7Schristoscomma separated list of <VAR>flag</VAR>s is used by the <CODE>msgfmt</CODE>
120*946379e7Schristosprogram to give the user some better diagnostic messages.  Currently
121*946379e7Schristosthere are two forms of flags defined:
122*946379e7Schristos
123*946379e7Schristos</P>
124*946379e7Schristos<DL COMPACT>
125*946379e7Schristos
126*946379e7Schristos<DT><CODE>fuzzy</CODE>
127*946379e7Schristos<DD>
128*946379e7Schristos<A NAME="IDX53"></A>
129*946379e7SchristosThis flag can be generated by the <CODE>msgmerge</CODE> program or it can be
130*946379e7Schristosinserted by the translator herself.  It shows that the <CODE>msgstr</CODE>
131*946379e7Schristosstring might not be a correct translation (anymore).  Only the translator
132*946379e7Schristoscan judge if the translation requires further modification, or is
133*946379e7Schristosacceptable as is.  Once satisfied with the translation, she then removes
134*946379e7Schristosthis <CODE>fuzzy</CODE> attribute.  The <CODE>msgmerge</CODE> program inserts this
135*946379e7Schristoswhen it combined the <CODE>msgid</CODE> and <CODE>msgstr</CODE> entries after fuzzy
136*946379e7Schristossearch only.  See section <A HREF="gettext_8.html#SEC58">8.3.6  Fuzzy Entries</A>.
137*946379e7Schristos
138*946379e7Schristos<DT><CODE>c-format</CODE>
139*946379e7Schristos<DD>
140*946379e7Schristos<A NAME="IDX54"></A>
141*946379e7Schristos<DT><CODE>no-c-format</CODE>
142*946379e7Schristos<DD>
143*946379e7Schristos<A NAME="IDX55"></A>
144*946379e7SchristosThese flags should not be added by a human.  Instead only the
145*946379e7Schristos<CODE>xgettext</CODE> program adds them.  In an automated PO file processing
146*946379e7Schristossystem as proposed here the user changes would be thrown away again as
147*946379e7Schristossoon as the <CODE>xgettext</CODE> program generates a new template file.
148*946379e7Schristos
149*946379e7SchristosThe <CODE>c-format</CODE> flag tells that the untranslated string and the
150*946379e7Schristostranslation are supposed to be C format strings.  The <CODE>no-c-format</CODE>
151*946379e7Schristosflag tells that they are not C format strings, even though the untranslated
152*946379e7Schristosstring happens to look like a C format string (with <SAMP>&lsquo;%&rsquo;</SAMP> directives).
153*946379e7Schristos
154*946379e7SchristosIn case the <CODE>c-format</CODE> flag is given for a string the <CODE>msgfmt</CODE>
155*946379e7Schristosdoes some more tests to check to validity of the translation.
156*946379e7SchristosSee section <A HREF="gettext_10.html#SEC143">10.1  Invoking the <CODE>msgfmt</CODE> Program</A>, section <A HREF="gettext_4.html#SEC17">4.6  Special Comments preceding Keywords</A> and section <A HREF="gettext_15.html#SEC233">15.3.1  C Format Strings</A>.
157*946379e7Schristos
158*946379e7Schristos<DT><CODE>objc-format</CODE>
159*946379e7Schristos<DD>
160*946379e7Schristos<A NAME="IDX56"></A>
161*946379e7Schristos<DT><CODE>no-objc-format</CODE>
162*946379e7Schristos<DD>
163*946379e7Schristos<A NAME="IDX57"></A>
164*946379e7SchristosLikewise for Objective C, see section <A HREF="gettext_15.html#SEC234">15.3.2  Objective C Format Strings</A>.
165*946379e7Schristos
166*946379e7Schristos<DT><CODE>sh-format</CODE>
167*946379e7Schristos<DD>
168*946379e7Schristos<A NAME="IDX58"></A>
169*946379e7Schristos<DT><CODE>no-sh-format</CODE>
170*946379e7Schristos<DD>
171*946379e7Schristos<A NAME="IDX59"></A>
172*946379e7SchristosLikewise for Shell, see section <A HREF="gettext_15.html#SEC235">15.3.3  Shell Format Strings</A>.
173*946379e7Schristos
174*946379e7Schristos<DT><CODE>python-format</CODE>
175*946379e7Schristos<DD>
176*946379e7Schristos<A NAME="IDX60"></A>
177*946379e7Schristos<DT><CODE>no-python-format</CODE>
178*946379e7Schristos<DD>
179*946379e7Schristos<A NAME="IDX61"></A>
180*946379e7SchristosLikewise for Python, see section <A HREF="gettext_15.html#SEC236">15.3.4  Python Format Strings</A>.
181*946379e7Schristos
182*946379e7Schristos<DT><CODE>lisp-format</CODE>
183*946379e7Schristos<DD>
184*946379e7Schristos<A NAME="IDX62"></A>
185*946379e7Schristos<DT><CODE>no-lisp-format</CODE>
186*946379e7Schristos<DD>
187*946379e7Schristos<A NAME="IDX63"></A>
188*946379e7SchristosLikewise for Lisp, see section <A HREF="gettext_15.html#SEC237">15.3.5  Lisp Format Strings</A>.
189*946379e7Schristos
190*946379e7Schristos<DT><CODE>elisp-format</CODE>
191*946379e7Schristos<DD>
192*946379e7Schristos<A NAME="IDX64"></A>
193*946379e7Schristos<DT><CODE>no-elisp-format</CODE>
194*946379e7Schristos<DD>
195*946379e7Schristos<A NAME="IDX65"></A>
196*946379e7SchristosLikewise for Emacs Lisp, see section <A HREF="gettext_15.html#SEC238">15.3.6  Emacs Lisp Format Strings</A>.
197*946379e7Schristos
198*946379e7Schristos<DT><CODE>librep-format</CODE>
199*946379e7Schristos<DD>
200*946379e7Schristos<A NAME="IDX66"></A>
201*946379e7Schristos<DT><CODE>no-librep-format</CODE>
202*946379e7Schristos<DD>
203*946379e7Schristos<A NAME="IDX67"></A>
204*946379e7SchristosLikewise for librep, see section <A HREF="gettext_15.html#SEC239">15.3.7  librep Format Strings</A>.
205*946379e7Schristos
206*946379e7Schristos<DT><CODE>scheme-format</CODE>
207*946379e7Schristos<DD>
208*946379e7Schristos<A NAME="IDX68"></A>
209*946379e7Schristos<DT><CODE>no-scheme-format</CODE>
210*946379e7Schristos<DD>
211*946379e7Schristos<A NAME="IDX69"></A>
212*946379e7SchristosLikewise for Scheme, see section <A HREF="gettext_15.html#SEC240">15.3.8  Scheme Format Strings</A>.
213*946379e7Schristos
214*946379e7Schristos<DT><CODE>smalltalk-format</CODE>
215*946379e7Schristos<DD>
216*946379e7Schristos<A NAME="IDX70"></A>
217*946379e7Schristos<DT><CODE>no-smalltalk-format</CODE>
218*946379e7Schristos<DD>
219*946379e7Schristos<A NAME="IDX71"></A>
220*946379e7SchristosLikewise for Smalltalk, see section <A HREF="gettext_15.html#SEC241">15.3.9  Smalltalk Format Strings</A>.
221*946379e7Schristos
222*946379e7Schristos<DT><CODE>java-format</CODE>
223*946379e7Schristos<DD>
224*946379e7Schristos<A NAME="IDX72"></A>
225*946379e7Schristos<DT><CODE>no-java-format</CODE>
226*946379e7Schristos<DD>
227*946379e7Schristos<A NAME="IDX73"></A>
228*946379e7SchristosLikewise for Java, see section <A HREF="gettext_15.html#SEC242">15.3.10  Java Format Strings</A>.
229*946379e7Schristos
230*946379e7Schristos<DT><CODE>csharp-format</CODE>
231*946379e7Schristos<DD>
232*946379e7Schristos<A NAME="IDX74"></A>
233*946379e7Schristos<DT><CODE>no-csharp-format</CODE>
234*946379e7Schristos<DD>
235*946379e7Schristos<A NAME="IDX75"></A>
236*946379e7SchristosLikewise for C#, see section <A HREF="gettext_15.html#SEC243">15.3.11  C# Format Strings</A>.
237*946379e7Schristos
238*946379e7Schristos<DT><CODE>awk-format</CODE>
239*946379e7Schristos<DD>
240*946379e7Schristos<A NAME="IDX76"></A>
241*946379e7Schristos<DT><CODE>no-awk-format</CODE>
242*946379e7Schristos<DD>
243*946379e7Schristos<A NAME="IDX77"></A>
244*946379e7SchristosLikewise for awk, see section <A HREF="gettext_15.html#SEC244">15.3.12  awk Format Strings</A>.
245*946379e7Schristos
246*946379e7Schristos<DT><CODE>object-pascal-format</CODE>
247*946379e7Schristos<DD>
248*946379e7Schristos<A NAME="IDX78"></A>
249*946379e7Schristos<DT><CODE>no-object-pascal-format</CODE>
250*946379e7Schristos<DD>
251*946379e7Schristos<A NAME="IDX79"></A>
252*946379e7SchristosLikewise for Object Pascal, see section <A HREF="gettext_15.html#SEC245">15.3.13  Object Pascal Format Strings</A>.
253*946379e7Schristos
254*946379e7Schristos<DT><CODE>ycp-format</CODE>
255*946379e7Schristos<DD>
256*946379e7Schristos<A NAME="IDX80"></A>
257*946379e7Schristos<DT><CODE>no-ycp-format</CODE>
258*946379e7Schristos<DD>
259*946379e7Schristos<A NAME="IDX81"></A>
260*946379e7SchristosLikewise for YCP, see section <A HREF="gettext_15.html#SEC246">15.3.14  YCP Format Strings</A>.
261*946379e7Schristos
262*946379e7Schristos<DT><CODE>tcl-format</CODE>
263*946379e7Schristos<DD>
264*946379e7Schristos<A NAME="IDX82"></A>
265*946379e7Schristos<DT><CODE>no-tcl-format</CODE>
266*946379e7Schristos<DD>
267*946379e7Schristos<A NAME="IDX83"></A>
268*946379e7SchristosLikewise for Tcl, see section <A HREF="gettext_15.html#SEC247">15.3.15  Tcl Format Strings</A>.
269*946379e7Schristos
270*946379e7Schristos<DT><CODE>perl-format</CODE>
271*946379e7Schristos<DD>
272*946379e7Schristos<A NAME="IDX84"></A>
273*946379e7Schristos<DT><CODE>no-perl-format</CODE>
274*946379e7Schristos<DD>
275*946379e7Schristos<A NAME="IDX85"></A>
276*946379e7SchristosLikewise for Perl, see section <A HREF="gettext_15.html#SEC248">15.3.16  Perl Format Strings</A>.
277*946379e7Schristos
278*946379e7Schristos<DT><CODE>perl-brace-format</CODE>
279*946379e7Schristos<DD>
280*946379e7Schristos<A NAME="IDX86"></A>
281*946379e7Schristos<DT><CODE>no-perl-brace-format</CODE>
282*946379e7Schristos<DD>
283*946379e7Schristos<A NAME="IDX87"></A>
284*946379e7SchristosLikewise for Perl brace, see section <A HREF="gettext_15.html#SEC248">15.3.16  Perl Format Strings</A>.
285*946379e7Schristos
286*946379e7Schristos<DT><CODE>php-format</CODE>
287*946379e7Schristos<DD>
288*946379e7Schristos<A NAME="IDX88"></A>
289*946379e7Schristos<DT><CODE>no-php-format</CODE>
290*946379e7Schristos<DD>
291*946379e7Schristos<A NAME="IDX89"></A>
292*946379e7SchristosLikewise for PHP, see section <A HREF="gettext_15.html#SEC249">15.3.17  PHP Format Strings</A>.
293*946379e7Schristos
294*946379e7Schristos<DT><CODE>gcc-internal-format</CODE>
295*946379e7Schristos<DD>
296*946379e7Schristos<A NAME="IDX90"></A>
297*946379e7Schristos<DT><CODE>no-gcc-internal-format</CODE>
298*946379e7Schristos<DD>
299*946379e7Schristos<A NAME="IDX91"></A>
300*946379e7SchristosLikewise for the GCC sources, see section <A HREF="gettext_15.html#SEC250">15.3.18  GCC internal Format Strings</A>.
301*946379e7Schristos
302*946379e7Schristos<DT><CODE>qt-format</CODE>
303*946379e7Schristos<DD>
304*946379e7Schristos<A NAME="IDX92"></A>
305*946379e7Schristos<DT><CODE>no-qt-format</CODE>
306*946379e7Schristos<DD>
307*946379e7Schristos<A NAME="IDX93"></A>
308*946379e7SchristosLikewise for Qt, see section <A HREF="gettext_15.html#SEC251">15.3.19  Qt Format Strings</A>.
309*946379e7Schristos
310*946379e7Schristos<DT><CODE>boost-format</CODE>
311*946379e7Schristos<DD>
312*946379e7Schristos<A NAME="IDX94"></A>
313*946379e7Schristos<DT><CODE>no-boost-format</CODE>
314*946379e7Schristos<DD>
315*946379e7Schristos<A NAME="IDX95"></A>
316*946379e7SchristosLikewise for Boost, see section <A HREF="gettext_15.html#SEC252">15.3.20  Boost Format Strings</A>.
317*946379e7Schristos
318*946379e7Schristos</DL>
319*946379e7Schristos
320*946379e7Schristos<P>
321*946379e7Schristos<A NAME="IDX96"></A>
322*946379e7Schristos<A NAME="IDX97"></A>
323*946379e7SchristosIt is also possible to have entries with a context specifier. They look like
324*946379e7Schristosthis:
325*946379e7Schristos
326*946379e7Schristos</P>
327*946379e7Schristos
328*946379e7Schristos<PRE>
329*946379e7Schristos<VAR>white-space</VAR>
330*946379e7Schristos#  <VAR>translator-comments</VAR>
331*946379e7Schristos#. <VAR>extracted-comments</VAR>
332*946379e7Schristos#: <VAR>reference</VAR>...
333*946379e7Schristos#, <VAR>flag</VAR>...
334*946379e7Schristos#| msgctxt <VAR>previous-context</VAR>
335*946379e7Schristos#| msgid <VAR>previous-untranslated-string</VAR>
336*946379e7Schristosmsgctxt <VAR>context</VAR>
337*946379e7Schristosmsgid <VAR>untranslated-string</VAR>
338*946379e7Schristosmsgstr <VAR>translated-string</VAR>
339*946379e7Schristos</PRE>
340*946379e7Schristos
341*946379e7Schristos<P>
342*946379e7SchristosThe context serves to disambiguate messages with the same
343*946379e7Schristos<VAR>untranslated-string</VAR>.  It is possible to have several entries with
344*946379e7Schristosthe same <VAR>untranslated-string</VAR> in a PO file, provided that they each
345*946379e7Schristoshave a different <VAR>context</VAR>.  Note that an empty <VAR>context</VAR> string
346*946379e7Schristosand an absent <CODE>msgctxt</CODE> line do not mean the same thing.
347*946379e7Schristos
348*946379e7Schristos</P>
349*946379e7Schristos<P>
350*946379e7Schristos<A NAME="IDX98"></A>
351*946379e7Schristos<A NAME="IDX99"></A>
352*946379e7SchristosA different kind of entries is used for translations which involve
353*946379e7Schristosplural forms.
354*946379e7Schristos
355*946379e7Schristos</P>
356*946379e7Schristos
357*946379e7Schristos<PRE>
358*946379e7Schristos<VAR>white-space</VAR>
359*946379e7Schristos#  <VAR>translator-comments</VAR>
360*946379e7Schristos#. <VAR>extracted-comments</VAR>
361*946379e7Schristos#: <VAR>reference</VAR>...
362*946379e7Schristos#, <VAR>flag</VAR>...
363*946379e7Schristos#| msgid <VAR>previous-untranslated-string-singular</VAR>
364*946379e7Schristos#| msgid_plural <VAR>previous-untranslated-string-plural</VAR>
365*946379e7Schristosmsgid <VAR>untranslated-string-singular</VAR>
366*946379e7Schristosmsgid_plural <VAR>untranslated-string-plural</VAR>
367*946379e7Schristosmsgstr[0] <VAR>translated-string-case-0</VAR>
368*946379e7Schristos...
369*946379e7Schristosmsgstr[N] <VAR>translated-string-case-n</VAR>
370*946379e7Schristos</PRE>
371*946379e7Schristos
372*946379e7Schristos<P>
373*946379e7SchristosSuch an entry can look like this:
374*946379e7Schristos
375*946379e7Schristos</P>
376*946379e7Schristos
377*946379e7Schristos<PRE>
378*946379e7Schristos#: src/msgcmp.c:338 src/po-lex.c:699
379*946379e7Schristos#, c-format
380*946379e7Schristosmsgid "found %d fatal error"
381*946379e7Schristosmsgid_plural "found %d fatal errors"
382*946379e7Schristosmsgstr[0] "s'ha trobat %d error fatal"
383*946379e7Schristosmsgstr[1] "s'han trobat %d errors fatals"
384*946379e7Schristos</PRE>
385*946379e7Schristos
386*946379e7Schristos<P>
387*946379e7SchristosHere also, a <CODE>msgctxt</CODE> context can be specified before <CODE>msgid</CODE>,
388*946379e7Schristoslike above.
389*946379e7Schristos
390*946379e7Schristos</P>
391*946379e7Schristos<P>
392*946379e7SchristosThe <VAR>previous-untranslated-string</VAR> is optionally inserted by the
393*946379e7Schristos<CODE>msgmerge</CODE> program, at the same time when it marks a message fuzzy.
394*946379e7SchristosIt helps the translator to see which changes were done by the developers
395*946379e7Schristoson the <VAR>untranslated-string</VAR>.
396*946379e7Schristos
397*946379e7Schristos</P>
398*946379e7Schristos<P>
399*946379e7SchristosIt happens that some lines, usually whitespace or comments, follow the
400*946379e7Schristosvery last entry of a PO file.  Such lines are not part of any entry,
401*946379e7Schristosand will be dropped when the PO file is processed by the tools, or may
402*946379e7Schristosdisturb some PO file editors.
403*946379e7Schristos
404*946379e7Schristos</P>
405*946379e7Schristos<P>
406*946379e7SchristosThe remainder of this section may be safely skipped by those using
407*946379e7Schristosa PO file editor, yet it may be interesting for everybody to have a better
408*946379e7Schristosidea of the precise format of a PO file.  On the other hand, those
409*946379e7Schristoswishing to modify PO files by hand should carefully continue reading on.
410*946379e7Schristos
411*946379e7Schristos</P>
412*946379e7Schristos<P>
413*946379e7SchristosEach of <VAR>untranslated-string</VAR> and <VAR>translated-string</VAR> respects
414*946379e7Schristosthe C syntax for a character string, including the surrounding quotes
415*946379e7Schristosand embedded backslashed escape sequences.  When the time comes
416*946379e7Schristosto write multi-line strings, one should not use escaped newlines.
417*946379e7SchristosInstead, a closing quote should follow the last character on the
418*946379e7Schristosline to be continued, and an opening quote should resume the string
419*946379e7Schristosat the beginning of the following PO file line.  For example:
420*946379e7Schristos
421*946379e7Schristos</P>
422*946379e7Schristos
423*946379e7Schristos<PRE>
424*946379e7Schristosmsgid ""
425*946379e7Schristos"Here is an example of how one might continue a very long string\n"
426*946379e7Schristos"for the common case the string represents multi-line output.\n"
427*946379e7Schristos</PRE>
428*946379e7Schristos
429*946379e7Schristos<P>
430*946379e7SchristosIn this example, the empty string is used on the first line, to
431*946379e7Schristosallow better alignment of the <CODE>H</CODE> from the word <SAMP>&lsquo;Here&rsquo;</SAMP>
432*946379e7Schristosover the <CODE>f</CODE> from the word <SAMP>&lsquo;for&rsquo;</SAMP>.  In this example, the
433*946379e7Schristos<CODE>msgid</CODE> keyword is followed by three strings, which are meant
434*946379e7Schristosto be concatenated.  Concatenating the empty string does not change
435*946379e7Schristosthe resulting overall string, but it is a way for us to comply with
436*946379e7Schristosthe necessity of <CODE>msgid</CODE> to be followed by a string on the same
437*946379e7Schristosline, while keeping the multi-line presentation left-justified, as
438*946379e7Schristoswe find this to be a cleaner disposition.  The empty string could have
439*946379e7Schristosbeen omitted, but only if the string starting with <SAMP>&lsquo;Here&rsquo;</SAMP> was
440*946379e7Schristospromoted on the first line, right after <CODE>msgid</CODE>.<A NAME="DOCF2" HREF="gettext_foot.html#FOOT2">(2)</A> It was not really necessary
441*946379e7Schristoseither to switch between the two last quoted strings immediately after
442*946379e7Schristosthe newline <SAMP>&lsquo;\n&rsquo;</SAMP>, the switch could have occurred after <EM>any</EM>
443*946379e7Schristosother character, we just did it this way because it is neater.
444*946379e7Schristos
445*946379e7Schristos</P>
446*946379e7Schristos<P>
447*946379e7Schristos<A NAME="IDX100"></A>
448*946379e7SchristosOne should carefully distinguish between end of lines marked as
449*946379e7Schristos<SAMP>&lsquo;\n&rsquo;</SAMP> <EM>inside</EM> quotes, which are part of the represented
450*946379e7Schristosstring, and end of lines in the PO file itself, outside string quotes,
451*946379e7Schristoswhich have no incidence on the represented string.
452*946379e7Schristos
453*946379e7Schristos</P>
454*946379e7Schristos<P>
455*946379e7Schristos<A NAME="IDX101"></A>
456*946379e7SchristosOutside strings, white lines and comments may be used freely.
457*946379e7SchristosComments start at the beginning of a line with <SAMP>&lsquo;#&rsquo;</SAMP> and extend
458*946379e7Schristosuntil the end of the PO file line.  Comments written by translators
459*946379e7Schristosshould have the initial <SAMP>&lsquo;#&rsquo;</SAMP> immediately followed by some white
460*946379e7Schristosspace.  If the <SAMP>&lsquo;#&rsquo;</SAMP> is not immediately followed by white space,
461*946379e7Schristosthis comment is most likely generated and managed by specialized GNU
462*946379e7Schristostools, and might disappear or be replaced unexpectedly when the PO
463*946379e7Schristosfile is given to <CODE>msgmerge</CODE>.
464*946379e7Schristos
465*946379e7Schristos</P>
466*946379e7Schristos<P><HR><P>
467*946379e7SchristosGo to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_2.html">previous</A>, <A HREF="gettext_4.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
468*946379e7Schristos</BODY>
469*946379e7Schristos</HTML>
470