docs/html/gettext/gettext_4.html

   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>
  25 xgettext [<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>
  34 Extract all strings.
  35
  36 <DT><SAMP>`-c [<VAR>tag</VAR>]'</SAMP>
  37 <DD>
  38 <DT><SAMP>`--add-comments[=<VAR>tag</VAR>]'</SAMP>
  39 <DD>
  40 Place comment block with <VAR>tag</VAR> (or those preceding keyword lines)
  41 in output file.
  42
  43 <DT><SAMP>`-C'</SAMP>
  44 <DD>
  45 <DT><SAMP>`--c++'</SAMP>
  46 <DD>
  47 Recognize C++ style comments.
  48
  49 <DT><SAMP>`--debug'</SAMP>
  50 <DD>
  51 Use the flags <KBD>c-format</KBD> and <KBD>possible-c-format</KBD> to show who was
  52 responsible for marking a message as a format string.  The later form is
  53 used if the <CODE>xgettext</CODE> program decided, the format form is used if
  54 the programmer prescribed it.
  55
  56 By default only the <KBD>c-format</KBD> form is used.  The translator should
  57 not 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>
  63 Use <TT>`<VAR>name</VAR>.po'</TT> for output (instead of <TT>`messages.po'</TT>).
  64
  65 The special domain name <TT>`-'</TT> or <TT>`/dev/stdout'</TT> means to write
  66 the 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>
  72 Change to <VAR>directory</VAR> before beginning to search and scan source
  73 files.  The resulting <TT>`.po'</TT> file will be written relative to the
  74 original directory, though.
  75
  76 <DT><SAMP>`-f <VAR>file</VAR>'</SAMP>
  77 <DD>
  78 <DT><SAMP>`--files-from=<VAR>file</VAR>'</SAMP>
  79 <DD>
  80 Read the names of the input files from <VAR>file</VAR> instead of getting
  81 them from the command line.
  82
  83 <DT><SAMP>`--force'</SAMP>
  84 <DD>
  85 Always write output file even if no message is defined.
  86
  87 <DT><SAMP>`-h'</SAMP>
  88 <DD>
  89 <DT><SAMP>`--help'</SAMP>
  90 <DD>
  91 Display 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>
  97 List of directories searched for input files.
  98
  99 <DT><SAMP>`-j'</SAMP>
 100 <DD>
 101 <DT><SAMP>`--join-existing'</SAMP>
 102 <DD>
 103 Join 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>
 109 Additional keyword to be looked for (without <VAR>word</VAR> means not to
 110 use default keywords).
 111
 112 The default keywords, which are always looked for if not explicitly
 113 disabled, 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>
 120 Use <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>
 126 Use <VAR>string</VAR> or "" as suffix for msgstr entries.
 127
 128 <DT><SAMP>`--no-location'</SAMP>
 129 <DD>
 130 Do 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>
 136 Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>'</SAMP> lines (default).
 137
 138 <DT><SAMP>`--omit-header'</SAMP>
 139 <DD>
 140 Don't write header with <SAMP>`msgid ""'</SAMP> entry.
 141
 142 This is useful for testing purposes because it eliminates a source
 143 of variance for generated <CODE>.gmo</CODE> files.  We can ship some of
 144 these files in the GNU <CODE>gettext</CODE> package, and the result of
 145 regenerating 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>
 151 Output 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>
 157 Generate sorted output and remove duplicates.
 158
 159 <DT><SAMP>`--strict'</SAMP>
 160 <DD>
 161 Write out strict Uniforum conforming PO file.
 162
 163 <DT><SAMP>`-v'</SAMP>
 164 <DD>
 165 <DT><SAMP>`--version'</SAMP>
 166 <DD>
 167 Output 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>
 173 Entries from <VAR>file</VAR> are not extracted.
 174
 175 </DL>
 176
 177 <P>
 178 Search path for supplementary PO files is:
 179 <TT>`/usr/local/share/nls/src/'</TT>.
 180
 181 </P>
 182 <P>
 183 If <VAR>inputfile</VAR> is <SAMP>`-'</SAMP>, standard input is read.
 184
 185 </P>
 186 <P>
 187 This implementation of <CODE>xgettext</CODE> is able to process a few awkward
 188 cases, like strings in preprocessor macros, ANSI concatenation of
 189 adjacent 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>
 197 PO mode is particularly powerful when used with PO files
 198 created through GNU <CODE>gettext</CODE> utilities, as those utilities
 199 insert special comments in the PO files they generate.
 200 Some of these special comments relate the PO file entry to
 201 exactly where the untranslated string appears in the program sources.
 202
 203 </P>
 204 <P>
 205 When the translator gets to an untranslated entry, she is fairly
 206 often faced with an original string which is not as informative as
 207 it normally should be, being succinct, cryptic, or otherwise ambiguous.
 208 Before choosing how to translate the string, she needs to understand
 209 better what the string really means and how tight the translation has
 210 to be.  Most of the time, when problems arise, the only way left to make
 211 her judgment is looking at the true program sources from where this
 212 string originated, searching for surrounding comments the programmer
 213 might have put in there, and looking around for helping clues of
 214 <EM>any</EM> kind.
 215
 216 </P>
 217 <P>
 218 Surely, when looking at program sources, the translator will receive
 219 more help if she is a fluent programmer.  However, even if she is
 220 not versed in programming and feels a little lost in C code, the
 221 translator should not be shy at taking a look, once in a while.
 222 It is most probable that she will still be able to find some of the
 223 hints she needs.  She will learn quickly to not feel uncomfortable
 224 in program code, paying more attention to programmer's comments,
 225 variable and function names (if he dared choosing them well), and
 226 overall organization, than to the program code itself.
 227
 228 </P>
 229 <P>
 230 The following commands are meant to help the translator at getting
 231 program source context for a PO file entry.
 232
 233 </P>
 234 <DL COMPACT>
 235
 236 <DT><KBD>s</KBD>
 237 <DD>
 238 Resume the display of a program source context, or cycle through them.
 239
 240 <DT><KBD>M-s</KBD>
 241 <DD>
 242 Display of a program source context selected by menu.
 243
 244 <DT><KBD>S</KBD>
 245 <DD>
 246 Add a directory to the search path for source files.
 247
 248 <DT><KBD>M-S</KBD>
 249 <DD>
 250 Delete a directory from the search path for source files.
 251
 252 </DL>
 253
 254 <P>
 255 The 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
 257 some source program file, and already positioned in such a way that
 258 it shows an actual use of the string to be translated.  By doing
 259 so, the command gives source program context for the string.  But if
 260 the entry has no source context references, or if all references
 261 are unresolved along the search path for program sources, then the
 262 command diagnoses this as an error.
 263
 264 </P>
 265 <P>
 266 Even if <KBD>s</KBD> (or <KBD>M-s</KBD>) opens a new window, the cursor stays
 267 in the PO file window.  If the translator really wants to
 268 get into the program source window, she ought to do it explicitly,
 269 maybe by using command <KBD>O</KBD>.
 270
 271 </P>
 272 <P>
 273 When <KBD>s</KBD> is typed for the first time, or for a PO file entry which
 274 is different of the last one used for getting source context, then the
 275 command reacts by giving the first context available for this entry,
 276 if any.  If some context has already been recently displayed for the
 277 current PO file entry, and the translator wandered off to do other
 278 things, typing <KBD>s</KBD> again will merely resume, in another window,
 279 the context last displayed.  In particular, if the translator moved
 280 the cursor away from the context in the source file, the command will
 281 bring the cursor back to the context.  By using <KBD>s</KBD> many times
 282 in a row, with no other commands intervening, PO mode will cycle to
 283 the next available contexts for this particular entry, getting back
 284 to the first context once the last has been shown.
 285
 286 </P>
 287 <P>
 288 The command <KBD>M-s</KBD> behaves differently.  Instead of cycling through
 289 references, it lets the translator choose of particular reference among
 290 many, and displays that reference.  It is best used with completion,
 291 if the translator types <KBD>TAB</KBD> immediately after <KBD>M-s</KBD>, in
 292 response to the question, she will be offered a menu of all possible
 293 references, as a reminder of which are the acceptable answers.
 294 This command is useful only where there are really many contexts
 295 available for a single string to translate.
 296
 297 </P>
 298 <P>
 299 Program source files are usually found relative to where the PO
 300 file stands.  As a special provision, when this fails, the file is
 301 also looked for, but relative to the directory immediately above it.
 302 Those two cases take proper care of most PO files.  However, it might
 303 happen that a PO file has been moved, or is edited in a different
 304 place than its normal location.  When this happens, the translator
 305 should tell PO mode in which directory normally sits the genuine PO
 306 file.  Many such directories may be specified, and all together, they
 307 constitute what is called the <STRONG>search path</STRONG> for program sources.
 308 The command <KBD>S</KBD> (<CODE>po-consider-source-path</CODE>) is used to interactively
 309 enter 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,
 311 one 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>
 319 Compendiums are yet to be implemented.
 320
 321 </P>
 322 <P>
 323 An incoming PO mode feature will let the translator maintain a
 324 compendium of already achieved translations.  A <STRONG>compendium</STRONG>
 325 is a special PO file containing a set of translations recurring in
 326 many different packages.  The translator will be given commands for
 327 adding entries to her compendium, and later initializing untranslated
 328 entries, or updating already translated entries, from translations
 329 kept in the compendium.  For this to work, however, the compendium
 330 would 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>