]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/html/gettext/gettext_4.html
projects / wxWidgets.git / blame_incremental
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (non-incremental) | history | HEAD
define _HPUX_SOURCE under HP-UX, otherwise many things are not defined in standard...
[wxWidgets.git] / docs / html / gettext / gettext_4.html
... / ...
CommitLineData
1<HTML>
2<HEAD>
3<!-- This HTML file has been created by texi2html 1.54
4 from gettext.texi on 25 January 1999 -->
5
6<TITLE>GNU gettext utilities - Making the Initial PO File</TITLE>
7<link href="gettext_5.html" rel=Next>
8<link href="gettext_3.html" rel=Previous>
9<link href="gettext_toc.html" rel=ToC>
10
11</HEAD>
12<BODY>
13<p>Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_3.html">previous</A>, <A HREF="gettext_5.html">next</A>, <A HREF="gettext_12.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
14<P><HR><P>
15
16
17<H1><A NAME="SEC19" HREF="gettext_toc.html#TOC19">Making the Initial PO File</A></H1>
18
19
20
21<H2><A NAME="SEC20" HREF="gettext_toc.html#TOC20">Invoking the <CODE>xgettext</CODE> Program</A></H2>
22
23
24<PRE>
25xgettext [<VAR>option</VAR>] <VAR>inputfile</VAR> ...
26</PRE>
27
28<DL COMPACT>
29
30<DT><SAMP>`-a'</SAMP>
31<DD>
32<DT><SAMP>`--extract-all'</SAMP>
33<DD>
34Extract all strings.
35
36<DT><SAMP>`-c [<VAR>tag</VAR>]'</SAMP>
37<DD>
38<DT><SAMP>`--add-comments[=<VAR>tag</VAR>]'</SAMP>
39<DD>
40Place comment block with <VAR>tag</VAR> (or those preceding keyword lines)
41in output file.
42
43<DT><SAMP>`-C'</SAMP>
44<DD>
45<DT><SAMP>`--c++'</SAMP>
46<DD>
47Recognize C++ style comments.
48
49<DT><SAMP>`--debug'</SAMP>
50<DD>
51Use the flags <KBD>c-format</KBD> and <KBD>possible-c-format</KBD> to show who was
52responsible for marking a message as a format string. The later form is
53used if the <CODE>xgettext</CODE> program decided, the format form is used if
54the programmer prescribed it.
55
56By default only the <KBD>c-format</KBD> form is used. The translator should
57not have to care about these details.
58
59<DT><SAMP>`-d <VAR>name</VAR>'</SAMP>
60<DD>
61<DT><SAMP>`--default-domain=<VAR>name</VAR>'</SAMP>
62<DD>
63Use <TT>`<VAR>name</VAR>.po'</TT> for output (instead of <TT>`messages.po'</TT>).
64
65The special domain name <TT>`-'</TT> or <TT>`/dev/stdout'</TT> means to write
66the output to <TT>`stdout'</TT>.
67
68<DT><SAMP>`-D <VAR>directory</VAR>'</SAMP>
69<DD>
70<DT><SAMP>`--directory=<VAR>directory</VAR>'</SAMP>
71<DD>
72Change to <VAR>directory</VAR> before beginning to search and scan source
73files. The resulting <TT>`.po'</TT> file will be written relative to the
74original directory, though.
75
76<DT><SAMP>`-f <VAR>file</VAR>'</SAMP>
77<DD>
78<DT><SAMP>`--files-from=<VAR>file</VAR>'</SAMP>
79<DD>
80Read the names of the input files from <VAR>file</VAR> instead of getting
81them from the command line.
82
83<DT><SAMP>`--force'</SAMP>
84<DD>
85Always write output file even if no message is defined.
86
87<DT><SAMP>`-h'</SAMP>
88<DD>
89<DT><SAMP>`--help'</SAMP>
90<DD>
91Display this help and exit.
92
93<DT><SAMP>`-I <VAR>list</VAR>'</SAMP>
94<DD>
95<DT><SAMP>`--input-path=<VAR>list</VAR>'</SAMP>
96<DD>
97List of directories searched for input files.
98
99<DT><SAMP>`-j'</SAMP>
100<DD>
101<DT><SAMP>`--join-existing'</SAMP>
102<DD>
103Join messages with existing file.
104
105<DT><SAMP>`-k <VAR>word</VAR>'</SAMP>
106<DD>
107<DT><SAMP>`--keyword[=<VAR>word</VAR>]'</SAMP>
108<DD>
109Additional keyword to be looked for (without <VAR>word</VAR> means not to
110use default keywords).
111
112The default keywords, which are always looked for if not explicitly
113disabled, are <CODE>gettext</CODE>, <CODE>dgettext</CODE>, <CODE>dcgettext</CODE> and
114<CODE>gettext_noop</CODE>.
115
116<DT><SAMP>`-m [<VAR>string</VAR>]'</SAMP>
117<DD>
118<DT><SAMP>`--msgstr-prefix[=<VAR>string</VAR>]'</SAMP>
119<DD>
120Use <VAR>string</VAR> or "" as prefix for msgstr entries.
121
122<DT><SAMP>`-M [<VAR>string</VAR>]'</SAMP>
123<DD>
124<DT><SAMP>`--msgstr-suffix[=<VAR>string</VAR>]'</SAMP>
125<DD>
126Use <VAR>string</VAR> or "" as suffix for msgstr entries.
127
128<DT><SAMP>`--no-location'</SAMP>
129<DD>
130Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>'</SAMP> lines.
131
132<DT><SAMP>`-n'</SAMP>
133<DD>
134<DT><SAMP>`--add-location'</SAMP>
135<DD>
136Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>'</SAMP> lines (default).
137
138<DT><SAMP>`--omit-header'</SAMP>
139<DD>
140Don't write header with <SAMP>`msgid ""'</SAMP> entry.
141
142This is useful for testing purposes because it eliminates a source
143of variance for generated <CODE>.gmo</CODE> files. We can ship some of
144these files in the GNU <CODE>gettext</CODE> package, and the result of
145regenerating them through <CODE>msgfmt</CODE> should yield the same values.
146
147<DT><SAMP>`-p <VAR>dir</VAR>'</SAMP>
148<DD>
149<DT><SAMP>`--output-dir=<VAR>dir</VAR>'</SAMP>
150<DD>
151Output files will be placed in directory <VAR>dir</VAR>.
152
153<DT><SAMP>`-s'</SAMP>
154<DD>
155<DT><SAMP>`--sort-output'</SAMP>
156<DD>
157Generate sorted output and remove duplicates.
158
159<DT><SAMP>`--strict'</SAMP>
160<DD>
161Write out strict Uniforum conforming PO file.
162
163<DT><SAMP>`-v'</SAMP>
164<DD>
165<DT><SAMP>`--version'</SAMP>
166<DD>
167Output version information and exit.
168
169<DT><SAMP>`-x <VAR>file</VAR>'</SAMP>
170<DD>
171<DT><SAMP>`--exclude-file=<VAR>file</VAR>'</SAMP>
172<DD>
173Entries from <VAR>file</VAR> are not extracted.
174
175</DL>
176
177<P>
178Search path for supplementary PO files is:
179<TT>`/usr/local/share/nls/src/'</TT>.
180
181</P>
182<P>
183If <VAR>inputfile</VAR> is <SAMP>`-'</SAMP>, standard input is read.
184
185</P>
186<P>
187This implementation of <CODE>xgettext</CODE> is able to process a few awkward
188cases, like strings in preprocessor macros, ANSI concatenation of
189adjacent strings, and escaped end of lines for continued strings.
190
191</P>
192
193
194<H2><A NAME="SEC21" HREF="gettext_toc.html#TOC21">C Sources Context</A></H2>
195
196<P>
197PO mode is particularly powerful when used with PO files
198created through GNU <CODE>gettext</CODE> utilities, as those utilities
199insert special comments in the PO files they generate.
200Some of these special comments relate the PO file entry to
201exactly where the untranslated string appears in the program sources.
202
203</P>
204<P>
205When the translator gets to an untranslated entry, she is fairly
206often faced with an original string which is not as informative as
207it normally should be, being succinct, cryptic, or otherwise ambiguous.
208Before choosing how to translate the string, she needs to understand
209better what the string really means and how tight the translation has
210to be. Most of the time, when problems arise, the only way left to make
211her judgment is looking at the true program sources from where this
212string originated, searching for surrounding comments the programmer
213might have put in there, and looking around for helping clues of
214<EM>any</EM> kind.
215
216</P>
217<P>
218Surely, when looking at program sources, the translator will receive
219more help if she is a fluent programmer. However, even if she is
220not versed in programming and feels a little lost in C code, the
221translator should not be shy at taking a look, once in a while.
222It is most probable that she will still be able to find some of the
223hints she needs. She will learn quickly to not feel uncomfortable
224in program code, paying more attention to programmer's comments,
225variable and function names (if he dared choosing them well), and
226overall organization, than to the program code itself.
227
228</P>
229<P>
230The following commands are meant to help the translator at getting
231program source context for a PO file entry.
232
233</P>
234<DL COMPACT>
235
236<DT><KBD>s</KBD>
237<DD>
238Resume the display of a program source context, or cycle through them.
239
240<DT><KBD>M-s</KBD>
241<DD>
242Display of a program source context selected by menu.
243
244<DT><KBD>S</KBD>
245<DD>
246Add a directory to the search path for source files.
247
248<DT><KBD>M-S</KBD>
249<DD>
250Delete a directory from the search path for source files.
251
252</DL>
253
254<P>
255The commands <KBD>s</KBD> (<CODE>po-cycle-reference</CODE>) and <KBD>M-s</KBD>
256(<CODE>po-select-source-reference</CODE>) both open another window displaying
257some source program file, and already positioned in such a way that
258it shows an actual use of the string to be translated. By doing
259so, the command gives source program context for the string. But if
260the entry has no source context references, or if all references
261are unresolved along the search path for program sources, then the
262command diagnoses this as an error.
263
264</P>
265<P>
266Even if <KBD>s</KBD> (or <KBD>M-s</KBD>) opens a new window, the cursor stays
267in the PO file window. If the translator really wants to
268get into the program source window, she ought to do it explicitly,
269maybe by using command <KBD>O</KBD>.
270
271</P>
272<P>
273When <KBD>s</KBD> is typed for the first time, or for a PO file entry which
274is different of the last one used for getting source context, then the
275command reacts by giving the first context available for this entry,
276if any. If some context has already been recently displayed for the
277current PO file entry, and the translator wandered off to do other
278things, typing <KBD>s</KBD> again will merely resume, in another window,
279the context last displayed. In particular, if the translator moved
280the cursor away from the context in the source file, the command will
281bring the cursor back to the context. By using <KBD>s</KBD> many times
282in a row, with no other commands intervening, PO mode will cycle to
283the next available contexts for this particular entry, getting back
284to the first context once the last has been shown.
285
286</P>
287<P>
288The command <KBD>M-s</KBD> behaves differently. Instead of cycling through
289references, it lets the translator choose of particular reference among
290many, and displays that reference. It is best used with completion,
291if the translator types <KBD>TAB</KBD> immediately after <KBD>M-s</KBD>, in
292response to the question, she will be offered a menu of all possible
293references, as a reminder of which are the acceptable answers.
294This command is useful only where there are really many contexts
295available for a single string to translate.
296
297</P>
298<P>
299Program source files are usually found relative to where the PO
300file stands. As a special provision, when this fails, the file is
301also looked for, but relative to the directory immediately above it.
302Those two cases take proper care of most PO files. However, it might
303happen that a PO file has been moved, or is edited in a different
304place than its normal location. When this happens, the translator
305should tell PO mode in which directory normally sits the genuine PO
306file. Many such directories may be specified, and all together, they
307constitute what is called the <STRONG>search path</STRONG> for program sources.
308The command <KBD>S</KBD> (<CODE>po-consider-source-path</CODE>) is used to interactively
309enter a new directory at the front of the search path, and the command
310<KBD>M-S</KBD> (<CODE>po-ignore-source-path</CODE>) is used to select, with completion,
311one of the directories she does not want anymore on the search path.
312
313</P>
314
315
316<H2><A NAME="SEC22" HREF="gettext_toc.html#TOC22">Using Translation Compendiums</A></H2>
317
318<P>
319Compendiums are yet to be implemented.
320
321</P>
322<P>
323An incoming PO mode feature will let the translator maintain a
324compendium of already achieved translations. A <STRONG>compendium</STRONG>
325is a special PO file containing a set of translations recurring in
326many different packages. The translator will be given commands for
327adding entries to her compendium, and later initializing untranslated
328entries, or updating already translated entries, from translations
329kept in the compendium. For this to work, however, the compendium
330would have to be normalized. See section <A HREF="gettext_2.html#SEC12">Normalizing Strings in Entries</A>.
331
332</P>
333
334<P><HR><P>
335<p>Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_3.html">previous</A>, <A HREF="gettext_5.html">next</A>, <A HREF="gettext_12.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
336</BODY>
337</HTML>
wxWidgets (Impactor)